grill-with-docs 使用指南：怎么用，怎么用好
grill-with-docs 是一个"边盘问边沉淀文档"的技能。它会在你设计方案的早期，用连续的提问帮你把模糊的想法逼到墙角，同时把过程中结晶出的术语和决策当场写成文件。本文讲清楚两件事：怎么把它跑起来，以及怎么用才不浪费它的设计意图。
一、它适合什么场景
先判断要不要用它，比用对它更重要。这个技能的核心是"无情质询加当场写文件"，适合的是决策密度高、术语还在漂移的阶段。
它最值钱的场景是设计早期、方案还没定型时。这时候决策多、术语还在混乱，每解决一个都能立刻沉淀，收益最大。具体来说：新项目立项、架构选型、领域模型建模、复杂业务流程梳理、技术方案评审前的自我压力测试，都属于这个阶段。
反过来，如果代码已经写完了再回头补 grill，就晚了——决策都已经做完了，再问也只是走形式，产出的文档也是事后编的。更糟的是拿它来处理日常小改动：选个变量名、调个样式、改个 bug，用无情质询属于杀鸡用牛刀，还把自己累个半死。
判断标准很简单：如果你现在面对的是"一堆还没想清楚的决策"，用它；如果是"已经清楚了只是要执行"，别用它。
二、怎么触发它
触发方式是这个技能最容易踩坑的地方。因为它设置了 disable-model-invocation: true，禁止自动触发，所以只有一种可靠方式能跑起来它。
唯一可靠的方式是显式输入 /grill-with-docs。这会明确告诉系统你要的是这个组合技能，连带触发 grilling 的质询协议和 domain-modeling 的文档产出。
常见的踩坑场景是：你口头说"帮我盘一下这个方案"或"压力测试一下我的想法"。这种说法更可能触发的是裸 grilling 技能——它能给你质询，但不会带上 domain-modeling 的文档产出。结果就是你聊了半小时，什么文件都没沉淀下来，完全浪费了组合技能的意义。
所以记住一个原则：想要文档产出，就必须显式 /grill-with-docs；只想要质询不需要文档，才用裸 /grilling。
三、它会做什么
一旦触发，它会套上两层协议同时运作。
第一层是 grilling 的对话协议。它会一次只抛一个问题，不会一下子问三个让你懵掉。每个问题之后，它会给出自己的推荐答案——这是重点，你可以直接说"同意"或"不行"，不需要每个问题都从零想答案。凡是能查的事实（文件存不存在、代码里怎么写的、工具状态），它自己去查，不来烦你；凡是决策（你的意图、取舍、偏好），它一律等你回答，绝不替你做主。
第二层是 domain-modeling 的产物纪律。在你回答的过程中，它会同时做三件事：你提到一个模糊或冲突的术语，它当场指出，并写入 CONTEXT.md；浮现出符合三门槛的决策，它提议写 ADR（注意是提议，不是强写）；你说的事实和代码不一致，它当场把矛盾摆出来。
最终你会在项目里得到这些产出物：根目录的 CONTEXT.md 记录统一语言词表，docs/adr/ 下按序编号的架构决策记录。如果是 monorepo 或多上下文项目，还会有 CONTEXT-MAP.md 做路由。
四、实际产出物长什么样
实际跑完一轮，项目里会多出几个文件。CONTEXT.md 是词表，每个词条带定义和"避免使用"的同义词列表，比如定义"Order 是客户发起的购买请求，避免使用 Purchase 或 transaction"。docs/adr/ 下是 ADR，模板极简，可以只有标题加三句话：背景是什么、决定了什么、为什么这么决定。
注意 ADR 不是强写的。技能只会在三个条件同时满足时才"提议"写：决策难逆（改主意成本高）、反直觉（后人会问"为什么这么做"）、真权衡（确有备选方案）。三者缺一就跳过，避免 ADR 目录被没价值的小决策淹没。
五、怎么用好：六条实践
想用好它，不是知道规则就行，而是要在互动中配合它的设计意图。
第一，把可查的事实喂给它，而不是问它。 你说"这块逻辑现在是 X"，它应该去翻代码核实，而不是反问你。你该做的是主动指出"这块代码在 xxx 文件里，你可以查"，把脑力留给真正的决策。反过来，如果它问了你能查的东西，提醒它"这个你自己查"。
第二，善用它每题带的推荐答案。 这是它省你脑力的核心机制。快速采纳或否决，比从零想答案快得多。觉得推荐不对就直说"都不是，我想的是…"，让它重新推荐。千万别因为它给了推荐就不思考——推荐是起点不是终点，你要判断它推荐的理由成不成立。
第三，不要抗拒它当场写文件。 domain-modeling 的核心哲学是"capture as they happen, don't batch"——结晶的瞬间就落盘。你可能觉得"还没想清楚先别写"，但恰恰是写下来的动作逼你想清楚。文档不是聊完才补的，是聊着就长出来的。
第四，严守 ADR 的三门槛。 它提议写 ADR 时，你要自己判断满不满足三个条件。不满足就拒掉，别图省事都写。一个干净的 ADR 目录比一个塞满废话的目录有价值得多。
第五，让 CONTEXT.md 只当词表用。 它的定义就是 glossary，不是需求文档、不是设计草稿。一旦你发现自己在往里塞实现细节（"用 Redis 做缓存"），就跑偏了——实现细节该进 ADR 或代码注释，词表只管"这个词什么意思"。
第六，多上下文项目要走 CONTEXT-MAP 路由。 如果你的项目是 monorepo 或有多个 bounded context，不要把所有术语堆在根目录的 CONTEXT.md 里。应该用 CONTEXT-MAP.md 声明各上下文的位置，术语写到对应子上下文的 CONTEXT.md。这能避免一个臃肿的根词表，也尊重上下文边界。
六、五个常见陷阱
知道哪里会翻车，比知道怎么开更重要。
第一个陷阱是以为它会自动触发。很多人说"我提到了 grill，它怎么没出文档"，就是因为 disable-model-invocation: true 导致只有显式 /grill-with-docs 才生效。口头提到 grill 只会触发裸 grilling，丢掉文档产出。
第二个陷阱是ADR 滥用。放宽三门槛，什么决策都写 ADR，很快就会有一堆没价值的小文件。后人翻 ADR 目录找不到关键决策，反而被噪音淹没。
第三个陷阱是CONTEXT.md 跑偏。写着写着变成需求文档或设计草稿，违背"glossary only"的定义。一旦跑偏，词表就失去价值，既当不了好的术语对照，也替代不了真正的需求文档。
第四个陷阱是多上下文写错位置。monorepo 场景下，把所有术语堆在根目录，而不是按 bounded context 分发到子上下文。结果是术语定义冲突、上下文边界模糊。
第五个陷阱是高强度交互让人累。无情质询是为关键决策设计的，节奏很密。拿它处理日常小改动，既累又没收益。用之前先问自己"这事儿值得盘吗"，不值就别开。
七、和现有工作流打通的建议
如果你像本文读者那样有"飞书写文档本地要留存"的要求，可以把 grill 的产出物直接接到飞书协作流里。
具体做法是：让技能把产出的 CONTEXT.md 和 ADR 写成飞书 docx，同时按本地留存规则用导出命令把 markdown 落到桌面指定文件夹。这样 grill 的产出——统一语言加决策记录——就同时进了飞书协作空间和本地档案，既方便团队查阅，又满足本地备份。
甚至可以基于这套思路做一个变体技能：grill-with-feishu，等于 grilling 的质询加上飞书文档落地加本地留存。把本文讲的组合器模式再用一次：grill 管过程，飞书 skill 管产物落地，本地留存管备份，三者正交，组合起来就是一个完整的"设计协作加沉淀"工作流。
八、一句话总结
用 grill-with-docs 的关键是三件事：该用的时候用（决策密集的早期，不是日常小改动），显式触发（/grill-with-docs，不是口头提 grill），配合它的产物纪律（当场写不拖延，严守 ADR 三门槛，CONTEXT 只当词表）。做到这三点，它就是一个能把混乱的设计讨论变成清晰文档的利器；做不到，它就只是个让你答一堆问题还什么都没留下的累赘。