ask-matt

Files (3)

• PHASE-BOUNDARIES.md
• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Ask Matt

你记不住每一个 skill，所以来问。

一条 **流程（flow）** 是穿过各 skill 的路径。多数路径沿着一条 **主流程** 走，另有两条 **入口匝道** 并入主流程。其余要么是独立 skill，要么是在底层运行的词汇层。

## 主流程：想法 → 上线

大多数工作走的路线。你有一个想法，想把它做出来。

1. **`/grill-with-docs`** — 用访谈把想法磨锋利。只要你是在 **工作目录里干活**，就从这里开始：它是有状态的，会把学到的内容留在 `CONTEXT.md` 和 ADR 里。（没有工作目录？用 `/grill-me` — 见独立 skill。两者跑的是同一个 `/grilling` 原语；`grill-with-docs` 会留下书面记录，只要有仓库能放下这些记录，它就是两者中更好的那个。）
2. **分支 — 每个问题都能在对话里敲定吗？** 若某个问题需要可运行的答案（状态、业务逻辑、必须亲眼看到的 UI），就绕道做原型，双向用 **`/handoff`** 衔接（原型活在自己的目录里，而这正是 `/handoff` 的用途 — 见阶段边界）：
   - **`/handoff`** 出去，然后对新文件开一个全新会话，
   - **`/prototype`** 用一次性代码回答那个问题，
   - **`/handoff`** 把学到的带回来，并在原来的想法线程里引用它。
3. **分支 — 这是一次跨多会话的构建吗？**
   - **是** → **`/to-spec`**（把线程变成 spec），再 **`/to-tickets`** 拆成 tracer bullet 的 ticket，每个 ticket 声明自己的 **阻塞边**。在本地 tracker 上，每个 ticket 是 `.scratch/<feature>/issues/` 下的一个文件，按阻塞优先手工推进；在真正的 tracker 上，这些边会变成原生阻塞链接，于是任何阻塞已完成的 ticket 都可以被领取 — 每个 ticket 启动一次 **`/implement`**，每次之间 **`/clear`** 掉 context。每个 ticket 是自包含的，所以上一个 ticket 的 context 可以丢掉。
   - **否** → 就在这里、同一个 context window 里直接 **`/implement`**。

   无论哪条路，**`/implement`** 都通过内部驱动 **`/tdd`** 来构建每个 issue — 一次一块 red-green — 收尾时跑 **`/code-review`**，对 diff 做双轴审查（Standards + Spec），然后再提交。只想测试先行地做一个具体行为、而不需要完整 spec 时，单独用 **`/tdd`**；想对照某个固定点审查分支或 PR 时，单独用 **`/code-review`**。

### Context 卫生

把步骤 1–3 保持在 **同一个不间断的 context window** 里 — 在 `/to-tickets` 之前不要 compact 或 clear — 这样 grilling、spec 和 tickets 都建立在同一套思考上。之后每次 `/implement` 都从空白开始，以 ticket 为工作依据。

上限是 **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**：在这个窗口内（当前最强模型大约 ~150k tokens）模型仍然能锐利推理。若会话在到达 `/to-tickets` 之前就接近这个上限，不要在退化状态下硬撑 — 在最近的阶段边界 `/compact`，然后继续（见阶段边界）。

## 入口匝道

一种起始处境会先产生工作，再并入主流程。

- **Bug 和请求堆起来了** → **`/triage`**。它把 issue 送过 triage 角色，产出 agent 可接手的 issue，之后由 **`/implement`** 领取。

  Triage 只用于 **不是你创建的** issue — bug 报告、外来的功能请求、任何原始抵达的东西。`/to-tickets` 产出的 ticket 已经是 agent 可接手的，所以 **不要对它们做 triage**。

- **有东西坏了** → **`/diagnosing-bugs`**。给硬骨头用：一眼看不穿的 bug、间歇性失败、在两个已知良好状态之间悄悄溜进来的回归。在拥有 **紧反馈循环** — 一条已经会在 *这个* bug 上变红的命令 — 之前，它拒绝空想；然后用回归测试来修。事后回顾若真正发现是没有好的 seam 能把 bug 锁死，就交接给 **`/improve-codebase-architecture`**。

- **一场巨大、雾蒙蒙的努力 — 绿地项目或大功能构建，大到一次会话装不下** → **`/wayfinder`**，这里认知负担最重的流程。从这里到目的地的路还看不见时，它在 issue tracker 上画出一张由 **决策 ticket** 组成的 **共享地图**，一次解决一个 — 产出的是 **决策，不是交付物** — 直到雾被推开、路变得清楚。**`/grill-with-docs`** 磨的是你能在一次会话里握住的想法；wayfinder 是给握不住的那个 — 它更慢、更密，所以只留给那种情况，绝不要用在范围已经清楚的功能上。

  当地图变清晰，**它交接，不构建**：在 **`/to-spec`** 并入主流程，把地图上相互链接的决策折叠成可构建的计划，然后照常 `/to-tickets` 和 `/implement`。把地图直接绕进 `/implement` 会跳过那次折叠，把链接起来的细节扔掉 — 只有当这场努力其实真的很小，才直接去 `/implement`。

## 代码库健康

不是功能工作 — 是保养。

- **`/improve-codebase-architecture`** — 只要有空档、想让代码库继续适合 agent 操作，就跑它。它会浮现 **加深机会**；选中一个会 _生成一个想法_，你可以把它带进主流程的 `/grill-with-docs`。它是找出候选的勘察；**`/codebase-design`**（见下）是你在上面设计所选方案的工作台。

## 底层词汇

