从 rubber duck 到 grill-with-docs：把 AI 当成 45 分钟的领域语言共建会

为什么现在谈这个

2026 年 3 月，Matt Pocock 发了一条视频《My ‘Grill Me’ Skill Went Viral》——一个 6 行的 Claude Code skill（让 agent 持续追问需求直到达成共识），随后在开发者社区被广泛采用。同月，4 月他把它升级为 /grill-with-docs（带落盘能力的版本），到 8 月初的 v1.2 时，这个原始协议已经膨胀成 25 个 skill 组成的工程流水线。

这背后不是一个 skill 突然火——而是 DDD（Domain-Driven Design）领域语言传统在 agent 时代的复活。1999 年程序员拿橡胶鸭解释代码给橡皮鸭听（Pragmatic Programmer），2003 年 Eric Evans 在 Domain-Driven Design 里把"通用语言（ubiquitous language）“立为对抗需求蔓延的武器，2011 年 Michael Nygard 提出 ADR（Architectural Decision Record）固化"难以回头的决策”，2026 年 LLM 把这两件事压缩成一段 6 行的 prompt。

我学完这套协议后，落地的姿势不是"装一个 skill"——而是把它接进已有的"需求模板 → 任务拆分 → 派活执行"流水线，在"人提需求 → agent 出活"这个日常动作里塞一道 5-10 轮的"语言咬合"关卡。本文记录这次学习的两个部分：方法论源头 + 实践落点。

方法论源头：四股历史力量的合流

grill-with-docs 不是孤立发明的。它是 27 年软件工程里四个独立传统的合流——理解这四条线才能知道它的能力边界。

1. 橡胶鸭调试（1999-）

出处：Andrew Hunt, David Thomas, 《The Pragmatic Programmer: From Journeyman to Master》, 1999

程序员给一只橡皮鸭逐行解释代码，问题会在解释过程中"跳出来"。核心机制：强迫你把内部模型外化成语言——外化的瞬间，模型的漏洞就暴露了。

Matt 自陈 grill-me 的本质就是 “rubber ducking 的 AI 化”——区别在于：(a) 鸭子不会反问，AI 会；(b) 鸭子不记得上一轮，AI 有上下文；(c) 鸭子不查代码，AI 会。

2. DDD 通用语言（2003-）

出处：Eric Evans, 《Domain-Driven Design: Tackling Complexity in the Heart of Software》, 2003 推广：Martin Fowler, “Ubiquitous Language”, 2006

Evans 提出的核心论断：复杂的业务系统里，开发者和领域专家（domain expert）必须用同一套词讨论问题。如果代码里的 “Account” 含义是财务账户、运营讨论时 “Account” 指用户账号、销售说 “Account” 是潜在客户名单——系统注定扭曲。通用语言就是把所有人口径对齐到同一张术语表。

Fowler 2006 年的 bliki 文章把它定调成 DDD 战术模式的核心——不仅在需求阶段用，代码里也必须用一致的命名（类名、字段名、状态枚举名）。

domain-modeling skill 的 CONTEXT.md 就是这张表的最小可用形式：每个术语一段定义 + 一个 _Avoid_ 子项（告诉你放弃哪些同义词）。

3. 架构决策记录 ADR（2011-）

出处：Michael Nygard, “Documenting Architecture Decisions”, Cognitect Blog, 2011-11-15 变体：MADR（Markdown ADR, 2017-）→ YADR（YAML ADR, 2026-03）

Nygard 的洞见：六个月后新人问"为什么当初选 PostgreSQL 不选 MongoDB"时，原作者可能已经离职，剩下的人靠记忆和传说不一定能复现当时的权衡。ADR 是一次决策的快照：上下文 + 决定 + 后果——1 页 Markdown，git 跟踪，5 分钟写完，半年后救命。

Matt 的 ADR 模板更克制：标题 + 1-3 句正文。能用三句说完的决策就不该用三页——三页的那种叫设计文档，不叫决策记录。

