ask-matt

在开展面向代码库的工作前，请先阅读 ../../WORK-ROUTING.md。它是项目文档、工作流选择、计划归属和收尾工作的共享路由依据。

向 Matt 求助

你不可能记住每项技能，所以尽管询问。

流程是穿梭于各项技能之间的一条路径。大多数路径沿着一条主流程展开，另有两条入门路径汇入其中。其他技能要么独立使用，要么作为底层的术语层运行。

主流程：从想法到交付

大多数工作都会走这条路径。你有一个想法，并希望将其实现。

1. /grill-with-docs — 通过访谈打磨想法。只要你在工作目录中工作，就从这里开始：它会保留状态，将学到的内容记录在 CONTEXT.md 和 ADR 中。（没有工作目录？使用 /grill-me——参见“独立使用”。二者都运行相同的 /grilling 基础流程；grill-with-docs 会留下文档记录，因此只要有代码库可供记录，它就是更好的选择。）

2. 分支——你能否在对话中解决所有问题？ 如果问题需要通过可运行的答案来解决（状态、业务逻辑，或必须亲眼查看的 UI），就绕道制作原型，并通过双向的 /handoff 衔接（原型位于自己的目录中，而这正是 /handoff 的用途——参见“阶段边界”）：

   • 先 /handoff 出去，然后针对该文件开启一个全新会话，
   • 使用 /prototype 通过一次性代码回答问题，
   • 再用 /handoff 带回所学内容，并在原始想法的讨论串中引用它。

3. 分支——这是否是一个跨多个会话的构建？

   • 是 → 使用 /to-spec（将讨论串整理为规格说明），然后使用 /to-tickets 将其拆分为示踪子弹式任务票，每个任务票都要声明其阻塞依赖。在本地跟踪器中，每个任务票对应 .scratch/<feature>/issues/ 下的一个文件，并由人工按阻塞项优先的顺序处理；在实际的跟踪器中，这些依赖会成为原生阻塞链接，因此任何阻塞项已完成的任务票都可以领取——每个任务票都启动一次 /implement，并在每次之间使用 /clear 清除上下文。每个任务票都是独立完整的，因此最后一个任务票的上下文可以丢弃。
   • 否 → 就在这里、同一个上下文窗口中使用 /implement。

   无论哪种情况，/implement 都会在内部通过 /tdd 来构建每个问题——一次完成一个红绿循环切片——然后在提交前运行 /code-review 收尾，对差异进行两个维度的审查（规范 + 规格说明）。如果你只想先写测试再实现某个具体行为，而不需要完整的规格说明，就单独使用 /tdd；如果你想依据一个固定基准审查分支或 PR，就单独使用 /code-review。

上下文管理

步骤 1–3 应在同一个不中断的上下文窗口中完成——在 /to-tickets 之后再压缩或清除上下文——这样访谈、规格说明和任务票才能建立在同一套思路上。之后，每次 /implement 都从全新上下文开始，并依据任务票开展工作。

这条建议的限制是**智能区**：模型仍能清晰推理的窗口范围（最先进的模型约为 150k tokens）。如果会话在 /to-tickets 之前就接近上限，不要在性能下降时硬撑——在最近的阶段边界使用 /compact，然后继续（参见“阶段边界”）。

入门路径

一种会产生工作、随后并入主流程的起始情境。

• Bug 和请求堆积如山 → /triage。它会通过分诊角色处理问题，并产出可供 Agent 直接处理的问题，之后由 /implement 接手。

  分诊只适用于并非由你创建的问题——Bug 报告、收到的功能请求，以及任何原始提交的问题。/to-tickets 生成的工单已经可以由 Agent 直接处理，所以不要对它们进行分诊。

• 出了问题 → /diagnosing-bugs。适用于棘手情况：乍看之下找不出原因的 Bug、间歇性故障，以及在两个已知正常状态之间悄然出现的回归问题。在有紧密反馈循环之前，它不会进行推测——也就是先找到一条已经能针对这个 Bug 运行失败的命令——然后再修复并添加回归测试。如果事后复盘发现，真正的问题是缺少能锁定 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 用来保持 CONTEXT.md 作为清晰词汇表的实践方法。
• /codebase-design — 提供深模块设计词汇（模块、接口、深度、切入点、适配器、杠杆、本地性），用于设计模块的形态：在清晰的切入点后，以小型接口承载大量行为。/tdd 和 /improve-codebase-architecture 都会使用这套词汇。

阶段边界

阶段是一个会话中的一段工作——梳理需求、实现、QA。在两个阶段的边界处，你有五种选择；在整个决策图中，这是最难判断的一项：

• Continue — 留在当前会话。不会产生任何成本，也不会丢失任何内容。
• /clear — 清空上下文窗口，适用于当前内容对接下来的工作毫无用处的情况。
• /handoff — 编写一个可移植的 markdown 文件。适用范围有限：仅用于新的 harness、新的目录、同事，或在阶段进行中分出一项独立任务。它带来的是可移植性。
• Subagent — 将一项范围明确的任务交给自己的上下文窗口，并取回报告。
• /compact — 压缩当前上下文，并用压缩后的内容开启一个新会话。这是默认选项，位于决策树底部，而不是首选。

阅读 PHASE-BOUNDARIES.md，了解按顺序排列的决策树——五个问题、每个分支背后的理由，以及为什么应当最先排除会带来原始来源成本的 Continue。请在边界处做出决定；阶段进行中则继续当前工作，或将剩余任务拆分给子 Agent。

独立使用

完全不属于主流程。

• /grill-me — 与 /grill-with-docs 一样进行不懈的访谈，但无状态：不会在本地保存任何内容，也不会创建 CONTEXT.md。当你不在工作目录中时使用它——完善计划、设计、文稿，或任何没有代码仓库的内容。如果你在工作目录中，请改用 /grill-with-docs：它会进行同样的访谈并留下记录，因此严格来说更合适。
• /grilling — 访谈本身的基本机制：轮次、前沿、事实由 Agent 负责，决策由你做出。/grill-me 和 /grill-with-docs 是两种指定的入口，而 /triage、/wayfinder 和 /improve-codebase-architecture 都会在内部运行它。只有在你想直接进行访谈、不需要任何封装时，才直接使用它。
• /resolving-merge-conflicts — 逐块处理正在进行的合并或变基冲突，根据追溯到双方主要来源的意图来解决，而不是挑选代码行，然后完成操作。它绝不会运行 --abort。这是独立于所有流程的工具：当你已经陷入冲突时使用它。
• /prototype — 编写一个小型、用后即弃的程序，回答一个设计问题：这种状态模型是否合适，或者这个 UI 应该是什么样子。用后即弃是对代码编写方式的限制，并不意味着一定要销毁它：答案会融入正式代码，而原型本身会作为主要来源保留在脱离 main 的 prototype/<name> 分支上，并从实现 issue 中链接到它。这是主流程第 2 步中的一条岔路，但只要设计问题难以通过讨论解决，随时都可以使用它。
• /research — 将阅读工作委派给后台 Agent：它会针对主要来源调查问题，然后在代码仓库中留下带引用的 Markdown 文件。它阅读时，你可以继续工作。它生成的文件可在 /grill-with-docs 中带入主流程——研究为思考提供依据，而不是取代思考。
• /to-questionnaire — 当阻碍你的信息不在你脑中或代码库里，而在其他人那里时，用它编写一份问卷让对方填写。这是 /grill-me 的反向版本：它不会就主题采访你，而是采访你，了解这份问卷的发送——要发给谁、需要对方回复什么——并针对信息缺口提出问题。收到的内容可用于 /grill-with-docs 或 /to-spec。
• /wizard — 用于只有人类才能完成的步骤：配置基础设施、设置凭据或 CI 密钥、在不熟悉的第三方控制面板中逐项操作、运行一次性迁移或切换。它会生成交互式 bash 脚本，打开每个 URL、收集每项值，并将其写入 .env 和 GitHub secrets——这样就不必每次都向 Agent 重新解释操作步骤。它由模型调用，因此 Agent 一遇到只有你才能解决的障碍，就会使用它。如果 Agent 能自行完成，就应该自行完成；此工具适用于确实需要人类介入的情况。
• /wait-what — 用于纠正未能让人理解的内容。在对话中途、任何其他技能内部都可以使用它；Agent 会结合你之前缺失的上下文，用通俗易懂的语言重新解释刚才说过的话，并使用 CONTEXT.md 中的词汇。它适用于事后补救；/grill-with-docs 则是事前的解决办法，因为尽早约定共同语言，就能避免术语一开始就冒出来。
• /teach — 利用当前目录作为有状态的工作区，跨多个会话学习一个概念。
• /writing-for-agents — 为 Agent 编写其会读取的文档的参考资料：技能、AGENTS.md、定向文档。

前置条件

/setup-matt-pocock-skills — 在首次运行工程流程前执行，以配置其他技能所依赖的 issue 跟踪器、triage 标签和文档布局。也支持自定义 issue 跟踪器。