尧图网站建设 
grill-with-docs 技能实战一次会话内完成设计拷问与领域文档沉淀【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills导读grill-with-docs是本仓库Skills for Real Engineers一套面向真实工程实践的 Agent 技能集中最重要的工程类技能之一它用一场不留情面的访谈把你对一个计划或设计的理解与 Agent 的理解打磨到完全一致并且在访谈过程中就把沉淀下来的词汇与关键决策直接写入仓库。本文以该技能的官方文档为主体结合仓库内 grilling 访谈原语、domain-modeling 领域建模纪律、ADR-FORMAT 与 CONTEXT-FORMAT 的源码细节讲清它的工作原理、使用时机、文档产出机制、常见故障与排错方法。读完你将能在改动开始前用它对齐认知、让领域术语与关键决策以文件形式留在仓库里并正确衔接to-spec等后续构建链技能。它是什么一场有纸面记录的拷问grill-with-docs会在一个代码仓库中围绕你的某个计划或设计对你进行持续访谈直到你和 Agent 对设计形成同一个理解访谈期间它把项目专属的词汇写进CONTEXT.md术语表把符合三重条件的硬决策写成 ADR架构决策记录。它和 grill-me 使用同一套访谈节奏——一轮问题 → 等待回答 → 下一轮问题——但区别在于它瞄准的是代码库并且是有状态的其他 grill 系列技能把会话留在你的脑子里而它把文件留在磁盘上。一个术语得到解决就当场落入CONTEXT.md而不是在结尾批量写入一个决策通过三道门槛就落成一份 ADR。这正是它与众不同的全部要点也是使用它时最容易出问题的地方产物是真实仓库里的真实文件所以它们可能在你预期时不存在也可能在多人同时书写时发生漂移。一行 SKILL.md 背后的双技能委托架构从源码看这个技能的入口文件极其精简——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-docsAgent 不会自行伸手去用。这也解释了文档中反复强调的部署前提单独安装grill-with-docs得到的只是一个一行字的技能如果没有同时安装grilling和domain-modeling它就无法工作。什么时候用它按你手头的东西选技能官方文档给出的决策表非常清晰——它定位为单会话工具核心适用场景是在仓库里、在一项改动开始前、当计划还很模糊、描述事物的词汇尚未定稿时。具体选择逻辑如下你手头有什么该用哪个根本不在某个工作目录里grill-me一个仓库且改动能在一次会话内敲定grill-with-docs大到一次会话装不下的工程绿地构建、大型功能wayfinder一个仓库完全没有任何领域文档也没有特定功能在脑中grill-with-docs目标对准仓库而非某次改动一个卡在别人脑子里知识上的决策to-questionnairegrill-with-docs与wayfinder的分水岭就是会话次数/grill-with-docs用于单会话规划/wayfinder用于多会话规划。前置条件仓库可写且两个依赖技能在场由于该技能会往你的仓库里写文件你需要处于可以安全写入的位置术语落盘位置已解决的术语写入仓库根目录的CONTEXT.md术语表若根目录存在CONTEXT-MAP.md标记仓库为多上下文则写入对应上下文的CONTEXT.md决策落盘位置写入docs/adr/目录懒创建原则以上文件全部按需创建不存在任何前置脚手架。第一个术语或决策结晶之前什么都不会出现。这里有个容易踩的坑它需要另外两个技能同时在场grilling提供访谈、domain-modeling提供写作因为它自己的SKILL.md就是一行委托指令。访谈引擎grilling 的设计树与轮次机制grill-with-docs的拷问环节完全由 grilling 驱动理解它才能真正理解整个技能的运行节奏。其核心思想是把访谈建模成一颗设计树每一个决策都会分支成挂靠在它下面的若干决策。具体执行方式按轮次推进设计树。前沿frontier指所有前置条件已经敲定的决策——也就是你现在就能问、而不必猜测尚未听到答案的问题集合。一轮之内问完整个前沿给每个问题编号并附上你的推荐答案然后等待用户回答再进入下一轮。每轮的回答重塑这棵树已敲定的决策把前沿向外推解封依赖它们的问题重新计算前沿后继续下一轮。一个问题的答案依赖于本轮仍未解答的另一问题它属于更晚的轮次而不是本轮。一轮问题的标准格式如下❓ **Q1** - **问题标题**: 问题正文可以是多段包含多个选项 ➡️ 你的推荐答案 --- ❓ **Q2** - **问题标题**: 问题正文可以是多段包含多个选项 ➡️ 你的推荐答案值得注意的是找事实是你的活不是用户的这一原则当某个前沿问题需要环境中的事实文件系统、工具等时就派一个子代理去查绝不向用户询问任何你能自己查到的东西同时不要阻塞等待——运行中的探查是一个未敲定的前置条件只有依赖它的下游问题需要等子代理回报前沿中的其余问题现在就可以先问。但决策权始终在用户每个决策都要摆到用户面前然后等待。当设计树的前沿为空时会话结束——每一条分支都被访问过没有任何东西被默默假设。在用户确认达成共识之前不要基于此采取任何行动。写作引擎domain-modeling 的领域建模纪律访谈一旦开始写作引擎 domain-modeling 就同步工作。这是一门主动的学科挑战术语、发明边界用例、在术语和决策结晶的瞬间把它们写下来。仅仅为了查词而读CONTEXT.md不属于本技能那是任何技能都能做到的一行习惯本技能适用于你在改变模型而不只是消费它。会话期间的五个动作对照术语表发起挑战当用户使用的术语与CONTEXT.md中已有语言冲突时立刻指出——你的术语表把 cancellation 定义为 X但你似乎指的是 Y。到底是哪个锐化模糊语言当用户使用含糊或过载的词汇时提议一个精确的规范术语——你说 account你指的是 Customer 还是 User这是两个不同的东西。讨论具体场景讨论领域关系时用具体场景做压力测试编造能探测边缘情况的场景逼用户把概念之间的边界说精确。与代码交叉引用当用户描述某事物如何工作时检查代码是否同意。发现矛盾就浮出水面——你的代码取消了整个 Order但你刚才说支持部分取消。哪个是对的内联更新CONTEXT.md一个术语被解决就当场更新CONTEXT.md绝不批量攒着。格式遵循 CONTEXT-FORMAT.md。ADR 要吝啬地提供该技能只在以下三个条件同时成立时才提议创建 ADR难以逆转日后改变主意的成本很高缺乏上下文会令人惊讶未来的读者会疑惑他们为什么这么做真实权衡的结果存在真正可选的方案你出于具体原因选了一个。三个条件缺一就跳过 ADR。因此大多数决策根本不配 ADR大多数会话也产不出 ADR。纸面记录一次会话的三类产出物官方文档明确强调一次会话会产出三样东西且它们并不平等什么被解决了落在哪里一个术语项目自己对某个事物的称呼CONTEXT.md内联写入在解决的那一刻一个难以逆转、缺乏上下文会令人惊讶、且是真实权衡的决策docs/adr/下的一份 ADR你决定的其他一切只有对话本身没有别处第三行正是最容易让人踩坑的地方CONTEXT.md是术语表且刻意只做术语表——不写实现细节、不写规格spec、不写草稿笔记。ADR 被三道门槛同时卡住所以大多数决策不符合条件大多数会话产出零份 ADR。一次术语表变锋利了、ADR 为零的会话是符合设计的但它意味着你达成共识的大部分内容只存在于达成共识的那个上下文窗口里。此时应把同一段对话交给 to-spec 去合成规格而不是直接清空上下文。术语表才是重点。领域语言是这个技能真正在构建的东西项目自己的词汇一次敲定从此你、Agent 和同事都不必反复为重新推导它们付出成本。仓库 README 也对此给出了佐证——一个共享语言带来的连锁收益包括变量、函数和文件按共享语言一致命名代码库对 Agent 更易导航Agent 因为拥有更简练的语言而花费更少的思考 token。术语表怎么写CONTEXT-FORMAT 规范CONTEXT-FORMAT.md 给出了CONTEXT.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。技能会自行推断适用哪种结构存在CONTEXT-MAP.md就读它找上下文只有根CONTEXT.md就是单上下文两者皆无则在第一个术语解决时懒创建根CONTEXT.md。多上下文时技能会推断当前主题属于哪个上下文不确定就问你。决策记录怎么写ADR-FORMAT 规范ADR-FORMAT.md 规定 ADR 存放在docs/adr/使用顺序编号0001-slug.md、0002-slug.md依此类推docs/adr/目录同样懒创建——只在第一份 ADR 需要时建立。模板极其精简# {决策的短标题} {1-3 句话背景是什么、我们决定了什么、为什么。}就是这样。一份 ADR 可以只有一段。价值在于记录**做了决定和为什么**而不在于填满各个小节。可选章节只在真正有价值时才加Statusfrontmatterproposed | accepted | deprecated | superseded by ADR-NNNN当决策会被重新审视时有用Considered Options只有被否掉的替代方案值得记住时才写Consequences只有需要点名非显而易见的连锁影响时才写。编号规则扫描docs/adr/中现存的最大编号加一即可。什么配得上 ADR官方文档给出了具体的够格清单这些条目本身也是判断是否值得记录的实用指南架构形态如我们用 monorepo写模型是事件溯源读模型投影到 Postgres上下文之间的集成模式如Ordering 与 Billing 通过领域事件通信而非同步 HTTP带来锁定效应的技术选型数据库、消息总线、认证提供方、部署目标——不是每个库都要记只记换掉要花一个季度的那种边界与范围决策如Customer 数据归 Customer 上下文所有其他上下文只按 ID 引用它。明确的不做和要做同样有价值对显而易见路径的刻意偏离如我们用手写 SQL 而不是 ORM因为 X。凡是合理读者会默认相反的都要记这能阻止下一位工程师去修正某个刻意为之的决定代码里看不见的约束如合规要求我们不能用 AWS因为合作方 API 契约响应时间必须低于 200ms被否掉的替代方案且否掉理由不明显时你权衡过 GraphQL 而选了 REST 且原因微妙就记下来否则六个月后还会有人再提 GraphQL。常见问题与已知边界该用我还是/wayfinder范围决定。任何能在一个会话内敲定的事用它装不下的大工程用 wayfinder——它先把工作描绘成一张决策票据ticket地图再逐张解决。Wayfinder 更慢更稠密在一个范围良好的功能上过度伸手是常见错误。它并不取代本技能它可以为了地图中适合的部分下探到一次 grilling 会话里。跑完了但既没有CONTEXT.md也没有 ADR两个已知原因。平庸的那个没有东西够格。ADR 需要三扇门全过而一次没有新词汇的改动会话确实无物可写。真正的 bug当技能运行在另一层编排一个规格驱动开发包装器、一个多 Agent 框架、一条把它作为他人流水线一步的规则内部时写文件的那一半会被报告为静默不发生而访谈照常进行。该问题已登记、未修复。若你处于这种配置先检查工作目录再信任会话输出。它一次性把所有问题都问了、没有任何推荐、也从没提过CONTEXT.md这是技能没能加载两个依赖的症状。因为SKILL.md是一行委托一个没有拾取grilling与domain-modeling的 Agent 只能靠猜来理解grilling是什么意思结果就是一次无差别的提问倾倒。更让人困惑的是部分加载grilling加载了、domain-modeling没加载于是你得到一场很好的访谈却没有任何纸面记录。这通常与模型和 effort 级别相关是该技能被报告最多的问题。如果你怀疑这一点直接问 Agent 它加载了哪些技能。我其余的所有决策都去哪了只进了对话。这是关于该技能最实质的公开抱怨术语表不是规格大多数回答也挣不到一份 ADR而且没有任何账本把每个已解决的回答一路对应到规格、票据和测试。精确的回答顺序保证、否定性需求、数值默认值会在下游被弱化成较含糊的散文结果可能看起来完整、却丢掉了你真正决定的东西。当前可用的缓解手段保留会话并直接喂给 to-spec并且拿你自己的回答重新读一遍规格而不是假定它已经捕获了这些回答。能把它指向一个完全没有任何文档的既有仓库吗可以。这正是适合没有 ADR、没有领域语言、没有设计原则的代码库的技能调用它并说帮我记录我的仓库。社区常见搭配是 improve-codebase-architecture 来构建或修复CONTEXT.md。要做好引导它的准备它会读代码、就发现的东西问你而代码库里已有的哪些词是正确的词由你说了算。会话结束时该做什么该技能的收尾消息往往比较开放这是已知的毛边。主流流程中答案是在同一段对话里调用 to-spec如果改动小到可以立即构建就直奔 implement。为什么叫这个名字没人对这个名字满意。有一个开放的改名建议叫grill-domain-model更诚实地描述其行为但一直没动。如果改名落地文档页会跟着移动、URL 会变化。它工作正常的标志官方文档给出了一组可验证的判定标准CONTEXT.md在会话期间逐词变化而不是结尾一次性冒出来术语表读起来是纯粹的词汇你项目自己的词 紧凑定义不含任何实现细节或规格式散文代码库能回答的问题由读代码库来回答而不是拿来问你你得到很少或零份ADR而得到的那些都是你不得不重新辩一遍会很烦的决策它会因为你的既有术语表对某个词有不同定义而挑战你刚用出的这个词。它在构建链中的位置grill-with-docs是主构建链的头部grill-with-docs → to-spec → to-tickets → implement → code-review它先于任何规格被写下来它产出的是 to-spec 后续直接综合成规格所需的共享理解与已敲定的词汇而不用再访谈你一遍。它的近亲包括grill-me——同样的访谈但无仓库无文件domain-modeling——它所驱动的术语表与 ADR 纪律两者都坐落在 grilling 原语之上。上游的 wayfinder 规划大到装不进一次会话的工程并把地图的部分下传给它。不确定该用哪个技能或流程时ask-matt 负责路由。安装与启用本技能属于用户手动触发的工程类技能需要完整安装依赖才能工作。按照仓库 README.md 的安装说明Claude Codeclaude plugins install mattpocock-skills或在会话内/plugin install mattpocock-skills之后在每个仓库运行一次/setup-matt-pocock-skills完成配置Codex 及其他 Agent / 想自己改的玩家npx skillslatest add mattpocock/skills安装器会让你挑选要装哪些技能务必确保setup-matt-pocock-skills、grilling与domain-modeling都在其中否则grill-with-docs会成为一行空壳。配置完成后在仓库内输入/grill-with-docs即可启动一次边拷问边写文档的会话让设计树在前沿上逐轮生长让术语在解决的瞬间落进CONTEXT.md让真正过三关的决策成为docs/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导读grill-with-docs是本仓库Skills for Real Engineers一套面向真实工程实践的 Agent 技能集中最重要的工程类技能之一它用一场不留情面的访谈把你对一个计划或设计的理解与 Agent 的理解打磨到完全一致并且在访谈过程中就把沉淀下来的词汇与关键决策直接写入仓库。本文以该技能的官方文档为主体结合仓库内 grilling 访谈原语、domain-modeling 领域建模纪律、ADR-FORMAT 与 CONTEXT-FORMAT 的源码细节讲清它的工作原理、使用时机、文档产出机制、常见故障与排错方法。读完你将能在改动开始前用它对齐认知、让领域术语与关键决策以文件形式留在仓库里并正确衔接to-spec等后续构建链技能。它是什么一场有纸面记录的拷问grill-with-docs会在一个代码仓库中围绕你的某个计划或设计对你进行持续访谈直到你和 Agent 对设计形成同一个理解访谈期间它把项目专属的词汇写进CONTEXT.md术语表把符合三重条件的硬决策写成 ADR架构决策记录。它和 grill-me 使用同一套访谈节奏——一轮问题 → 等待回答 → 下一轮问题——但区别在于它瞄准的是代码库并且是有状态的其他 grill 系列技能把会话留在你的脑子里而它把文件留在磁盘上。一个术语得到解决就当场落入CONTEXT.md而不是在结尾批量写入一个决策通过三道门槛就落成一份 ADR。这正是它与众不同的全部要点也是使用它时最容易出问题的地方产物是真实仓库里的真实文件所以它们可能在你预期时不存在也可能在多人同时书写时发生漂移。一行 SKILL.md 背后的双技能委托架构从源码看这个技能的入口文件极其精简——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-docsAgent 不会自行伸手去用。这也解释了文档中反复强调的部署前提单独安装grill-with-docs得到的只是一个一行字的技能如果没有同时安装grilling和domain-modeling它就无法工作。什么时候用它按你手头的东西选技能官方文档给出的决策表非常清晰——它定位为单会话工具核心适用场景是在仓库里、在一项改动开始前、当计划还很模糊、描述事物的词汇尚未定稿时。具体选择逻辑如下你手头有什么该用哪个根本不在某个工作目录里grill-me一个仓库且改动能在一次会话内敲定grill-with-docs大到一次会话装不下的工程绿地构建、大型功能wayfinder一个仓库完全没有任何领域文档也没有特定功能在脑中grill-with-docs目标对准仓库而非某次改动一个卡在别人脑子里知识上的决策to-questionnairegrill-with-docs与wayfinder的分水岭就是会话次数/grill-with-docs用于单会话规划/wayfinder用于多会话规划。前置条件仓库可写且两个依赖技能在场由于该技能会往你的仓库里写文件你需要处于可以安全写入的位置术语落盘位置已解决的术语写入仓库根目录的CONTEXT.md术语表若根目录存在CONTEXT-MAP.md标记仓库为多上下文则写入对应上下文的CONTEXT.md决策落盘位置写入docs/adr/目录懒创建原则以上文件全部按需创建不存在任何前置脚手架。第一个术语或决策结晶之前什么都不会出现。这里有个容易踩的坑它需要另外两个技能同时在场grilling提供访谈、domain-modeling提供写作因为它自己的SKILL.md就是一行委托指令。访谈引擎grilling 的设计树与轮次机制grill-with-docs的拷问环节完全由 grilling 驱动理解它才能真正理解整个技能的运行节奏。其核心思想是把访谈建模成一颗设计树每一个决策都会分支成挂靠在它下面的若干决策。具体执行方式按轮次推进设计树。前沿frontier指所有前置条件已经敲定的决策——也就是你现在就能问、而不必猜测尚未听到答案的问题集合。一轮之内问完整个前沿给每个问题编号并附上你的推荐答案然后等待用户回答再进入下一轮。每轮的回答重塑这棵树已敲定的决策把前沿向外推解封依赖它们的问题重新计算前沿后继续下一轮。一个问题的答案依赖于本轮仍未解答的另一问题它属于更晚的轮次而不是本轮。一轮问题的标准格式如下❓ **Q1** - **问题标题**: 问题正文可以是多段包含多个选项 ➡️ 你的推荐答案 --- ❓ **Q2** - **问题标题**: 问题正文可以是多段包含多个选项 ➡️ 你的推荐答案值得注意的是找事实是你的活不是用户的这一原则当某个前沿问题需要环境中的事实文件系统、工具等时就派一个子代理去查绝不向用户询问任何你能自己查到的东西同时不要阻塞等待——运行中的探查是一个未敲定的前置条件只有依赖它的下游问题需要等子代理回报前沿中的其余问题现在就可以先问。但决策权始终在用户每个决策都要摆到用户面前然后等待。当设计树的前沿为空时会话结束——每一条分支都被访问过没有任何东西被默默假设。在用户确认达成共识之前不要基于此采取任何行动。写作引擎domain-modeling 的领域建模纪律访谈一旦开始写作引擎 domain-modeling 就同步工作。这是一门主动的学科挑战术语、发明边界用例、在术语和决策结晶的瞬间把它们写下来。仅仅为了查词而读CONTEXT.md不属于本技能那是任何技能都能做到的一行习惯本技能适用于你在改变模型而不只是消费它。会话期间的五个动作对照术语表发起挑战当用户使用的术语与CONTEXT.md中已有语言冲突时立刻指出——你的术语表把 cancellation 定义为 X但你似乎指的是 Y。到底是哪个锐化模糊语言当用户使用含糊或过载的词汇时提议一个精确的规范术语——你说 account你指的是 Customer 还是 User这是两个不同的东西。讨论具体场景讨论领域关系时用具体场景做压力测试编造能探测边缘情况的场景逼用户把概念之间的边界说精确。与代码交叉引用当用户描述某事物如何工作时检查代码是否同意。发现矛盾就浮出水面——你的代码取消了整个 Order但你刚才说支持部分取消。哪个是对的内联更新CONTEXT.md一个术语被解决就当场更新CONTEXT.md绝不批量攒着。格式遵循 CONTEXT-FORMAT.md。ADR 要吝啬地提供该技能只在以下三个条件同时成立时才提议创建 ADR难以逆转日后改变主意的成本很高缺乏上下文会令人惊讶未来的读者会疑惑他们为什么这么做真实权衡的结果存在真正可选的方案你出于具体原因选了一个。三个条件缺一就跳过 ADR。因此大多数决策根本不配 ADR大多数会话也产不出 ADR。纸面记录一次会话的三类产出物官方文档明确强调一次会话会产出三样东西且它们并不平等什么被解决了落在哪里一个术语项目自己对某个事物的称呼CONTEXT.md内联写入在解决的那一刻一个难以逆转、缺乏上下文会令人惊讶、且是真实权衡的决策docs/adr/下的一份 ADR你决定的其他一切只有对话本身没有别处第三行正是最容易让人踩坑的地方CONTEXT.md是术语表且刻意只做术语表——不写实现细节、不写规格spec、不写草稿笔记。ADR 被三道门槛同时卡住所以大多数决策不符合条件大多数会话产出零份 ADR。一次术语表变锋利了、ADR 为零的会话是符合设计的但它意味着你达成共识的大部分内容只存在于达成共识的那个上下文窗口里。此时应把同一段对话交给 to-spec 去合成规格而不是直接清空上下文。术语表才是重点。领域语言是这个技能真正在构建的东西项目自己的词汇一次敲定从此你、Agent 和同事都不必反复为重新推导它们付出成本。仓库 README 也对此给出了佐证——一个共享语言带来的连锁收益包括变量、函数和文件按共享语言一致命名代码库对 Agent 更易导航Agent 因为拥有更简练的语言而花费更少的思考 token。术语表怎么写CONTEXT-FORMAT 规范CONTEXT-FORMAT.md 给出了CONTEXT.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。技能会自行推断适用哪种结构存在CONTEXT-MAP.md就读它找上下文只有根CONTEXT.md就是单上下文两者皆无则在第一个术语解决时懒创建根CONTEXT.md。多上下文时技能会推断当前主题属于哪个上下文不确定就问你。决策记录怎么写ADR-FORMAT 规范ADR-FORMAT.md 规定 ADR 存放在docs/adr/使用顺序编号0001-slug.md、0002-slug.md依此类推docs/adr/目录同样懒创建——只在第一份 ADR 需要时建立。模板极其精简# {决策的短标题} {1-3 句话背景是什么、我们决定了什么、为什么。}就是这样。一份 ADR 可以只有一段。价值在于记录**做了决定和为什么**而不在于填满各个小节。可选章节只在真正有价值时才加Statusfrontmatterproposed | accepted | deprecated | superseded by ADR-NNNN当决策会被重新审视时有用Considered Options只有被否掉的替代方案值得记住时才写Consequences只有需要点名非显而易见的连锁影响时才写。编号规则扫描docs/adr/中现存的最大编号加一即可。什么配得上 ADR官方文档给出了具体的够格清单这些条目本身也是判断是否值得记录的实用指南架构形态如我们用 monorepo写模型是事件溯源读模型投影到 Postgres上下文之间的集成模式如Ordering 与 Billing 通过领域事件通信而非同步 HTTP带来锁定效应的技术选型数据库、消息总线、认证提供方、部署目标——不是每个库都要记只记换掉要花一个季度的那种边界与范围决策如Customer 数据归 Customer 上下文所有其他上下文只按 ID 引用它。明确的不做和要做同样有价值对显而易见路径的刻意偏离如我们用手写 SQL 而不是 ORM因为 X。凡是合理读者会默认相反的都要记这能阻止下一位工程师去修正某个刻意为之的决定代码里看不见的约束如合规要求我们不能用 AWS因为合作方 API 契约响应时间必须低于 200ms被否掉的替代方案且否掉理由不明显时你权衡过 GraphQL 而选了 REST 且原因微妙就记下来否则六个月后还会有人再提 GraphQL。常见问题与已知边界该用我还是/wayfinder范围决定。任何能在一个会话内敲定的事用它装不下的大工程用 wayfinder——它先把工作描绘成一张决策票据ticket地图再逐张解决。Wayfinder 更慢更稠密在一个范围良好的功能上过度伸手是常见错误。它并不取代本技能它可以为了地图中适合的部分下探到一次 grilling 会话里。跑完了但既没有CONTEXT.md也没有 ADR两个已知原因。平庸的那个没有东西够格。ADR 需要三扇门全过而一次没有新词汇的改动会话确实无物可写。真正的 bug当技能运行在另一层编排一个规格驱动开发包装器、一个多 Agent 框架、一条把它作为他人流水线一步的规则内部时写文件的那一半会被报告为静默不发生而访谈照常进行。该问题已登记、未修复。若你处于这种配置先检查工作目录再信任会话输出。它一次性把所有问题都问了、没有任何推荐、也从没提过CONTEXT.md这是技能没能加载两个依赖的症状。因为SKILL.md是一行委托一个没有拾取grilling与domain-modeling的 Agent 只能靠猜来理解grilling是什么意思结果就是一次无差别的提问倾倒。更让人困惑的是部分加载grilling加载了、domain-modeling没加载于是你得到一场很好的访谈却没有任何纸面记录。这通常与模型和 effort 级别相关是该技能被报告最多的问题。如果你怀疑这一点直接问 Agent 它加载了哪些技能。我其余的所有决策都去哪了只进了对话。这是关于该技能最实质的公开抱怨术语表不是规格大多数回答也挣不到一份 ADR而且没有任何账本把每个已解决的回答一路对应到规格、票据和测试。精确的回答顺序保证、否定性需求、数值默认值会在下游被弱化成较含糊的散文结果可能看起来完整、却丢掉了你真正决定的东西。当前可用的缓解手段保留会话并直接喂给 to-spec并且拿你自己的回答重新读一遍规格而不是假定它已经捕获了这些回答。能把它指向一个完全没有任何文档的既有仓库吗可以。这正是适合没有 ADR、没有领域语言、没有设计原则的代码库的技能调用它并说帮我记录我的仓库。社区常见搭配是 improve-codebase-architecture 来构建或修复CONTEXT.md。要做好引导它的准备它会读代码、就发现的东西问你而代码库里已有的哪些词是正确的词由你说了算。会话结束时该做什么该技能的收尾消息往往比较开放这是已知的毛边。主流流程中答案是在同一段对话里调用 to-spec如果改动小到可以立即构建就直奔 implement。为什么叫这个名字没人对这个名字满意。有一个开放的改名建议叫grill-domain-model更诚实地描述其行为但一直没动。如果改名落地文档页会跟着移动、URL 会变化。它工作正常的标志官方文档给出了一组可验证的判定标准CONTEXT.md在会话期间逐词变化而不是结尾一次性冒出来术语表读起来是纯粹的词汇你项目自己的词 紧凑定义不含任何实现细节或规格式散文代码库能回答的问题由读代码库来回答而不是拿来问你你得到很少或零份ADR而得到的那些都是你不得不重新辩一遍会很烦的决策它会因为你的既有术语表对某个词有不同定义而挑战你刚用出的这个词。它在构建链中的位置grill-with-docs是主构建链的头部grill-with-docs → to-spec → to-tickets → implement → code-review它先于任何规格被写下来它产出的是 to-spec 后续直接综合成规格所需的共享理解与已敲定的词汇而不用再访谈你一遍。它的近亲包括grill-me——同样的访谈但无仓库无文件domain-modeling——它所驱动的术语表与 ADR 纪律两者都坐落在 grilling 原语之上。上游的 wayfinder 规划大到装不进一次会话的工程并把地图的部分下传给它。不确定该用哪个技能或流程时ask-matt 负责路由。安装与启用本技能属于用户手动触发的工程类技能需要完整安装依赖才能工作。按照仓库 README.md 的安装说明Claude Codeclaude plugins install mattpocock-skills或在会话内/plugin install mattpocock-skills之后在每个仓库运行一次/setup-matt-pocock-skills完成配置Codex 及其他 Agent / 想自己改的玩家npx skillslatest add mattpocock/skills安装器会让你挑选要装哪些技能务必确保setup-matt-pocock-skills、grilling与domain-modeling都在其中否则grill-with-docs会成为一行空壳。配置完成后在仓库内输入/grill-with-docs即可启动一次边拷问边写文档的会话让设计树在前沿上逐轮生长让术语在解决的瞬间落进CONTEXT.md让真正过三关的决策成为docs/adr/里的一份编号记录——然后带着这些纸面资产把会话直接交给to-spec进入构建链的下一环。【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考