进阶：技能档案

十章讲的是怎么用。这一页讲的是这些东西内部到底怎么运作—— 25 个技能，每个一张档案：做什么、什么时候用、产出什么、为什么这样设计、怎么判断跑对了、哪里最容易翻车。

这一页是给谁的

技能到底有几个

你会看到好几种数字。它们都不是错的，只是口径不同。先把这个搞清楚， 你才不会在网上抄到一个自相矛盾的说法。

25 个技能分五组，分工是这样的：

主链五步

先记住每一步的职责——这是最容易搞混的地方，因为五个名字看起来都在"规划"。 其实它们各自负责一个不同性质的动词。

/grill-with-docs —— 构建之前先对齐

做什么

用一轮轮的提问面谈你的计划或设计，直到你和 AI 对它有同一份理解；同时把谈出来的词汇和"够格的决策"写进你的仓库。

何时用

一次变更的开始、计划还模糊、用词还没敲定的时候。它是单会话工具——一次谈得完的计划用它。不在这个目录里用 /grill-me；装不下一个会话的用 /wayfinder；答案在别人脑子里的用 /to-questionnaire。

产出什么

术语落到根目录的 CONTEXT.md；够格的决策落到 docs/adr/ 下的 ADR。两个都是用到才建，没有东西结晶之前不存在。其余所有决定只留在对话里，哪都不去。

关键认知

它是这组里唯一有状态的：别的拷问技能把结论留在脑子里，它往磁盘写。而且术语一谈定就当场落盘，不攒到最后批量生成。决策要同时过三道门才写成 ADR，所以多数会话产出 0 条 ADR——这是设计如此，不是失败。它真正在造的东西是词汇表。

怎么判断

CONTEXT.md 在会话进行中逐条变化，而不是结尾爆发一大块；读起来是纯词汇，没有实现细节；代码库能回答的问题它去读代码，而不是拿来问你；ADR 很少或没有；它会质疑你用的某个词，因为词表里的定义不一样。

常见坑

它依赖 /grilling 和 /domain-modeling 两个技能，只装它一个会得到"一股脑把问题全抛出来 + 没有推荐答案"的劣质访谈。另外，你答话里的精确约束（排序保证、负向需求、数值默认值）会在下游被软化成模糊散文，所以规格写好后要对着自己的原话重读一遍。

/to-spec —— 把共识写成决策记录

做什么

把刚刚那段对话综合成一份规格，作为单个 issue 发布到你的 issue tracker。它不再访谈你——到这一步，"做决定"已经完成了。

何时用

变更大到要跨多个会话时才值得。还没决定过任何事 → 先跑 /grill-with-docs；装得进一个上下文窗口 → 直接 /implement；wayfinder 地图已经清了 → /to-spec #<地图 issue>。

产出什么

tracker 上的一个规格 issue。真实 tracker（GitHub、Linear）可以，也可以在 .scratch/ 下用本地 markdown，开箱即用。

关键认知

它存在的全部理由是上下文窗口会结束——拷问时谈定的一切都在一段即将被清掉的对话里。规格是决策的记录，不是做决定的地方：里面断言了任何你没有实际说过的东西，都是缺陷。写第一个字之前，它会先勾出这个功能将在哪些缝上被测试并跟你确认；偏好已有的缝、取最高的缝，理想情况整个改动只有一个缝。

怎么判断

它开始写，而不是又问你一轮；动笔前把缝摆给你看；用你项目的名词而不是通用产品黑话；里面每个决策你都记得自己做过；「范围外事项」那一段有真东西——你刻意拒绝做的那些，通常是整页最有用的几行。

常见坑

它的旧名叫 /to-prd（所以网上老资料会写 PRD）。它发布的规格会带一个 ready-for-agent 标签，而轮询这个标签的后台 agent 会把整份规格当成一张工单试图一次做完——这是被报告最多的粗糙面。重构、模块边界这类工作套这个模板不合身，因为它硬靠"用户故事"。规格第一次被实现教育就会过期，长期该留着的东西属于 CONTEXT.md 和 ADR，不是规格。

/to-tickets —— 切成曳光弹工单

做什么

把规格或对话切成一组工单，每张声明它的阻塞边——也就是哪些工单必须先完成。

何时用

