grill-with-docs 实战拆解逐轮拷问设计让领域文档直接落进仓库【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills本文拆解 Skills for Real Engineersmattpocock/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指所有前置条件已敲定的决策集合即你现在就能问、不用猜那些还没听到的答案的问题。每轮的动作是把前沿里的全部问题编号问出每题附你的推荐答案等用户答完才进下一轮你的回答重塑树已敲定的决策把前沿往外推解封依赖它们的后续问题某问题的答案依赖本轮仍未解答的另一问它属于更晚的轮次不许提前问。一轮问题的标准长这样❓ **Q1** - **问题标题**: 问题正文可多段、含多个选项 ➡️ 你的推荐答案 --- ❓ **Q2** - **问题标题**: 问题正文可多段、含多个选项 ➡️ 你的推荐答案分工很清楚找事实是 Agent 的活不是你的。前沿问题需要环境里的事实文件、工具输出它派子代理去查能自己查到的绝不问你而且不阻塞——进行中的探查只是未敲定的前置条件只有依赖它的下游问题要等前沿其余问题照常先问。但决策权始终在你每个决策都会摆到你面前你拍板然后它才等。前沿变空会话结束设计树每条分支都被访问过没有任何东西被默默假设。且在你确认达成共识之前它不会据此采取任何行动。边问边写建模纪律写作引擎 domain-modeling 与访谈并行运转。它是一门主动的学科不等结尾再整理而是当场挑战、压测、落笔。一场会话里它做五件事对照术语表挑战你蹦出的词与CONTEXT.md已有语言冲突时立刻指出来——术语表里 cancellation 是 X你刚才的意思更像 Y到底是哪个锐化模糊词你说account它追问你指的是 Customer 还是 User这是两个不同的东西具体场景压测谈领域关系时编造边界场景逼你把概念之间的界限说精确与代码交叉引用你说某事如何运作它去核对代码是否同意。矛盾直接摆上台面——代码路径取消的是整单你却说能按行项目取消哪个才是真的内联更新术语表一个术语被解决当场写进CONTEXT.md严禁攒批。而 ADRArchitecture 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.mdADR 存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.mdADR 卡三门槛其余只留在对话里。更麻烦的是精确答案顺序保证、数值默认、否定性需求在下游合成时容易被弱化成含糊散文规格看着完整实际丢了你真正拍板的东西。 处理保留整段会话直接喂给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。九、装好它最后两条安装路径外加一个不能漏的依赖清单。两条路径二选一都装会每个技能双份路径 AClaude Code 插件整包托管、只读、自动更新claude plugins install mattpocock-skills会话内则用/plugin install mattpocock-skills。装完后在每个仓库跑一次/setup-matt-pocock-skills配置 issue tracker、triage 标签与文档布局。路径 Bnpx skillsCodex 与其他 Agent或想自己改文件的人安装器把技能作为可编辑文件拷进你的项目npx skillslatest 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考