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 应该是什么样子。“一次性”是对代码编写方式的约束，并不意味着要销毁它：其成果会合并到正式代码中，而原型本身会作为一手资料保留在从主分支分出的 prototype/<name> 分支上，并在实现问题中提供链接。它是主流程第 2 步中的绕行方案，但只要设计问题难以通过书面讨论敲定，随时都可以使用。
• /research：将资料阅读工作委派给后台 Agent：它会针对一手资料调查问题，然后在代码仓库中留下带引用的 Markdown 文件。它阅读时，你可以继续工作。生成的文件可带入主流程，在 /grill-with-docs 中使用，因为研究是为了辅助思考，而不是取代思考。
• /to-questionnaire：当阻碍你的信息不在你自己或代码仓库中，而在其他人那里时，就使用它；它会生成一份问卷供对方填写。它与 /grill-me 互为反向：它不会就主题采访你，而是会就问卷的发送采访你（发送给谁、你需要对方提供什么），并针对信息缺口设计问题。收到的内容可用于 /grill-with-docs 或 /to-spec。
• /wizard：用于只能由人类完成的步骤：配置基础设施、设置凭据或 CI 密钥、在不熟悉的第三方控制面板中逐步操作，或执行一次性的迁移或切换。它会生成一个交互式 bash 脚本，打开每个 URL、收集每个值，并将其写入 .env 和 GitHub 密钥，这样就不必每次都向 Agent 重新解释操作流程。它由模型调用，因此 Agent 一遇到只有你能解决的障碍就会使用它。如果 Agent 能自己完成，就应该自己完成；只有确实需要人类参与时才用它。
• /wait-what：用于纠正未能让人理解的消息。可在对话中途、任何其他技能内部使用；Agent 会结合你之前缺少的上下文，用通俗易懂的语言并采用 GLOSSARY.md 中的词汇，重新解释刚才说过的内容。它可以事后补救；/grill-with-docs 则是事前的解决方案，因为及早商定共同语言，才能避免术语一开始就出现。
• /teach：利用当前目录作为有状态的工作区，通过多次会话学习一个概念。
• /writing-for-agents 是编写供 Agent 使用的文档的参考资料：技能、AGENTS.md 和定向文档。

前置条件

/setup-agent-skills：在首次运行工程流程前使用，用于配置问题跟踪器、分类标签和其他技能所依赖的文档布局。也支持自定义问题跟踪器。