4. LLM 的不确定性 / 歧义检测（2025-）

工业界有最新数据给这套传统加注脚：ICSME 2025 工业研究（Requirements Ambiguity Detection with LLMs）表明，10-shot 提示比 0-shot 在歧义分类任务上平均提升 20.2%——给模型看 10 个歧义 vs 不歧义的例子，能显著减少它把模糊需求当成明确需求跑掉的情况。arxiv 2507.05981 的多智能体辩论实验（F1 0.726 → 0.841，n=0 单辩论，n=1 边际收益仅 0.006）则提示我们：多轮追问比多 agent 辩论更划算——前者和 grill 协议天然同构。

把这四股力量拼起来看：rubber ducking 提供"对话形式" → DDD 提供"产物格式（CONTEXT.md）" → ADR 提供"决策产物（docs/adr/）" → LLM 能力提供"执行者"。grill-with-docs 是把这四块第一次用一个 6 行 prompt 装到一块的合流点。

grill 协议本身：6 行 prompt 的解构

公开版本（mattpocock/skills）的核心文本：

Interview me relentlessly about every aspect of this plan until we reach
a shared understanding. Walk down each branch of the design tree resolving
dependencies between decisions one by one. If a question can be answered by
exploring the codebase, explore the codebase instead. For each question,
provide your recommended answer.

四句话各对应一个机制：

第四句是 Matt 后来加的（2026 年 3 月之后），改之前用户被 540 个无推荐问题淹没——加上之后，“是 / 否 / 改成 X” 比"自己想答案"效率高一个量级。

落盘机制：grill-me vs grill-with-docs

grill-me 和 grill-with-docs 用的是同一段追问协议，唯一的区别是落不落盘：

CONTEXT.md 不是 spec、不是 README、不是 changelog——它是一张术语词典。三件事必须遵守：

1. 每个术语一段话定义。一句话能说清就别写两句。
2. _Avoid_ 子项显式列出放弃的同义词。这是后续 agent 接手时最值钱的部分——告诉它"别再用 X 替代这个概念"。
3. 没有任何实现细节。“这个 Order 有 status 字段” 写到 ADR 里；“Order 是客户下的单"写进 CONTEXT.md。混淆这两者的人最后得到的不是术语表，是 spec。

ADR 比 CONTEXT.md 严格得多——必须三关全过才落盘：

1. Hard to reverse：明天反悔成本多大？选 Redis 选 Memcached 容易反悔，不写 ADR；选 PostgreSQL 选 MongoDB 反悔要重写数据层，写 ADR。
2. Surprising without context：六个月后的人看到代码会问"为什么这么写"吗？不问的就不写。
3. Real trade-off：存在真实备选方案吗？没有的（“我们就是用 Python 因为组里没人会 Ruby”）就不该写成 ADR。

只要有一关不过——尤其是反过来发现"其实可以轻松改”——就该停。Matt 原话：「miss any one of the ADR’s three tests and there is no ADR. An easily-reversed decision will just get reversed」。

失败模式库：9 个坑的真实分布

Matt 在 2026-05 的 9 Things People Get Wrong 视频里把常见失败归成 9 类。我按"踩坑代价 × 发生频率"重新排序，标注哪些是老大和我的日常会撞上的：

高频高代价（立刻影响交付）

1. 试图在 grilling 会话里答高保真问题（hands-on 验证问题）

问"表单字段应该拆页还是一页"这种问题——你不实际看一版 UI 根本答不了。grill 会话里纯靠语言讨论，得不到新信息，只能编。Matt 提的解法叫 handoff 模式：

grill（低保真问题） → prototype（做一版 UI 看效果） → grill 回来继续

我自己的版本：接到一个新 idea，先问 5-8 个低保真问题把"边界/术语/外延"对齐——一旦撞到"必须看一版实物才能答的"，立刻停下，开一个 prototype session 做 mock，回过头再 grill。

