企业官网建设流程全解析

grill-with-docs 实战指南：一次 Agent 会话如何对齐设计并沉淀领域文档

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

在开源仓库 Skills for Real Engineers（Matt Pocock 的 Agent 技能合集）里，grill-with-docs 是唯一"边访谈、边落盘"的设计对齐技能：它用一轮一轮不留情面的提问把你和 Agent 的计划磨到同一理解，同时把敲定的词当场写进GLOSSARY.md、把够格的决策写成docs/adr/下的编号 ADR。读完本文，你能说出它何时该用、一次会话里到底发生了什么、结束后仓库多了什么文件、以及跑完该核对哪几处。

启动 grill-with-docs 前要检查什么

先看入口文件 skills/engineering/grill-with-docs/SKILL.md，正文只有一行：

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

也就是说它自身不实现任何逻辑：访谈节奏委托给 grilling（提供"按轮提问"的访谈原语），术语表与 ADR 的写作纪律委托给 domain-modeling。元数据里声明了disable-model-invocation: true——Agent 绝不会自行触发它，必须你自己敲/grill-with-docs。代价是：单独安装它只装到一张一行字的"转接件"，两个依赖技能必须同时在场它才能工作。

启动前确认三件事，因为它会往你的仓库写文件：

1. 仓库可写：你正处在"可以安全写入"的位置。术语落在根目录GLOSSARY.md（多上下文仓库则落在对应上下文的GLOSSARY.md），决策落在docs/adr/；
2. 两个依赖技能在场：grilling供访谈，domain-modeling供写作。缺一个，会话就会退化，对照关系见文末故障排查；
3. 无需前置脚手架：所有目标文件懒创建——第一个术语敲定才建GLOSSARY.md，第一份 ADR 需要时才建docs/adr/。在此之前，仓库里什么都不出现。

坚持懒创建只有一个目的：零产出的会话不留下任何垃圾文件，git status保持干净。

一次会话如何对齐设计：设计树、前沿与轮次

访谈引擎是grilling。它把访谈对象建模成一棵设计树：每个决策都分支出挂靠在它下面的子决策。三个概念支撑整个流程：

• 设计树：决策之下还挂着决策的树状结构；
• 前沿：所有前置条件已敲定的决策集合——即现在就能诚实地问、不必猜测尚未听到的答案的问题；
• 轮次：一轮 = 整个前沿。全部问完、全部答完，再进下一轮。

一轮内把前沿问题全部问出：每个问题带编号、附 Agent 自己的推荐答案，然后等你的回答。标准格式长这样：

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

这个格式存在只有一个理由：让你能按编号作答——"1 同意，2 选第二个，3 不同意，理由是……"。

举个例子。你让它盘一个"订单取消"功能，前沿上挂着三个前置已敲定的决策，它可能抛出：

❓ **Q1** - **取消的粒度**: 只支持整单取消，还是允许部分取消（逐行取消）？ ➡️ 推荐：v1 只做整单取消，部分取消放到后续迭代。 --- ❓ **Q2** - **取消的状态落点**: 取消是写一个 CANCELLED 状态，还是引入独立取消记录？ ➡️ 推荐：写状态，简单且可查询；代码里没有独立取消模型的痕迹。

你回答后，这棵树被重塑：已敲定的决策把前沿向外推，解封依赖它们的下游问题；重算前沿，问下一轮。反过来，某个问题的答案取决于本轮另一道还没答的问题时，它属于更晚的轮次，不塞进当前轮。

还有一条分工线：找事实是 Agent 的活，不是你的。前沿问题需要环境事实（文件系统、工具）时，它派子代理去查，绝不向你索要任何自己能查到的东西。而且不阻塞：运行中的探查算"未敲定的前置条件"，只有依赖它的下游问题等子代理回报，前沿其余问题现在就问。举例：它想问"Order 实体现在有哪些状态字段"，就派子代理读代码，不问你；但"要不要支持部分取消"这种决策，必须摆到你面前、等你拍板。

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

术语什么时候写进 GLOSSARY.md：访谈中并行的五个动作

domain-modeling是一门"主动"学科：挑战术语、发明边界场景、在概念结晶的瞬间写下来。先划一条界——为了查词而"读"术语表不算这门技能，那是一行谁都会的习惯；它适用于你在改变模型，而不只是消费模型。

会话期间它并行做五件事：

1. 对照术语表挑战：你用的词和GLOSSARY.md已有定义冲突，立刻指出——"术语表把 'cancellation' 定义为 X，但你这句话听起来像 Y，到底哪个？"；
2. 锐化模糊语言：你说出含糊或过载的词时，提议一个精确的规范术语——"你说 'account'：指的是 Customer 还是 User？这是两个东西。"；
3. 用具体场景压测：讨论领域关系时，编造探测边缘情况的场景，逼你把概念之间的边界说精确——"如果订单里有三件商品，用户只取消其中一件，另外两件已经发货，这笔算 cancellation 吗？"；
4. 与代码交叉引用：你描述某事物如何工作时，检查代码是否同意。发现矛盾就摆到桌面——"你的代码取消了整个 Order，但你刚说支持部分取消，哪个是对的？"；
5. 内联更新GLOSSARY.md：术语一敲定就当场更新，绝不攒着批量写。

这里有一条硬边界：GLOSSARY.md刻意只做术语表——不含实现细节、规格、草稿笔记。

ADR 何时才值得写：三道判定门槛

