pedro-oscar/shorts-ai

询问 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 一次性实现整个规范。它将工单作为任务图读取，跨就绪的前沿并行运行实现子代理，并将所有内容归并到一个集成分支上。当你更想编排构建流程而不是亲自驱动每个工单时，可以选用此方式。
   • 否 → 在当前上下文窗口中直接使用 /implement。

   无论哪种方式，代码的构建都是通过驱动 /tdd（一次一个红-绿循环）来完成，并以 /code-review（对 diff 进行标准和规范的双轴审查）收尾。/implement 每个工单都会运行这两者；/implement-spec 的每个实现者各自驱动 /tdd，然后对集成分支运行一次 /code-review。当你只是想在没有完整规范的情况下，以测试优先的方式构建一个具体行为时，可以独立使用 /tdd；当你想针对一个固定点审查分支或 PR 时，也可以独立使用 /code-review。

   当工作以拉取请求的形式提交时，/pr 负责整理其主体：展示变更的最小视觉证据、证明其有效的变更前后对比，以及标识这是一单向门还是双向门决策。它由模型调用，因此每当 AI 助手编写 PR 时，都会自动使用它。

4. /retro 进行复盘闭合。在一个构建任务之后，特别是当它出现问题之后，它会回顾整个会话，并建议对 AI 助手的环境（而非代码）进行更改：导航提示、自动化检查、/code-review 所强制执行的编码标准、引导文件、工具配置。机械性的错误变为确定性检查；判断性的问题变为编码标准。这样，下一个构建任务就能从更好的环境开始。

上下文卫生

将步骤 1 到 3 保持在一个不间断的上下文窗口中（在 /to-tickets 之前不要压缩或清除上下文），以便需求打磨、规范和工单都建立在相同的思考基础上。然后每个 /implement 都是从工单开始的全新会话。/retro 应在它要回顾的会话中、在你清除上下文之前运行；清除之后，则指向该会话的日志。

这一限制取决于智能区（https://www.aihero.dev/ai-coding-dictionary/smart-zone）：即模型仍能清晰推理的窗口（最先进的模型约为 150k token）。如果一个会话在到达 /to-tickets 前就接近该限制，不要继续在降级状态下推进；应在最近的阶段边界执行 /compact 并继续（参见阶段边界）。

入口

一些起始情况会产生工作，然后汇入主流程。

• 错误和请求不断堆积 → /triage。它将问题按分类角色进行流转，并生成可供 AI 助手直接处理的工单，供后续的 /implement 领取。

  分类仅适用于不是你创建的问题：错误报告、外来的功能请求，以及任何原始提交的内容。由 /to-tickets 生成的工单已经是 AI 助手就绪状态，因此无需对其分类。

• 某功能出问题了 → /diagnosing-bugs。针对那些棘手的问题：一眼看不出原因的错误、间歇性闪断、在两个已知正常状态之间悄悄引入的回归。它在获得一个紧密的反馈循环（一个能立即复现当前错误的命令）之前拒绝进行理论分析，然后通过回归测试进行修复。修复完成后，在同一会话中运行 /retro，询问是什么本可以预防该错误；如果真正的发现是没有好的隔离层来锁定它，那么这就是 /improve-codebase-architecture 的任务。

• 一项庞大而模糊的工作：绿色项目或大型功能构建，过大以致于一个会话无法完成 → /wayfinder，这是这里认知要求最高的流程。当从当前状态到目标状态的路还不清晰时，它会在问题跟踪器上绘制一个由决策工单组成的共享地图，并逐一解决这些工单，产出决策，而非交付物，直到迷雾散尽、路径清晰。/grill-with-docs 用于打磨可以在一个会话中容纳的想法，而 wayfinder 则用于那些无法在一个会话中容纳的想法；它更慢、更密集，因此请仅在的确需要时使用它，而绝不用于一个范围明确的功能。

  当地图清晰后，它将任务交接出去，而不是直接构建：汇入主流程的 /to-spec 步骤，该步骤将地图中相互关联的决策压缩成一个可构建的计划，然后是 /to-tickets 和 /implement。直接将地图循环输入 /implement 会跳过这个压缩步骤，并丢弃相互关联的细节，因此只有在工作确实很小的情况下才直接使用 /implement。

代码库健康

不是功能开发，只是日常维护。

• /improve-codebase-architecture 在你空闲时运行，以保持代码库对 AI 助手友好。它会识别出可深化改造的机会；选择一个机会会_产生一个想法_，你可以将其带入主流程的 /grill-with-docs 步骤。它是用于发现候选方案的普查；/codebase-design（如下所述）则是你设计所选方案的工作台。

底层词汇

两个由模型调用的引用，运行在其他技能之下，每一个都是其词汇的唯一真实来源。当词语（而非流程）成为问题时，直接使用它们；或者让上述技能将它们拉入。

