安装此技能
npx skills@latest add mattpocock/skills --skill=grill-with-docs 然后在你的编码 agent 里输入 /grill-with-docs 。
本页目录
它做什么
grill-with-docs 会就一个计划或设计反复访谈你，直到你和 agent 对它达成同一份理解，并在这个过程中把词汇和那些艰难的决定写进你的仓库。它和 grill-me 跑的是同一场访谈（一轮问题，然后等待，再下一轮），只是对准了一个代码库。
它是**有状态（stateful）**的。其他每一个质询（grilling）技能都把会话（session）留在你脑子里；这一个会在磁盘上留下文件。当一个术语定下来时，技能立刻把它写进 GLOSSARY.md，而不是到最后批量写入。当一个决定通过三道门槛时，技能把它写成一份 ADR。全部区别就在这里，而人们使用这个技能时遇到的大部分麻烦也来自这里。这些产物是真实仓库里的真实文件，所以它们可能在你期待的时候并不存在，也可能在不止一个人写它们的时候发生漂移。
什么时候用它
你通过输入 /grill-with-docs 来调用它；agent 不会主动去拿它。
在一个仓库里、一次改动的开头用它，此时计划还很模糊，关于这件事的词也还没定下来。它是单场会话的工具。你想要哪个质询技能，取决于你面前是什么：
| 你手上有什么 | 该用哪个 |
|---|---|
| 你根本不在一个工作目录里工作 | grill-me |
| 一个仓库，以及一次能在一场会话里定下来的改动 | grill-with-docs |
| 一件大到一场会话装不下的工作（一次全新构建、一个大功能） | wayfinder |
| 一个完全没有领域文档、也没有在考虑某个具体功能的仓库 | grill-with-docs，对准仓库而不是某次改动 |
| 一个卡在别人脑子里的知识上的决定 | to-questionnaire |
与 wayfinder 的分界归结为会话数量：单场会话的规划用 /grill-with-docs，跨多场会话的规划用 /wayfinder。
前提条件
这个技能会往你的仓库里写东西，所以你得处在一个可以安全写入的地方。定下来的术语会写进根目录的 GLOSSARY.md 词汇表；如果根目录的 GLOSSARY-MAP.md 把仓库标记为多上下文（multi-context），则写进对应上下文的 GLOSSARY.md。决定写进 docs/adr/。技能只在需要时才创建这两者。在第一个术语或决定定下来之前，什么都不存在，所以你不需要提前做任何配置。
它还需要另外两个技能在场，因为它自己的 SKILL.md 只有一行，把工作委派给它们。grilling 提供访谈，domain-modeling 提供写作。只安装 grill-with-docs 的话，你得到的会是一个不能工作的技能。
纸面记录
一场会话会产出三样东西，而它们并不等价。
| 定下来的是什么 | 它落在哪里 |
|---|---|
| 一个术语：项目对某样东西自己的叫法 | GLOSSARY.md，就在原地，在它定下来的那一刻 |
| 一个难以逆反、离开上下文会令人意外、并且是真正取舍的决定 | docs/adr/ 下的一份 ADR |
| 你决定的其他一切 | 这场对话，别处没有 |
第三行才是让人栽跟头的那一行。GLOSSARY.md 只是一份词汇表。它不装实现细节，不装规范文档（spec），也不装草稿笔记。一份 ADR 需要同时满足全部三个条件，所以大多数决定不够格，大多数会话一份也产不出来。一场会话如果只产出了一份更锋利的词汇表、零份 ADR，那是按设计在工作，但这意味着你们商定的大部分内容只存在于你们商定它时的那个上下文窗口（context window）里。把同一场对话交给 to-spec，而不是把它清除（clearing）掉。
词汇表是主要产出。这个技能在建立领域语言（domain language）：项目自己的词，一次商定，好让你、agent 和你的同事不必再重新琢磨一遍。并非所有人都同意这能提升 agent 的表现。最强的反对意见是：一个术语和它的平白英文展开式从模型（model）那里得到的结果相同，而这套词汇主要缩短的是共享它的那些人之间的沟通。按这个看法，词汇表仍然有价值，但价值归于人。
常见问题
我该用它还是 /wayfinder？
范围决定一切。任何能在一场会话里定下来的事都用它；当工作大到一场会话装不下时，用 wayfinder，它会先把这件工作画成一张决策工单（ticket）组成的地图。wayfinder 更慢、更密，在一个范围划得很清楚的功能上动用它，是常见的错误。它不取代这个技能，而且它可以为地图上那些适合质询的部分发起一场质询会话。
它跑了，但没有出现 GLOSSARY.md，也没有 ADR。
有两个已知原因。第一个是没有任何东西够格。ADR 需要通过全部三道门槛，而一场关于某次改动、没有引入新词汇的会话，没有什么可写的。第二个是一个真实的 bug。当技能在另一个编排层里运行（一个规范驱动开发的包装层、一个多代理框架、一条把它当作别人流水线中某一步来调用的规则），用户报告说：写文件的那一半悄无声息地没有发生，而访谈照常进行。这个 bug 已经提交，尚未修复。如果你处在那样的配置里，在信任这场会话的输出之前，先检查工作目录。
它一次性问完了所有问题，没有任何推荐，也从未提到 GLOSSARY.md。
那是技能没能加载它的两个依赖。因为 SKILL.md 是一行式的委派，没有加载到 grilling 和 domain-modeling 的 agent 会去猜质询是什么意思，于是你会一次性拿到所有问题，毫无结构。部分加载更让人困惑。grilling 加载了，domain-modeling 没加载，你得到一场很好的访谈，却没有纸面记录（paper trail）。这种情况多久发生一次，取决于模型和投入级别（effort），这是关于这个技能报告得最多的问题。如果你怀疑是这种情况，直接问 agent 它加载了哪些技能。
我其他的那些决定都去哪了？ 只在对话里。这是关于这个技能最严重的未决抱怨。词汇表不是规范文档，大多数答案挣不到一份 ADR，也没有任何记录把每个定下来的答案链接到一份规范文档、一个工单和一项测试。后续步骤会把精确的答案（顺序保证、否定性需求、数值默认值）软化成更弱的散文，结果看起来完整，却漏掉了你真正决定的东西。目前，保留这场会话，直接把它喂给 to-spec。然后对照你自己的答案重读那份规范文档，而不是假定它已经把你的答案都收进去了。
我能把它对准一个完全没有文档的现有仓库吗？
能。对于一个没有 ADR、没有领域语言、没有设计原则的代码库，这就是正确的技能：调用它，然后说「帮我把我的仓库文档化」。用户常常把它和 improve-codebase-architecture 搭配，用来构建或修复 GLOSSARY.md。要做好引导它的准备。它会读代码，并就它发现的东西问你，由你来决定代码库中已有的哪些词才是对的。
会话结束时我该做什么？ 这个技能的结束语常常是开放式的，这是一个已知问题。在主流程里，答案是 to-spec，就在同一场对话里。如果这次改动小到可以立刻实现，那就直接去 implement。
为什么它叫这个名字？
没有人对这个名字满意。有一个仍未关闭的建议，提议把它改名为 grill-domain-model，那个名字更准确地描述了它的行为。这件事没有任何进展。如果哪天改名落地了，文档页会跟着搬走，URL 也会变。
它生效的标志
GLOSSARY.md是在会话进行中逐个术语变化的，而不是到最后一次性冒出来。- 词汇表读起来是纯粹的词汇（你项目自己的词，配上紧凑的定义），不包含任何实现细节或像规范文档一样的散文。
- 代码库能回答的问题，靠读代码库来回答，而不是来问你。
- 你得到的 ADR 很少，甚至没有；而你得到的那些，都是那种你一想到还得再争论一遍就烦的决定。
- 它挑战你用过的一个词，因为你现有的词汇表对它的定义不一样。
它在体系中的位置
grill-with-docs 是主构建链的起点：
grill-with-docs → to-spec → to-tickets → implement → code-review → retro
它出现在任何东西被写成规范文档之前。它产出的共同理解和已经定下来的词汇，随后由 to-spec 不再访谈你就直接综合成文。它最近的邻居是 grill-me，同一场访谈，但没有仓库也没有文件；以及 domain-modeling，它所驱动的词汇表与 ADR 纪律；两者都用 grilling 这个原语来做访谈。在它的上游，wayfinder 为一场会话装不下的工作绘制地图，并且可以把地图的某些部分交回给它。当你不确定哪个技能或哪条流程合适时，ask-matt 会为你路由。