一份 ADR（架构决策记录）只有在三个条件同时成立时才被提议：

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

缺一条就跳过。背后的算盘：容易逆转的，到时再逆转，不必记录；不令人惊讶的，没人会问；没有真实替代的，做的只是"唯一明显的动作"，无物可记。

所以大多数决策不配 ADR，大多数会话产出零份ADR。一次"术语表变锋利了、ADR 为零"的会话不是失灵，而是按设计工作——只是共识的大部分内容只留在当前上下文窗口里，出口见后文。

两份产出文件的格式：GLOSSARY.md 与 docs/adr/

会话落盘的文件各有严格格式，格式本身决定了什么"够格"被写进去。

GLOSSARY.md 的模板与四条书写规则

GLOSSARY-FORMAT.md 给出的标准结构：

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

四条书写规则：

• 要有主见：同一概念有多个词时，选最好的一个，其余列进_Avoid_；
• 定义要紧凑：最多一两句，定义它"是什么"，而不是"做什么"；
• 只收项目专属术语：通用编程概念（超时、错误类型、工具模式）即使项目大量使用也不属于这里。加词前自问：这是本上下文独有的概念，还是通用编程概念？
• 自然聚簇时用子标题分组：术语能归入子标题就分组；全部同属一个内聚区域时，平铺列表即可。

docs/adr/ 的模板、编号与三个可选项

ADR-FORMAT.md 规定：ADR 存放在docs/adr/，顺序编号0001-slug.md、0002-slug.md；编号规则是扫描目录里当前最大号加一。目录同样懒创建。模板极简：

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

一份 ADR 可以只有一段——价值在记录"做了决定、为什么"，而不是填满各个小节。三个可选章节只在真正增值时才加：

• Statusfrontmatter（proposed | accepted | deprecated | superseded by ADR-NNNN）：决策会被反复讨论、需要标记状态流转时；
• Considered Options：落选方案本身值得被记住时；
• Consequences：不明显的下游影响需要点名时。

多上下文仓库如何识别：GLOSSARY-MAP.md 推断逻辑

单上下文与多上下文自动推断，无需配置：

• 根目录存在GLOSSARY-MAP.md，即多上下文仓库——读它找各上下文的位置。该文件还带Relationships段，说明上下文之间如何交互（如 "Ordering emitsOrderPlacedevents; Fulfillment consumes them"）；
• 只有根GLOSSARY.md，就是单上下文；
• 两者皆无，则在第一个术语敲定时懒创建根GLOSSARY.md。

多上下文时，它会推断当前主题属于哪个上下文；不确定就问。

一次会话结束后，仓库里多了哪些文件

三类产出，份量不等：

第三行最容易让人失落：大部分共识没有文件出口，只存在于当前上下文窗口里。出口是：会话收尾时别直接清空对话，把同一场对话交给to-spec技能合成规格，再拿规格对照你逐条答过的内容读一遍，别默认它全收下了；改动小且马上能动手的，直接进implement。

五类场景如何选型：何时改用 grill-me、wayfinder、to-questionnaire

仓库里的五路选型判断，关键分水岭是"能否一次会话内敲定"：

两条补充判断：

• grill-with-docs与wayfinder的分水岭就是会话次数：单会话走/grill-with-docs，多会话走/wayfinder。常见错误是拿wayfinder够一个范围良好的功能——它更慢更稠密；反过来wayfinder也不取代本技能，地图中适合单次访谈的部分，它会下探到一场 grilling 会话里。
• 对完全没有领域文档的仓库，启动后说一句"帮我给这个仓库补领域文档"即可：它会读代码、就发现的东西来问你，由你拍板代码里已有的词哪些是对的。用户常把它和improve-codebase-architecture搭配，用于建设或修复GLOSSARY.md。

跑完没反应或行为不对：故障对照与核对清单

跑了，但没有 GLOSSARY.md、也没有 ADR 出现

两种已知原因：其一，确实没东西够格落盘——ADR 要过三道门槛，一场没有新词汇、没有重决策的会话自然无字可写；其二，真实 bug——当这个技能跑在别的编排层里（spec 驱动开发的包装器、多 Agent 框架、把当成人家流水线里一步的规则），有用户报告文件写入那一半静默失效，访谈却照常跑，该问题已记录未修复。在这种环境下，先检查工作目录，再信会话产出。

它一口气问完所有问题、没有推荐答案、从不提术语表

这是依赖没加载成功的信号。入口只有一行，agent 没拿到grilling就只能猜"grill"是什么意思，全量失败就变成"一次把所有问题倒给你"；半加载更迷惑——grilling在了而domain-modeling没在，你会得到一场好访谈但没有文件落盘。怀疑时直接问 agent：你加载了哪些技能？

跑完一次会话后的核对要点

• 术语表在会话期间逐词变化，而不是结尾一次性冒出来；
• GLOSSARY.md读起来只是词汇——混进实现细节说明写作纪律没生效；
• 代码能回答的问题由代码回答，没有反过来问你；
• ADR 少而准：写下来的都是你不想再争一遍的决策；
• 它会拿术语表里已有的定义，来挑战你新用的词——说明对照检查在工作。

收尾：它在构建链里的位置

grill-with-docs是主构建链的第一站，后面依次是to-spec、to-tickets、implement、code-review、retro。它的产出——共识和定死的词汇——正是to-spec不再重复访谈、直接合成规格的原料。拿不准该走哪条链时，还有ask-matt负责路由。

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