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 的实现者各自运行 /tdd，并对集成分支运行一次 /code-review。如果你只想以测试优先的方式构建一个具体行为，而不需要完整规格说明，就单独使用 /tdd；如果你想根据固定基准审查某个分支或 PR，就单独使用 /code-review。

   工作以拉取请求的形式提交时，/pr 会组织 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 阅读的文档（如技能、AGENTS.md 和被引用的文档）的参考。

前置条件

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

可选的 fork 边界工具

• /to-goal 将已批准的证据编译成可移植的执行契约。
• /goal-crafter 帮助编写可验证的目标，可以独立编写，也可以基于已批准的证据编写。
• /execute-spec-in-fork 将范围明确的已批准工作传送到 Codex App fork，并验证其回执。
• /spec-executor 执行范围明确的已批准源，并返回证据；SPEC READY 是可选项。
• /roundtable 从多个角度检验已形成的提案。
• /resolving-merge-conflicts 仍是由 fork 维护的独立技能，用于按意图解决冲突。

可独立使用这些工具，也可以组合使用其产物。可选的规划、测试和审查技能不是 fork 自有核心的运行时依赖项。