2. Scope 太大撑爆 context window

Grilling session 一般 45 分钟、累积下来的"决策密度"会在 context window 120k token 之后明显下降（Matt 称之为 “dumb zone”）。超 120k 之后模型开始丢三落四、立场漂移、答非所问。

解法：开局先让 agent 把大 scope 拆 grillable chunks，每个 chunk 单 session 跑。这正是任何任务拆分流程都在强调的"bite-sized 2-5 分钟任务"思路的会话级对应物。

3. 太被动——被 agent 反向 scope creep

passive vs active 是一根轴。passive 用户会被 agent 扔 540 个无意义问题，scope 失控；overly active 用户会陷入"在低保真细节上 grill 个没完"——问题在于你没判断"该写代码了就停"。

正确姿势：每个 session 开局明确"我打算这轮只问 3 类问题，问完就停"。

4. 选错模型

Grilling 强烈依赖模型的参数化知识（parametric knowledge）——不是你塞给它的上下文，而是它"先天知道的东西"，否则你提一个方案它反驳不出更好的。小模型 grill 不出好东西——它们没有足够的训练语料去提"你想过 X 吗"。Matt 的建议是：grill 用 frontier model；implement 可以用小模型。

对我们的实际影响：grill 这步必须云端大模型——本地 8B 提不出"你考虑过 X 吗"这种主动挑战。

中频中代价（影响落盘质量）

5. 清空 context 写 PRD = 扔掉所有决策

Grilling 跑完时，context window 装满了"为什么这么设计"的活证据。你想清理一下再来写 spec——大错特错。你刚把决策密度最值钱的部分扔了。

正确姿势：context 够就直接在同一个 session 调 to-spec（Matt 流水线第二步）；不够就并行开第二个 session 接续。

6. 跑完没出 CONTEXT.md / ADR

两个原因：

• 平庸原因：session 讨论的本来就没新词汇/新决策——0 个 ADR 是正常结果，不是 bug
• 真 bug：skill 在外部编排层（spec-driven wrapper、多 agent 框架）里跑时，文件写入被静默吃掉，但 interview 还在跑

自检手法：让 agent 显式列出它加载了哪些 skill——Matt 提到 grill-with-docs 自己的 SKILL.md 只有一行委托，如果 grilling 加载了但 domain-modeling 没加载，会得到"很棒的追问 + 没有落盘"这个混合态。

7. 假装有 domain 但其实没有

Matt 的金句：A domain language you do not understand yourself becomes meaningless drivel once written down. —— CONTEXT.md 不替代你的理解，只强制你的理解要精确。

判断手法：你能不能在 30 秒内给"什么是 X"一个别人能复述的定义？不能就别往 CONTEXT.md 里写——写出来只会变成 lore。

低频高代价（容易掉以轻心）

8. CONTEXT.md 失控膨胀

500 行、1000 行、3000 行的 CONTEXT.md 是病不是症状——病是文件被灌进了实现细节和决策。解法是直接给 agent：

/grill-with-docs make my CONTEXT.md more concise and remove any implementation details from it

不要先拆 CONTEXT-MAP.md 成多个小文件——拆膨胀文件只会得到多个膨胀文件。先瘦身，再决定要不要拆。

9. ADR 用了，但格式被团队家规覆盖

grill-with-docs 把 glossary 和 ADR 装在一个 skill 里。如果团队已有 ADR 约定（不同模板/不同位置/不同命名），skill 默认指令和家规冲突。当前没有干净的解法：要么本地 fork 改 skill，要么在 docs/agents/domain.md 写明 override 规则。Matt 自己承认这是一个 open request。

我们的实践姿势：嵌进现有流水线

大多数组织都已有"需求模板 → 任务拆分 → 派活执行"这条流水线（比如 SPEC 文档 + sprint 切分 + Jira 工单）。grill-with-docs 的合理位置是前置——在写模板之前先把领域语言对齐。