有规格、且要跨多个会话时。计划只在对话里没写出来也能直接读。装得进一个上下文窗口就直接 /implement，跳过这一步。它产出的工单天生就是"可接"的，不要再拿 triage 过它们——分诊是给别人的工作用的。

产出什么

tracker 上的工单。本地 markdown 模式写 .scratch/<功能名>/issues/<NN>-<名字>.md，一张工单一个文件、按依赖顺序、阻塞者在前。

关键认知

整个技能建立在垂直切片 vs 水平切片上。水平切片是"先写全部数据层、再写全部接口层"——在每一层都落地之前，什么都不能工作。垂直切片（也叫曳光弹）是一条细窄的路径纵向穿过所有层，完成的瞬间就能演示，这才是它能安全交给一个 agent 的原因。有个可查的案子：一个团队按层切了 26 张工单，每张关闭的工单平均约 20 次 agent 运行，其中约 3/4 是返工，他们自己的复盘把每一个失败类别都追回"横向切片"。

怎么判断

每张都答得出"做完我能演示什么"，而且答案是行为不是某一层；列表带编号和 Blocked by 行先给你确认才发布；最顶上那张零阻塞、可以立刻开工；正文里没有文件路径和行号；读起来像一个全新会话不需要你在场就能完成。

常见坑

过度拆分是最常被抱怨的——三行改动拆出 12 张工单，因为模型默认按最小原子单位切，丢掉了让它们有意义的归组。工单之间并行开是不安全的。还有一条容易被忽略：/implement 不会可靠地关闭工单或勾选验收项，状态得你自己维护——在依赖链上这很伤，因为"可开工"是靠"阻塞者全部关闭"定义的。

/implement —— 每个工单一个全新会话

做什么

构建已经决定好的东西：写代码、在缝上驱动 /tdd、一路做类型检查、结尾跑 /code-review、提交到当前分支。它从不重开计划——不访谈、不澄清、不提别的方案。

何时用

/implement #42，一次一个工单，工单之间清上下文。规格还没切且跨会话 → 先 /to-tickets；计划只在对话里而且还小 → 同一窗口直接打；什么都没写下来 → 先 /grill-with-docs。

产出什么

落在你当前分支上的一个 commit。它不建分支，也不问；开跑前自己确认你在想要的分支上。工单的关闭和验收项勾选不归它。

关键认知

一次运行是五个节拍：读工单找出缝 → 在预先约定的缝上驱动 tdd（一次一个红-绿切片）→ 频繁类型检查、单测试文件随跑 → 结尾跑一次完整测试套件 → 跑 code-review 然后提交。

「预先约定」是它最弱的一个关节：实现技能内部没有任何东西去约定缝，是 tdd 问的，而 tdd 拒绝在未确认的缝上写测试。所以约定要么发生在上游规格里，要么在这一轮对话里——哪儿都没发生的话，它会悄悄退化成"直接把代码写了"。它还信任上游、不重新验证拿到的形状：横向分层切出来的工单，会被照原样建成横向的。

怎么判断

会话开头它读工单并复述要建什么，而不是问你要建什么；过程里能看到真的 /tdd 调用，而不是只有测试文件从 diff 里冒出来；类型检查和单测反复跑、完整套件只在结尾跑一次；不用你催就到了提交；diff 恰好是一张工单的量。

常见坑

它没有收尾步骤：跑完工单还开着、勾选框还没勾（GitHub 和本地 markdown 都是）。不能一次指向所有工单，也不能并行——同一个工作目录里并行开几个会出真事故（有报告说 commit 落错分支、暂存区被另一个会话清掉）。它没有内建的 PR 模式。还有一条：它 diff 的是"固定点...HEAD"，排除已暂存和工作区的改动，所以流程是"先提交再审查"，不是反过来。

/code-review —— 双轴审查

做什么

审你指定的固定点与 HEAD 之间的 diff，沿两条互不相干的轴：标准（代码遵不遵循本仓库写码的方式）与规格（代码做没做原始 issue 要求的事）。

何时用

打 /code-review，你必须提供固定点（一个 commit、分支、标签），不提供它会问而不猜。想在 diff 里抓 bug（空指针、竞态、差一错误）用 Claude Code 自带的那个 /code-review，不是这个。

产出什么

一份报告，分成 ## Standards 和 ## Spec 两个区块。找不到规格时，规格轴被跳过、报告明写"无规格"，而不是从代码反推需求来凑数。

