让 Agent 有章可循：
Matt Pocock Skills 技能集完全手册

大多数人对 AI 编程的第一印象是：快。第二印象是：它怎么又自作主张了？

把"帮我实现这个登录功能"丢给一个全新的 agent，常见结局是它边写边重新设计你的方案——因为它手里只有一句话，没有被你否决过的三个备选、没有"我们必须兼容旧 token"这条约束、没有你项目里管"取消"叫 void 而不是 cancel 的惯例。它只能猜，而猜错了你也往往在三天后才发现。

Matt Pocock 的这套技能集（以下简称"这套技能"）给出的答案可以概括为一句话：

人负责决策，agent 负责执行，文件负责记忆。聊天框里什么都不会留下，文件才会。

具体拆开来是三个心智模型，后面所有技能都是它们的推论：

整条技能体系是一张手绘的地图（ literally——路由 skill ask-matt 就是它的人肉查询版）。结构如下：

主链：从想法到交付

两条匝道：外来工作与超大工程

一张底图：词汇层与方法论

独立工具箱（随时取用，不在任何链上）

setup-matt-pocock-skills 回答三个问题：issue 住在哪、triage 标签叫什么、域文档放哪，答案写成 docs/agents/ 下的 markdown。核心设计思想值得单独强调：

它写什么

• docs/agents/issue-tracker.md — tracker 选择 + 工作流描述（含 wayfinder 的 "Wayfinding operations" 一节）
• docs/agents/domain.md — 域文档布局
• docs/agents/triage-labels.md — 仅当装了 triage
• CLAUDE.md 或 AGENTS.md 里的 ## Agent skills 块 — 指向上面每个文件

tracker 四选一

所有 skill 的源头是一个共同原语：grilling——一轮问题、等你回答、再下一轮。套在它外面的三个 skill 各管一段：

grill-with-docs 与其他 grilling skill 的全部差别在于：它是 stateful 的——术语敲定那一刻就写进 GLOSSARY.md，决策过三道杠就落成一条 ADR。别的 grilling 把 session 留在你脑子里，它把文件留在磁盘上。

两个工件，两道杠

词汇层：codebase-design 的七个词

这套体系给模块设计强制了一套语言：module（任何"接口+实现"的东西，与规模无关）、interface（签名 + 不变量 + 顺序约束 + 错误模式 + 配置 + 性能特征）、depth（每学一个单位接口能行使多少行为）、seam（不改此处就能改变行为的地方——Feathers 的术语）、adapter（接缝处满足接口的具体角色）、leverage（调用方得到什么）、locality（维护者得到什么）。

同时禁掉四个松散词：component、service、API、boundary。这条纪律看着形式主义，实际效果立竿见影——当讨论里有人说"这里该拆个组件"，你可以追问"拆出来的接口是什么、深度够吗、过没过删除测试"，争论就从口味变成可判定的题。

规划阶段只有两个 skill，但分工极清：

竖切 vs 横切：一套技能里最重要的图

按层切（先全部 schema、再全部 API）是最直觉的分法，也是这套体系明确反对的分法：

• 横切：全部落地前没有任何可演示的东西；每张票的验收标准要伸手到别的票的工作里。真实案例：一个 26 张横切票的团队，每张票关闭平均需要 ~20 次 agent 运行，其中约 75% 是返工——复盘把每一类失败都归因于切法而非实现。
• 竖切（tracer bullet）：每张票落地即可演示、拥有它考核的一切；验证过的形状反过来锁定测试结构。

两条容易忘的实操纪律

另外，装得进一个上下文窗口的改动根本不该走 spec+tickets——grilling 之后直接 /implement。spec 只在跨 session 的工作上才值回成本。

implement：信任上游的工匠

implement 的立身之本：绝不重新打开计划。没有访谈、没有澄清轮、没有"换个方案怎么样"——上游敲定什么是输入，它的全部工作是把输入变成一个 commit。这正是它和对全新 agent 说"build this"的区别：后者常边做边重新设计。

一次运行五步：① 读票/spec、定接缝 → ② 在预先敲定的接缝上驱动 tdd（一个 red-green 切片接一个）→ ③ 频繁 typecheck、随跑单测 → ④ 收尾完整测试套件跑一遍 → ⑤ 跑 code-review，提交到当前分支。

implement-spec：一座工厂

整张 spec 一次落地时，调度者从"你"换成一个编排 agent：frontier 上的票全部同时开工，每个 implementer 在自己的 git worktree 里构建，汇入一条集成分支（fast-forward 合并），最后统一 code-review 并 resolve 票。

tdd：方法论而非司机

tdd 是 reference：装着"什么是好测试"的规则，跑 session 的是 implement（或你）。要点三则：接缝在任何代码存在之前商定（未确认的接缝上它拒绝写测试——没人商定，运行就静默退化成"直接写码"）；三个让套件一文不值的反模式要会认——实现耦合（重命名内部函数测试就红）、重言式（期望值用代码同款算法算出）、横切（一批测试先于任何实现落地）；mocks 只用于系统边界，绝不 mock 自己的模块。

