企业官网建设流程全解析

grill-with-docs 实战拆解：逐轮拷问设计，让领域文档直接落进仓库

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

本文拆解 Skills for Real Engineers（mattpocock/skills）里的grill-with-docs技能：它围绕你的计划或设计逐轮提问，同时把敲定的术语和决策写进CONTEXT.md与 ADR，让认知对齐不随对话结束而蒸发。

一、从"想法没对齐"说起

这节铺垫问题本身：一行代码还没写，你和 Agent 可能想的已经是两回事。

你准备给订单加"取消"功能，对话里随口说了句"cancellation"。你心里是"订单内某行项目可退"，Agent 理解成"整单作废并退款"。你没明说，它也没问，代码写完才发现整个方向错了。丢掉的不仅是一天工时：你们争论过的每个叫法、每个取舍，也随着上下文窗口一起清零，下一个 Agent 得从零重新推导。

这种"改动前认知不一致"正是 AI 协作开发里最常见的翻车方式，而 Skills for Real Engineers 把"先对齐、再动手"列作第一优先级要修的故障。grill-with-docs就是为此设计的。

二、一句话认识 grill-with-docs

这节说清它的定位，以及和兄弟技能 grill-me 的分界线在哪。

grill-with-docs是一个面向代码仓库的访谈工具：它围绕你的某个计划或设计持续追问，直到你和 Agent 对这件事的理解完全重合。关键在于它有状态——白话讲，就是产出会写进仓库文件，而不是只留在对话窗口里。

它的节奏和 grill-me 一脉相承：一轮问题、等你回答、再下一轮。但 grill-me 不碰仓库也不碰文件，整场拷问结束后，你的脑子里剩下理解，磁盘上什么都不剩。两者本质区别就一句话：一个往磁盘上留痕迹，一个不留。只要你人站在一个可写的仓库里，前者严格优于后者。

三、它是怎么跑起来的

这节按使用者视角，把它的三层机制串成一条叙事线：入口委托、访谈节奏、写作纪律。

一行委托背后的分工

翻开这个技能的 SKILL.md，全文只有一句指令：

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

它自己不干活，而是拆给两个引擎：

• grilling 管问：提供"设计树 + 轮次提问"的拷问机制，下面细讲；
• domain-modeling 管写：提供术语锐化、CONTEXT.md与 ADR 的落盘纪律。

正因是委托架构，两个依赖技能必须同时在场，否则它就是一行空壳。另外它的元数据声明了模型不得自行调用（见 openai.yaml 里allow_implicit_invocation: false），所以只能由你手动敲/grill-with-docs启动，Agent 不会自己伸手。

设计树与轮次：拷问的节奏

访谈引擎是 grilling。核心思想：把整场对话建模成一棵设计树——每个决策都会分支出挂在下层的子决策，类似族谱，先定长辈、再谈晚辈。

推进按"轮次"走。先解释一个术语：前沿（frontier），指所有前置条件已敲定的决策集合，即你现在就能问、不用猜那些还没听到的答案的问题。每轮的动作是：

1. 把前沿里的全部问题编号问出，每题附你的推荐答案；
2. 等用户答完，才进下一轮；
3. 你的回答重塑树：已敲定的决策把前沿往外推，解封依赖它们的后续问题；
4. 某问题的答案依赖本轮仍未解答的另一问，它属于更晚的轮次，不许提前问。

一轮问题的标准长这样：

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

分工很清楚：找事实是 Agent 的活，不是你的。前沿问题需要环境里的事实（文件、工具输出），它派子代理去查，能自己查到的绝不问你；而且不阻塞——进行中的探查只是"未敲定的前置条件"，只有依赖它的下游问题要等，前沿其余问题照常先问。但决策权始终在你：每个决策都会摆到你面前，你拍板，然后它才等。

前沿变空，会话结束：设计树每条分支都被访问过，没有任何东西被默默假设。且在你确认达成共识之前，它不会据此采取任何行动。

边问边写：建模纪律

写作引擎 domain-modeling 与访谈并行运转。它是一门"主动"的学科：不等结尾再整理，而是当场挑战、压测、落笔。一场会话里它做五件事：

