/grill-with-docs 技能

它能做什么

grill-with-docs 会围绕一项计划或设计持续向你追问，直到你和智能体形成一致理解；在这个过程中，它还会把术语和那些艰难的决策写进仓库。它采用与 grill-me 相同的访谈方式——提出一轮问题，等待回答，再进入下一轮——只是这一次，访谈对象落在了具体代码库上。

它是有状态的。其他深度追问技能只把一次会话的结果留在你的脑中；这个技能则会在磁盘上留下文件。每当一个术语得到明确，它会立即写入 CONTEXT.md，而不是等到最后再批量整理。某项决策通过三道判断门槛后，则会以 ADR 的形式落盘。这就是它与其他技能的全部区别，也正是多数使用问题的根源：这些产物是实际仓库中的真实文件，所以它们可能在你以为会出现时并不存在，也可能在多人共同维护时逐渐偏离现状。

何时使用

你需要主动输入 /grill-with-docs 来调用它——智能体不会自行决定使用这个技能。

当你准备在仓库中开始一项改动，而计划仍然模糊、相关概念的叫法也尚未统一时，就适合使用它。它面向单次会话。究竟该选择哪一种深度追问技能，取决于你当前面对的情况：

wayfinder 与它的分界可以归结为所需会话数：单次会话内能够完成的规划使用 /grill-with-docs；需要跨多次会话推进的规划使用 /wayfinder。

使用前提

这个技能会直接写入仓库，因此你必须位于一个允许安全写入的工作目录中。已经明确的术语会进入仓库根目录的 CONTEXT.md 词汇表；如果根目录中的 CONTEXT-MAP.md 表明该仓库包含多个上下文，则写入对应上下文的 CONTEXT.md。决策会写入 docs/adr/。这两类文件都是按需创建的：在第一个术语或决策真正成形之前，什么都不会生成，因此无需提前搭建目录或文件骨架。

它还依赖另外两个技能，因为它自己的 SKILL.md 只有一行委托说明：追问审视 负责访谈，domain-modeling 负责写入文档。只安装 grill-with-docs，得到的是一个无法正常工作的技能。

落盘记录

一次会话会产生三类结果，但它们的去向和重要性并不相同。

真正容易让人误判的是第三行。CONTEXT.md 就是一份词汇表，而且会被刻意限制为词汇表——不写实现细节，不写规格说明，也不收录临时笔记。ADR 必须同时满足三项条件，因此大多数决定都达不到记录门槛，大多数会话也不会生成任何 ADR。一次会话即使只得到更清晰的词汇表、没有生成 ADR，也完全符合设计预期；但这也意味着，你们达成的大部分共识只存在于当时的上下文窗口里。不要清空它，而应把同一段对话直接交给 to-spec。

词汇表本身就是重点。这个技能真正构建的是领域语言——项目内部对事物采用的专有叫法。大家只需约定一次，你、智能体和同事以后就不必反复重新推导这些概念。需要说明的是，并非所有人都认同这能直接提升智能体表现。最有力的公开反对意见认为：对模型而言，一个术语和它的通俗解释通常能得到同样结果；词汇真正压缩的是共享这些术语的人类之间的沟通成本。即使接受这种解释，词汇表依然有价值，只是价值所在发生了变化。

它默认只有一位维护者

这些有状态输出默认由一个人统一维护。一个两人开发团队在同一仓库使用四个月后发现，抽样检查的已合并 PR 中约有 20% 出现状态漂移，其中 ADR 引用和 README 中的陈述最容易失真——这些由人精心维护的文档，漂移情况甚至比智能体记忆更严重。定期清理过期文档并不能解决问题；几天后，同一批内容又会过时。真正有效的做法是彻底删除重复保存的“影子状态”，并在 CI 中加入确定性的引用与链接检查器。

另一个相关问题是：在同一仓库中针对互不相关的改动反复运行此技能，容易积累主题混杂的文档，因为当前没有机制区分不同会话的输出。上述两个问题目前都尚未在技能本身中得到解决。

常见问题

我应该用它，还是用 /wayfinder？取决于工作范围。凡是能在一次会话内敲定的内容，都使用本技能；如果任务大到一次会话容纳不下，则使用 wayfinder，先把工作梳理成一张决策任务地图。Wayfinder 更慢、信息密度也更高，最常见的错误是在边界已经清晰的功能上仍然使用它。它并不取代本技能——对于地图中适合单次深度访谈的部分，它仍可下钻到一次 grilling 会话。

