grill-with-docs：1 次会话跑通，仓库里落 2 份文件-二趣网

grill-with-docs：1 次会话跑通，仓库里落 2 份文件

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

grill-with-docs是开源技能集 Skills for Real Engineers 里的一个访谈技能：它让 Agent 一轮一轮地向你追问设计决策，同时在会话进行中把敲定的术语写进仓库的GLOSSARY.md，把够格的关键决策写成docs/adr/下的编号 ADR（架构决策记录，记录"当时为什么这么选"的短文档）。本文先摆出最终产物长什么样，再倒推它们是怎么在对话里产生的，最后讲首次跑通、技能选型和故障排查。

它到底往你仓库里写了什么：3 类产物、2 个落点

本节解决第一个疑问：跑完一次会话，仓库里多出来几个文件，各长什么样。

一场会话一共产生三类东西，只有前两类落盘：

会话里敲定了什么	落在哪里	写入时机
术语（项目自己专属的叫法）	根目录`GLOSSARY.md`	敲定一个词就当场写入，逐词落盘
通过三道门槛的决策	`docs/adr/0001-slug.md`，顺序编号	提议后你点头才写
其余所有决定	只在对话上下文里，不产生文件	无

GLOSSARY.md的标准结构在仓库的格式文件 GLOSSARY-FORMAT.md 里给出：

# {上下文名称} {一两句话：这个上下文是什么、为什么存在} ## Language **Order**: {对该术语一两句话的描述} _Avoid_: Purchase, transaction **Customer**: A person or organization that places orders. _Avoid_: Client, buyer, account

你期望看到的是一份只有词和紧凑定义的术语表：每个词只有一两句定义，被放弃的同义词列在_Avoid_下。四条书写规则：同一概念多个叫法时选一个定下来；定义说"是什么"而不是"做什么"；只收项目专属术语（"超时""错误类型"这类通用编程概念不收）；术语自然聚簇时用子标题分组。

ADR 的模板同样极简，规定在 ADR-FORMAT.md：

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

一份 ADR 可以只有一段，价值在记录"做了决定、为什么"，不在填满小节。编号规则是扫描docs/adr/取现有最大编号加一。状态、备选方案、影响三个可选章节只在真正增值时才加。

两个文件都是懒创建：有了第一个术语才开GLOSSARY.md这本账，第一份 ADR 过审才建docs/adr/。零产出的会话不会留下任何垃圾文件，diff 保持干净。另外，如果根目录存在GLOSSARY-MAP.md，说明是多上下文仓库，术语会写到该 map 指向的各上下文GLOSSARY.md里，而不是根目录那份。

倒推过程：两份文件分别在哪一刻产生

本节解决第二个疑问：对话进行中，谁在决定"何时提问"和"何时落笔"。答案由两个依赖技能分工完成。

访谈引擎：问题按什么顺序出来

访谈原语来自 skills/productivity/grilling/SKILL.md。它把访谈对象建模成一棵设计树：每个决策下面分支出挂靠它的子决策。三个术语构成节奏：

设计树：决策之下还挂着决策的树状结构；
前沿：所有前置条件已敲定的决策集合，现在就能诚实发问、不必猜答案的问题；
轮次：把整个前沿一口气问完、答完，再进下一轮。

一轮的固定格式如下，取自该技能文件：

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

这个格式的唯一目的是让你按编号作答："1 同意，2 选第二个，3 不同意，理由是……"。你期望看到一份编号问题清单，每个问题带一行独立推荐，整轮可以用一行回答完。

机制的另一半是"事实"与"决策"的分工。找事实是 Agent 的活：前沿问题需要环境事实时，它派子代理去查，绝不向你索要自己能查到的东西，且不阻塞——只有依赖该事实的下游问题等待回报，前沿其余问题现在就问。决策权则始终是你的：每个决策都要摆到你面前然后等待。前沿为空时会话结束，即便如此，在你确认达成共识之前，它不会据此采取任何行动。

写作引擎：会话期并行的五个动作

写作纪律来自 skills/engineering/domain-modeling/SKILL.md。它是一门"主动"学科，会在对话中途打断你，五个动作并行：

对照术语表挑战：你用的词与已有定义冲突，立刻指出——"术语表把 'cancellation' 定义为 X，但你似乎指的是 Y，到底哪个？"；
把模糊词换成定死的词："你说 'account'：指的是 Customer 还是 User？这是两个东西。"；
用具体场景压测：讨论领域关系时编造边缘场景，逼你把概念边界说精确；
与代码交叉引用："你的代码取消了整个 Order，但你刚说支持部分取消，哪个是对的？"；
内联更新GLOSSARY.md：术语一敲定就当场写，绝不攒到散场。散场前批量写出的术语表只是会话摘要，当场写下的才是会话产出。

边界要说清：为了查词而读GLOSSARY.md不算这个技能，那是一行谁都会的习惯。它只在你改变模型时介入，而不是消费模型时。

ADR 门槛：三个条件同时成立才提议

一份 ADR 只有在以下条件同时为真时才被提议：

难以逆转：日后改主意的成本是实打实的；
缺乏上下文会令人惊讶：未来的读者会问"他们为什么这么做？"；
真实权衡的结果：存在真正可选的方案，你出于具体原因选了一个。