1. 对照术语表挑战：你蹦出的词与CONTEXT.md已有语言冲突时，立刻指出来——"术语表里 'cancellation' 是 X，你刚才的意思更像 Y，到底是哪个？"
2. 锐化模糊词：你说"account"，它追问你指的是 Customer 还是 User，这是两个不同的东西；
3. 具体场景压测：谈领域关系时编造边界场景，逼你把概念之间的界限说精确；
4. 与代码交叉引用：你说某事如何运作，它去核对代码是否同意。矛盾直接摆上台面——"代码路径取消的是整单，你却说能按行项目取消，哪个才是真的？"
5. 内联更新术语表：一个术语被解决，当场写进CONTEXT.md，严禁攒批。

而 ADR（Architecture Decision Record，记录"做了什么决定、为什么"的文档）是吝啬提供的：三个条件必须同时成立才提——难以逆转（日后改主意代价高）、缺乏上下文会令人惊讶（未来读者会问"为什么这么做"）、真实权衡的结果（存在真正可选的方案，你因具体原因选了一个）。缺一即跳过。所以大多数决策不配 ADR，大多数会话产不出 ADR，这是设计使然，不是失灵。

四、什么时候该选它

这节按"你手头有什么"给条件句式选路指南。

• 如果你根本不在任何工作目录里（纯想法、无代码在手），就用grill-me；
• 如果你在一个仓库里，且改动一次会话就能敲定，用grill-with-docs；
• 如果工程大到一次会话装不下（绿地项目、巨型功能），用wayfinder——它先在 issue tracker 上画一张"决策票据地图"，再逐张解决；
• 如果仓库完全没有领域文档，你脑中也暂无特定功能，依然用它，把目标对准"给整个仓库建档"而非某次改动；
• 如果卡住你的知识在别人的脑子里，改用to-questionnaire把问卷发出去。

grill-with-docs与wayfinder的分水岭只有一个数字：会话次数。一次会话装得下的规划走前者，装不下走后者。后者更慢更稠密，拿它处理一个范围良好的功能属于过度伸手。

五、跑完一单，你手里多了什么

这节盘点一次会话的三类产出物，以及它们各自的落盘位置和创建时机。

一次会话的产物分三份，分量并不平等：

• 术语（项目自己对某物的叫法）→ 内联写进CONTEXT.md术语表，时机是解决的那一刻；
• 决策（过三门槛的那种）→ 落成docs/adr/下的一份 ADR；
• 你敲定的其他一切→ 只留在对话里，别处没有。

落盘位置有讲究：若仓库根目录存在CONTEXT-MAP.md（标记这是多上下文仓库），术语写进当前主题所属上下文的CONTEXT.md，推断不出就问你；否则一律写根目录CONTEXT.md。ADR 统一进docs/adr/。两处都遵循懒创建——白话讲，"用到了才建"：第一个术语解决前不存在CONTEXT.md，第一份 ADR 需要前不存在docs/adr/，没有任何前置脚手架。

第三份是最容易踩的坑：CONTEXT.md是术语表，而且是刻意只做术语表——不写实现细节、不写规格式散文、不写草稿。你共识里那些精确默认值、否定性需求，全留在对话窗口里。所以会话结束别急着清空上下文，应把整段对话喂给to-spec合成规格。"术语表变锋利了、ADR 数量为 0"的会话完全健康；指望从CONTEXT.md里读出规格，才是预期错了。

六、两份格式模板速查

这节给出两份文档的最小可用模板与书写要点，落地时照着填即可。

CONTEXT.md 最小模板

结构定义见 CONTEXT-FORMAT.md：

# {上下文名称} {一两句话：这个上下文是什么、为何存在} ## Language **Order**: {该术语的一两句描述} _Avoid_: Purchase, transaction **Invoice**: A request for payment sent to a customer after delivery. _Avoid_: Bill, payment request

书写要点：

• 要有主见：同一概念有多个叫法时，选最好的一个，其余全列进_Avoid_；
• 定义要紧凑：最多一两句话，写它"是什么"，别写它"做什么"；
• 只收本上下文专属术语：超时、错误类型这类通用编程概念，你用得再多也不属于这里；
• 术语自然聚簇时用子标题分组，都在一片区域则平铺列表即可。

ADR 最小模板

