ask-matt

问问 Matt

你不可能记住每一项技能，所以遇事就问。

在说明某项技能的作用或建议跳过某个步骤之前，请先阅读该技能的 SKILL.md。此处的概述仅供快速了解。

流程是贯穿各项技能的一条路径。大多数路径沿着一条主流程前进，并有两个入口汇入其中。其余技能要么是独立使用的，要么是运行在底层的词汇层。

主流程：想法 → 交付

大多数工作所走的路线。你有一个想法，希望把它做出来。

1. /grill-with-docs 通过访谈打磨想法。只要你身处工作目录，就从这里开始：它是有状态的，会把学到的内容保存在 GLOSSARY.md 和 ADR 中。（没有工作目录？请改用 /grill-me，见下文“独立技能”部分。两者运行的都是同一个 /grilling 原语；但 grill-with-docs 会留下书面记录，因此只要有代码仓库可以留存记录，它就是更好的选择。）

2. 分支：所有问题都能在对话中解决吗？ 如果某个问题需要可运行的答案（状态、业务逻辑、需要亲眼看到的 UI），就绕道做一个原型，并通过 /handoff 在两个方向上衔接（原型位于独立目录中，这正是 /handoff 的用途；参见“阶段边界”）：

   • 用 /handoff 导出交接文件，然后针对该文件打开一个全新的会话，
   • 用 /prototype 以一次性代码回答该问题，
   • 再用 /handoff 把所学的内容交回，并在原始想法的讨论线程中引用它。

3. 分支：这是一个跨多个会话的构建任务吗？

   • 是 → 先用 /to-spec（把讨论线程转化为规格说明），再用 /to-tickets 将其拆分为穿刺式工单，每张工单都声明其阻塞边。然后以下两种方式之一推进工单：
     • 逐张使用 /implement，每张工单之间执行 /clear 清空上下文。在本地跟踪器上，每张工单对应 .scratch/<feature>/issues/ 下的一个文件，由你手动按阻塞项优先的顺序处理；在真实的跟踪器上，这些边会成为原生的阻塞链接，因此任何阻塞项已完成的工单都可以被认领。每张工单都是自包含的，所以上一张工单的上下文可以随时丢弃。
     • 使用 /implement-spec 在一次运行中处理整份规格。它将工单读作任务图，在就绪的前沿上并行运行实现类子 Agent，并把所有成果合并到一个集成分支上。当你更愿意编排整个构建过程，而不是逐张工单亲自推进时，就选它。
   • 否 → 直接在当前上下文窗口中使用 /implement。

   无论哪种方式，代码都是通过驱动 /tdd（每次完成一个红-绿切片）来构建的，并以 /code-review 收尾，即对差异进行的双轴审查（标准与规格）。/implement 会为每张工单分别运行这两项；/implement-spec 的各个实现类子 Agent 各自驱动 /tdd，并在集成分支上运行一次 /code-review。如果你只想以测试先行的方式构建某个具体行为，而不需要完整规格，就单独使用 /tdd；如果你想针对一个固定的基准点审查某个分支或 PR，则单独使用 /code-review。

   当工作以拉取请求（PR）的形式提交时，/pr 负责规划 PR 正文：用最小的可视化内容展示变更，提供前后对比的证据以证明其有效，并给出单向门或双向门的判断。它由模型调用，因此 Agent 每次编写 PR 时都会自动使用它。

4. /retro 负责闭环。每次构建之后，尤其是构建过程出了岔子时，它会回顾整个会话，并针对 Agent 的环境而非代码提出修改建议：导航指引、自动化检查、/code-review 所执行的编码规范、引导文件、工具链等。机械性的错误会变成确定性的检查，而需要判断的事项则会变成编码规范。下一次构建将从一个更好的环境出发。

上下文卫生

步骤 1–3 要在同一个连续上下文窗口中完成（在 /to-tickets 之后再压缩或清除），这样调研、规格说明和工单才能基于同一套思路逐步展开。每次 /implement 都要从全新的上下文开始，并根据工单开展工作。在要回顾的会话中运行 /retro，然后再清除上下文；清除后，则将其指向该会话的日志。

这方面的限制是**智能区间**：模型仍能敏锐推理的窗口范围（最先进的模型约为 150k 个 token）。如果在运行 /to-tickets 之前会话已接近这个范围，不要在性能下降时硬撑；在最近的阶段边界运行 /compact，然后继续（参见“阶段边界”）。

入门路径

从某种会引出工作的起始情形出发，然后并入主流程。

• 出问题了 → /diagnosing-bugs。适用于棘手的问题：初看难以发现的 bug、间歇性故障，或在两个已知正常状态之间悄然引入的回归。它会先要求建立紧密的反馈循环（一条命令就能让这个 bug 复现失败），然后再着手修复并添加回归测试。修复完成后，在同一会话中运行 /retro，询问如何才能避免这个 bug；如果真正的发现是缺少合适的切入点来锁定问题，那就该使用 /improve-codebase-architecture。