缺一条就跳过。容易逆转的，到时再逆转；不令人惊讶的，没人会问；没有真实替代方案的，你做的只是"唯一明显的动作"，无物可记。所以大多数会话产出零份 ADR，这是按设计工作，不是失灵。

首次运行：从安装到第一轮问题出现的 3 步

本节解决上手唯一卡点：装什么、在哪跑、怎么触发。

第 1 步，装全技能，不是装单个。grill-with-docs的入口文件 SKILL.md 正文只有一行：

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

它自己不实现任何逻辑，只是把活转给另外两个技能，单独安装它拿到的是一个空壳。二选一安装：

# Claude Code 插件方式，默认自动更新 claude plugin install mattpocock-skills@claude-plugins-official # 或：clone 本仓库，用自带脚本把技能软链到本地 agent 目录 git clone https://gitcode.com/GitHub_Trending/skills13/skills bash skills/scripts/link-skills.sh

注意link-skills.sh的注释明确写着 dev-only，不是受支持的安装方式，仅供仓库维护者本地使用。你期望看到每行一条linked <技能名> -> <路径>的输出。如果只打算选择性安装，务必把grilling和domain-modeling两个原语带上，否则访谈会退化。

第 2 步，选一个可写的目标仓库。在你正在开发的项目里运行，不要在本仓库里跑。确认目录在你控制下、文档可以提交即可。不需要任何前置脚手架：GLOSSARY.md和docs/adr/都是懒创建，启动前什么都不用建。

第 3 步，手动输入/grill-with-docs。元数据里声明了disable-model-invocation: true，Agent 绝不会自行触发。启动后你应看到第一轮带编号、带推荐答案的问题，而不是它直接开始动手写代码。

5 个入口技能里，什么时候按 grill-with-docs

本节解决选型问题：仓库里有好几个名字相近的访谈入口，按哪个取决于你面前是什么。

你面前有什么	按哪个技能	原因
不在任何工作目录，话题甚至不是代码	`/grill-me`	纯访谈，不依赖仓库、不写文件
有仓库，改动一次会话内能敲定	`/grill-with-docs`	唯一把领域文档落到纸面的访谈
工程大到一次会话装不下（绿地构建、大型功能）	`/wayfinder`	先在 issue tracker 上画决策票据地图，再逐张解决
仓库完全没有任何领域文档，也没有特定功能	`/grill-with-docs`	对准仓库本身，说一句"help me document my repo"，借访谈补齐
决策卡在别人脑子里的知识上	`/to-questionnaire`	盘问你无效，做成问卷异步填写

grill-with-docs与wayfinder的分水岭是会话数：单会话用前者，多会话用后者。常见错误是拿wayfinder够一个范围良好的功能——它更慢更稠密；反过来它也不取代本技能，地图中适合单次访谈的部分会下探到一场访谈会话里。

跑不通时先看哪里：4 种故障的排查入口

本节解决"行为不符合预期"的排查问题。以下症状在仓库文档 docs/engineering/grill-with-docs.md 中均有记录，据文档描述，部分属于已提交未修复的 bug：

症状	先查哪里
一次性问出所有问题、没有推荐答案、全程不提`GLOSSARY.md`	两个依赖没加载，Agent 在自由发挥访谈。直接问它"你加载了哪些 skill"，通常能恢复
访谈正常但一个文件都没写	只加载了`grilling`、漏了`domain-modeling`（部分加载，是最常被报告的问题）。指名让两个技能都加载
会话跑完了但什么都没生成	两种可能：确实没有内容过门槛（无新术语、决策都可逆转）；或技能运行在另一个编排层里（spec 包装器、多代理框架），写文件那半被静默跳过。先核对工作目录
问题问完就开始动手构建	确认门禁被跳过，弱模型常见。在自己的`AGENTS.md`或`CLAUDE.md`里写一行"未经许可以前不要实现"

还有一种不算故障的异常：Agent 向你索要它自己能查到的事实（比如某个文件的形状）。这是运行中的 bug，技能文本把事实与决策分开正是为了杜绝这一点。

结束前逐条核对：验证清单与 3 个最容易踩的坑

本节解决最后一个疑问：怎么确认这场会话真的跑通了、落盘的东西可信。

会话结束后对着 diff 核对五条：

GLOSSARY.md在会话期间逐词变过，而不是结尾一次性生成；
术语表读起来是纯词汇加紧凑定义，没有实现细节和 spec 式散文。如果它已经膨胀，跑一句/grill-with-docs make my GLOSSARY.md more concise and remove any implementation details from it，据文档描述多数内容会被清掉；
本可由代码回答的问题，它是读代码答的，没有问你；
ADR 很少或为零，写出来的那几份是"你会不想再为它争论一遍"的决策；
你说过与术语表冲突的词时，它停下来问过你指的是哪个。

最容易踩的三个坑：

只装了grill-with-docs就启动。入口文件是一行转派指令，两个依赖不在场，你拿到的是一个不工作的空壳，表现为整轮问题无结构、无推荐。
把"零份 ADR"当成失灵。大多数决策不值得 ADR，"术语表变锋利了、ADR 为零"是正常输出，不是失败信号。
以为所有决定都写下来了。只有术语和 ADR 在磁盘上，其余共识留在上下文窗口里，后续步骤会把精确答案（顺序保证、数值默认值）磨成弱化的散文。会话结束直接接/to-spec——同一个对话里把刚讨论完的内容合成为 spec，不再重新访谈；改动足够小就直奔/implement。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析