规则见 ADR-FORMAT.md：ADR 存docs/adr/，按0001-slug.md、0002-slug.md顺序编号，取现有最大编号加一。模板就一段话：

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

可选章节只在真有价值时加：Status frontmatter（决策日后会被重审时有用）、Considered Options（被否方案值得记住时才写）、Consequences（需要点名非显而易见的连锁影响时才写）。够格被记录的东西大致是：架构形态、上下文之间的集成模式、有锁定效应的技术选型（数据库、消息总线这种换一次要一个季度的，不是每个库）、明确的"不做"边界决策、对显而易见路径的刻意偏离、代码里看不见的约束（合规、合作方契约）、以及否得理由不自明的备选方案。

七、症状 → 原因 → 处理

这节把三类高发故障整理成排查手册，对号入座即可。

症状：一次性倾倒全部问题、零推荐答案、全程没提过CONTEXT.md原因：两个依赖技能没加载成功。SKILL.md就一行委托，没拾取 grilling 和 domain-modeling 的 Agent 只能靠猜来理解"grilling"，产物就是无差别提问。 处理：直接问 Agent"你加载了哪些技能"来核实，补齐缺失项重跑。留意一个更迷惑的变体——部分加载：grilling 在、domain-modeling 缺席，你会得到一场很好的访谈，但纸面记录为零。这是该技能报告最多的问题，常与模型和 effort 档位相关。

症状：跑完整场，既没有CONTEXT.md也没有 ADR原因：二分。平庸的那种：没有东西够格，一次没有新词汇的会话本就无物可写。真正的 bug：技能运行在别的编排层内部（规格驱动包装器、多 Agent 框架、别人流水线里的一步规则）时，"写文件"那一半会被报告为静默不发生，访谈却照常进行。此问题已登记、未修复。 处理：若你处于这类配置，先检查工作目录里文件是否真被写出，再信任会话输出。

症状：会话里定了一堆决策，事后找不到下落原因：技能本就如此设计——术语进CONTEXT.md，ADR 卡三门槛，其余只留在对话里。更麻烦的是，精确答案（顺序保证、数值默认、否定性需求）在下游合成时容易被弱化成含糊散文，规格看着完整，实际丢了你真正拍板的东西。 处理：保留整段会话直接喂给to-spec，生成规格后，拿你当时的原始回答逐条核对规格，而不是默认它已经捕获。

八、它在技能链里的上下游

这节给grill-with-docs在主构建链中的坐标，并列出近亲关系。

它是主构建链的头部：

grill-with-docs → to-spec → to-tickets → implement → code-review

它站在任何规格被写下之前：产出的是 to-spec 合成规格所需的共享理解与已敲定的词汇，而 to-spec 承诺不再访谈你，只做综合。若改动小到能立刻动手，可以跳过规格直奔implement。

近亲方面：grill-me是同一场访谈的无状态版，无仓库无文件；domain-modeling是它驱动的建模纪律本身；两者都踩在grilling这个访谈原语上。上游wayfinder负责规划大到装不进一次会话的工程，并把地图中适合的部分下传成一次 grilling 会话。选路拿不准时问ask-matt——它是整套技能的路由器，其路由规则很直白：只要你在一个工作目录里，就优先选grill-with-docs。

九、装好它

最后两条安装路径，外加一个不能漏的依赖清单。

两条路径二选一，都装会每个技能双份：

路径 A：Claude Code 插件，整包托管、只读、自动更新：

claude plugins install mattpocock-skills

会话内则用/plugin install mattpocock-skills。装完后在每个仓库跑一次/setup-matt-pocock-skills，配置 issue tracker、triage 标签与文档布局。

路径 B：npx skills（Codex 与其他 Agent，或想自己改文件的人），安装器把技能作为可编辑文件拷进你的项目：

npx skills@latest add mattpocock/skills

⚠️ 关键提醒：安装器会让你勾选装哪些技能，务必确认setup-matt-pocock-skills、grilling、domain-modeling都在其中。漏掉后两个，grill-with-docs就是上一节排错手册里那个"提问倾倒、零纸面记录"的现场。

装好之后，在仓库里输入/grill-with-docs即可开一场"边拷问边写文档"的会话。收尾时别清上下文，把整段对话交给to-spec，构建链就滚到下一环了。

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