grill-with-docs：构建前先达成一致

作用

grill-with-docs 会围绕一项计划或设计采访你，直到你和 智能体 对它形成一致理解；在此过程中，它还会把术语和艰难决策写入你的 repo。这与 grill-me 执行的是同一种采访：提出一轮问题，等待回答，再进入下一轮；只不过这次采访指向一个代码库。

它是 有状态的。其他所有 追问审视 Skill 都只把 会话 留在你的脑海里，而这个 Skill 会在磁盘上留下文件。一个术语一旦确定，就会立即写入 CONTEXT.md ，而不是等到最后再批量写入。一项决策通过三道门槛后，就会作为 ADR 落盘。这就是它全部的不同之处，也是人们使用这个 Skill 时大多数麻烦的来源：这些产物是真实 repo 中的真实文件，所以它们可能在你以为应该存在时并不存在，也可能在多人共同编写时发生漂移。

何时使用它

你需要输入 /grill-with-docs 来调用它——Agent 不会自行启用它。

在 repo 中刚开始一项变更、计划仍然模糊、相关事物的称谓尚未确定时使用它。它适合单次会话。具体该选哪个追问 Skill，取决于你眼前的情况：

是否使用 wayfinder，归根结底取决于所需会话数： /grill-with-docs 用于单次会话规划， /wayfinder 用于多次会话规划。

前置条件

这个 Skill 会写入你的 repo，因此你必须处在可以安全写入的位置。已确定的术语会进入根目录中的 CONTEXT.md 术语表；如果根目录中的 CONTEXT.md表明该 repo 包含多个上下文，则写入相关上下文的 CONTEXT-MAP.md 。决策写入 docs/adr/。两者都会按需创建：第一个术语或决策真正成形前，不会出现任何文件，因此无需预先搭建目录或模板。

它还要求另外两个 Skills 已经存在，因为它自己的 SKILL.md 只有一行内容，用来把工作委派给它们： 追问审视 负责采访， domain-modeling 负责写入文档。只安装 grill-with-docs ，得到的会是一个无法工作的 Skill。

留下的文档记录

一次会话会产生三类结果，但它们的待遇并不相同。

第三行最容易让人措手不及。 CONTEXT.md 是术语表，并且被有意严格限制为术语表——不包含实现细节、不包含 规格，也不包含临时笔记。ADR 必须同时满足三个条件，因此大多数决策都不合格，大多数会话也不会产出 ADR。如果一次会话让术语表更准确，却没有产生任何 ADR，它仍然是在按设计工作；但这意味着你们达成的大部分共识只存在于当时的 上下文窗口 中。把同一段会话直接交给 to-spec ，不要 清空上下文 它。

术语表才是重点。这个 Skill 真正在构建的是领域语言——对项目自己的词汇达成一次共识，让你、Agent 和同事不必反复付出重新推导它们的成本。需要指出的是，并非所有人都认同这能提升 Agent 表现：公开讨论中最尖锐的反对意见认为，使用术语或使用它对应的通俗解释，交给 模型都会得到相同结果；词汇真正压缩的是共享它的人类之间的沟通。即便按这种理解，术语表仍然有价值，只是价值所在发生了变化。

它假设只有一位维护者

这些 有状态 有状态产物假设由一个人负责维护。一个由两名开发者组成的团队在同一 repo 中运行四个月后报告称，抽样检查的已合并 PR 中约有 20% 出现状态漂移，其中 ADR 引用和 README 中的说明是漂移最严重的部分——经过刻意维护、由人类整理的文档，漂移程度反而超过了 Agent 记忆。清理陈旧文档并不能长期奏效，几天后同一批内容又会过时。真正有效的做法是彻底删除影子状态，并在 CI 中加入确定性的引用与链接 Linter。

另一个相关问题是：在同一个 repo 中针对互不相关的变更反复运行该 Skill，往往会积累主题混杂的文档，因为没有任何机制把不同会话的产物分隔开来。目前这两个问题都尚未在 Skill 中解决。

常见问题

我应该使用它，还是使用 /wayfinder? 由工作范围决定。能在单次会话中敲定的事情使用本 Skill；如果工作规模大到一次会话容纳不下，则使用 wayfinder ；它会先把工作绘制成一张由决策 工单 组成的地图。Wayfinder 更慢、信息密度也更高；对范围已经很明确的功能使用它，是一种常见错误。它不会取代本 Skill——地图中适合单次会话的部分，仍然可以下沉到一次追问会话中处理。