它运行了，但没有生成 CONTEXT.md，也没有出现 ADR。目前已知有两个原因。普通情况是没有任何内容达到写入门槛：ADR 必须同时通过三项判断，而一次没有产生新术语的改动会话，确实可能无内容可写。真正的缺陷则出现在技能运行于另一层编排之中时——例如规格驱动开发包装器、多智能体框架，或某条把它作为其他流水线步骤调用的规则。已有报告称，此时访谈仍会正常进行，但文件写入部分可能悄无声息地失效。这个问题已经登记，尚未修复。如果你处于这类环境，先检查工作目录中的实际文件，再相信会话给出的完成结果。

它一次性问完了所有问题，没有给出建议，也从未提到 CONTEXT.md。这说明技能没有成功加载两个依赖。由于 SKILL.md 只包含一行委托说明，如果智能体没有加载 追问审视 和 domain-modeling，就只能猜测“深度追问”该怎么做，最终抛出一堆没有层次的问题。部分加载更容易令人困惑：grilling 成功加载，domain-modeling 却没有，于是访谈质量不错，但不会留下任何落盘记录。这个问题与所用模型及推理强度有关，也是该技能最常见的故障报告。如果怀疑发生了这种情况，直接询问智能体实际加载了哪些技能。

其他决定都去哪了？它们只存在于对话中。这是目前针对该技能最实质性的公开质疑：词汇表不是规格说明，大多数回答达不到写入 ADR 的门槛，也没有一份台账把每个已解决的问题一路关联到规格、任务和测试。精确答案——例如顺序保证、明确禁止的行为、数字默认值——在下游很容易被弱化成含糊的文字，最终产物看似完整，却漏掉了你真正作出的决定。当前可行的缓解办法是保留会话并直接交给 to-spec，随后对照自己的原始回答重新审阅规格，不要想当然地认为所有决定都已被准确捕捉。

我能把它用于一个完全没有文档的现有仓库吗？可以。对于没有 ADR、没有领域语言、也没有设计原则的代码库，这正是合适的技能。调用它并说明“帮我为这个仓库补齐文档”即可。社区中的常见做法是搭配 improve-codebase-architecture，用来新建或修复 CONTEXT.md。你仍需要主动引导它：它会阅读代码，并根据发现向你提问；而你负责判断代码库中已经出现的哪些词才是项目真正认可的叫法。

会话结束后应该做什么？这个技能的收尾提示往往比较开放，这是一个已知的使用瑕疵。在主流程中，下一步是在同一段对话里运行 to-spec。如果改动足够小，可以立即开始构建，则直接进入 implement。

为什么叫这个名字？没有人真正满意这个名称。目前有人提议把它改为 grill-domain-model，因为这个名字更诚实地描述了它的行为，但该提议尚无进展。如果将来真的完成重命名，文档页面会一并迁移，URL 也会随之改变。

出现这些迹象，说明它工作正常

• CONTEXT.md 会在会话过程中随着术语逐一明确而持续更新，而不是等到最后一次性生成。
• 词汇表保持为纯粹的术语说明——只收录项目自己的用词和严谨定义，不包含实现细节，也没有类似规格说明的长篇文字。
• 代码库本身能够回答的问题，会通过阅读代码得到答案，而不会再抛给你。
• 你只会得到少量 ADR，甚至一个也没有；真正被记录下来的，都是那些如果以后还要重新争论会让你十分恼火的决策。
• 当你使用的词与现有词汇表定义不一致时，它会主动指出并要求你澄清。

它在流程中的位置

grill-with-docs 位于主构建链的起点：

grill-with-docs → to-spec → to-tickets → implement → code-review

它发生在任何内容被写成规格说明之前：先形成共同理解并统一术语，然后由 to-spec 直接综合成规格，无需再次访谈。与它最接近的是 grill-me——同样进行访谈，但不依赖仓库，也不写文件——以及 domain-modeling——负责它所采用的词汇表与 ADR 记录规范；两者都建立在 追问审视 这一基础能力上。更上游的 wayfinder 用来规划一次会话容纳不下的大型任务，并可把地图中合适的部分交回本技能继续深入。当你不确定该使用哪个技能或流程时，ask-matt 会帮你选择路线。