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 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 跟踪器同样适用。