关键认知

两条轴必须分开，是因为一个改动可以过一条、挂另一条：遵守了所有约定却实现了错的东西 → 过标准、挂规格；完全照工单做却破了仓库约定 → 反过来。混在一起裁决，会让通过的那条掩盖失败的那条。每条轴在自己的子代理里跑，互相看不到对方的推理。标准轴以仓库自己的文档为准，仓库永远压过内建基线；什么都没写时，退回内建的十二个代码坏味道（Fowler《重构》第三章）。

怎么判断

引用错了或 diff 为空时，它在任何子代理启动之前就拒绝开跑；报告以两个分开的区块到达，而不是一张合并列表；每条标准发现点名仓库文件里的一条规则、或十二个坏味道之一，并引用相关代码块；结尾每轴给"最严重的一个问题"，但拒绝评选总冠军。

常见坑

它和 Claude Code 自带的 /code-review 撞名——这是报告最多、且至今未修的问题。第 8 章里讲了这个撞名怎么处理。另外，子代理会再次调用 /code-review 并扇出更多 agent，有报告达到 50 个以上。还有最重要的一条：发现是假设，不是证据——报告是聚合出来的，并没有逐条对着文件重新验证过。有团队报告过一整批破坏性改动被这种"基于散文的审查"放行。每一条发现，先读它引用的那段代码，再决定要不要动。

真实产物长什么样

下面是这套流程里两个最重要的文件。照抄格式就行——它们的设计意图比字面更重要。

一份规格的七段式骨架。注意顺序：先说问题、再说方案、然后才是细节，最后是明确不做什么。

## Problem Statement
   用户现在没法只看到货未到的补货单，得自己一页页翻。

## Solution
   补货页加一个状态筛选器，作为 URL 参数，默认为「全部」。

## User Stories
   1. 作为仓库管理员，我想只看到货未到的补货单，以便安排收货。
   2. 作为仓库管理员，我想让筛选条件留在 URL 里，以便分享给同事。
   （这是一份很长的编号清单，一条一句，不要合并。）

## Implementation Decisions
   筛选状态存在 URL 的 query 参数里，不用本地存储。
   （这一节不要写文件路径，也不要贴代码。唯一例外：原型阶段已经产出的代码片段。）

## Testing Decisions
   在「补货单列表数据源」这一个缝上测：给定补货单集合和筛选状态，返回哪些补货单。

## Out of Scope
   不做多状态同时筛选，不做保存筛选方案，不做移动端专门的布局。

## Further Notes
   状态字段未来可能增加，筛选逻辑要能容纳新状态而不用改结构。

再看两张工单，好的和坏的并排放，差别一眼就能看出来。

# 03: 补货单列表按状态筛选

**What to build:**
用户可以在补货页选择状态，列表
只显示该状态的补货单，默认「全部」。

**Blocked by:** 01, 02
**Status:** ready-for-agent

- [ ] 选「待到货」后，列表只剩
      待到货的补货单
- [ ] 刷新后筛选条件保留在 URL
- [ ] 无结果时显示空状态文案，
      而不是一片空白

# 补货模块改造

**What to build:**
完成补货相关的所有数据库、
接口和前端工作。

- [ ] 建 restock_requests 表，加 status
      字段（src/db/schema.ts:42）
- [ ] 写 /api/restock-requests 接口
- [ ] 前端页面接上接口

四个底层原语

这四个你很少直接敲——它们是被上面那些技能反复调用的零件。 但它们是整套方法论的承重墙：前面五个技能里所有"为什么这样设计"的答案，都在这四个身上。

/grilling —— 沿设计树一问一轮

做什么

沿一棵设计树拷问你：从目标往下走到实现决策，每一层问一个问题，然后用你的答案重算下一步该问什么。这样的一来一回叫一轮。

何时用

模型调用型，你自己也能敲。设计还没定、而且你想要的是"被追问"而不是"被给方案"的时候。/grill-with-docs 在后台调的就是它。

产出什么

一段拷问对话，不写任何文件。要落盘就上 /grill-with-docs——这是两者最本质的区别。

关键认知

它不是"一次把问题全倒出来"，而是一轮一轮走：每轮的问题建立在上轮答案上，所以问题会越问越尖。它走的是一棵设计树，每个决策是一个节点；每个答案剪掉一批分支、打开一批新的。被剪掉的分支才是真产出——那些是你压根没想到会被排除的可能性。还有一点：它默认会给出推荐答案，这个推荐是它的价值所在，没有推荐的拷问只是一份问卷。

