grill-with-docs 实战指南一次 Agent 会话如何对齐设计并沉淀领域文档【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills在开源仓库 Skills for Real EngineersMatt 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。代价是单独安装它只装到一张一行字的转接件两个依赖技能必须同时在场它才能工作。启动前确认三件事因为它会往你的仓库写文件仓库可写你正处在可以安全写入的位置。术语落在根目录GLOSSARY.md多上下文仓库则落在对应上下文的GLOSSARY.md决策落在docs/adr/两个依赖技能在场grilling供访谈domain-modeling供写作。缺一个会话就会退化对照关系见文末故障排查无需前置脚手架所有目标文件懒创建——第一个术语敲定才建GLOSSARY.md第一份 ADR 需要时才建docs/adr/。在此之前仓库里什么都不出现。坚持懒创建只有一个目的零产出的会话不留下任何垃圾文件git status保持干净。一次会话如何对齐设计设计树、前沿与轮次访谈引擎是grilling。它把访谈对象建模成一棵设计树每个决策都分支出挂靠在它下面的子决策。三个概念支撑整个流程设计树决策之下还挂着决策的树状结构前沿所有前置条件已敲定的决策集合——即现在就能诚实地问、不必猜测尚未听到的答案的问题轮次一轮 整个前沿。全部问完、全部答完再进下一轮。一轮内把前沿问题全部问出每个问题带编号、附 Agent 自己的推荐答案然后等你的回答。标准格式长这样❓ **Q1** - **问题标题**: 问题正文可以是多段包含多个选项 ➡️ 你的推荐答案 --- ❓ **Q2** - **问题标题**: 问题正文可以是多段包含多个选项 ➡️ 你的推荐答案这个格式存在只有一个理由让你能按编号作答——1 同意2 选第二个3 不同意理由是……。举个例子。你让它盘一个订单取消功能前沿上挂着三个前置已敲定的决策它可能抛出❓ **Q1** - **取消的粒度**: 只支持整单取消还是允许部分取消逐行取消 ➡️ 推荐v1 只做整单取消部分取消放到后续迭代。 --- ❓ **Q2** - **取消的状态落点**: 取消是写一个 CANCELLED 状态还是引入独立取消记录 ➡️ 推荐写状态简单且可查询代码里没有独立取消模型的痕迹。你回答后这棵树被重塑已敲定的决策把前沿向外推解封依赖它们的下游问题重算前沿问下一轮。反过来某个问题的答案取决于本轮另一道还没答的问题时它属于更晚的轮次不塞进当前轮。还有一条分工线找事实是 Agent 的活不是你的。前沿问题需要环境事实文件系统、工具时它派子代理去查绝不向你索要任何自己能查到的东西。而且不阻塞运行中的探查算未敲定的前置条件只有依赖它的下游问题等子代理回报前沿其余问题现在就问。举例它想问Order 实体现在有哪些状态字段就派子代理读代码不问你但要不要支持部分取消这种决策必须摆到你面前、等你拍板。前沿为空时会话结束每条分支都访问过没有任何东西被默默假设。即便如此在你确认达成共识之前它不会据此采取任何行动。术语什么时候写进 GLOSSARY.md访谈中并行的五个动作domain-modeling是一门主动学科挑战术语、发明边界场景、在概念结晶的瞬间写下来。先划一条界——为了查词而读术语表不算这门技能那是一行谁都会的习惯它适用于你在改变模型而不只是消费模型。会话期间它并行做五件事对照术语表挑战你用的词和GLOSSARY.md已有定义冲突立刻指出——术语表把 cancellation 定义为 X但你这句话听起来像 Y到底哪个锐化模糊语言你说出含糊或过载的词时提议一个精确的规范术语——你说 account指的是 Customer 还是 User这是两个东西。用具体场景压测讨论领域关系时编造探测边缘情况的场景逼你把概念之间的边界说精确——如果订单里有三件商品用户只取消其中一件另外两件已经发货这笔算 cancellation 吗与代码交叉引用你描述某事物如何工作时检查代码是否同意。发现矛盾就摆到桌面——你的代码取消了整个 Order但你刚说支持部分取消哪个是对的内联更新GLOSSARY.md术语一敲定就当场更新绝不攒着批量写。这里有一条硬边界GLOSSARY.md刻意只做术语表——不含实现细节、规格、草稿笔记。ADR 何时才值得写三道判定门槛一份 ADR架构决策记录只有在三个条件同时成立时才被提议难以逆转日后改变主意的成本是实打实的缺乏上下文会令人惊讶未来的读者会疑惑他们为什么这么做真实权衡的结果存在真正可选的方案你出于具体原因选了一个。缺一条就跳过。背后的算盘容易逆转的到时再逆转不必记录不令人惊讶的没人会问没有真实替代的做的只是唯一明显的动作无物可记。所以大多数决策不配 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 可以只有一段——价值在记录做了决定、为什么而不是填满各个小节。三个可选章节只在真正增值时才加Statusfrontmatterproposed | 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。多上下文时它会推断当前主题属于哪个上下文不确定就问。一次会话结束后仓库里多了哪些文件三类产出份量不等会话里敲定了什么落在哪一个术语这个项目对某事物的专属叫法GLOSSARY.md当场内联写入通过三道门槛的决策docs/adr/下一份新 ADR其余所有共识只留在对话里没有文件第三行最容易让人失落大部分共识没有文件出口只存在于当前上下文窗口里。出口是会话收尾时别直接清空对话把同一场对话交给to-spec技能合成规格再拿规格对照你逐条答过的内容读一遍别默认它全收下了改动小且马上能动手的直接进implement。五类场景如何选型何时改用 grill-me、wayfinder、to-questionnaire仓库里的五路选型判断关键分水岭是能否一次会话内敲定你手头有什么用哪个不在任何工作目录里话题甚至不是代码grill-me不依赖仓库、不写文件的纯访谈有仓库改动能在一次会话内敲定grill-with-docs一次会话装不下的工程绿地构建、大型功能wayfinder先画决策票据地图再逐张解决完全没有任何领域文档的仓库脑中也没有特定功能grill-with-docs目标对准仓库本身而非某次改动决策卡在别人脑子里的知识上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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考