老大提一个 idea（"我要做一个……"）
    ↓
[1] /grill-with-docs 跑 5-10 轮（单 session）
    ↓ 产出：
    ↓ - CONTEXT.md（老大脑子里的术语词典，已落盘）
    ↓ - docs/adr/0001-xxx.md（hard-to-reverse 决策）
    ↓
[2] /grill-me 同协议跨项目复用（如果 idea 还跨多个仓库）
    ↓
[3] 用需求模板把 CONTEXT 翻译成 PRD（功能清单/边界/验收/不要做四件套）
    ↓（领域术语已锁 → 模板里的 "input/output/边界" 不会再被同名异义拖累）
    ↓
[4] 任务拆分：写 markdown plan，把需求切成 2-5 分钟可执行单元
    ↓
[5] 派活执行：人工或 AI agent 跑单元任务

收益点不在 grill 这一步本身——收益在 [1]→[3] 的衔接：当 CONTEXT.md 锁了"账户=Customer 不是 User 不是 Account"之后，后续的 PRD 模板、任务描述、agent prompt 全部自动用 Customer——人和 agent 不会再为"你说的账户到底指啥"吵三遍。

实操节奏建议

• 每天 ≤ 2 次 grill——超过 2 次 context window 累计会进 dumb zone 的边缘
• 每个 grill 30-45 分钟封顶——不是模型死了，是人的耐心和精确度到顶
• 强制落盘检查：每个 session 结束前问 agent “本次 CONTEXT.md 改了哪几行，ADR 写了几个”——答案模糊就重启
• 不写 CONTEXT.md 的 session 不是失败——可能你这次没新词汇——但 5 次里有 4 次空产出，说明你的 idea 太散

触发条件

不是所有需求都要 grill。建议自动 grill 的触发条件（任一）：

• 涉及 ≥ 3 个之前没明确命名的实体（“账号 / 订单 / 任务 / 凭据”）
• 涉及架构层切换（关系型 → 向量库 / 单体 → 微服务 / 同步 → 异步）
• 涉及"什么算成功"模糊（“做一个好用的工具”）
• 涉及跨人/跨 agent 协作（交付物会被第三方接手）

不属于这些的（小修小补、单文件改动、明确 bug 修复）——直接 任务拆分 → 派活执行，grill 是杀鸡用牛刀。

边界与局限

grill 协议不解决的：

1. 不知道什么值得做——grill 只解决"做出来对不对"，不解决"该不该做"。后者需要市场/用户研究（我们已有 product-ideation 技能负责）。
2. 不知道怎么做——grill 帮你对齐"做什么"，怎么做交给 TDD + implement。
3. 不能替代批判性思维——Matt 自己承认，glossary 对 agent 性能是否有提升有公开争议：一种声音是"term 和它的 plain-English 展开对模型效果一样"——glossary 真正的价值是让团队成员（人）和 agent 的工作对齐，而不是"让 agent 更聪明"。
4. 必须用大模型——本地 8B 跑 grill 提不出有意义的挑战。

grill-with-docs 当前的已知 bug（Matt 自陈）：

• 在外部编排层（spec-driven wrapper、多 agent 框架）里跑时，文件写入可能被静默吃掉
• session 结束消息倾向开放（不像 to-spec 那样有明确出口）——容易"跑完没下一步"
• CONTEXT.md 大小没有内生控制——膨胀了不会自动警告

这些不是"我不小心踩的坑"，是上游 skill 仓库自己承认的开放问题。引用以保诚实。

收尾

Grill 协议的本质不是"一个新工具"——是软件工程里"通用语言"和"决策记录"两个老传统，被 LLM 时代重新包装成一段 6 行 prompt。它解决的不是工程问题，是语言问题：当人、agent、未来的你用同一个词指同一个东西，复杂系统的扭曲点会少一半。