怎么判断

问题从"你想要什么"逐渐变成"那 X 和 Y 冲突时怎么办"；每轮题量不大（十来道题分三轮左右是常态）；每个问题后面跟一行推荐答案；它开始问你从没考虑过的事；越往后问题越具体、越难答。

常见坑

它是一个技巧而不是一件工具——不装任何技能也能拷问，装了只是让纪律稳定。最大的坑是你回答得太快：推荐答案写得很顺，顺着点过去就等于没拷问。对每一行推荐答案停一下，问自己"我是同意，还是我只是懒得想"。另一个坑前面说过：结论不落盘的，会话一清就全没了。

一轮拷问的实际格式是这样的——注意问题下面那行推荐答案，那是它能省下你时间的地方：

❓ Q3：筛选状态存在哪里？
   A. URL 查询参数    B. 本地存储    C. 服务端会话

➡️ 推荐 A：可分享、可收藏、刷新不丢，而且不需要后端改动。
   代价是 URL 会变长；如果将来状态组合变多，地址会不好看。

❓ Q4：那"无结果"的时候显示什么？
   A. 空白页    B. 一行文案    C. 文案 + 清除筛选的按钮

➡️ 推荐 C：空白页会让人以为数据丢了。

/domain-modeling —— 把语言和决策结晶成文件

做什么

把项目里的语言和决策结晶成文件：术语进 CONTEXT.md，够格的决策进 docs/adr/。

何时用

模型调用型，通常由 /grill-with-docs 在后台调用；你也可以直接用。

产出什么

两个文件——下面有真实样例。单上下文项目用一个根目录的 CONTEXT.md；多上下文时用 CONTEXT-MAP.md 指向各个上下文自己的那份。

关键认知

这两样东西的门槛完全不同，这是最容易搞混的一点。

术语没有门槛：只要它是这个项目特有的词，就写；写错了改掉就行。

决策有硬门槛，必须同时过三道：① 很难反悔 ② 没有上下文会让人意外 ③ 是真的权衡过的结果。三条全中才写 ADR。所以"我们今天用了 React"不是 ADR——它不好反悔，但一点也不意外，而且没权衡过。多数会话产出 0 条 ADR，这是设计如此：真正"很难反悔"的决定本来就少。

怎么判断

CONTEXT.md 里没有实现细节、也没有通用词（"用户""数据"不写，除非你们赋予它特殊含义）；出现 "_Avoid_" 那一行是好信号——说明这个词被误用过，值得记一笔；ADR 文件很少、每篇只有标题加一两句话。

常见坑

它不搜你的 issue tracker（官方已知）——所以它可能建议一个你三个月前就否掉的方案，你得自己拦。另一个：它倾向把词的定义写得中立、泛化，你要主动要求"写得更武断一点"，因为词表的全部价值就在于选边。

下面是这两个文件的真实形状。先看词表——注意每个词底下的 _Avoid_ 行， 那是这份文件最聪明的设计：

# 补货

仓库经理在系统里提交的补货需求。

## Language

**RestockRequest（补货单）**:
仓库经理确认要从某个供应商补的货，包含若干行项目和期望到货时间。
_Avoid_: 订单、进货单

**Shipment（到货）**:
供应商实际送来的东西。一张补货单可以对应多次到货，也可能一次都还没到。
_Avoid_: 快递、物流单

**Backorder（欠货）**:
补货单里已经确认、但供应商暂时发不出货的那部分。
_Avoid_: 缺货、待定

再看一条 ADR。整篇就这么长——这不是偷懒，是刻意的：

docs/adr/0007-到货回调不做幂等.md

# 到货回调不做幂等处理

供应商的回调会重复推送，我们不按回调 ID 去重。上游保证同一批货按顺序重试，
而重复的到货记录由仓库经理在界面上手工合并——这比在回调路径上维护一张去重表更简单，
出错的代价也更低。

三条全过，所以它值得占一个文件。反过来——"我们把按钮改成蓝色"三条全不过，所以它哪儿也不写。

/tdd —— 红绿循环，没有第三个字

做什么

红 → 绿循环：先写一个失败的测试（红），再写刚好让它通过的代码（绿）。

