grill-with-docs 实战指南：如何用一场设计拷问把术语与决策沉淀进仓库
【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills
Skills for Real Engineers 是一套面向真实工程的 Agent 技能包，其中工程类技能 grill-with-docs 是它最常被用的一个：它围绕你要做的改动逐轮访谈，把定下来的术语与决策当场写进仓库的CONTEXT.md术语表和 ADR 决策记录，一次会话同时完成认知对齐与文档沉淀。
快速上手：30 秒装好并跑起来
先明确一个前提：该技能只能手动触发，openai.yaml 里allow_implicit_invocation为 false，Agent 不会自己伸手用，必须你输入/grill-with-docs启动。
安装按 README.md 说明二选一，推荐后者：
npx skills@latest add mattpocock/skills（Claude Code 用户也可以用claude plugins install mattpocock-skills。）安装器会让你勾选要装哪些技能，务必保证setup-matt-pocock-skills、grilling、domain-modeling三个都在——少一个，grill-with-docs就是一行空壳，后面踩坑一节有对应解法。
接着两步：在目标仓库里先跑一次/setup-matt-pocock-skills（它会问你用哪个 issue tracker、triage 标签、文档存哪），然后在会话里输入/grill-with-docs。
启动后你会看到什么：它不写代码、不搭环境，而是直接开始按编号提问，每个问题都附带它自己的推荐答案，答完等你的回应，再算下一轮。同时盯着仓库看：会话中一旦有术语敲定，根目录就会出现CONTEXT.md（懒创建，出现之前什么都没有）。
它是怎么干活的：一行入口 + 两套引擎
它的 SKILL.md 正文只有一句委托：Call the Skill tool twice, for "grilling" and "domain-modeling".真正干活的是两套引擎，分工如下：
| 组成 | 角色 |
|---|---|
| grill-with-docs | 入口：只做一行委托，且仅手动触发 |
| grilling | 访谈引擎：设计树、轮次提问、前沿计算 |
| domain-modeling | 写作引擎：术语辨析、术语表与 ADR 的落盘纪律 |
设计树与前沿：只问"现在能问"的问题
结论：访谈不是问题轰炸，而是像剥洋葱——每轮只问前置条件已全部敲定的"前沿"。
- 输入：你的计划或设计（此时还模糊、词汇未定）。
- 处理：把访谈建模成设计树，每个决策都分支出挂在它下面的若干决策；"前沿"就是前置全部敲定的决策集合，即现在就能问、不必猜测未听到答案的问题。每轮问完整个前沿：逐题编号、每题附推荐答案，然后停下等回答。
- 输出：一轮轮编号问题。你的回答重塑这棵树，前沿向外推移并解锁下游问题，重算后进入下一轮；某题依赖本轮另一道未解的题，它自动归入更晚的轮次。
两条分工原则值得记住：找事实是 Agent 的活，不是你的——前沿问题需要环境事实（文件系统、工具输出）时，它派子代理去查，且不阻塞当前轮次，只等它的下游问题；决策权始终在你——每个决策都摆到你面前，等拍板。前沿为空即会话结束：每条分支都访问过，没有静默假设；在你确认共识前，它不会采取任何行动。
问题轮次的格式（摘自 grilling 的 SKILL.md）：
❓ Q1 - <问题标题>: <问题正文，可含多个选项> ➡️ <它的推荐答案>落盘纪律：结晶即写，不攒批
结论：写作侧只有一条原则——术语或决策在敲定的那一刻就写盘，绝不攒到最后。
- 输入：访谈中出现的术语冲突、含糊措辞、关键决策。
- 处理：四种主动动作——对照术语表挑战冲突用词（"术语表把 'cancellation' 定义成 X，你指的好像 Y？"）、锐化模糊词（"account 指 Customer 还是 User？这是两回事"）、编造边界场景压力测试领域关系、把口述与代码交叉核对（代码与说法矛盾就立刻摆上台面）。
- 输出：敲定的术语内联写入
CONTEXT.md；决策则先过三道门槛才配成 ADR——①难以逆转（日后反悔代价高）；②缺少上下文会让后来者惊讶（"他们为什么这么做？"）；③真实权衡的结果（有可选项，且因具体原因选了一个）。三关全过才写，缺一即跳过，所以大多数决策不配 ADR，大多数会话 ADR 产出为零。
选型指南：什么时候用、什么时候别用
它的定位是单会话工具，最佳时机：在仓库里、改动开始前、计划还模糊、描述事物的词汇尚未定稿时。手头有什么决定跑什么：
| 你手头的情况 | 该跑什么 |
|---|---|
| 根本不在某个工作目录里 | grill-me（同样的访谈，无仓库无文件） |
| 一个仓库 + 一次会话能敲定的改动 | /grill-with-docs |
| 一次会话装不下的工程（绿地构建、大型功能） | wayfinder（多会话规划） |
| 仓库里完全没有领域文档，也没有特定功能在脑中 | /grill-with-docs，目标对准仓库本身 |
| 决策卡在别人脑子里的知识上 | to-questionnaire |
两个边界场景值得单独说：
- 与 wayfinder 的分水岭只有会话数。单会话规划用它，多会话规划用 wayfinder；在范围良好的小功能上动用 wayfinder 是常见错误，反过来 wayfinder 的地图里适合单会话的部分也能下传给它来做一轮拷问。
- 对准零文档的存量仓库不但行，而且正是目标用法：直接说"帮我记录我的仓库"即可，Agent 会读代码并就发现向你提问，代码库里哪些词才算"正确的词"由你拍板。
跑完你会得到什么：两份文件 + 一份"无"
先说结论：一次会话的产出只有三样，其中两样是文件，一样是什么都没有。所有文件均懒创建，无任何前置脚手架；第一个术语或决策结晶之前，磁盘上一切如常。
| 解决了什么 | 落在哪里 | 写入时机 |
|---|---|---|
| 一个术语：项目对某事物的专属称呼 | 根目录CONTEXT.md；若根目录有CONTEXT-MAP.md标记多上下文，则写对应上下文的CONTEXT.md | 术语解决的那一刻，内联写入，不攒批 |
| 同时过三关的决策 | docs/adr/下顺序编号的0001-slug.md式文件 | 第一份 ADR 需要时才建目录；编号 = 现存最大号 + 1 |
| 你敲定的其他一切 | 无处落盘 | 只存在于对话本身 |
第三行最容易让人踩坑：相当一部分共识按设计就不落盘。CONTEXT.md是术语表，且刻意只做术语表——不写实现细节、不写规格、不写草稿笔记。它的结构遵循 CONTEXT-FORMAT.md：同一概念选一个规范词、其余列入_Avoid_，定义一两句话封顶，只收本项目独有的词（"超时"这类通用编程概念不配入选）：
## Language **Order**: {一两句话的定义} _Avoid_: Purchase, transactionADR 的格式更简（见 ADR-FORMAT.md）：正文就是一个标题加 1–3 句"背景—决定—为什么"，一段话即可；Status、Considered Options、Consequences 三个可选章节只在真有价值时加。
验收清单：判断它是否真在工作
会话结束后对照这五条，全中即工作正常：
CONTEXT.md在会话期间逐词变化，而不是结尾一次性冒出来- 术语表读起来是纯词汇：项目自己的词 + 紧凑定义，零实现细节、零规格式散文
- 代码库能回答的问题，由读代码库回答，而不是拿来问你
- ADR 很少甚至为零，且出现的那几份都是"不得不重新辩一遍会很烦"的决策
- 它会因为既有术语表定义不同，主动挑战你刚用出的某个词
踩坑速查 ⚠️
1. 跑完了，既没有CONTEXT.md也没有 ADR→ 原因：两种。平庸的那种是"没东西够格"——没有新术语、ADR 又要三关全过，确实无物可写。另一种是已知且未修复的 bug：当技能嵌在另一层编排里（规格驱动开发包装器、多 Agent 框架、被规则作为他人流水线的一步调用），写文件的那一半会静默失效，而访谈照常进行。 → 处理：若你处于后一种配置，先核对工作目录，再决定要不要相信会话输出。
2. 一次性把所有问题都问完，没有推荐答案，全程没提CONTEXT.md→ 原因：两个依赖技能没加载成功。它只是一行委托，没拾取grilling与domain-modeling的 Agent 只能靠猜；部分加载（grilling 在、domain-modeling 缺）更迷惑——访谈很好，纸面记录为零。此问题与模型和 effort 级别强相关，是该技能被报告最多的毛病。 → 处理：直接问 Agent"你加载了哪些技能"；并确认安装清单里setup-matt-pocock-skills、grilling、domain-modeling三件齐全。
3. 会话里答的那些精确决定"不见了"→ 原因：按设计而非故障。术语表不是规格，多数回答挣不到 ADR，也没有账本把每个答案一路对应到规格、票据、测试；顺序保证、否定性需求、数值默认值这类精确答案，在下游很容易被弱化成含糊散文。 → 处理：保留会话直接喂给/to-spec，规格出来后拿你本人的回答逐条回读核对，别假定它捕获了一切。
4. 会话收尾消息很开放，不知道下一步干什么→ 原因：已知毛边，技能不给硬性出口。 → 处理：主流流程是同一段对话里调 to-spec；改动小到能立刻动手的，直奔 implement。
5. 想对准零文档的老仓库，怕它卡住→ 原因：不必担心，这正是它瞄准的场景。但要做好引导的准备：Agent 会读代码、就发现问你，而"代码库里已有的哪些词是正确的词"由你说了算。 → 处理：直接说"帮我记录我的仓库"；社区常见搭配是 improve-codebase-architecture 来构建或修复CONTEXT.md。
全流程位置与下一步
grill-with-docs是主构建链的头部，先于一切规格文字：
grill-with-docs → to-spec → to-tickets → implement → code-review
它产出的是 to-spec 后续直接合成规格所需的共享理解与已敲定的词汇——不用再访谈你一遍。它的上游是 wayfinder，负责规划装不进一次会话的工程，并把地图中适合的部分下传给它；拿不准该用哪个技能或流程时，找 ask-matt，它是这套技能的总路由。
下一步很明确：会话结束时别清空上下文——把同一段对话交给/to-spec，让它合成规格并发布到 issue tracker，随后拆票、进入实现，纸面资产才算真正接上流水线。
【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
