Matt Pocock Skills 深度实战：AI Agent 工程化技能集——从需求对齐到架构审查的完整指南（2026）
2026年5月 GitHub 月榜第2名，月增星 71,266，总星 112,644。这个开源项目解决了一个所有 AI 编程者都在面临的根本性问题：AI 写代码太快，快到你的工程纪律追不上它。
一、背景：AI 编程的「速度陷阱」
Matt Pocock 是 TypeScript 圈最知名的教育者之一，他做了 Total TypeScript 课程平台，日常重度使用 Claude Code 写代码。他发现了一个致命的问题：
AI 写代码的速度，远超你的代码审查速度。
手动编程时，一个模块可能要半天，你有足够的时间停下来想架构、做 TDD、写 Code Review。但 AI 三分钟就能生成了一个 500 行的模块。你甚至来不及想"这个模块的职责划分是否合理"，代码已经躺进仓库了。一个礼拜下来，项目就成了屎山。
这不是 AI 蠢的问题，而是 AI 天然缺少工程纪律。
四个经典失败模式
| 失败模式 | 表现 | 后果 |
|---|---|---|
| 需求没对齐 | 你以为 AI 懂了，它理解偏了 | 返工率极高 |
| 没有共享语言 | AI 每次都用大白话解释概念，啰嗦又烧 token | context window 被撑爆 |
| 没有反馈循环 | 写完代码不看测试、不看类型、不看浏览器 | 代码上线 = 炸弹上线 |
| 没有架构审查 | AI 往一个模块里塞五个职责，函数 20 行变 200 行 | 屎山堆得比手写快 10 倍 |
Matt Pocock 解决这个问题的方案，就是把他日常使用的工程纪律——Code Review、需求评审、TDD、架构审查——固化成 18 个 Skill 文件，让 AI 被迫执行这些步骤。
二、核心理念：不给 AI 加能力，给 AI 加纪律
mattpocock/skills 的设计哲学非常清晰：
不绑定任何模型。每个 Skill 是一个独立的 Markdown 文件，可以自由组合、随意修改。不做框架，做工具。
本质上，这不是在增强 AI 的编程能力，而是在 AI 的行为链路上加一层"工程纪律教练"：
你丢需求给 AI → /grill-with-docs 强制需求对齐 → /to-prd 生成 PRD
→ /to-issues 拆解任务 → /tdd 强制 TDD → /improve-codebase-architecture 定期架构审查
核心逻辑只有一句话：好工程师该做的事，AI 被 skill 逼着也得做。
三、安装与初始化配置
3.1 一键安装
npx skills@latest add mattpocock/skills
这个命令会自动克隆 Matt Pocock 的 .claude/skills 目录到你的本地，并注册所有技能。
3.2 初始化配置
安装完成后，每个新仓库必须运行一次：
/setup-matt-pocock-skills
这个初始化技能会依次问你三个问题：
问题1：Issue Tracker 选择
你用哪个工具管理 Issues？
→ GitHub Issues / Linear / 本地文件
Skill 会根据你的选择生成对应格式的 issue 描述。
问题2：Triage 标签词汇表
给 Issue 打标签时用哪些词汇？（例如：bug、feature、needs-triage）
/triage 技能会使用这些标签来组织和管理 issue 状态。
问题3：文档路径结构
生成的 ADR 和文档放哪？
这里有两个选择：
- Single-context：适合单一产品/应用的仓库。ADR 统一放在
docs/adr/，根目录只有一个CONTEXT.md。大多数项目选这个。 - Multi-context：适合 Monorepo。每个子模块有独立的 context 文件，根目录有
CONTEXT-MAP.md索引。
初始化完成后，项目根目录会自动生成一个 CONTEXT.md 文件——这是 AI 与你之间的共享语言词典，也是后续所有技能的核心数据基础。
3.3 Skills 作用域机制
Skills 存储在三个作用域中，可被不同粒度的工具使用：
个人技能： ~/.agents/skills/ # 所有项目共享
项目技能： ./.agents/skills/ # 随仓库 clone，团队共享
机器级技能： /etc/codex/skills/ # 容器/机器默认配置
触发方式有两种：
- 显式调用：在 CLI 中输入
/skill名称（如/tdd） - 隐式触发：任务描述与 Skill 描述匹配时，AI 自动激活对应技能
四、核心工程技能详解
4.1 /grill-with-docs —— 需求对齐 + 术语建设
这是整个技能体系里最核心的一个。 Matt Pocock 称之为"可能是我做过的最酷的事"。
工作原理
当你给 AI 一个模糊需求（比如"加个登录功能"），/grill-with-docs 会触发一轮苏格拉底式追问：
你：加个用户登录功能
AI（/grill-with-docs 激活）：
"你说的'用户'是指 Customer 还是 Admin？
登录方式是邮箱密码还是手机验证码？
是否需要支持 SSO（Google/GitHub 登录）？
Token 存在哪里？HttpOnly Cookie 还是 LocalStorage？
登录超时时间是多少？
是否需要记住我？"
核心价值：共享语言（Ubiquitous Language）
/grill-with-docs 在追问的同时，会维护一个 CONTEXT.md 文件。追问确认后，相关术语的定义会自动写入这个文件。
例如，你在项目中说"materialization cascade"，而不是说一大段"当课程章节里的某个课时被标记为'正式发布'时，需要在文件系统中为它分配物理存储位置并触发一系列连锁反应"。
Before（无共享语言）：
"There's a problem when a lesson inside a section of a course is made 'real' (i.e. given a spot in the file system)"
After（使用共享语言）：
"There's a problem with the materialization cascade"
这种精确性带来的好处是：
- 变量名、函数名、文件名都基于共享语言命名，一致性大幅提升
- AI 的 context window 不再被冗长描述塞满
- 同一个概念在不同 session 中保持一致的理解
生成 ADR（架构决策记录）
遇到重大技术决策（如"选 PostgreSQL 还是 MongoDB"），/grill-with-docs 会当场引导你写一份 ADR，放入 docs/adr/ 目录，记录决策理由和备选方案对比。
4.2 /grill-me —— 快速需求澄清（轻量版）
如果你不需要建文档、不想维护 CONTEXT.md，只想在开始写代码前快速对齐需求，用 /grill-me：
你：我想给 API 加个缓存层
AI（/grill-me 激活）：
"缓存失效策略是什么？TTL 还是主动失效？
存热点数据还是全量数据？
用什么缓存中间件？（Redis / Memcached / 内存）
是否需要分布式一致性？"
不写文档，不更新 CONTEXT.md，专注快速澄清。适合非编码场景（技术选型讨论、方案设计）和还没建 CONTEXT.md 的项目。
4.3 /tdd —— 测试驱动开发的正确打开方式
核心要求：红→绿→重构，单步执行
/tdd 强制 AI 遵循 TDD 的三个阶段：
- Red（红）：先写一个失败的测试，描述你期望的行为
- Green（绿）：写最少的代码让测试通过
- Refactor（重构）：在测试保护下改善代码质量
/tdd 的具体约束
规则1：每次只写一个测试，只写刚好让它通过的代码
规则2：只测公开接口行为，不碰实现细节
规则3：禁止一次性写完所有测试，要水平切片
规则4：测试名必须描述行为，而非实现
实际效果：
你要加一个"购物车结算"功能。AI 不先写代码，而是先问你：
"结算接口的输入是什么？（Cart 对象）
输出是什么？（OrderConfirmation）
失败情况有哪些？（库存不足、支付失败、优惠券过期）
结算过程中需要记录哪些审计日志？"
然后逐条写失败的测试，逐条写让它通过的实现。每一步都有测试保护，任何回归立刻被发现。
解决的核心问题
没有 TDD 时，AI 写代码是"假设正确"，有 TDD 时是"证明正确"。在 AI 编程场景下，TDD 更是关键——因为 AI 可能在没有任何预警的情况下悄悄破坏已有功能，而测试套件就是你的安全网。
4.4 /diagnose —— 系统化调试六步法
遇到复现困难、原因不明的 bug，/diagnose 提供了一个结构化的调试框架：
Phase 1: 造一个 pass/fail 信号（最关键！）
→ 在碰任何代码之前，先写一个能自动判断 bug 是否存在的脚本
→ 测试、curl 脚本、headless 浏览器脚本均可
Phase 2: 隔离触发条件
→ 用 pass/fail 信号反复运行，收集失败时的上下文
Phase 3: 假设成因
→ 基于 Phase 2 的数据，提出最可能的假设
Phase 4: 验证假设
→ 针对性地加日志或断点，验证或推翻假设
Phase 5: 修复
→ 在 pass/fail 信号保护下修复
Phase 6: 确认修复
→ 运行信号确认 bug 已消除
Phase 1 是整个方法论的灵魂。没有反馈循环，就别碰代码。这听起来简单，但恰恰是 AI 编程中最容易被跳过的步骤——因为 AI 太急于"帮你解决问题"，在没有清晰反馈机制的情况下就开始盲目修改。
实际例子：一个 API 偶尔返回 500，日志里什么也没有。AI 用 /diagnose，先写一个重试脚本每 5 秒发一次请求，跑 10 分钟后收集到 3 次失败请求的特征数据——全部发生在请求体包含某个特殊字符时。最终锁定根因并修复，零误判。
4.5 /improve-codebase-architecture —— 架构体检
这是防止屎山形成的日常维护技能。Matt Pocock 建议每隔几天跑一次，或者在代码量明显增长后立即运行。
工作原理
/improve-codebase-architecture 会让 AI 派 subagent 遍历整个代码库，找出"浅模块"（Shallow Modules）。
什么是浅模块？ John Ousterhout 在《A Philosophy of Software Design》中定义：最好的模块是深的——通过简洁的接口暴露大量功能。浅模块则相反：接口跟实现差不多复杂，等于没有封装。
输出示例
架构报告：UserService 发现浅模块问题
问题：UserService 接口暴露了 15 个方法
分析：其中 8 个只是直接转调 UserRepository 的同名方法
建议：
1. 将这 8 个方法合并为 upsertUser() + queryUser()
2. UserService 对外只暴露 2 个方法，内部处理 CRUD 逻辑
3. UserRepository 降级为包的私有实现细节
预期效果：
✓ 接口从 15 个减到 2 个
✓ 调用方代码大幅简化
✓ 以后改 UserRepository 不会破坏 UserService 的外部接口
通过定期"架构体检"，在 AI 疯狂加速编码的过程中及时踩刹车，保持代码库的长期可维护性。
4.6 /to-prd —— 对话自动生成 PRD
当你和 AI 经过一番需求讨论后，运行：
/to-prd
AI 会自动把当前对话上下文压缩成一份完整的 Product Requirements Document，提交到你的 issue tracker（GitHub Issues 或 Linear）。
PRD 包含：
- Problem Statement（问题描述）
- Proposed Solution（解决方案）
- User Stories（用户故事）
- Implementation Decisions（实现决策）
- Testing Decisions（测试决策）
- Out of Scope（不在范围内）
你不需要写一个字，聊完天直接生成可归档的文档。这解决了 AI 编程中一个很实际的问题：对话里讨论了很多细节，但最后什么都没有沉淀下来。
4.7 /to-issues —— PRD 拆解为垂直切片任务
PRD 确认后，运行：
/to-issues
AI 将 PRD 拆解成垂直切片的独立 issue。每个 issue 贯穿所有集成层（前后端都包含），可以独立交付。
同时，每个 issue 会标注：
- AFK（Agent Freely Known）：AI 可以独立完成
- HITL（Human In The Loop）：需要人类决策
PRD "数据导出功能" 被拆解为：
issue #1（AFK）：后端导出接口 + CSV 生成
issue #2（AFK）：前端导出按钮 + 日期选择器
issue #3（HITL）：权限控制——谁有权导出全部数据？
→ 需要你拍板，AI 无法替你决定数据访问权限策略
垂直切片 vs 水平切片（前后端分别开发再联调）的区别在于：垂直切片的每个 issue 交付后都能看到完整的功能，而不是半成品。
4.8 /triage —— Issue 状态机管理
一个基于标签的 issue 分类系统：
状态机：
needs-triage → needs-info → ready-for-agent → done
↘ ready-for-human
↘ wontfix → 归档到 .out-of-scope/
类别：
bug / enhancement / question / documentation
当有人提了个"支持 WebSocket 实时推送"的需求，/triage 会：
- 标记为 enhancement + needs-triage
- 列出技术权衡分析
- 如果判断不适合当前阶段，标记 wontfix 并写一份拒绝理由放入
.out-of-scope/ - 半年后有人再提，直接引用已有文档，无需重复讨论
4.9 /zoom-out —— 全局视角看代码
在动手改一个模块之前，先搞清楚它在整个系统中的位置：
/zoom-out
AI 会画出当前模块的相关模块和调用方地图，并标注影响范围。
你要改 PaymentService.processPayment()
AI 报告：
模块地图：
PaymentService.processPayment()
├── 被调用方：OrderController, SubscriptionRenewal, RefundHandler
├── 依赖方：PaymentGateway, InvoiceGenerator
└── 影响范围：订单、订阅、退款、发票 4 个功能域
警告：修改此方法签名会影响 3 个上游调用方
建议：只改内部实现，或同步更新所有调用方
避免"改完发现自己炸了三个模块"的悲剧。
4.10 /prototype —— 可丢弃的原型验证
对某个设计决定没把握时，用 /prototype 生成一个最小可行原型来验证假设：
规则：
✓ 用最少代码验证设计假设
✓ 逻辑问题 → 终端小程序推状态机
✓ UI 问题 → 同一路由用 URL 参数切换多方案
✗ 不写测试
✗ 不做抽象
✗ 原型代码明确标记 throwaway
实际例子：你不确定"任务看板"是用拖拽还是弹窗来移动任务。跑 /prototype，AI 生成：
/kanban?variant=drag → 拖拽版
/kanban?variant=modal → 弹窗版
你在浏览器里切换对比，5 分钟决定用哪个。然后删掉原型，把设计决策合并进正式代码。
4.11 /handoff —— 跨 Session 交接文档
这是 Matt Pocock 技能集中最被低估的一个技能。
当你和 Claude Code 干了半天，刚把 PRD 拆成 issue，该睡觉了。运行：
/handoff
AI 生成一份交接文档，包含：
- 本次对话完成了什么
- 当前卡点和原因
- 下一步行动计划
第二天早上，新的 Claude Code session 读取这个文档，直接知道昨天做了什么、从哪里继续。
解决的问题：AI 编程中，每个 session 都是"失忆"的——对话结束后，所有上下文消失，下次又要从头解释。但工程实践中，很多任务需要跨越多个 session 才能完成。/handoff 把 session 之间的上下文断裂给缝上了。
4.12 /caveman —— 省 token 模式
当 context window 快满时，运行：
/caveman
AI 切成电报体，砍掉所有冠词、寒暄和 filler words：
正常模式：
"好的，我来帮你分析一下 PaymentService 这个类的结构。
这个类目前有大约 200 行代码，包含了支付处理的所有逻辑..."
caveman 模式：
"分析 PaymentService
→ 4 个方法, 2 个 helper
→ 提取 helper 到 PaymentsHelpers
→ 开始？"
token 节省约 75%。适合在 context window 紧张时快速推进对话。
4.13 /write-a-skill —— 构建你自己的工程纪律
这是技能的元技能——教你怎么创建新的 Skill。
Matt Pocock 的 Skill 文件格式非常开放：
# SKILL.md 示例结构
## 触发词
/skill-name
## 触发条件
当用户想要做 X 的时候激活
## 执行步骤
1. 第一步做什么
2. 第二步做什么
3. ...
## 输出格式
描述输出的结构和位置
## 注意事项
- 什么情况下应该终止
- 什么情况下可以跳过
你公司有一堆代码规范（commit 格式、分支命名、部署 checklist），跑 /write-a-skill，AI 引导你把这些写成 /code-review、/pre-deploy 两个技能，新来的 Agent 自动遵守你们团队的规范。
五、推荐工作流：从需求到交付的完整闭环
mattpocock/skills 设计的精髓在于把所有工程纪律串联成一个可执行的工作流：
┌─────────────────────────────────────────────┐
│ 第一阶段：需求定义 │
│ /grill-with-docs → 需求对齐 + 术语建设 │
│ /to-prd → 生成 PRD │
│ /to-issues → 拆解垂直切片 issue │
│ /triage → 状态分类（ready-for-agent）│
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ 第二阶段：编码实现 │
│ /tdd → 红→绿→重构 │
│ /zoom-out → 改代码前看全局 │
│ /prototype → 重要决策先做原型验证 │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ 第三阶段：调试与审查 │
│ /diagnose → 结构化调试（先造信号！） │
│ /improve-codebase-architecture → 定期架构体检│
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ 辅助技能： │
│ /handoff → 跨 session 交接 │
│ /caveman → 省 token 加速 │
│ /write-a-skill → 扩展自己的技能体系 │
└─────────────────────────────────────────────┘
六、与 QClaw Skills 的对比：殊途同归的工程纪律
有意思的是，Matt Pocock Skills 的设计思路和 QClaw 的 Skill 机制高度共鸣。两者都认识到：
- AI 需要工程纪律的约束，而不是更多能力加持
- Skill 应该是开放标准，不是专有框架——mattpocock/skills 的 SKILL.md 可以被 Codex CLI、Claude Code、GitHub Copilot 等多个平台直接复用
- 文档和交接是 AI 编程的生命线——CONTEXT.md、handoff、ADR，这些文档机制解决的是 AI 的"记忆断裂"问题
但两者也有分工上的差异：
- Matt Pocock Skills 主要面向单个项目内的工程实践（TDD、架构、调试、PRD）
- QClaw Skills 更偏向跨任务的工具链集成（搜索、发布、云存储、多平台协作）
如果你同时使用两者，合理的分工是：QClaw Skills 负责你的外部工作流（研究、发布、协作），Matt Pocock Skills 负责你的代码工程纪律。
七、安装与快速上手
7.1 安装步骤
# 1. 安装 skills CLI（如果没有）
npm install -g skills@latest
# 2. 添加 Matt Pocock Skills
npx skills@latest add mattpocock/skills
# 3. 进入项目目录，初始化
cd your-project
claude # 启动 Claude Code
/setup-matt-pocock-skills # 回答三个配置问题
# 4. 开始使用
/grill-with-docs # 新需求的第一次对话
7.2 新手建议
不要一次启用所有技能。Matt Pocock 本人建议：
第一周：只启用 /grill-with-docs 和 /tdd
感受需求对齐和 TDD 的效果
第二周：加入 /diagnose 和 /zoom-out
改善调试和代码理解
第三周：加入 /improve-codebase-architecture
开始定期架构审查
第四周：加入 /to-prd、/to-issues、/triage
完善需求管理工作流
八、总结：AI 编程的下半场是工程纪律
mattpocock/skills 回答了一个 2026 年每个开发者都在面临的问题：有了 AI 之后，工程师的核心价值是什么？
Matt Pocock 的答案是：工程纪律，而不是写代码本身。
当 AI 能以 10 倍速度写代码时，唯一能与之匹配的是同样 10 倍严格的工程纪律——更早的需求对齐、更快的反馈循环、更频繁的架构审查、更系统的调试方法。
mattpocock/skills 的本质，是把几十年软件工程积累的最佳实践，转化为 AI 可以执行的 Skill 指令。它不改变 AI 的能力边界，它改变的是 AI 的行为模式——从"你让写什么我就写什么"到"在做任何事情之前，让我先确认我理解了对的、测试了对了、考虑了全局了"。
正如 Kent Beck 所说："每天投资于系统的设计"（Invest in the design of the system every day）。有了 mattpocock/skills，AI 终于也能参与到这个投资中了。
参考资料：
- GitHub: https://github.com/mattpocock/skills
- skills.sh 安装器: https://skills.sh/mattpocock/skills
- Matt Pocock Newsletter: https://www.aihero.dev/s/skills-newsletter
- 《The Pragmatic Programmer》— David Thomas & Andrew Hunt
- 《Domain-Driven Design》— Eric Evans
- 《A Philosophy of Software Design》— John Ousterhout
- 《Extreme Programming Explained》— Kent Beck