它运行了，但没有出现 CONTEXT.md ，也没有出现 ADR。 已知有两个原因。普通原因是没有任何内容符合条件：ADR 必须通过全部三道门槛，而一场不涉及新词汇的变更会话，确实可能没有内容可写。另一个是真正的 Bug：有报告称，当该 Skill 运行在另一层编排系统内部时——例如规格驱动开发包装器、多 Agent 框架，或在其他流水线中把它作为某一步调用的规则——采访仍会继续，但写文件的部分会悄无声息地失效。这个问题已经登记，尚未修复。如果你使用的是这类配置，请先检查工作目录，再相信会话产物。

它一次问完了所有问题，既没有给出建议，也从未提到 CONTEXT.md. 这说明该 Skill 未能加载两个依赖项。由于 SKILL.md 只是单行委派，如果 Agent 没有加载 追问审视 和 domain-modeling ，就只能猜测“追问”意味着什么，结果便是一股脑抛出一堆毫无区分的问题。只加载一部分依赖的情况更加令人困惑—— grilling 加载成功， domain-modeling 没有加载，于是你会得到一场不错的采访，却没有任何文档记录。这个问题与模型和 推理投入 级别相关，也是这个 Skill 被报告最多的问题。如果怀疑遇到了它，直接询问 Agent 加载了哪些 Skills。

我的其他决策都去了哪里？ 它们只存在于会话中。这是目前针对该 Skill 最实质性的未解决批评：术语表不是规格，大多数回答不足以形成 ADR，也没有台账把每个已经确定的答案一路关联到规格、工单和测试。精确答案——例如顺序保证、否定性需求、数字默认值——在下游会被弱化为不够严格的文字，结果看似完整，却漏掉了你真正作出的决定。目前可行的缓解方式是保留会话，并把它直接交给 to-spec；然后对照自己的回答重新阅读规格，不要想当然地认为规格已经全部捕获。

我能把它用于一个完全没有文档的现有 repo 吗？ 可以。对于没有 ADR、没有领域语言、也没有设计原则的代码库，这正是合适的 Skill——调用它并说“帮我记录这个 repo”。社区中的常见做法是将它与 improve-codebase-architecture 搭配，用于构建或修复 CONTEXT.md。你需要做好引导它的准备：它会阅读代码，并针对发现的内容向你提问；而你负责判断代码库中已经存在的哪些词才是正确用语。

会话结束后我应该做什么？ 这个 Skill 的结束语往往比较开放，这是一个已知的不够顺滑之处。在主流程中，答案是继续使用 to-spec，并且要在同一次会话中继续。如果变更足够小，可以立即构建，则直接进入 implement 。

它为什么叫这个名字？ 没有人满意这个名字。目前有一项公开建议，希望将它重命名为 grill-domain-model，这个名称能更如实地描述其行为。但这项建议尚无进展。如果未来真的完成重命名，文档页面也会随之迁移，URL 也会改变。

出现这些迹象，说明它运行正常

• CONTEXT.md 会 在 会话过程中逐个术语发生变化，而不是到最后一次性出现全部内容。
• 术语表读起来就是纯粹的词汇表——项目自己的词配上严谨定义——不包含实现细节，也不包含类似规格的文字。
• 代码库能够回答的问题，会通过阅读代码库得到答案，而不会再拿来询问你。
• 你只会得到少量 ADR，甚至一个也没有；而真正形成 ADR 的，都是那些若要重新争论会让你感到恼火的决策。
• 当你使用的某个词与现有术语表中的定义不同时，它会对这个用词提出质疑。

它在流程中的位置

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

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

它发生在任何内容被写成规格之前——它先产出共同理解和确定的词汇，随后由 to-spec 进行整合，无需再次采访你。与它最接近的是 grill-me——采用相同的采访方式，但不涉及 repo，也不生成文件——以及 domain-modeling——也就是它所驱动的术语表与 ADR 纪律；两者都建立在 追问审视 这一基础能力之上。在它的上游， wayfinder 会为单次会话无法容纳的大型工作绘制地图，并能把地图中的部分内容重新下放给它处理。如果不确定应该使用哪个 Skill 或流程， ask-matt 会为你选择路线。