2026/9/16 10:59:15
FEATURED · 精选文章 
grill-with-docs 实战指南一次会话内完成设计拷问与领域文档沉淀【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills把改动交给 AI 编程助手之前最常见的翻车不是代码写错而是你和助手对要做什么的理解根本不在一个频道。grill-with-docs 就是为这个问题设计的 Agent 技能在一次会话里逐轮拷问你的设计词一敲定就写进 CONTEXT.md 术语表决策过三关就落成编号的架构决策记录ADR。读完本文你能判断该选哪个拷问技能、把它装对并启用、看懂会话里每轮提问的推进逻辑并知道会话结束后拿什么去喂下游规格流程。选对拷问技能四种处境对应四个出口选型不看项目大小看两件事你在不在仓库里以及这件事能不能装进一次会话。你面前的处境跑哪个技能没进任何项目目录只想把想法聊清楚grill-me同样的逐轮节奏但不碰仓库、不写文件在仓库里且这次改动一轮对话能敲定grill-with-docs绿地构建或超大功能一次对话装不下wayfinder先把工作铺成决策票据地图再逐张解决在仓库里但完全没有领域文档也没想好具体功能仍是grill-with-docs目标改成整个仓库开口就说帮我把这个仓库记录下来决策卡住了答案在别人脑子里to-questionnaire把问题整理成问卷发给能拍板的人grill-with-docs和wayfinder的分界就一条会话数。装得进一次会话就用前者硬用后者去规划一个范围良好的功能是社区里最常见的手滑——它更慢、更重为多会话工程而生。安装前的三项依赖检查缺一个就是空壳这个技能最反直觉的一点是入口文件正文只有一行英文指令。打开 SKILL.md正文就是把 Skill 工具分别调用 grilling 和 domain-modeling 各一次——它自己不实现任何逻辑访谈节奏全部委托给grilling落盘纪律全部委托给 domain-modeling。所以第一项检查是两个依赖技能必须同时在场缺任何一个是装上了但跑不动。第二项这个技能被声明为仅手动触发元数据里的disable-model-invocation: true对应各 Agent 配置里的allow_implicit_invocation: false。Agent 永远不会自己伸手去用它你必须亲自输入/grill-with-docs。第三项装全三件套。两条安装路径# Claude Code claude plugins install mattpocock-skills # Codex 及其他 Agent npx skillslatest add mattpocock/skillsClaude Code 装完后在每个仓库里执行一次/setup-matt-pocock-skills它会问清你用哪个 issue 跟踪器、triage 用什么标签、文档存哪里。走npx这条路的安装器会让你勾选要装哪些技能——务必确认setup-matt-pocock-skills、grilling、domain-modeling三项都在勾选列表里否则主技能只是一行没人接力的空指令。访谈推进机制设计树的前沿如何逐轮生长进入会话后你会看到提问不是撒网式的一次问完而是一轮一轮推。技能把你的设计建模成一棵树每个决策都分支出若干挂在它下面的子决策。它把所有前置条件都已敲定的决策称为前沿——也就是现在就能问、不必猜测未听到答案的问题集合。每一轮整条前沿一次问完问题编号每个问题附一个推荐答案然后停下等你的回答。你的回答会重塑这棵树敲定的决策把前沿往外推解封那些依赖它的问题某个问题的答案若依赖本轮仍未解决的另一问题它就被推迟到更晚的轮次不会提前抛出。还有两条纪律值得留意查事实是它的活不是你的——前沿问题需要环境事实时文件内容、现有行为等它派子代理去查绝不向你伸手要任何自己能查到的东西且不等探查返回就阻塞整轮只有下游问题在等前沿其余部分照常问但决策权始终在你每个决策都要摆到你面前然后等待。当前沿清空会话结束每条分支都访问过没有东西被默默假设。你确认达成共识之前它不会基于此采取任何行动。术语当场落盘的五个动作术语表的形成纪律访谈进行的同时第二台引擎在并行运转它做的是主动的领域建模你每说出一个词它就找机会把它磨成术语表里的一条。五个动作会交替出现。对照术语表挑战你用的词和 CONTEXT.md 里的既有定义冲突时它当场指出——术语表把 cancellation 定义为 X但你刚才说的像是 Y到底指哪个锐化模糊词你说account它会追问指 Customer 还是 User这两个是不同的东西不能共用一个词。造场景压测讨论概念间的关系时它编造边界场景逼你把概念边界说精确而不是停在大致上。和代码交叉验证你描述某事如何工作时它去查代码是否同意矛盾会被浮出来——代码里取消的是整个 Order但你刚说支持部分取消哪个对当场写入术语一敲定立刻落进 CONTEXT.md绝不攒到结尾批量补。术语表只当术语表用不写实现细节、不写规格、不当草稿纸。格式规范见 CONTEXT-FORMAT.md标准结构如下# {上下文名称} {一两句话这个上下文是什么、为什么存在。} ## Language **Order**: {对术语的一两句话描述} _Avoid_: Purchase, transaction **Customer**: A person or organization that places orders. _Avoid_: Client, buyer, account书写规则同一概念有多个叫法时选最好的一个其余丢进_Avoid_定义一两句话写它是什么而非做什么只收项目专属术语通用编程概念超时、错误类型不配入表术语自然聚簇时用子标题分组。落盘位置还有一层推断根目录存在CONTEXT-MAP.md说明是多上下文仓库术语写进当前主题所属上下文的 CONTEXT.md推断不出就问你只有根 CONTEXT.md 则是单上下文两者皆无就在第一个术语解决时懒创建根文件——在此之前什么都不会凭空出现。三道门槛什么样的决策才配一份 ADR决策的待遇比术语苛刻得多一次会话里你拍板的多数决定不值得留下任何文件。技能只在三个条件同时成立时才提议创建 ADR难以逆转日后改主意的代价可观比如换数据库、换消息总线这类要花一个季度迁走的选型缺上下文会令人惊讶未来的读者看着代码会问为什么偏偏这么做真实的权衡确实存在竞争方案你比较后出于具体理由选了其中一个。缺一即跳过。够格的典型题材架构形态monorepo、写模型事件溯源上下文之间的集成模式领域事件而非同步 HTTP边界与范围决策Customer 数据归谁所有、别处只按 ID 引用对显而易见路径的刻意偏离手写 SQL 不用 ORM记下原因免得下一个人去修正它代码里看不见的约束合规禁用某云、合作方契约限定响应时间被否掉的替代方案且否得并不显然——不然六个月后总有人再提 GraphQL 一遍。落盘在docs/adr/顺序编号扫描现存最大编号加一0001-slug.md、0002-slug.md依此类推目录本身也是懒创建。模板极简一份 ADR 可以只有一段# {决策的短标题} {1-3 句话背景是什么、决定了什么、为什么。}Status frontmatter、Considered Options、Consequences 这类章节只在真正增值时才加。所以术语表变锋利了、ADR 一份没出的会话不是失败是符合设计的常态。会话结束后的三种去向你的其他决策在哪一次会话结束能留在磁盘上的只有三样东西而且地位并不平等解决了什么落在哪一个词项目对某事物的专属叫法CONTEXT.md敲定的那一刻内联写入同时过三道门槛的决策docs/adr/下的一份编号文件你拍板的其他一切对话本身没有别处第三行是最容易踩的坑。CONTEXT.md 是术语表不是规格那些精确的答案——顺序保证、否定性需求、数值默认值——大多挣不到 ADR于是只活在共识达成的那个上下文窗口里。正确的接法是不要清空上下文把整段对话原样交给 to-spec 去合成规格规格生成后拿你自己的原始回答逐条回读核对——下游可能把你的精确答案弱化成含糊散文看起来完整、其实丢掉了你真正拍板的东西。这正是它在构建链里所处的头部位置grill-with-docs → to-spec → to-tickets → implement → code-review它先于任何规格存在产出的是to-spec直接可用、无需再访谈你的共享理解与已敲定词汇。若改动小到可以立刻动手也可以跳过规格直奔implement。两个跑完却没发生什么的排障路径这个技能的故障形态不是报错而是看起来结束了但什么都没发生。⚠️坑一会话跑完仓库里没有 CONTEXT.md 也没有 ADR。两个成因。无害的那个无物可写——本次改动没有产生新词汇、也没有决策过门槛本来就不该出现任何文件。真正的问题当技能嵌套在另一层编排里运行规格驱动开发包装器、多 Agent 框架、别人流水线里的一步时写文件那一半会被静默吞掉访谈却照常进行。如果你处于这种配置先检查实际工作目录的状态再决定是否信任会话的输出。坑二问题一次性全部倾倒、没有任何推荐答案、也从不提 CONTEXT.md。这是两个依赖技能没被完整加载的信号。正文只是一行委托找不到grilling和domain-modeling的 Agent 只能猜grilling是什么意思产出就是一通无差别提问。更迷惑的是部分加载grilling在了、domain-modeling不在你得到一场体面的访谈却没有一行纸面记录。该现象与模型和 effort 级别相关是这个技能被报告最多的问题。怀疑时直接问 Agent 它加载了哪些技能。自检五个它在正常工作的信号下次会话结束后对照这五条确认它真的在按设计运转CONTEXT.md 在会话期间逐词变化而不是结尾一次性冒出来术语表读起来是纯粹的词汇——项目自己的词加紧凑定义没有任何实现细节或规格式散文代码库能回答的问题由读代码回答没有被拿来问你ADR 很少甚至为零而留下的每一份都是你不想重辩一遍的决策它会因为既有术语表对某个词有不同定义而当场挑战你刚说出口的用词。五条都中你就可以放心地把这段对话交给to-spec进入构建链的下一环。【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
grill-with-docs 实战指南：一次会话内完成设计拷问与领域文档沉淀
grill-with-docs 实战指南一次会话内完成设计拷问与领域文档沉淀【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills把改动交给 AI 编程助手之前最常见的翻车不是代码写错而是你和助手对要做什么的理解根本不在一个频道。grill-with-docs 就是为这个问题设计的 Agent 技能在一次会话里逐轮拷问你的设计词一敲定就写进 CONTEXT.md 术语表决策过三关就落成编号的架构决策记录ADR。读完本文你能判断该选哪个拷问技能、把它装对并启用、看懂会话里每轮提问的推进逻辑并知道会话结束后拿什么去喂下游规格流程。选对拷问技能四种处境对应四个出口选型不看项目大小看两件事你在不在仓库里以及这件事能不能装进一次会话。你面前的处境跑哪个技能没进任何项目目录只想把想法聊清楚grill-me同样的逐轮节奏但不碰仓库、不写文件在仓库里且这次改动一轮对话能敲定grill-with-docs绿地构建或超大功能一次对话装不下wayfinder先把工作铺成决策票据地图再逐张解决在仓库里但完全没有领域文档也没想好具体功能仍是grill-with-docs目标改成整个仓库开口就说帮我把这个仓库记录下来决策卡住了答案在别人脑子里to-questionnaire把问题整理成问卷发给能拍板的人grill-with-docs和wayfinder的分界就一条会话数。装得进一次会话就用前者硬用后者去规划一个范围良好的功能是社区里最常见的手滑——它更慢、更重为多会话工程而生。安装前的三项依赖检查缺一个就是空壳这个技能最反直觉的一点是入口文件正文只有一行英文指令。打开 SKILL.md正文就是把 Skill 工具分别调用 grilling 和 domain-modeling 各一次——它自己不实现任何逻辑访谈节奏全部委托给grilling落盘纪律全部委托给 domain-modeling。所以第一项检查是两个依赖技能必须同时在场缺任何一个是装上了但跑不动。第二项这个技能被声明为仅手动触发元数据里的disable-model-invocation: true对应各 Agent 配置里的allow_implicit_invocation: false。Agent 永远不会自己伸手去用它你必须亲自输入/grill-with-docs。第三项装全三件套。两条安装路径# Claude Code claude plugins install mattpocock-skills # Codex 及其他 Agent npx skillslatest add mattpocock/skillsClaude Code 装完后在每个仓库里执行一次/setup-matt-pocock-skills它会问清你用哪个 issue 跟踪器、triage 用什么标签、文档存哪里。走npx这条路的安装器会让你勾选要装哪些技能——务必确认setup-matt-pocock-skills、grilling、domain-modeling三项都在勾选列表里否则主技能只是一行没人接力的空指令。访谈推进机制设计树的前沿如何逐轮生长进入会话后你会看到提问不是撒网式的一次问完而是一轮一轮推。技能把你的设计建模成一棵树每个决策都分支出若干挂在它下面的子决策。它把所有前置条件都已敲定的决策称为前沿——也就是现在就能问、不必猜测未听到答案的问题集合。每一轮整条前沿一次问完问题编号每个问题附一个推荐答案然后停下等你的回答。你的回答会重塑这棵树敲定的决策把前沿往外推解封那些依赖它的问题某个问题的答案若依赖本轮仍未解决的另一问题它就被推迟到更晚的轮次不会提前抛出。还有两条纪律值得留意查事实是它的活不是你的——前沿问题需要环境事实时文件内容、现有行为等它派子代理去查绝不向你伸手要任何自己能查到的东西且不等探查返回就阻塞整轮只有下游问题在等前沿其余部分照常问但决策权始终在你每个决策都要摆到你面前然后等待。当前沿清空会话结束每条分支都访问过没有东西被默默假设。你确认达成共识之前它不会基于此采取任何行动。术语当场落盘的五个动作术语表的形成纪律访谈进行的同时第二台引擎在并行运转它做的是主动的领域建模你每说出一个词它就找机会把它磨成术语表里的一条。五个动作会交替出现。对照术语表挑战你用的词和 CONTEXT.md 里的既有定义冲突时它当场指出——术语表把 cancellation 定义为 X但你刚才说的像是 Y到底指哪个锐化模糊词你说account它会追问指 Customer 还是 User这两个是不同的东西不能共用一个词。造场景压测讨论概念间的关系时它编造边界场景逼你把概念边界说精确而不是停在大致上。和代码交叉验证你描述某事如何工作时它去查代码是否同意矛盾会被浮出来——代码里取消的是整个 Order但你刚说支持部分取消哪个对当场写入术语一敲定立刻落进 CONTEXT.md绝不攒到结尾批量补。术语表只当术语表用不写实现细节、不写规格、不当草稿纸。格式规范见 CONTEXT-FORMAT.md标准结构如下# {上下文名称} {一两句话这个上下文是什么、为什么存在。} ## Language **Order**: {对术语的一两句话描述} _Avoid_: Purchase, transaction **Customer**: A person or organization that places orders. _Avoid_: Client, buyer, account书写规则同一概念有多个叫法时选最好的一个其余丢进_Avoid_定义一两句话写它是什么而非做什么只收项目专属术语通用编程概念超时、错误类型不配入表术语自然聚簇时用子标题分组。落盘位置还有一层推断根目录存在CONTEXT-MAP.md说明是多上下文仓库术语写进当前主题所属上下文的 CONTEXT.md推断不出就问你只有根 CONTEXT.md 则是单上下文两者皆无就在第一个术语解决时懒创建根文件——在此之前什么都不会凭空出现。三道门槛什么样的决策才配一份 ADR决策的待遇比术语苛刻得多一次会话里你拍板的多数决定不值得留下任何文件。技能只在三个条件同时成立时才提议创建 ADR难以逆转日后改主意的代价可观比如换数据库、换消息总线这类要花一个季度迁走的选型缺上下文会令人惊讶未来的读者看着代码会问为什么偏偏这么做真实的权衡确实存在竞争方案你比较后出于具体理由选了其中一个。缺一即跳过。够格的典型题材架构形态monorepo、写模型事件溯源上下文之间的集成模式领域事件而非同步 HTTP边界与范围决策Customer 数据归谁所有、别处只按 ID 引用对显而易见路径的刻意偏离手写 SQL 不用 ORM记下原因免得下一个人去修正它代码里看不见的约束合规禁用某云、合作方契约限定响应时间被否掉的替代方案且否得并不显然——不然六个月后总有人再提 GraphQL 一遍。落盘在docs/adr/顺序编号扫描现存最大编号加一0001-slug.md、0002-slug.md依此类推目录本身也是懒创建。模板极简一份 ADR 可以只有一段# {决策的短标题} {1-3 句话背景是什么、决定了什么、为什么。}Status frontmatter、Considered Options、Consequences 这类章节只在真正增值时才加。所以术语表变锋利了、ADR 一份没出的会话不是失败是符合设计的常态。会话结束后的三种去向你的其他决策在哪一次会话结束能留在磁盘上的只有三样东西而且地位并不平等解决了什么落在哪一个词项目对某事物的专属叫法CONTEXT.md敲定的那一刻内联写入同时过三道门槛的决策docs/adr/下的一份编号文件你拍板的其他一切对话本身没有别处第三行是最容易踩的坑。CONTEXT.md 是术语表不是规格那些精确的答案——顺序保证、否定性需求、数值默认值——大多挣不到 ADR于是只活在共识达成的那个上下文窗口里。正确的接法是不要清空上下文把整段对话原样交给 to-spec 去合成规格规格生成后拿你自己的原始回答逐条回读核对——下游可能把你的精确答案弱化成含糊散文看起来完整、其实丢掉了你真正拍板的东西。这正是它在构建链里所处的头部位置grill-with-docs → to-spec → to-tickets → implement → code-review它先于任何规格存在产出的是to-spec直接可用、无需再访谈你的共享理解与已敲定词汇。若改动小到可以立刻动手也可以跳过规格直奔implement。两个跑完却没发生什么的排障路径这个技能的故障形态不是报错而是看起来结束了但什么都没发生。⚠️坑一会话跑完仓库里没有 CONTEXT.md 也没有 ADR。两个成因。无害的那个无物可写——本次改动没有产生新词汇、也没有决策过门槛本来就不该出现任何文件。真正的问题当技能嵌套在另一层编排里运行规格驱动开发包装器、多 Agent 框架、别人流水线里的一步时写文件那一半会被静默吞掉访谈却照常进行。如果你处于这种配置先检查实际工作目录的状态再决定是否信任会话的输出。坑二问题一次性全部倾倒、没有任何推荐答案、也从不提 CONTEXT.md。这是两个依赖技能没被完整加载的信号。正文只是一行委托找不到grilling和domain-modeling的 Agent 只能猜grilling是什么意思产出就是一通无差别提问。更迷惑的是部分加载grilling在了、domain-modeling不在你得到一场体面的访谈却没有一行纸面记录。该现象与模型和 effort 级别相关是这个技能被报告最多的问题。怀疑时直接问 Agent 它加载了哪些技能。自检五个它在正常工作的信号下次会话结束后对照这五条确认它真的在按设计运转CONTEXT.md 在会话期间逐词变化而不是结尾一次性冒出来术语表读起来是纯粹的词汇——项目自己的词加紧凑定义没有任何实现细节或规格式散文代码库能回答的问题由读代码回答没有被拿来问你ADR 很少甚至为零而留下的每一份都是你不想重辩一遍的决策它会因为既有术语表对某个词有不同定义而当场挑战你刚说出口的用词。五条都中你就可以放心地把这段对话交给to-spec进入构建链的下一环。【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