何时用

模型调用型，通常由 /implement 在已经约定好的缝上调用。

产出什么

测试文件和实现代码，在同一个切片里一起长出来，一次一片。

关键认知

三个反直觉点：

① 缝必须先约定。它的原话是"只在预先约定的缝上测……未确认的缝上不写任何测试"。这不是洁癖——缝选错了，测试就绑在实现细节上，将来一重构全废。

② 一次只切一片：一个测试 → 一部分实现 → 下一个测试。不是"先把所有测试写完再写实现"。

③ 循环里没有重构。重构归 /code-review。这条最反直觉，因为大多数讲 TDD 的材料把"红-绿-重构"当成三位一体——它偏偏把第三个字拿掉了，理由是"一边修 bug 一边改结构"这两件事会互相掩盖。

怎么判断

能看到测试先红了一次，而不是写完就绿；测的是行为不是实现（改内部结构，测试不该挂）；每个切片都很小，小到你觉得"这也要单独跑一次？"

常见坑

官方点名三种坏味道：和实现耦合（测试里提到了内部函数名或私有字段）、同义反复（测试和被测代码用同一套逻辑算期望值，等于什么都没验证）、水平切片（一次写完所有测试再写实现，这正是它要防的那件事）。还有一条已知不一致：它给自己的说明里还写着"红-绿-重构"，跟实际的"重构不属于循环"是矛盾的，官方至今没改——所以你会在它的自述里看到一个跟它自己的规则打架的说法。

/codebase-design —— 一套描述"代码该长成什么形状"的词汇

做什么

给出一整套描述代码形状的词汇：深模块、接口与实现的分离、深度、适配器、杠杆、局部性。

何时用

模型调用型。做架构决策时，或者审查里出现"这结构不对"却说不清哪里不对时。

产出什么

通常不产出文件；产出的是判断。它的术语会流进规格的「实现决策」段，和审查的标准轴。

关键认知

核心是深模块——接口小而简单，背后藏着大量能力。反例是浅模块：接口和实现一样复杂，加了等于没加。"深度"就是这两者之间的距离。

配套的删除测试很好用：想象把这个模块删掉——如果复杂度原地消失、只是功能没了，那它可能本来就没创造价值；如果复杂度扩散到一堆调用点上，那它就是在收敛复杂度，值得留着。它还有杠杆效应：一个正确的形状，让后面十个改动都变简单。

怎么判断

你说得出每个模块"删掉会怎样"；新功能是不是只在一个地方改；接口能不能在不看实现的情况下用对。

常见坑

不要在没有任何具体改动的情况下纯做架构。没有第二个真实用例做参照，"深度"只能靠猜——所以它通常和预先重构（动工之前先把该重构的改掉）配合，而不是单独跑一遍。

想法装不下一个会话时

这三件事共同回答一个问题：当"一次谈不完、一次做不完"的时候怎么办。 它们是纯开销——小改动不要碰，用了反而慢。

/wayfinder —— 把雾铺成一张决策地图

做什么

把一个大到装不下一个会话的模糊想法，铺成一张决策地图：四种决策工单（问题 / 研究 / 原型 / 规格）挂在一张地图 issue 下面，用标签分门别类。

它为什么用"工单"这个词

因为最容易的误读就是把 wayfinder 的工单当成实现工单——"切好的一块活，去把它做出来"。它不是。它是一张决策工单：一张工单的答案是一个决定，不是一段代码。名字里那个"工单"是刻意借的。

何时用

想法太大、路线还是雾的时候。装得进一个会话的不要用它——那是 /grill-with-docs 的活。

产出什么

一张地图 issue + 若干子 issue，标签形如 wayfinder:map 和 wayfinder:<类型>。地图走清了，才轮到 /to-spec。

常见坑

地图本身不产出代码，所以很容易被当成进度条来看——它是决策的记录，不是任务清单。旧名叫 decision-mapping，查老资料时注意对上。

/prototype —— 写一个丢掉也不可惜的版本

做什么

为了回答一个具体问题，快速写一个丢掉也不可惜的探索版本。它不是产品雏形。

何时用

有个"这样到底行不行"的问题，读文档和讨论都答不了，必须动手试。

产出什么

代码通常长成这样：一个自包含的 HTML 文件——纯 HTML/CSS/JS，不用构建、不用起服务，双击就能打开。这样不懂技术的人也能用自己行业的词去操作它：有标签的状态面板、随时能点的自由探索按钮、还有几组带步骤提示的引导式演练。

那个能带走的部分（纯逻辑模块）会被搬进真正的代码里；HTML 外壳是扔掉的那层。

另外它有一个很好的习惯："扔掉"不等于"删掉"。原型会被存到一条一次性分支上，主分支只留下那个验证过的决定，而探索过程仍然找得到。规格里唯一允许贴代码的例外，就是原型产出的片段。

常见坑

原型代码被顺手留下来当正式代码用。原型的全部前提是可以扔掉——一旦开始想"留着以后改改就能用"，它就从资产变成了债。

/research —— 让一个子代理替你去翻

做什么

把一个开放问题交给一个子代理去查：读代码、读文档、翻 issue，产出一份带出处的结论。

何时用

答案在代码或文档里，只是散落各处、你不想自己翻。答案在别人脑子里用 /to-questionnaire；需要动手试的用 /prototype。

产出什么

一份带引用出处的调研结论，回到对话里。在 wayfinder 的地图上，研究工单的结论会留在一个一次性分支上，主线上只留一个指向它的引用。

顺带一个例外：它是一个"一个会话一张工单"规则的例外——因为查资料不用你盯着，wayfinder 可以在铺完地图之后并行把几张研究工单一起派出去，不用等。

常见坑

它会再派子代理，有失控的报告。官方记着这个案子：一次调研消耗约 45 万 token。所以问题要问得窄，而且别在它跑的时候走开。

维护组

前面那些都是"从零做一个东西"。这一组解决的是另一类问题：东西已经在了，但它在坏。

/diagnosing-bugs —— 按阶段查，不许跳步

做什么

按一套固定阶段查 bug（复现 → 缩小 → 定位 → 假设 → 验证 → 修），而不是让 AI 乱猜。

何时用

有个明确不工作的地方，而且你要的是找到原因，不是"让它先别报错"。

产出什么

一个能说明白"为什么坏"的结论，然后才是修复。过程中它会在代码里埋带标记的日志（形如 [DEBUG-a4f2]）——这个标记是为了让日志能一次性清干净，不会留在生产代码里。

常见坑

跳阶段直接修。"先让它不报错"是这套方法明令禁止的默认动作——同一个 bug 会以别的形态回来，而且这次你连它原来在哪都不知道了。旧名叫 diagnose。

/triage —— 给涌进来的东西分诊

做什么

把外部涌进来的报告（bug、需求）分类、贴标签，判断哪些够格被做成工单。

何时用

有人在给你报东西、收件箱开始堆的时候。

产出什么

被分诊过的条目，带上五个状态标签和两个类别标签。它产出的东西天生"可接"，接下来交给 /to-tickets。

常见坑

不要对 /to-tickets 已经切好的工单再跑一遍分诊——那批工单已经分好诊了，再分一次等于把已有的结论重新猜一遍。另外，老技能 /qa 的功能被拆到了 /triage 和 /to-tickets 两个技能里。

/improve-codebase-architecture —— 主动扫一遍

做什么

在没有具体需求的时候，主动找出代码库里该改进的结构问题——就是那些"没坏，但开始烂"的地方。

何时用

感觉代码越来越难改，但说不出具体要做什么功能。
它不会把整个代码库平均扫一遍——你要是给个方向它就顺着方向看，不给的话它会去读最近约 20 条提交记录，把注意力压到最近真的在改的那几块上。

产出什么

一批架构改进项，通常接给 /to-spec 变成规格。

常见坑

跟 /codebase-design 的区别要分清：那个提供词汇和判断，这个是主动扫一遍找问题。还有——扫出来的清单不要一次性全做，那本身就是一次大重构，而大重构正是最该被切片的事情。

/wizard —— 把"每隔几个月做一次"的流程写下来

做什么

把一套手动、多步、容易漏的流程，变成一个 AI 生成、你来执行的交互式脚本——它会替你打开每个网址、告诉你点什么、把拿到的值收进配置文件。升级依赖、迁移配置、接第三方服务、上线检查单这类。

何时用

有件事你每隔几个月做一次，每次都得回头翻上次的笔记。判断标准就一句：这一步只能由人来做吗？AI 自己能做的活就该让 AI 做——它管的是那些必须你亲手点的按钮、亲身过的审批、要跑一趟的外部后台。

产出什么

一个可执行的脚本，把流程分成若干阶段，每阶段给你进度和剩余时间、在关键处停下来等你确认、隐藏地读入密钥，还能把值写进环境变量文件和 CI 的密钥里。可复用，下次再跑一遍就行。

常见坑

最容易犯的错是让向导去干 AI 自己能干的活——它明确给自己划了一条线："别为了 agent 自己能做的步骤调用它"。把一个"改个配置项"也写成向导，只会多出一层没必要的确认。

另一个：只做一次的流程不值得写成向导，写它的成本比做一次还高——下次还会不会做，才是标准。

/resolving-merge-conflicts —— 先看懂两边想干什么

做什么

指导和 AI 一起解合并冲突，重点是让它先理解两边各自的意图再动手。

何时用

合并或变基时出现冲突。

产出什么

解完的冲突，外加一份"为什么这么解"的说清。

常见坑

自动选一边、或者两边都留着——产出的代码能编译，但语义是错的。冲突的本质是两个意图在打架；不看清意图的任何解法都是赌。

效率与入门组

这一组没有共同的技术主题——它们的共同点是你平时不会想到去用， 但用上一次能省掉一整个下午。

/ask-matt —— 不知道用哪个的时候问它

做什么

你不确定该用哪个技能的时候问它。它会读你的处境，推荐一条路径。

何时用

面对一堆技能名字不知道从哪下手；或者事情卡住了，怀疑"是不是该换一个技能"。

产出什么

一段"你现在在哪、下一步该用什么"的建议。

常见坑

它给的是路径建议，不是答案。推荐了技能你还是得自己跑——别指望它替你把事做完。

/setup-matt-pocock-skills —— 只跑一次的那个

做什么

一次性的安装与配置：把这套技能装进你的 AI 编程工具，并把该设置的设置好。

何时用

第一次用这套东西的时候。就一次。

产出什么

一套可用的技能，加上配套配置。

常见坑

它只该跑一次。重复跑会覆盖你的本地改动或把配置搞乱；想升级是另一件事，别拿它当升级命令。

/grill-me —— 入口最浅的那一个

做什么

轻量版的拷问——不写文件、不建词表，就是把你脑子里模糊的想法问清楚。

何时用

想法还在你脑子里、只想先跟自己理一遍的时候。不是在某个代码仓库里做正式设计——那是 /grill-with-docs 的活。

产出什么

一段对话。什么都不落盘。

常见坑

它是这套东西里安装量最大的一个（约 50.8 万次），所以最容易被当成"整套方法论的代表"——其实它只是入口最浅的那一个。最大的误会是拿它在项目里替代 /grill-with-docs：结果是谈得很爽，什么都没留下。

/handoff —— 让工作能"旅行"

做什么

把一个会话的上下文打包成一份可携带的文件，让下一个会话、或者另一个人、或者另一个工具能接着干。

何时用

活要"出门"的时候——换工具、换目录、交给同事、或者从主线分出一条支线任务。同一个会话里还要接着干？那是 /compact 的活，不是它。

产出什么

一份交接文件。注意它写在系统临时目录里——所以你要主动把它挪到需要它的地方，别以为它会自己出现在仓库里。

常见坑

两条铁律。① 它只带"在飞的工作"——还没落地的那些。凡是已经写成规格、ADR、issue、diff 的东西，只写路径和链接，绝不复制内容：复制就会有两份，然后两份会开始不一致。② 它是过境文档，不是长期资产——长期留在仓库里的是规格和 ADR。还有一条现实提醒：交接前先脱敏，别把密码、密钥、客户信息打包进去。

/teach —— 让你看懂，而不是替你做

做什么

让 AI 用讲解的方式带你理解一段代码或一个概念，而不是替你改。

何时用

你想看懂的时候。

产出什么

一份解释。不动代码。

常见坑

讲解会顺着你的水平讲，所以它会不自觉地把不确定的地方讲得很肯定。凡是看到具体的数字、版本号、行为断言，还是得自己核一遍——这一点在第 4 章讲过。

/to-questionnaire —— 答案在别人脑子里

做什么

把你要问别人的问题整理成一份问卷。

何时用