两个由模型调用的参考，运行在 *其他 skill 之下* — 各自是其词汇的单一事实来源。当问题出在 **用词** 而不是流程时，直接去用它们；或者让上面的 skill 把它们拉进来。

- **`/domain-modeling`** — 磨利项目的 *领域* 语言：挑战模糊术语、拆开过载的词（一个「account」干了三份活）、把难以逆转的决策记成 ADR。这是 `/grill-with-docs` 用来让 `CONTEXT.md` 保持干净词汇表的主动纪律。
- **`/codebase-design`** — deep module 词汇（module、interface、depth、seam、adapter、leverage、locality），用来设计一个模块的 *形状*：在干净的 seam 上，小接口后面藏大量行为。`/tdd` 和 `/improve-codebase-architecture` 都说这套话。

## 阶段边界

一个 **阶段（phase）** 是会话内部的一块工作 — grilling、实现、QA。在两者之间的 **边界** 上你有五个选项，在它们之间做选择是整张地图里最模糊的决定：

- **继续** — 留在原地。零成本，零损失。
- **`/clear`** — 清空窗口，当这里没有任何东西对下一步有用。
- **`/handoff`** — 写一份可携带的 markdown 文件。用途很窄：只用于 **新 harness**、**新目录**、**同事**，或在 **阶段中途** 分叉旁路任务。它买到的是可携带性。
- **Subagent** — 把范围收得很紧的任务送到它自己的窗口，拿回一份报告。
- **`/compact`** — 压缩当前 context，并用它播种一个新会话。这是 **默认项**，在决策树底部，而不是第一伸手就去的。

阅读 [PHASE-BOUNDARIES.md](PHASE-BOUNDARIES.md) 看有序决策树 — 五个问题、每条分支背后的理由，以及为什么 primary source 的代价让 **继续** 必须最先被排除。在边界 **上** 做决定；阶段中途，继续做，或把剩下的拆给 subagent。

## 独立 skill

完全离开主流程。

- **`/grill-me`** — 与 `/grill-with-docs` 同样不留情面的访谈，但是 **无状态的**：本地什么都不保存，也不建 `CONTEXT.md`。在你 **不是在工作目录里干活** 时用它 — 磨一份计划、一个设计、一篇文字，底下没有仓库的任何东西。若你在工作目录里，改用 `/grill-with-docs`：它跑同样的访谈并留下书面记录，因此严格地更好。
- **`/grilling`** — 访谈原语本身：轮次、前沿；事实是 agent 的活，决策是你的。`/grill-me` 和 `/grill-with-docs` 是两条具名入口，`/triage`、`/wayfinder` 和 `/improve-codebase-architecture` 都会在内部跑它。只有当你想要没有包装的访谈本身时，才直接用它。
- **`/resolving-merge-conflicts`** — 处理进行中的 merge 或 rebase 冲突，一块一块来，按追溯到各方 primary source 的 **意图** 解决，而不是挑行，然后完成这次操作。它从不跑 `--abort`。独立、不在任何流程上：已经身处冲突中途时再用它。
- **`/prototype`** — 一个小的、一次性的程序，用来回答一个设计问题：这个状态模型感觉对不对，或这个 UI 该长什么样。一次性是对代码怎么写的约束，不是保证要毁掉它：答案会折进真正的代码，原型本身作为 **primary source** 保存在离开 main 的 `prototype/<name>` 分支上，并从实现 issue 指向它。它是主流程第 2 步的绕道，但任何难以在纸上敲定的设计问题都可以用它。
- **`/research`** — 把阅读苦力委托给 **后台 agent**：它对照 **primary source** 调查一个问题，然后在仓库里留下一份带引用的 Markdown 文件。它在读的时候你继续干活。它产出的文件是要 *带进* 主流程 `/grill-with-docs` 的东西 — 研究喂养思考，并不替代思考。
- **`/to-questionnaire`** — 当挡住你的东西不在你脑子里、也不在代码库里，而在 **别人脑子里** 时，给对方写一份要填的问卷。它是 `/grill-me` 的反面：不是就主题采访你，而是就 **发送** 采访你 — 寄给谁、你需要拿回什么 — 并把问题对准那个缺口。回来的材料给 `/grill-with-docs` 或 `/to-spec` 用。
- **`/wizard`** — 给只有 **人** 能走的那些步骤：开通基础设施、配置凭证或 CI secrets、点开不熟悉的第三方控制台、跑一次性迁移或切换。它生成交互式 bash 脚本，打开每个 URL、捕获每个值，并写入 `.env` 和 GitHub secrets — 这样流程就不再是每次都要向 agent 重新解释的东西。由模型调用，所以 agent 一撞上只有你能过的墙就会伸手去用。若 agent 自己就能做，它就该自己做；这是给人真正在环里的地方。
- **`/wait-what`** — 给没听懂的那句话做矫正。在对话中途、在任何其他 skill 内部使用，agent 会用你当时缺的 context、用白话、用 `CONTEXT.md` 词汇，把刚说的话重新讲一遍。它是事后补救；`/grill-with-docs` 是事先预防，因为早早约定的共享语言才是阻止行话出现的东西。
- **`/teach`** — 跨多个会话学一个概念，把当前目录当作有状态的工作区。
- **`/writing-for-agents`** — 写给 agent 消费的文档的参考：skills、AGENTS.md、被指向的文档。

## 前置条件

**`/setup-matt-pocock-skills`** — 在第一次工程流程之前跑，配置其他 skill 所假定的 issue tracker、triage 标签和文档布局。自定义 issue tracker 也可以。

From shenjunjian/matt-skill-cn, MIT.

More from shenjunjian/matt-skill-cn