• 规模庞大、尚不明朗的工作：从零开始的项目，或大到无法在一次会话中完成的功能构建 → /wayfinder，这里认知负荷最高的工作流。当从当前状态到目标的路径尚不清晰时，它会在问题跟踪器上绘制一张由决策工单组成的共享地图，逐一解决，产出的是决策，而非交付物，直到拨开迷雾、路径清晰为止。/grill-with-docs 用来打磨你能在一次会话中把握的想法，而 wayfinder 适用于你无法在一次会话中把握的想法；它更慢、内容更密集，因此只在确有必要时使用，切勿用于范围明确的功能。

  地图清晰后，它会交接，而不是构建：转入主流程的 /to-spec，将地图中相互关联的决策整理成可构建的计划，然后照常使用 /to-tickets 和 /implement。直接从地图跳到 /implement 会跳过这一步整理，并丢掉相互关联的细节；因此，只有当工作最终确实很小时，才直接转到 /implement。

代码库健康

不是功能开发，只是日常维护。

• /improve-codebase-architecture 可在有空时运行，确保代码库便于 Agent 操作。它会揭示可深化的机会；选中其中一项后，便会产生一个想法，你可以通过 /grill-with-docs 将其带入主流程。它负责调查并找出候选项；/codebase-design（见下文）则是设计所选方案的工作台。

背后的术语

两个由模型调用的参考指南，位于其他技能的底层，各自是其术语体系的唯一事实来源。当问题出在用词而非流程时，可以直接使用它们；也可以让上面的技能调用它们。

• /domain-modeling：打磨项目的领域语言：质疑含糊的术语，厘清一词多义的词语（例如一个 “account” 承担了三种职责），并将难以逆转的决策记录为 ADR。这是 /grill-with-docs 用来确保 GLOSSARY.md 始终是清晰术语表的主动方法。
• /codebase-design 提供深模块设计的术语体系（模块、接口、深度、切入点、适配器、杠杆、局部性），用于设计模块的形态：在清晰的切入点之后，以精简的接口承载大量行为。/tdd 和 /improve-codebase-architecture 都使用这套术语。

阶段边界

阶段是会话中的一段工作：深入探讨、实现、QA。在两个阶段的边界处，你有五种选择；在整张图中，这可能是最模糊的决策：

• Continue：留在当前上下文。不花费任何东西，也不会丢失任何东西。
• /clear：清空窗口，适用于这里的内容与接下来无关的情况。
• /handoff 会写入一个可移植的 Markdown 文件。适用范围很窄：仅用于新工具框架、新目录、同事，或在阶段中途分出一项支线任务。它带来的是可移植性。
• Subagent：把范围明确的任务交给它自己的窗口，然后获取报告。
• /compact 会压缩当前上下文，并用它为新会话提供初始信息。这是默认选项，位于决策树底部，而不是首先想到的选择。

阅读 PHASE-BOUNDARIES.md，了解有序决策树：五个问题、每个分支背后的推理，以及为什么基于一手资料的成本意味着应该首先排除 Continue。在阶段边界处做出决定；阶段中途则继续，或把剩余工作拆分给多个 subagent。

独立工具

完全不属于主流程。

• /grill-me：与 /grill-with-docs 一样进行不间断访谈，但它是无状态的：不会在本地保存任何内容，也不会创建 GLOSSARY.md。当你不在工作目录中时使用它（例如完善计划、设计、文稿，或任何不隶属于代码仓库的内容）。如果你在工作目录中，则使用 /grill-with-docs：它会进行相同的访谈并留下记录，因此是更好的选择。
• /grilling 是访谈本身的基础原语：轮次、前沿问题、事实由 Agent 负责，决策则由你做出。/grill-me 和 /grill-with-docs 是两种指定的入口，/wayfinder 和 /improve-codebase-architecture 内部也会运行它。只有在你想直接进行访谈、不需要任何封装时，才直接使用它。
• /prototype 是一个小型的一次性程序，用于回答某个设计问题：这种状态模型是否合适，或者这个 UI 应该是什么样子。“一次性”限制的是代码的编写方式，并不意味着承诺销毁它：其结论会融入正式代码，而原型本身会作为一手资料保留在从 main 分出的 prototype/<name> 分支上，并在实现 issue 中链接。它是主流程第 2 步中的一个绕行选项，但任何难以通过书面推敲解决的设计问题，都可以使用它。
• /research：把阅读资料的工作委派给后台 Agent：它会根据一手资料调查问题，然后在代码仓库中留下带引用的 Markdown 文件。调查期间，你可以继续工作。它生成的文件应在 /grill-with-docs 中带入主流程，因为研究是为思考提供依据，而不是取代思考。
• /wait-what 用于纠正未能传达清楚的信息。在对话中途、任何其他技能中都可以使用它；Agent 会结合你缺失的上下文，用通俗易懂的语言并使用 GLOSSARY.md 中的词汇，重新表达刚才说的内容。它是事后补救；/grill-with-docs 则是事前解决方案，因为提前约定共同语言，才能避免一开始就出现术语堆砌。
• /teach：跨多个会话学习一个概念，并使用当前目录作为有状态的工作区。
• /writing-for-agents 是编写供 Agent 使用的文档的参考指南：技能、AGENTS.md，以及被明确引用的文档。

前置条件

/setup-repo：在首次工程流程开始前运行，用于配置问题跟踪器、分类标签、文档布局和其他技能所依赖的编码规范。它会依次运行 /setup-matt-pocock-skills 和 /setup-coding-standards，并预先填入你通常会给出的答案；如果你只想完成部分设置，也可以使用这些基础原语。自定义问题跟踪器同样可用。