你缺的信息只有人能给：业务规则、历史上的某个决定、一次事故的经过。
它有一个很聪明的设计：它拷问的是"这份问卷要发给谁、你需要拿回什么"，而不是拷问你问卷上的题目——因为题目本身正是你答不上来的东西。所以它能把火力集中在"你和对方之间的信息差"上。

产出什么

一份可以直接发出去的问卷（markdown），对方可以异步填，也可以约个会一起过。

常见坑

它的成品质量取决于你的问题质量。问得太宽（"你们想要什么"）拿回来的东西没法用；要问具体的边界，比如"同一张补货单能出现在两次到货里吗？"

/wait-what —— 四个字，成本最低的纠错

做什么

你没听懂上一条回复的时候打这两个词，它会用另一种方式重讲一遍：补一点上下文、换成更直白的语言，并且换用你 CONTEXT.md 里定义的词。

何时用

AI 说了一段你完全没看懂的东西，而你不想装作懂了往下走。

产出什么

同一个意思的另一种说法。注意它只修这一条消息，不会预防下一条。

常见坑

这个技能最被低估，因为它看起来像是"承认自己看不懂"。但零基础的人最大的浪费就是假装懂了——后面每一步都建在这个没懂的点上，而你还以为路线是对的。它是立刻纠正、成本最低的方式。

/writing-for-agents —— 怎么写给 AI 读的东西

做什么

讲怎么把指令写得让 AI 能稳定执行——也就是怎么写技能本身、写 CLAUDE.md 这类给 agent 读的文档。

何时用

你要自己写一个技能，或者维护给 AI 看的说明文档时。平时不用管它。

产出什么

一份写得好的、给 AI 读的说明。

常见坑

它的核心是一句反直觉的话：给人读的文档和给 AI 读的文档是两种东西。给人读的可以靠上下文补全，给 AI 读的必须把前提写全。另外它改过两次名（write-a-skill → writing-great-skills → writing-for-agents），网上三种写法都有人在用。

25 个技能速查

一张表走完。点「详见」跳回前面的档案。 主线常用的那一小张索引在第 10 章；这里收的是全部 25 个。

会话管理：五个选项，各自保护一种东西

这一节是跨技能的，但它是最实用的一节—— 因为它管的是"上下文窗口是有限资源"这件所有技能都绕不开的事。

先记住一句话：不同选项保住的不是"多少上下文"，而是"哪一种上下文"。

工程词汇表

这一页的工程词，大多已经在上面各自的技能档案里随文解释过： 缝（/to-spec）、设计树与轮（/grilling）、 深模块与删除测试（/codebase-design）、ADR 三门槛（/domain-modeling）、 决策工单（/wayfinder）。拆票与重构相关的词（曳光弹、扩张-收缩、预先重构等）， 系统的讲法见 第 8 章 · 为什么不能按层切； 「爆炸半径」指一次改动会波及的范围，「紧反馈循环」指从改完到知道对不对之间的距离。

系统的常用术语在 第 10 章 · 一页术语表； 架构与选型相关的词在 进阶：架构与选型 · 术语表。

一条上手路线

这一页信息量很大，不要一次全上。按这个顺序走：

1. 第一天：只做安装。 跑一次 /setup-matt-pocock-skills，然后什么都别做。 去把第 6 章完整读一遍，看看这条流程到底长什么样。 这一天的目标是知道有什么，不是用起来。
2. 第二天：拿一个真小改动跑两步。 挑一个明确的小改动，只做两件事：先用 /grill-with-docs 问清楚， 再 /implement 做出来。跳过规格、跳过拆票、跳过 wayfinder—— 那些是给"大到装不下一个会话"的东西准备的，小改动用了只是白花钱。
3. 第三天：试着走完整条主链。 找一件确实要跨几天的事：/grill-with-docs → /to-spec → /to-tickets → 一张一张 /implement。 这一步的重点是体会"上下文清空之后还能接着干"—— 那是整套方法真正在卖的东西。
4. 之后：按需要，缺什么补什么。 东西坏了用 /diagnosing-bugs；别人开始给你报东西了用 /triage； 想法大到一时说不清了用 /wayfinder；看不懂 AI 在说什么就打 /wait-what。 不要为了"用全"而用。

诚实边界

这一节比前面任何一节都重要。 下面这些不是"我们发现的 bug"，而是上游自己写在文档里的已知问题—— 我们照原样转述，因为一套方法论值不值得用，取决于它对自己的短板说不说实话。