grill-with-docs：拷问你直到达成共识，边拷边写文档
前言
" Matt Pocock（就是写 TS 教程那位）搞了一个 Agent Skills 库，里面有个 skill 名字起得挺凶：grill-with-docs——grill 是"拷问"的意思。
它干的事：你的计划还很模糊、措辞还没定下来的时候，Agent 开始轮番面试你，问一轮、等你答、再问下一轮，直到你和它对这件事的理解完全一致。而且它不是聊完就完——每敲定一个术语，当场写进仓库；每个硬决策，落成 ADR。
有意思的是，这篇文档没有吹这个 skill，反而花了大量篇幅讲它的坑：依赖装不全会静默失败、在编排层里文件写入会消失、大多数决策根本不配写 ADR。这种"官方吐槽"反而让它可信。
- 文档：https://github.com/mattpocock/skills/blob/main/docs/engineering/grill-with-docs.md
- 作者生态：AI Hero（aihero.dev）
一、项目身份
- 是什么：mattpocock/skills 仓库 engineering 分支下的一个 skill 文档，主构建链的头部
- 核心机制：状态化拷问——区别于其他所有 grilling 类 skill 的关键："别的拷问 skill 把会话留在你脑子里，这个把文件留在磁盘上"
- 两个前提：得在可以安全写入的仓库里；得同时装上 grilling（供面试）和 domain-modeling（供写文档）两个依赖——只装它一个是跑不起来的
- 触发方式：手动
/grill-with-docs，Agent 不会自己想起来用它
定位一句话：单次会话内，把模糊计划拷问成共识，并把共识沉淀为仓库文件。
二、主执行链路
两条细节值得注意：代码库能回答的问题它自己去读代码，不浪费你的时间；挑战你的用词也是它在正常工作——如果你说的词和现有术语表定义不一致，它会提出来。
三、核心模块：三样产出，地位不平等
一次会话产出三种东西，但大多数人不理解它们的权重差异：
术语表是主角。这个 skill 真正在构建的是领域语言：项目自己的词，约定一次，你、Agent、同事都不用反复重新推导。
文档还很诚实地记了一条反对意见：有人认为模型对"术语"和"术语的英文展开"给出同样好的结果，词汇真正压缩的是人之间的沟通，不是人机之间。这个批评即使成立，术语表也没贬值——只是价值挪了位置。
ADR 是稀缺品。三道门（难逆转、缺上下文会费解、真实权衡）全过才落盘，所以一次会话产出零 ADR 是设计内的正常状态——只换来一份更锐利的术语表，不叫失败。
其余决策会蒸发。这是该 skill 最实质的公开抱怨：没有账本把每个回答串到 spec、工单和测试。精确的答案（顺序保证、否定性需求、数值默认值）会在下游被软化成含糊的散文。文档给的缓解方案：会话别清掉，直接喂给 to-spec，然后对照你自己的原答案重读 spec——别假设它记全了。
四、数据与状态流
"状态化"是这个 skill 的灵魂，值得单独画一张：
两个流向要注意：术语表会反向作用于面试（用词对不上已定义的术语，它会质问你）；多人多会话同时写这些文件时，漂移是文档明说的麻烦来源。
五、跨端边界：整个 grilling 家族
选哪个 skill，取决于你面前有什么：
| 你手上有什么 | 用哪个 |
|---|---|
| 根本不在工作目录里 | grill-me（无仓库无文件的同一套面试） |
| 有仓库，一个会话能敲定的变更 | grill-with-docs |
| 大到装不进一个会话（绿地项目、大特性） | wayfinder（先画成决策工单地图） |
| 仓库没有任何领域文档，也没特定目标 | grill-with-docs，对准仓库本身："帮我给我的仓库写文档" |
| 决策卡在别人脑子里的知识 | to-questionnaire |
分界线就是会话数：单会话用 grill-with-docs，多会话用 wayfinder。在范围明确的特性上误用 wayfinder 是社区常见错误。
它在主构建链的位置：grill-with-docs → to-spec → to-tickets → implement → code-review——站在一切被写成 spec 之前，负责产出共享理解和定案词汇，让 to-spec 不用再面试你一遍。
六、配置边界
这个 skill 的配置面极小，但有两个硬约束：
- 依赖是强制的。它自己的 SKILL.md 只有一行——委托给 grilling 和 domain-modeling。文档原文警告："只装 grill-with-docs，得到的是一个不能工作的 skill"
- 写入位置约定：术语进根目录
CONTEXT.md（若根目录CONTEXT-MAP.md标记为多上下文仓库，则进各上下文自己的 CONTEXT.md）；决策进docs/adr/。全部懒创建——第一个术语敲定之前，什么文件都不存在，无需预先搭脚手架
"工作正常的判据"文档也给了清单，最直观的三条：CONTEXT.md 在会话过程中逐条变化而不是结尾一次性出现；术语表保持纯词汇；它主动用代码库回答问题而不是问你。
七、扩展点
- 对准空仓库："帮我给我的仓库写文档"是官方支持用法，社区常搭配 improve-codecodebase-architecture skill 修复 CONTEXT.md——但你要引导它：读代码后由你裁决代码库里哪些词是对的
- 嵌入大流程：作为主构建链头部，上游接 wayfinder 的地图切片，下游接 to-spec；拿不准选哪个 skill，ask-matt 帮你路由
- 改名动议：社区建议改成 grill-domain-model（更诚实），尚未落地——名字本身是个开放扩展点
八、风险点（文档自己承认的那些）
- 依赖静默加载失败——被报告最多的问题。SKILL.md 只有一行委托，Agent 没捡起两个依赖时：全没加载 → 无差别问题轰炸；只加载了 grilling → 面试很好但没有纸面产出。这与模型和能力等级相关。怀疑时直接问 Agent："你加载了哪些 skill？"
- 编排层内文件写入消失。在 SDD 包装器、多 Agent 框架里作为流水线步骤运行时，面试照跑但文件写入被报静默失败——已立案未修复。文档建议：这种环境下先查工作目录再信任会话输出
- 决策蒸发。大多数决策不配 ADR，术语表也不是 spec，精确答案在下游被软化——没有账本串联回答→spec→工单→测试，这是最实质的公开抱怨
- 收尾开放。结束消息倾向开放式，是个已知毛边。正解：同一会话里接 to-spec，小改动直接 implement
- 名字不达意。连作者生态自己都承认没人满意这个名字——搜索和传播会付出理解成本
记住
grill-with-docs 的核心是一个区别：别的拷问 skill 把会话留在你脑子里，它把文件留在磁盘上。
术语当场进 CONTEXT.md，硬决策过三道门落 ADR，其余留在会话里——所以会话别急着清，喂给 to-spec，再对照原答案重读 spec。
一次会话只换来一份更锐利的术语表、零个 ADR？那是它在正常工作。
参考资源
- 文档：https://github.com/mattpocock/skills/blob/main/docs/engineering/grill-with-docs.md
- 作者生态：https://www.aihero.dev/
- 主构建链：grill-with-docs → to-spec → to-tickets → implement → code-review