grill-with-docs 运行逻辑全解：一次会话如何把设计磨成共识并沉淀领域术语

【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills

grill-with-docs 是这个仓库里"设计访谈 + 领域文档沉淀"技能：它围绕你的计划反复提问，直到你和 Agent 达成同一份理解，提问的同时把敲定的术语写进术语表GLOSSARY.md、把重要决策按编号写成docs/adr/下的 ADR。设计阶段最贵的开销是"问题没问全"和"决策没落地"，这个技能正好接管这两件事，你只负责做决定。下面先跑通最短路径，再依次拆解内部机制、该用还是绕开、产出文件格式、以及卡住时的排查方法。

先跑通一次：安装、配置、发起第一次访谈

📌 最短路径是三步：装、配、发。

1. 安装。参考 README，Claude Code 里一条命令：

claude plugin install mattpocock-skills@claude-plugins-official

其他 Agent 走通用路线：

npx skills@latest add mattpocock/skills -a <agent>

第一条装官方插件、自动更新；第二条把文件拷进你的项目、手动更新。⚠️ 注意：安装器若让你勾选技能，至少把grilling、domain-modeling和setup-matt-pocock-skills连同本技能一起装上——只装它自己，得到的是一行字的空壳。

2. 配置。在你的工作仓库里跑一次/setup-matt-pocock-skills：配置 issue tracker、triage 标签和领域文档的存放约定。

3. 发起。在 Agent 里输入/grill-with-docs，附一句你要磨什么，比如"帮我理清这次给订单加部分取消的功能"。

流程里藏着两个前提。其一，仓库必须可写：术语落在根目录GLOSSARY.md（多上下文仓库落在对应上下文里），决策落在docs/adr/。其二，两个依赖技能必须同时在场，缺了会话会退化，见第五节。前置脚手架则完全不需要：所有文件都是懒创建——第一个术语敲定才出现GLOSSARY.md，第一份 ADR 需要时才建docs/adr/。这换来了"零产出会话不留垃圾文件"，diff 保持干净。代价是元数据里disable-model-invocation: true：Agent 永远不会自己想起用它，必须你亲手输入。

内部在做什么：grilling 按轮提问，domain-modeling 边谈边落盘

入口文件就一行：

Call the Skill tool twice, for "grilling" and "domain-modeling".

这是一张转办单：访谈节奏交给 grilling，写作纪律交给 domain-modeling，各管一段。

grilling 决定问题怎么排。它把访谈对象建模成一棵设计树：每个决策下面分支出挂着的子决策。前沿是前置条件全部敲定的决策集合，即现在就能诚实地问、不用猜测未听到答案的问题。一轮把整个前沿一起问出，每题编号并附 Agent 的推荐答案：

❓ **Q1** - **<问题标题>**: <问题正文，可含多个选项> ➡️ <你的推荐答案>

编号存在的唯一目的，是让你按编号回话："1 同意，2 选第二个，3 不同意，理由是……"。你的回答重塑这棵树：敲定的决策把前沿往外推、解封下游问题；答案还取决于本轮另一个未答问题的，放到更晚的轮次。找事实是它的活、不是你的：前沿需要环境事实时它派子代理去查，其余问题不因此阻塞。决策权全在你：每个决策都要摆到你面前、然后等待。前沿为空会话才结束，且在你确认达成共识之前，它不会据此采取任何行动。代价是多轮往复、会话变长；换来的是你每个问题都只需表态，不用自己组织问题。

domain-modeling 决定词何时落盘。会话期间它并行做五件事：你的词与术语表冲突时立刻挑战——"术语表把 'cancellation' 定义为 X，但你似乎指的是 Y，到底哪个？"；对含糊的词提议规范术语；用具体场景压测边界；与代码交叉核对是否一致；术语一敲定就内联更新GLOSSARY.md，绝不攒着批量写。它换来了术语与决策的实时落盘，代价是这场会话比普通讨论"刻薄"——这是设计意图。ADR 则只在三个条件同时成立时才被提议：难以逆转、缺乏上下文会令人惊讶、真实权衡的结果。缺一条就跳过。大多数会话产出零份 ADR，这不是失灵，是按设计工作；对应代价是共识的大部分内容只留在当前上下文窗口里，没有文件出口。

该用它还是绕开它：分水岭是能几次会话敲定

看手头的东西选：

grill-me是不依赖仓库、不写文件的纯访谈，可以随身带；wayfinder先把工作画成一张决策票据地图再逐张解决，适合跨多个会话的工程；to-questionnaire把问题做成 Markdown 问卷异步发给知识持有者，会话里盘问你本人是无效的。

本技能与wayfinder的分水岭只有一个数：能几次会话敲定。常见错误是拿wayfinder够一个范围良好的功能——它更慢更稠密；反过来它也不取代本技能，地图里适合单次访谈的部分，它可以下探到一场 grilling 会话里。仓库零领域文档时还有第二种用法：对它说"help me document my repo"，它读代码、就发现向你提问，由你定夺哪些已有词是对的。预期需要你来掌舵。

两份产出文件：GLOSSARY.md 与 ADR 长什么样

GLOSSARY.md是术语表，且只做术语表。结构由 GLOSSARY-FORMAT.md 规定：

# {上下文名称} {一两句：这个上下文是什么、为什么存在} ## Language **Order**: {一两句话的定义} _Avoid_: Purchase, transaction

术语加粗、定义不超过两句、不想让人用的同义词列进_Avoid_。书写规则四条：同一概念有多个词时选最好的一个、其余进_Avoid_；只定义"是什么"，不写"做什么"；只收项目专属术语，通用编程概念再高频也不收；术语自然聚簇时用子标题分组。实现细节、规格、草稿笔记一律不进去，写跑偏了就是技能用错了。

ADR 存docs/adr/，顺序编号：0001-slug.md、0002-slug.md，目录同样懒创建。模板极简：

# {决策的短标题} {1-3 句话：背景是什么、决定了什么、为什么}

一段话就够——价值在记录"做了决定、为什么"，不是填满小节。Status、Considered Options、Consequences 三个可选章节只在真正增值时才加。编号取目录里现有最大序号加一。

写进哪个上下文自动推断，无需配置：根目录有GLOSSARY-MAP.md即多上下文仓库，读它找各上下文的术语表；只有根GLOSSARY.md就是单上下文；两者皆无，第一个术语敲定时懒创建根文件。多上下文时它推断当前主题属于哪个上下文，不确定就问你。

卡住了怎么办：对着五种症状排查

⚠️ 官方文档已把常见问题整理好了，先对表再动手：

还有一个主动检查法：会话刚开始就不按轮次提问、不给推荐答案，基本可以断定依赖加载失败——这是该技能被报告最多的问题，出现频率取决于模型和 effort 层级，问一句比猜快。

跑完后该核对什么

结束前对照这份清单，五条都中说明它正常工作：

• ✅GLOSSARY.md是在会话期间逐词变化的，而不是结尾一次性倒出；
• 术语表读起来是纯词汇：项目的词加紧凑定义，没有实现细节、没有规格口吻；
• 代码里能查到的事实，它是读代码回答的，不是问你的；
• ADR 数量很少或为零，而你拿到的那几份，都是你不想再吵一遍的决策；
• 它曾因为你用词与现有术语表冲突而当场挑战你。

一句话收尾：这个技能把"把问题问出来"和"把决策留下来"变成了默认发生的事，你做决定，它做记录和提问，设计阶段最贵的两笔开销就此过户。

【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills