ask-matt

问问 Matt

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

流程是穿过各项技能的一条路径。大多数路径沿着一条主流程前进，还有两条接入路径汇入其中。其余内容要么是独立技能，要么是贯穿其下方的词汇层。

主流程：从构想到发布

大多数工作都会走这条路线。你有一个构想，希望把它实现出来。

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，并在每个工单之间清除上下文。在本地跟踪器中，每个工单对应 .scratch/<feature>/issues/ 下的一个文件，手动按阻塞关系优先处理；在真正的跟踪器中，这些关系会成为原生阻塞链接，因此任何阻塞项都已完成的工单都可以领取。每个工单都是自包含的，所以最后一个工单的上下文可以丢弃。
     • 使用 /implement-spec 一次性完成整个规格。它会将工单作为任务图读取，让实现子 Agent 并行处理已就绪的前沿任务，并将所有内容合并到一个集成分支上。如果你更愿意统筹构建过程，而不是亲自推进每个工单，就选它。
   • 否 → 就在这里、同一个上下文窗口中使用 /implement。

   无论采用哪种方式，代码都会通过 /tdd（一次处理一个红绿迭代）构建完成，并以 /code-review 收尾，对差异进行双轴审查（标准 + 规格）。/implement 会在每个工单中运行这两项；/implement-spec 的实现器各自运行 /tdd，并对集成分支运行一次 /code-review。如果你只想先编写测试，再实现一个具体行为，而不需要完整规格，就单独使用 /tdd；如果你想针对一个固定基准审查分支或 PR，就单独使用 /code-review。

   工作以拉取请求形式提交时，/pr 会组织正文内容：展示改动的最精简视觉材料、证明改动有效的前后对比证据，以及单向或双向门决策。它由模型调用，因此 Agent 每次编写 PR 时都会使用它。

4. /retro 用于闭环。构建完成后，尤其是过程不顺利时，它会回顾会话，并建议改进 Agent 的环境而非代码：导航指引、自动化检查、/code-review 执行的编码规范、引导文件和工具。机械性错误会转化为确定性检查；需要判断的事项会转化为编码规范。这样，下一次构建就能从更好的环境开始。

上下文卫生

请将第 1–3 步保留在同一个不间断的上下文窗口中（在 /to-tickets 完成之前不要压缩或清空），这样拷问、规格说明和工单都基于同一套思路。之后每次 /implement 都从头开始，依据工单工作。在清空上下文之前，请在回顾对象所在的会话中运行 /retro；清空之后，则让它指向该会话的日志。

这里的限制是 智能区：即模型仍能敏锐推理的上下文窗口（当前最先进的模型约为 150k tokens）。如果会话在 /to-tickets 之前接近该上限，不要在能力下降的状态下硬撑；请在最近的阶段边界处运行 /compact，然后继续（参见阶段边界）。

入口

由某种起始情境产生工作，再汇入主流程。

• Bug 和需求不断堆积 → /triage。它会推动问题经过各个分类角色，并生成可供 Agent 处理的问题，之后由 /implement 接手。

  分类只适用于你并未创建的问题：Bug 报告、传入的功能需求，以及任何未经加工的原始内容。由 /to-tickets 生成的工单已经可供 Agent 处理，因此不要对它们进行分类。

• 出现故障 → /diagnosing-bugs。适用于较难的情况：初看无从下手的 Bug、间歇性出现的不稳定问题，以及在两个已知正常状态之间悄然引入的回归。它在获得一个紧凑的反馈回路（即一条已经能针对此个 Bug 报错的命令）之前，拒绝进行理论推测，然后通过回归测试进行修复。修复完成后，在同一会话中运行 /retro，探讨什么能够防止该 Bug；如果真正的结论是缺少可以锁定它的良好接缝，则应交由 /improve-codebase-architecture 处理。

• 庞大且模糊的工作：全新项目或规模过大、无法在单个会话内完成的大型功能开发 → /wayfinder，这是此处认知要求最高的流程。当从当前位置到达目标的路径尚不清晰时，它会在问题跟踪器上绘制一张共享地图，其中包含若干决策工单，并逐一解决它们。它产出的是决策，而非交付物，直到迷雾散去、路径清晰为止。而 /grill-with-docs 用于打磨可以在单个会话中掌握的想法，wayfinder 则面向无法在单个会话中掌握的想法。它更慢也更密集，因此应只在确有必要时使用，而非用于范围明确的功能。

  地图清晰之后，它的任务是交接，而非构建：在 /to-spec 处汇入主流程。/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 是深模块词汇（module、interface、depth、seam、adapter、leverage、locality），用于设计模块的形状：在一个干净的 seam 之后，用一个小的 interface 封装大量行为。/tdd 和 /improve-codebase-architecture 都使用这套词汇。

阶段边界

阶段是会话中的一段工作，例如梳理需求、实现、QA。在两个阶段的边界处，你有五种选择。在它们之间做选择是整张图中最模糊的决策：

• Continue：保持现状。没有成本，也不会丢失任何内容。
• /clear：清空窗口，适用于接下来的工作与此处内容无关的情况。
• /handoff 会写出一个可移植的 markdown 文件。适用范围很窄，仅用于新的 harness、新的目录、同事，或在阶段中途分出一个支线任务。它带来的好处是可移植性。
• Subagent：将一个范围严格限定的任务交给独立窗口处理，并取回报告。
• /compact 压缩当前上下文，并以此为种子开启一个新会话。这是默认选项，位于决策树底部，而不是首选项。

阅读 PHASE-BOUNDARIES.md 查看有序的决策树：五个问题、每个分支背后的理由，以及为什么主要来源的成本使 Continue 成为首先应当排除的选项。在边界处做出决策；阶段中途，则继续当前工作，或将剩余部分拆分给 Subagent。

独立使用

完全不在主流程之内。

• /grill-me：与 /grill-with-docs 相同的高强度访谈，但它是无状态的：不在本地保存任何内容，也不会生成 GLOSSARY.md。当你不在工作目录中时使用它，例如打磨计划、设计方案、一篇文章，或任何不依附于代码仓库的事项。如果你身处工作目录，请改用 /grill-with-docs：它进行同样的访谈，但会留下记录，因此严格来说是更好的选择。
• /grilling 是访谈的基础原语本身：包括轮次、待澄清前沿，事实由 Agent 负责，决策由你负责。/grill-me 和 /grill-with-docs 是两种具名入口，而 /triage、/wayfinder 和 /improve-codebase-architecture 都会在内部运行它。只有当你希望直接进行访谈、不需要任何外层封装时，才需要单独调用它。
• /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 会结合你缺失的上下文，用通俗的英文，并借助 GLOSSARY.md 中的词汇，重新表述它刚才所说的内容。它是事后补救；/grill-with-docs 则是前置的根治方法，因为尽早就共同语言达成一致，才能从源头避免术语难懂的问题。
• /teach：在多次会话中学习一个概念，并将当前目录用作有状态的工作空间。
• /writing-for-agents 是编写供 Agent 使用的文档的参考指南：包括 Skill、AGENTS.md 以及被指向的文档。

前置条件

/setup-matt-pocock-skills：在你进行第一个工程流程之前运行，用于配置其他技能所依赖的 Issue 跟踪器、分诊标签和文档结构。自定义 Issue 跟踪器同样适用。