• /domain-modeling：打磨项目的领域语言：挑战模糊的术语、解决过载的词语（例如“账户”承担了三个职责）、将难以撤销的决策记录为 ADR。这是 /grill-with-docs 驱动的主动规程，旨在保持 GLOSSARY.md 成为一份干净的术语表。
• /codebase-design 是用于设计模块形状的深层模块词汇（模块、接口、深度、接缝、适配器、杠杆、局部性）：在一条干净的接缝后面，用小接口承载大量行为。/tdd 和 /improve-codebase-architecture 都使用此词汇。

阶段边界

阶段是一个会话内的一块工作：需求打磨、实现、质量保证。在两个阶段的边界处，你有五个选项，在它们之间进行选择是整个地图中最模糊的决策：

• 继续：原地不动。零成本，无损失。
• /clear：清空窗口，当当前内容对下一步无关紧要时使用。
• /handoff 写一个可移植的 markdown 文件。用途狭窄：仅适用于新工作环境、新目录、同事，或阶段中分叉出一个旁支任务。它带来的是可移植性。
• 子代理：将一个范围狭窄的任务发送到其自己的窗口，并获取一份报告回来。
• /compact 压缩当前上下文，并用它来启动一个全新的会话。这是默认选项，位于决策树的底部而非首选。

阅读 PHASE-BOUNDARIES.md 了解有序的决策树：五个问题、每条分支背后的推理，以及为什么基于主要来源的成本使继续成为第一个需要排除的选项。在边界处做出决策；在阶段中间，要么继续，要么将剩余部分拆分为子代理。

独立技能

完全脱离主流程。

• /grill-me：与 /grill-with-docs 同样无情的访谈，但是无状态的：它不在本地保存任何内容，也不构建 GLOSSARY.md。当你不在工作目录下工作时（例如打磨一个计划、一个设计、一篇文章，或任何没有底层仓库的东西），使用它。如果你在工作目录下，请使用 /grill-with-docs：它运行同样的访谈并留下纸面记录，因此是严格更好的选择。
• /grilling 是访谈核心本身：轮次、前沿、事实是 AI 助手的工作，决策是你的工作。/grill-me 和 /grill-with-docs 是两种命名的进入方式，而 /triage、/wayfinder 和 /improve-codebase-architecture 都在内部运行它。仅在你想要没有包装的原始访谈时直接使用它。
• /prototype 是一个小型的、一次性程序，用于回答一个设计问题：这个状态模型感觉对吗，或者这个 UI 应该是什么样子。一次性是对代码编写方式的约束，而非销毁的承诺：答案会融入真实代码，原型本身作为主要来源保存在一个基于主库的 prototype/<name> 分支上，并由实现工单引用。这是主流程步骤 2 中的绕行路径，但任何时候当设计问题难以在纸上定论时，都可以使用它。
• /research：将阅读工作委托给一个后台 AI 助手：它针对主要来源调查一个问题，然后在仓库中留下一个带引用的 Markdown 文件。在它阅读的同时，你可以继续工作。它产生的文件会被带入主流程的 /grill-with-docs 步骤，因为研究喂养思考，而非取代思考。
• /to-questionnaire 适用于阻碍你的东西不在你脑子里或代码库中，而在别人的脑子里的情况，它会为你生成一份问卷让他们填写。这是 /grill-me 的反向操作：它不是就主题对你进行访谈，而是就发送对象（问卷发给谁、你需要什么样的回复）对你进行访谈，并将问题瞄准信息缺口。拿到的回复是 /grill-with-docs 或 /to-spec 的素材。
• /wizard 用于只有人类才能执行的步骤：配置基础设施、设置凭证或 CI 密钥、点击一个不熟悉的第三方仪表盘、运行一次性的迁移或切换。它会生成一个交互式 bash 脚本，打开每个 URL、捕获每个值，并将其写入 .env 文件和 GitHub 密钥，这样整个过程就不再需要每次向 AI 助手重新解释。由模型调用，因此一旦 AI 助手遇到只有你能通过的障碍，它就会自动使用。如果 AI 助手自己能做，它就应该自己做；这是针对人类确实在循环中的情况。
• /wait-what 是对某个未能理解的信息的纠正。在对话过程中，在任何其他技能内部使用它，AI 助手会使用你当时缺失的上下文，用通俗易懂的英语（使用 GLOSSARY.md 中的词汇）重新解释它刚才所说的话。它是在事后起作用；/grill-with-docs 是事前的解决方案，因为尽早达成共同语言可以防止行话的产生。
• /teach：跨多个会话学习一个概念，将当前目录用作有状态的工作空间。
• /writing-for-agents 是关于编写 AI 助手消费的文档（skills、AGENTS.md、作为目标的文档）的参考。

前提条件

/setup-matt-pocock-skills：在运行你的第一个工程流程之前执行，以配置其他技能所假定的问题跟踪器、分类标签和文档布局。自定义问题跟踪器也可以工作。