grill-with-docs 实操拆解:设计对齐的同时,把领域文档直接写进仓库【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills准备动手改代码,但计划还模糊、描述事物的词都没定下来时,在仓库里输入/grill-with-docs,Agent 会和你进行多轮设计澄清:期间每敲定一个术语就当场写入CONTEXT.md术语表,每个通过三道门槛的决策就落成一份 ADR。这就是 grill-with-docs 做领域文档沉淀的完整机制。下面从入口、选型、提问节奏、写作纪律到排错逐层拆解,读完你可以直接在自己的仓库里跑起来,并判断它是否工作正常。入口只是一行委托指令打开 skills/engineering/grill-with-docs/SKILL.md,正文只有一行:Call the Skill tool twice, for grilling and domain-modeling.它自己不含任何逻辑,而是委托给两个更底层的技能:grilling 提供提问机制,即沿设计树逐轮发问;domain-modeling 提供写作机制,即术语辨析与CONTEXT.md、ADR 的落盘纪律。元数据里还声明了disable-model-invocation: true(对应 openai.yaml 中的allow_implicit_invocation: false):该技能只能由你输入/grill-with-docs手动触发,Agent 不会自行伸手去用。这里有个坑:只装grill-with-docs而不装那两个依赖,你得到的就是一行空壳,后面的排错部分会展开讲。手边有什么,就选什么技能先记住一点:grill-with-docs是单会话工具,主战场是在仓库里、改动开始前、计划尚模糊、词汇未定稿。具体怎么选,五条判定句:根本不在任何工作目录里 → 用 grill-me;有仓库,且改动能在一次会话内敲定 → 用grill-with-docs;工程大到一次会话装不下(绿地构建、大型功能)→ 用 wayfinder;仓库没有任何领域文档,脑中也没有特定功能 → 还是grill-with-docs,只是目标对准整个仓库而非某次改动;决策卡在别人脑子里的知识上 → 用 to-questionnaire。grill-with-docs和wayfinder的分界只有一个点:需要几场会话。一次装得下就用前者;要跨多次就用后者——它先把工作拆成问题追踪器上的一张决策票据地图,再逐张解决直到路径清晰。对范围明确的功能动用 wayfinder 属于杀鸡用牛刀,而且它更慢更稠密。两者并非互斥:wayfinder 可以把地图中适合的部分下探回单轮 grilling 会话。开始前:文件落在哪、何时出现这个技能会往你的仓库里写文件,所以要先处于一个可以安全写入的位置:术语:已敲定的词进根目录CONTEXT.md术语表;若根目录存在CONTEXT-MAP.md(表明仓库是多功能上下文),则写进对应上下文自己的CONTEXT.md;决策:写进docs/adr/目录。这些文件全部懒创建——第一个术语或决策结晶之前,什么都不会出现,不需要任何前置脚手架。另外别忘了入口说过的前提:grilling与domain-modeling必须同时在场。提问节奏:设计树与前沿轮次提问阶段完全由 grilling 驱动,核心是把澄清过程建模成一棵设计树:每个决策都是一个节点,它的下面挂着一串依赖它的、必须逐一敲定的后续决策。节奏是发一轮问题 → 等你的回答 → 算出下一轮:找出前沿(frontier):所有前置条件已经敲定的决策,也就是现在就能发出、不必先猜测未听到答案的问题;一轮之内把整个前沿问完:每个问题编号,并附上 Agent 自己的推荐答案;你的回答重塑这棵树:已敲定的决策把前沿向外推,解封依赖它们的问题。某个问题的答案若取决于本轮仍未解答的另一问题,它属于更晚的轮次,而不是本轮。一轮问题的固定格式:❓ **Q1** - **问题标题**: 问题正文,可以是多段,包含多个选项 ➡️ 你的推荐答案 --- ❓ **Q2** - **问题标题**: 问题正文,可以是多段,包含多个选项 ➡️ 你的推荐答案两条边界值得注意。一是找事实是 Agent 的活:前沿问题需要环境中的事实(文件系统、工具等)时,它派子代理去查,不会向你索要自己就能查到的东西;也不阻塞等待——进行中的探查只算一个未敲定的前置条件,只有它下游的问题等回报,前沿其余部分现在就问。二是决定权始终在你手上:每个决策都摆到你面前,然后等。前沿里再无问题可发时,会话结束:设计树每个分支都访问过,没有任何隐藏假设;且在你确认双方对齐之前,它不会基于结果采取任何行动。写作纪律:会话中的五个动作澄清一开始,domain-modeling 就同步工作。这是一门主动学科:挑战术语、发明边界用例、在术语与决策结晶的瞬间写下来。(仅仅读CONTEXT.md查词不算这个技能,那是一行习惯,任何技能都能做;它适用于你在改变模型,而不只是消费模型。)具体是五个动作:对照术语表挑战:你用的词和CONTEXT.md既有语言冲突时当场指出——你的术语表把 cancellation 定义为 X,但你似乎指的是 Y;锐化模糊语言:你用含糊或过载的词时,提议一个精确的规范词——你说 account:指的是 Customer 还是 User?这是两个不同的东西;具体场景压测:讨论领域关系时,编造探测边缘情况的场景,逼你把概念之间的边界说精确;与代码交叉引用:你描述某事物如何工作时,检查代码是否同意——你的代码取消了整个 Order,但你刚才说支持部分取消,哪个是对的?;即时更新CONTEXT.md:术语一敲定就写进文件,绝不攒到结尾批量写。配套铁律:CONTEXT.md只做术语表——不写实现细节、不写规格、不写草稿笔记。什么情况要写 ADR:三道门槛与够格清单技能对 ADR 是吝啬的,只有以下三个条件同时成立才提议创建:难以逆转:日后改变主意的成本很高;缺乏上下文会令人惊讶:未来读者看到代码会问他们为什么这么做?;真实权衡的结果:存在真正可选的方案,你出于具体原因选了一个。缺一条就跳过。所以大多数决策不配 ADR,大多数会话产出零份 ADR,这都属正常。落盘纪律由 ADR-FORMAT.md 规定:ADR 存放在docs/adr/,顺序编号0001-slug.md、0002-slug.md依此类推;目录同样懒创建,只在第一份 ADR 需要时建立;编号方法是扫描docs/adr/现存最大编号加一。模板极简:# {决策的短标题} {1-3 句话:背景是什么、决定了什么、为什么。}一份 ADR 可以只有一段。它的价值在于留下这件事被决定了和为什么的标记,而不在于章节填得多满。可选章节只在真正增值时才加:Statusfrontmatter(proposed | accepted | deprecated | superseded by ADR-NNNN,决策会被重新审视时有用)、Considered Options(被否掉的替代方案值得记住时才写)、Consequences(需要点名非显而易见的连锁影响时才写)。哪些决策够格,官方清单如下:决策类型示例架构形态我们用 monorepo写模型是事件溯源,读模型投影到 Postgres上下文之间的集成模式Ordering 与 Billing 通过领域事件通信,而非同步 HTTP带来锁定效应的技术选型数据库、消息总线、认证提供方、部署目标——不是每个库,只记换掉要花一个季度的那种边界与范围决策Customer 数据归 Customer 上下文所有,其他上下文只按 ID 引用;明确的不做和要做同样有价值对显而易见路径的刻意偏离用手写 SQL 而不是 ORM,因为 X——能阻止下一位工程师去修正某个刻意为之的决定代码里看不见的约束合规要求,我们不能用 AWS因为合作方 API 契约,响应时间必须低于 200ms被否掉的替代方案(否掉理由不明显时)你权衡过 GraphQL 而选了 REST 且原因微妙,否则六个月后还会有人再提 GraphQLCONTEXT.md 怎么写:结构、规则与单/多上下文CONTEXT-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_;定义要紧凑——最多一两句话,写它是什么(IS),不写它做什么(does);只收本项目上下文专属术语——通用编程概念(超时、错误类型、工具模式)即使项目大量使用也不属于这里,加词前问一句:这是本上下文独有的,还是通用编程概念?自然聚簇时用子标题分组——若所有术语同属一个内聚区域,平铺列表也可以。单上下文与多上下文仓库:绝大多数仓库是单上下文,根目录一个CONTEXT.md即可;多上下文时,根目录放CONTEXT-MAP.md,列出各上下文的位置与关系,并用Relationships段描述上下文间交互(如 Ordering emitsOrderPlacedevents; Fulfillment consumes them to start picking【免费下载链接】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准备动手改代码,但计划还模糊、描述事物的词都没定下来时,在仓库里输入/grill-with-docs,Agent 会和你进行多轮设计澄清:期间每敲定一个术语就当场写入CONTEXT.md术语表,每个通过三道门槛的决策就落成一份 ADR。这就是 grill-with-docs 做领域文档沉淀的完整机制。下面从入口、选型、提问节奏、写作纪律到排错逐层拆解,读完你可以直接在自己的仓库里跑起来,并判断它是否工作正常。入口只是一行委托指令打开 skills/engineering/grill-with-docs/SKILL.md,正文只有一行:Call the Skill tool twice, for grilling and domain-modeling.它自己不含任何逻辑,而是委托给两个更底层的技能:grilling 提供提问机制,即沿设计树逐轮发问;domain-modeling 提供写作机制,即术语辨析与CONTEXT.md、ADR 的落盘纪律。元数据里还声明了disable-model-invocation: true(对应 openai.yaml 中的allow_implicit_invocation: false):该技能只能由你输入/grill-with-docs手动触发,Agent 不会自行伸手去用。这里有个坑:只装grill-with-docs而不装那两个依赖,你得到的就是一行空壳,后面的排错部分会展开讲。手边有什么,就选什么技能先记住一点:grill-with-docs是单会话工具,主战场是在仓库里、改动开始前、计划尚模糊、词汇未定稿。具体怎么选,五条判定句:根本不在任何工作目录里 → 用 grill-me;有仓库,且改动能在一次会话内敲定 → 用grill-with-docs;工程大到一次会话装不下(绿地构建、大型功能)→ 用 wayfinder;仓库没有任何领域文档,脑中也没有特定功能 → 还是grill-with-docs,只是目标对准整个仓库而非某次改动;决策卡在别人脑子里的知识上 → 用 to-questionnaire。grill-with-docs和wayfinder的分界只有一个点:需要几场会话。一次装得下就用前者;要跨多次就用后者——它先把工作拆成问题追踪器上的一张决策票据地图,再逐张解决直到路径清晰。对范围明确的功能动用 wayfinder 属于杀鸡用牛刀,而且它更慢更稠密。两者并非互斥:wayfinder 可以把地图中适合的部分下探回单轮 grilling 会话。开始前:文件落在哪、何时出现这个技能会往你的仓库里写文件,所以要先处于一个可以安全写入的位置:术语:已敲定的词进根目录CONTEXT.md术语表;若根目录存在CONTEXT-MAP.md(表明仓库是多功能上下文),则写进对应上下文自己的CONTEXT.md;决策:写进docs/adr/目录。这些文件全部懒创建——第一个术语或决策结晶之前,什么都不会出现,不需要任何前置脚手架。另外别忘了入口说过的前提:grilling与domain-modeling必须同时在场。提问节奏:设计树与前沿轮次提问阶段完全由 grilling 驱动,核心是把澄清过程建模成一棵设计树:每个决策都是一个节点,它的下面挂着一串依赖它的、必须逐一敲定的后续决策。节奏是发一轮问题 → 等你的回答 → 算出下一轮:找出前沿(frontier):所有前置条件已经敲定的决策,也就是现在就能发出、不必先猜测未听到答案的问题;一轮之内把整个前沿问完:每个问题编号,并附上 Agent 自己的推荐答案;你的回答重塑这棵树:已敲定的决策把前沿向外推,解封依赖它们的问题。某个问题的答案若取决于本轮仍未解答的另一问题,它属于更晚的轮次,而不是本轮。一轮问题的固定格式:❓ **Q1** - **问题标题**: 问题正文,可以是多段,包含多个选项 ➡️ 你的推荐答案 --- ❓ **Q2** - **问题标题**: 问题正文,可以是多段,包含多个选项 ➡️ 你的推荐答案两条边界值得注意。一是找事实是 Agent 的活:前沿问题需要环境中的事实(文件系统、工具等)时,它派子代理去查,不会向你索要自己就能查到的东西;也不阻塞等待——进行中的探查只算一个未敲定的前置条件,只有它下游的问题等回报,前沿其余部分现在就问。二是决定权始终在你手上:每个决策都摆到你面前,然后等。前沿里再无问题可发时,会话结束:设计树每个分支都访问过,没有任何隐藏假设;且在你确认双方对齐之前,它不会基于结果采取任何行动。写作纪律:会话中的五个动作澄清一开始,domain-modeling 就同步工作。这是一门主动学科:挑战术语、发明边界用例、在术语与决策结晶的瞬间写下来。(仅仅读CONTEXT.md查词不算这个技能,那是一行习惯,任何技能都能做;它适用于你在改变模型,而不只是消费模型。)具体是五个动作:对照术语表挑战:你用的词和CONTEXT.md既有语言冲突时当场指出——你的术语表把 cancellation 定义为 X,但你似乎指的是 Y;锐化模糊语言:你用含糊或过载的词时,提议一个精确的规范词——你说 account:指的是 Customer 还是 User?这是两个不同的东西;具体场景压测:讨论领域关系时,编造探测边缘情况的场景,逼你把概念之间的边界说精确;与代码交叉引用:你描述某事物如何工作时,检查代码是否同意——你的代码取消了整个 Order,但你刚才说支持部分取消,哪个是对的?;即时更新CONTEXT.md:术语一敲定就写进文件,绝不攒到结尾批量写。配套铁律:CONTEXT.md只做术语表——不写实现细节、不写规格、不写草稿笔记。什么情况要写 ADR:三道门槛与够格清单技能对 ADR 是吝啬的,只有以下三个条件同时成立才提议创建:难以逆转:日后改变主意的成本很高;缺乏上下文会令人惊讶:未来读者看到代码会问他们为什么这么做?;真实权衡的结果:存在真正可选的方案,你出于具体原因选了一个。缺一条就跳过。所以大多数决策不配 ADR,大多数会话产出零份 ADR,这都属正常。落盘纪律由 ADR-FORMAT.md 规定:ADR 存放在docs/adr/,顺序编号0001-slug.md、0002-slug.md依此类推;目录同样懒创建,只在第一份 ADR 需要时建立;编号方法是扫描docs/adr/现存最大编号加一。模板极简:# {决策的短标题} {1-3 句话:背景是什么、决定了什么、为什么。}一份 ADR 可以只有一段。它的价值在于留下这件事被决定了和为什么的标记,而不在于章节填得多满。可选章节只在真正增值时才加:Statusfrontmatter(proposed | accepted | deprecated | superseded by ADR-NNNN,决策会被重新审视时有用)、Considered Options(被否掉的替代方案值得记住时才写)、Consequences(需要点名非显而易见的连锁影响时才写)。哪些决策够格,官方清单如下:决策类型示例架构形态我们用 monorepo写模型是事件溯源,读模型投影到 Postgres上下文之间的集成模式Ordering 与 Billing 通过领域事件通信,而非同步 HTTP带来锁定效应的技术选型数据库、消息总线、认证提供方、部署目标——不是每个库,只记换掉要花一个季度的那种边界与范围决策Customer 数据归 Customer 上下文所有,其他上下文只按 ID 引用;明确的不做和要做同样有价值对显而易见路径的刻意偏离用手写 SQL 而不是 ORM,因为 X——能阻止下一位工程师去修正某个刻意为之的决定代码里看不见的约束合规要求,我们不能用 AWS因为合作方 API 契约,响应时间必须低于 200ms被否掉的替代方案(否掉理由不明显时)你权衡过 GraphQL 而选了 REST 且原因微妙,否则六个月后还会有人再提 GraphQLCONTEXT.md 怎么写:结构、规则与单/多上下文CONTEXT-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_;定义要紧凑——最多一两句话,写它是什么(IS),不写它做什么(does);只收本项目上下文专属术语——通用编程概念(超时、错误类型、工具模式)即使项目大量使用也不属于这里,加词前问一句:这是本上下文独有的,还是通用编程概念?自然聚簇时用子标题分组——若所有术语同属一个内聚区域,平铺列表也可以。单上下文与多上下文仓库:绝大多数仓库是单上下文,根目录一个CONTEXT.md即可;多上下文时,根目录放CONTEXT-MAP.md,列出各上下文的位置与关系,并用Relationships段描述上下文间交互(如 Ordering emitsOrderPlacedevents; Fulfillment consumes them to start picking【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考