但它有真边界：依赖大模型的参数化知识、依赖单 session 的 context window、依赖人能持续主动驱动对话。一周用它两次以下收益最高；当成万能仪式开每个会都跑——会变成新形式的"填表主义"。

对我来说最有价值的不是 skill 本身——是**它逼我想清楚"我脑子里的术语到底指什么"**这件事。CONTEXT.md 只是一张快照；真正的工序是 grill 过程中的"我刚才说的 A 和你说的 A 是不是一个 A"那种自问。

附录 C：实践记录 — Turtle Soup Voice（2026-09-03）

理论归理论，落地才算数。本节记录把 grill-with-docs 用在一个真实 idea 上的产物。

C.1 实践对象

Idea：“我想设计一个帮助人们日常和 AI 语音玩乌龟汤的游戏。”

老大原话 5 句话——非常 grill 适合的"低保真、边界模糊"状态。完全没写 玩法类型、用户画像、故事来源、技术栈、变现路径——这是 grill 的最佳土壤。

C.2 Grill 过程（30 分钟）

我开了 clarify 多选问，把模糊决策逐一收紧。5 轮问完后，老大回答汇总：

C.3 落盘产物

跑完 grill 后，我新建了一个项目骨架，目录结构按 grill-with-docs 协议要求：

• CONTEXT.md — 12 个术语锁住（含 _Avoid_ 同义词）。例如：
  • Turtle Soup = lateral thinking puzzle 的中文社区称呼，_Avoid_: 情境猜谜（容易和 collaborative fiction 混淆）
  • Verdict = Host 对 Question 的回答，必须是 yes / no / irrelevant 三选一，_Avoid_: 回答（暗示可以长句）
• docs/adr/0001-0004.md — 4 个 ADR 通过三关
  • 0001: Host 是 LLM 不是规则引擎（hard-to-reverse：换实现要重写判定逻辑）
  • 0002: Verdict 只允许 yes/no/irrelevant 三档（hard-to-reverse：开放判定 = 推翻玩法）
  • 0003: Story 是 LLM 现想不是池（hard-to-reverse：未来本地化路径和池模式冲突）
  • 0004: MVP 是 web app 不是 App Store（hard-to-reverse：原生上架走审核周期）

C.4 大模型 vs 本地实测（45 分钟）

按方法论"grill 必须 frontier model"论断本来应该做云端 vs 本地实验——但 grill 协议没覆盖到"云端能不能跑、能不能用哪家 provider"这个问题（C.6 详述），导致这一对照只完成了一半：本地 27B 跑了，云端 frontier 没跑（DEEPSEEK/MINIMAX key 当天失效，且当时没有回头问老大是否可以用其他 provider）。

测试 1：6 道经典酒吧喝水题判定

测试 2：10 题真实生成 Story 的判定闭环

同一个 Story（mirror-amnesia），让两个本地模型分别跑 10 道用户提问：

两模型错的是同一题——Q1 “Was the man in a bathroom?” 应 yes（surface 提到 bathroom），Q9 “Was he crying because someone died?” 应 irrelevant（truth 没提）。这是 prompt 边界问题：判定是否应基于 surface + truth 还是仅 truth。

测试 3：Story 即兴生成（3 次）

C.5 这次实践给方法论打了 3 个补丁

1. “5 次 grill 里 4 次空产出才是病”——可以缩成"3 次"。这次 5 轮问完，每一轮都产出了东西。原因是 idea 是真正未结构化的"一句话"。如果是已有结构的想法想精修，可能 5 次空产出。
2. “grill 必须 frontier model”——这条对判定任务是真，对生成任务不是铁律。本地 27B/35B 跑判定 80%+，跑 Story 生成也能写出"啊哈"故事（mirror-amnesia 的反转很地道）。生成能力门槛比判定低。
3. 本地产出节奏不可控——同一个 prompt 跑 3 次 Story 生成，2 次 38 秒，1 次 timeout 120 秒。MVP 必须有 60 秒超时 + 兜底文案（“换个故事试试”），不能干等。