code-review：两个互不见面的评审员

它评审 <fixed-point>...HEAD 的 diff，分两条轴、各由一个独立 sub-agent 跑：Standards（构建得对不对——仓库自己的规范 + Fowler 十二 smell 基线）与 Spec（构建的是不是对的东西——来源 issue/spec 逐条对照）。报告分两个块，每轴各给一个最差项，拒绝评总冠军。

pr：三段的正文，一段是主导想法

pr 只塑形正文、不开 PR：① Summary——是图不是段落，从六种视图（伪代码、调用树、组件树、文件树、Mermaid、shaped diff）里挑最小的讲清形状；② Evidence——前后对照（截图，或"曾失败现通过"的确切测试），"tests are green" 是主张不是证据；③ Merge Danger——一扇门（one-way：破坏性迁移、对外发出、公开 API 移除）还是两扇门，加爆炸半径。

retro：把"这次教会的东西"固化下来

在"比本该更难"的 session 末尾跑 retro。它一行代码都不修——被 ship 的 bug、找了一万年的文件、reviewer 漏掉的规则，它一个都不直接修；它问"仓库里什么允许了它发生"，然后提议检查、指针或标准。只提议，你选中之前什么都不变（human-in-the-loop 是刻意的：判断什么值得变成永久检查需要人）。

improve-codebase-architecture：周期保养的调查

每隔几天跑一次，扫描"浅模块可变深"的地方。两道过滤器挡掉泛泛建议：删除测试（删掉这个模块，复杂度退到更小接口后 = 配得一张卡；摊回调用方 = 不配）+ 聚焦常变路径（没人碰的代码里的加深永远不回本）。产出是一份 HTML 报告 + 你选中一张后的 grilling——产出决策，不是 diff，重构走正常构建流。

triage 只处理你没创建过的 issue：原始 bug 报文、外来功能请求、不请自来的外部 PR。它给类别（bug / enhancement）和五个状态（needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix）的建议，附带理由并停下来等你。

wayfinder 的触发条件极窄：工程大于一个 session，且路线看不清。分界是 session 数而非项目大小——一场对话装得下就 grilling，装不下才 wayfinder。greenfield 不是前提：legacy 的雾常是"这里已经什么是真的"。

地图的四节

• Destination——地图尽头的样子，在任一 ticket 存在之前命名（指整个地图的尽头，不是本场 session 的）。
• Decisions so far——每个已关闭 ticket 一行 + 链接。地图是索引不是仓库：决策只活在它的 ticket 里。
• Not yet specified（战争迷雾）——看得出要来、还说不清的问题。雾 vs ticket 的测试：你现在能否精确陈述这个问句（不是能否回答）。resolve 一张票，它前方的雾散开，能说清的毕业成新 ticket；Out of scope 永不毕业。
• Frontier（前线）——开放的、无阻塞的、未被认领的票；认领 = assign 给自己。

四种决策 ticket

给定 bug report，coding agent 的默认动作是读代码然后猜。diagnosing-bugs 把这条路堵死：在一条"紧的反馈环"存在之前，不允许形成任何理论。紧 = 秒级、确定性、断言的是你那个确切症状、agent 无需你就能跑。

1. 第 0 天 · 打地基：在一个真实仓库跑 /setup-matt-pocock-skills。确认 docs/agents/ 三个文件和 CLAUDE.md/AGENTS.md 的指针块都在——以及它们在你的 harness 实际读的那个文件里。
2. 第 1 天 · 小改动热身：挑一个装得进单窗口的小特性。/grill-with-docs 敲定 → 直接 /implement。故意跳过 spec 和 tickets，体会「什么尺寸才值得拆」的那条分界线。
3. 第 2–3 天 · 完整主链：一个稍大的特性走全链：grill-with-docs → to-spec → to-tickets → implement（逐票、票间清空）→ code-review → pr。重点体验两件事：to-spec/to-tickets 之间不清上下文；implement 跑完自己关票。
4. 第 4 天 · 复盘与保养：对昨天那场跑 /retro，挑一条候选落地（比如一个会失败的 check）。顺手跑一次 /improve-codebase-architecture，感受"调查不改码"的节奏。
5. 第 5 天 · 独立工具：各抽十分钟试 prototype（一个聊不决的小问题）、research（一个等事实的决策）、wizard（一个要配的服务）。
6. 持续 · 形成反射：困惑时 /ask-matt；外来报文进 triage；硬 bug 进 diagnosing-bugs；每隔几天 wayfinder/improve-codebase-architecture 做保养。每周把第 13 章清单过一遍。

最后一条经验：这套技能集最强的部分不是任何单个 skill，而是它背后的态度——把"AI 写代码"当成一门需要流程、词汇和纪律的工程学科。工具会过时（resolving-merge-conflicts 已因模型进步归档），纪律不会。