Grill-with-docs 字面意思是“伴随文档彻底追问”。AI 不仅会执着地追问计划中的漏洞，还会将对话中确定的术语记录在 CONTEXT.md 中，将难以回溯的设计决策记录在 ADR（Architecture Decision Record，架构决策记录）中。
这种差异之所以重要，原因很简单。当漫长的设计对话结束后，人们会记住结论，但下一个 AI 会话却不知道之前的对话。代码中虽然留下了“做了什么”，但“为什么选择这个术语”、“为什么放弃其他选项”却不甚明了。这样一来，在下一个会话中可能会重复相同的问题，或者不小心推翻了有意选择的结构。
Matt Pocock 的 grill-with-docs 是一种旨在解决这种断裂的小型编排技能。本文将结合实际的 SKILL.md，探讨与它一同调用的两个技能，以及它们与之前介绍的 Grill-me 有何不同，哪些文档何时创建，以及在实际工作中应信任和使用到何种程度。
令人惊讶的是，主体只有7行
Skills.sh 上公开的 grill-with-docs 的 SKILL.md，包括说明在内只有7行。核心指令只有一句话：
分别调用 grilling 和 domain-modeling 技能。
也就是说，这个技能不会冗长地重新定义提问方法和文档编写方法。它是一个用户调用型的编排器，一次性激活两个已分离的能力。
- grilling：将计划转化为决策树，并按轮次提出当前可回答的问题。
- domain-modeling：将对话中的术语与项目的共享语言进行比较，并将确定的术语和重要决策反映到文档中。
原文中还包含 disable-model-invocation: true。此设置旨在让用户明确调用此技能，而不是模型根据情况自动选择。而内部的 grilling 和 domain-modeling 则是多个上层工作流可以重用的子规则。
这种结构也给技能设计本身带来了有趣的信息。如果将所有行为复制到一个巨大的 SKILL.md 中，规则很容易分化。通过组合小型技能，当提问方式改进时，只需修改 grilling；当术语管理方式改变时，只需修改 domain-modeling。
图：7行编排器结合了提问和文档化的两个规则。根据官方仓库的 grill-with-docs 重构。
第一个引擎：将计划转化为决策树
grilling 将计划视为决策树，而非扁平的问题列表。它连接只有在上位决策确定后才有意义的下位问题，并仅将已解决前置条件的问题作为当前轮次的 Frontier 提出。
例如，假设有一个“创建订单取消功能”的计划。如果直接从 API 路径或数据库字段开始确定，可能会跳过重要的前提。首先，需要确认以下上位决策：
- 只能取消整个订单，还是可以取消部分商品？
- 支付批准前的取消和退款后的取消是否视为同一状态？
- 发货后是取消还是退货？
- 客服强制取消和客户普通取消的权限和审计记录有何不同？
用户给出答案后，下一个 Frontier 就会打开。届时才能具体化状态转换、事件名称、API 边界和测试场景。仍依赖于未解决的上位问题的下位问题将推迟到下一轮。
在此过程中，事实确认和决策也分离。现有代码是否支持部分取消，当前事件名称是什么，这些是代理应在仓库中调查的事实。是否允许部分取消作为产品策略，这是用户必须做出的决定。技能不会让用户代为查找文件，AI 也不会悄悄地代替组织做出价值判断。
第二个引擎：将对话与项目的共享语言进行比较
domain-modeling 不是一个生成大量问题的工具，而是一个使问题措辞更精确的规则。如果用户使用“账户”、“取消”、“客户”等范围广泛或有多重含义的词语，它会与现有的 CONTEXT.md 进行比较。
例如，如果项目词汇表中将 Cancellation 定义为“在支付批准前撤回订单”，但在对话中将发货后的退款也称为取消，它会立即揭示冲突。它会这样提问：“现有词汇表中的 Cancellation 与您刚才描述的操作不同，后者是指 Return 还是 Refund 概念？”
这里，CONTEXT.md 不是实现规范。原文强调不要放入实现细节，而只将其用作项目领域的词汇表。好的条目应该简短。
## Language
**Order**:
고객이 구매 의사를 확정해 생성한 거래 단위.
_Avoid_: Purchase, transaction
**Cancellation**:
결제 승인 전에 Order를 철회하는 행위.
_Avoid_: Refund, return如果多个词语指向同一个概念，则选择一个标准术语，并将应避免的同义词记录在 Avoid 中。它只包含理解该项目业务所需的词语，而非一般的编程术语。
单个领域仓库通常只需一个根目录下的 CONTEXT.md。如果存在订单、支付、配送等边界清晰的多个上下文，则使用根目录下的 CONTEXT-MAP.md 指向每个上下文的文档位置和关系。文件不会预先创建为空壳，而是在实际确定并需要记录内容时才生成。
并非所有决策都记录为 ADR
ADR 是 Architecture Decision Record 的缩写，是一种记录设计决策的文档，以便日后查看代码的人可能会问“为什么这样做？”Grill-with-docs 不会将对话中得出的所有结论都堆积为 ADR。它只在满足以下三个条件时才提出建议：
| 条件 | 要确认的问题 | 无需记录的示例 |
| — | — | — |
| 难以回溯 | 后期更改成本高吗？ | 选择易于替换的小型工具 |
| 无背景时令人惊讶 | 未来的开发者会好奇原因吗？ | 生态系统明显的默认设置 |
| 实际权衡 | 是否合理地选择了一个替代方案？ | 实际上只有一个选项的情况 |
例如，“订单和支付通过领域事件而非同步 HTTP 连接”的决策涉及故障隔离和一致性延迟的权衡，并且更改成本很高。未来的开发者可能希望切换到直接调用，因此这是一个 ADR 候选。
反之，如果将每个变量名、小型库、易于回溯的格式设置都制作成 ADR，重要的决策就会被埋没在文档堆中。原始模板出奇地简短，认为标题和解释“决定了什么以及为什么”的1-3句话就足够了。考虑过的替代方案、结果和状态仅在具有实际价值时才选择性添加。
图：术语记录在 CONTEXT.md 中，只有难以回溯、无背景时令人惊讶且存在实际权衡的决策才记录为 ADR。根据domain-modeling 原文重构。
与 Grill-me 有何不同
这两个技能并非竞争关系。grill-with-docs 内部调用 grilling，因此提问方式的根源是相同的。区别在于对话结束后留下了什么。
| 分类 | Grill-me | Grill-with-docs |
| — | — | — |
| 主要对象 | 一般计划、想法、决策 | 实际代码库的设计和领域模型 |
| 提问方式 | 决策树和 Frontier | 相同的 grilling 方式 |
| 代码对比 | 必要的事实调查 | 积极检查当前代码与术语定义是否冲突 |
| 共享语言 | 对话中达成一致 | 立即将确定的术语反映到 CONTEXT.md 中 |
| 决策记录 | 无单独的文档化规则 | 仅将满足条件的决策作为 ADR 提出 |
| 适用场景 | 产品想法、采购、运营计划等 | 长期维护代码库的设计变更 |
如果只是验证一次性计划或尚无仓库的想法，Grill-me 可能就足够了。反之，如果在一个由多人长期维护的代码库中，术语和设计原因需要保留到下一个会话，那么 Grill-with-docs 的文档化规则就具有意义。
一个会话实际如何进行
以订单取消功能为例，整个流程可以总结如下：
- 代理读取仓库中现有的代码、CONTEXT.md、CONTEXT-MAP.md 和 ADR。
- 将计划转化为决策树，并将已解决前置条件的问题归为一轮。
- 如果“取消”等模糊术语与现有词汇表冲突，立即询问精确的边界。
- 通过部分取消、退款、退货等具体异常场景来压迫模型的边界。
- 一旦术语确定，立即更新相应的 CONTEXT.md。
- 仅建议将难以回溯、无背景时令人惊讶且实际比较过替代方案的决策记录为 ADR。
- 即使问题树的 Frontier 为空并达成共享理解，在用户确认之前也不会开始实现。
重要的一点是，文档并非像会议记录一样在最后一次性创建。术语一经确定，立即反映到词汇表中；ADR 条件一经满足，立即判断是否记录。这样才能确保后续轮次的问题也使用刚刚确定的语言。
安装与调用
Skills.sh 页面提供了以下安装命令：
npx skills add https://github.com/mattpocock/skills --skill grill-with-docs仓库的 README 也指导了 Codex 和其他代理的以下形式：
npx skills@latest add mattpocock/skills第二种方式是选择要安装的技能和目标代理的流程。仓库指导首次运行 setup-matt-pocock-skills 一次，以设置文档位置和问题跟踪器等项目配置。
调用时，最好同时提供计划和文档范围。
이 주문 취소 설계를 grill-with-docs로 검토해줘.
현재 코드와 CONTEXT.md를 먼저 확인하고,
용어가 확정되면 glossary에 반영해줘.
ADR은 세 가지 조건을 모두 만족할 때만 제안하고,
합의 전에는 구현하지 마.安装命令是将外部仓库的代码引入项目的操作。在执行之前，最好检查当前的 SKILL.md、一同调用的子技能及其许可证，并在组织仓库中将更改视为代码审查对象，这样更安全。尽管此仓库以 MIT 许可证公开，但许可证本身并不意味着安全验证。
优点与局限
最大的优点是设计对话可以作为下一个会话的输入保留下来。标准化术语会增加在变量、函数、文件和说明中使用相同语言的可能性。ADR 减少了未来开发者将有意选择的结构误解为“不必要的复杂性”并将其推翻的可能性。
此外，由于它是一个小型组合技能，重用边界清晰。提问规则和文档规则可以单独改进，其他工作流也可以调用相同的 grilling 或 domain-modeling。
然而，它并不能自动保证良好的领域模型。如果用户确认了错误的假设，错误的概念可能会保留在简短一致的词汇表中。如果现有代码已经与业务规则不符，仅凭“代码与对话不同”这一事实无法决定哪一方是正确的。此时，需要进一步咨询领域专家、运营数据和实际政策。
更新文档的权限也需要注意。在仅仅探索想法的阶段，如果立即更改共享仓库中的 CONTEXT.md，尚未达成一致的术语可能会固化为官方语言。在团队环境中，最好通过 diff 审查更改，并明确 ADR 提案和实际反映的审批边界。
最后，这种方法并非国际标准或所有代理的内置功能。grill-with-docs、CONTEXT.md 格式和三个 ADR 门槛是 Matt Pocock 仓库选择的项目规则。虽然这是一个有用的模式，但如果组织有现有的 ADR 模板、领域文档位置和审批流程，则需要根据其体系进行调整。
总结
Grill-with-docs 的核心并非创建大量文档。它是通过提问来缩小模糊的设计范围，并仅将有价值的知识以最小的文档形式保留下来。
需要记住的结构分为三个阶段：grilling 寻找决策树中的空白，domain-modeling 揭示代码与术语的冲突，确定的结果则进入词汇表或通过严格门槛的 ADR。而且，即使所有问题都已回答完毕，在用户确认共享理解之前，也不会开始实现。
如果说之前的 Grill-me 是“如何彻底追问思维中的空白”，那么 Grill-with-docs 则更进一步。它将今天的共识转化为项目可读的记忆，以避免下一个会话重复相同的问题。
发表回复