C.6 收尾与评价

最终产物：

• 项目 CONTEXT.md（12 个术语锁定，每个都附带 _Avoid_ 同义词排除）
• 项目 docs/adr/0001-0004.md（4 个三关全过的决策）
• 实测：本地 27B 判定 80%+、Story 生成能写"啊哈"故事；本地产出节奏波动大（38s / 38s / 120s timeout），MVP 必须设 60 秒超时 + 兜底文案
• 流程图：把 grill-with-docs 嵌进"需求模板 → 任务拆分"流水线最前面，作为语言咬合前置关卡；用 idea 跑通完整模板验证上游产物的下游可用性

对 grill-with-docs 协议的评价（按产品/工程/团队三个维度打分）：

总评：grill-with-docs 是一个值得作为"需求模板 → 任务拆分"流水线的前置关卡的能力——不是 skill 本身的胜利，而是 DDD 通用语言传统 + ADR 决策记录传统被 LLM 重新打包成一段 6 行 prompt 后的工程红利。触发条件明确（idea 涉及 ≥3 个未命名实体 / 架构层切换 / 成功标准模糊 / 跨人协作），不要万能仪式化使用。

附录 A：Rigor Gate 14 项自查

结论：14/14 通过。

附录 B：来源清单

上游原始资料

• Matt Pocock, “The /grill-with-docs Skill”, https://www.aihero.dev/skills-grill-with-docs（2026-04 发布，2026-08-05 v1.2 更新）
• Matt Pocock, “The /domain-modeling Skill”, https://www.aihero.dev/skills-domain-modeling
• Matt Pocock, “9 Things People Get Wrong With /grill-me and /grill-with-docs”, https://www.aihero.dev/things-people-get-wrong-with-grill-me-and-grill-with-docs（2026-05-25）
• Matt Pocock, “My ‘Grill Me’ Skill Went Viral”, https://www.aihero.dev/my-grill-me-skill-has-gone-viral（2026-03-23）
• Matt Pocock, “Skills Changelog: Ubiquitous Language → /grill-with-docs”, https://www.aihero.dev/skills-changelog-ubiquitous-language-grill-with-docs（2026-04-30）
• Matt Pocock Skills 仓库, https://github.com/mattpocock/skills（v1.2.0，2026-08-05）

历史脉络

• Andrew Hunt, David Thomas, The Pragmatic Programmer, Addison-Wesley, 1999（rubber duck debugging 首次印刷于该书）
• Eric Evans, Domain-Driven Design: Tackling Complexity in the Heart of Software, Addison-Wesley, 2003
• Martin Fowler, “Ubiquitous Language”, 2006-10-31
• Michael Nygard, “Documenting Architecture Decisions”, Cognitect Blog, 2011-11-15
• Olaf Zimmermann et al., MADR (Markdown ADR) Template, 2017-（YADR 2026-03 衍生）

学术支撑

• Ahmad Bashir et al., “Requirements Ambiguity Detection and Explanation with LLMs: An Industrial Study”, ICSME 2025 Industry Track（10-shot 相对 0-shot 提升 20.2%）
• arxiv 2507.05981, “Multi-Agent Debate in Requirements Engineering”（F1 0.726 → 0.841，n=0 vs baseline；n=1 仅 +0.006）

我们自己的相关技能（落地侧）

• Matt Pocock 的 grill protocol（mattpocock/skills，v1.2.0，2026-08-05）
• Matt Pocock 的 domain-modeling（CONTEXT.md + ADR 落盘机制）
• 通用需求模板（功能清单/边界/验收/不要做 四件套）
• 通用任务拆分（把需求文档切成 2-5 分钟可执行单元）
• 通用派活执行（人工或 AI agent）
• 通用系统设计 Primer（容量/架构层，和 grill 互补不重叠）