mattpocock Skills 完全入门指南：让 AI 学会 TDD 和结构化调试

一句话总结： mattpocock/skills 是一套「工程方法论技能包」，装上它之后，你的 AI 编程工具不再瞎猜——它会像一个受过训练的工程师一样，按规矩写测试、按流程查 bug、按逻辑问你需求。

目录

• 为什么需要 mattpocock Skills？

• 这个项目是什么？

• 适合谁用？

• 环境准备

• 第一步：安装 Skills

• 第二步：初始化配置

• 第三步：用 /grill-me 对齐需求

• 第四步：用 /tdd 做测试驱动开发

• 第五步：用 /diagnose 做结构化调试

• 第六步：用 /write-a-skill 创建自定义技能

• 常见问题排查

• 进阶方向

• FAQ

为什么需要 mattpocock Skills？

你有没有遇到过这种情况：让 AI 帮你写代码，它速度飞快，但结果总是差点意思？

这不是 AI 工具的 bug，而是方法论的缺失。

Matt Pocock（TypeScript 领域的大神级人物）在大量实践中总结出 AI 编程的四个高频翻车模式：

mattpocock/skills 就是对症下药的解法。 它把几十年的工程经验压缩成一组可组合的技能（Skills），让 AI 在任何模型上都遵守同样的工程纪律。

这个项目是什么？

GitHub 仓库： github.com/mattpocock/skills

简单来说，mattpocock/skills 是一组预设的指令模板，你安装到 AI 编程工具（比如 Claude Code、Codex）里，然后通过 / 斜杠命令来调用。

每个技能都是一个结构化的「行动指南」，AI 读了之后就知道该怎么规范地做事——该问你的会问你，该写测试的会写测试，该查 bug 的会按流程来。

核心技能一览

适合谁用？

最适合的人群：

• 有 1-5 年经验的后端 / 全栈开发者

• 已经在用 Claude Code、Codex 或类似 AI 编程工具

• 觉得 AI 写的代码「能用但不靠谱」，想建立可控的开发节奏

• 对 TDD（测试驱动开发）有兴趣，但一直没找到合适的入门方式

不太适合的人群：

• 完全没用过命令行的纯新手

• 从没接触过 AI 编程工具的开发者（建议先熟悉工具，再回来）

环境准备

开始之前，确保你的环境满足以下条件：

注意： mattpocock/skills 通过 /slash 命令调用，你的 AI 工具必须支持「技能（Skills）」机制。如果不确定，先确认工具是否已启用 Skills 功能。

第一步：安装 Skills

打开终端，在你的项目目录下运行：

npx skills@latest add mattpocock/skills

安装脚本会引导你完成两件事：

1. 选择要激活的技能——你可以全选，也可以只选你需要的

2. 选择绑定到哪个 AI 工具——比如 Claude Code

关键一步： 确认选择 setup-matt-pocock-skills，这是后续所有技能的初始化入口，漏掉这步后面全白搭。

小贴士： 安装过程不需要 sudo 权限，也不会修改你的项目代码。Skills 存储在 AI 工具的配置目录中，与你的项目完全隔离。

第二步：初始化配置

安装完成后，在你的 AI 编程工具中执行：

/setup-matt-pocock-skills

这个 Skill 会依次问你三个问题：

问题 1：你用什么工具管理 Issue？

选择你常用的：

• GitHub ——最常见，选这个准没错

• Linear ——如果你团队用 Linear 管理任务

• 本地文件 ——不想依赖外部服务

问题 2：给 Issue 打标签用什么词汇？

比如 bug、feature、urgent 等。这个配置会被 /triage 技能使用，帮你自动给 Issue 分类。

问题 3：生成的文档放哪里？

指定一个路径，比如 docs/。ADR（架构决策记录）等文档会存放在那里。

配置完成后会发生什么？

项目根目录会生成一个 CONTEXT.md 文件。这个文件非常重要——它是你和 AI 之间的「共享语言词典」。

打个比方：你和 AI 说「购物车」，你指的是「用户选完商品、还没付款的那个列表」，但 AI 可能理解成「用户的订单历史」。CONTEXT.md 就是让你们对这些术语达成一致的地方。

第三步：用 /grill-me 对齐需求

这是你每次开始新功能之前必做的一步。

为什么要先对齐需求？

举个例子：你说「给支付模块加个退款功能」，AI 可能直接就开始写了——但它不知道：

• 退款是全额退还是部分退？

• 退款是用户自己发起，还是客服手动操作？

• 退款后库存怎么处理？

• 退款记录要不要存？

如果不问清楚就开始写，代码写出来大概率要推倒重来。

怎么用？

在 AI 编程工具中输入：

/grill-me

然后告诉 AI 你的需求。注意：不要怕被打断——AI 会像面试官一样逐一追问你：

AI：退款是全额还是部分？
你：都可以，但部分退款上限不能超过原订单金额。

AI：退款的触发条件是什么？
你：用户主动申请 + 客服审核通过。

AI：退款后库存怎么处理？
你：自动恢复，但如果商品已发货就不恢复。

AI：退款日志要持久化吗？
你：要，存到数据库，方便后续审计。

每个问题 AI 都会给你推荐默认答案，你只需要确认或纠正，效率很高。

/grill-me vs /grill-with-docs

经验之谈： 很多时候你觉得 AI「理解错了」，其实是你没有把需求说清楚。/grill-me 的本质就是「让 AI 帮你把需求想明白」。

第四步：用 /tdd 做测试驱动开发

这是 mattpocock/skills 最核心的部分。

什么是 TDD？用大白话解释

TDD = Test-Driven Development = 测试驱动开发。

核心思路就一句话：先写测试，再写代码。

类比一下：你要射箭，不是先射再画靶子，而是先把靶子立好，再瞄准射。测试就是那个靶子。

什么是「垂直切片」？

这是理解 /tdd 的关键概念。

错误做法（水平切片）： 一次性写完全部 10 个测试 → 再一次性写完全部实现代码。

为什么错？因为你写第 10 个测试的时候，代码还没写，你测的是「想象中的行为」，不是「真实的行为」。等你把代码写完，测试可能全部要改。

正确做法（垂直切片）： 一次只做一个小功能的完整循环。

RED:    写一个测试 → 运行 → 测试失败 ✗GREEN:  写最少的代码让测试通过 → 测试通过 ✓REFACTOR: 重构（可选）→ 进入下一个切片

实战演示：购物车结算功能

第一轮：测「购物车能添加商品」

import { describe, it, expect } from 'vitest';import { Cart } from './cart';describe('Cart', () => {  it('allows adding an item', () => {    const cart = new Cart();
    cart.addItem({ id: 'book-1', name: 'TypeScript 入门', price: 59 });    expect(cart.items).toHaveLength(1);
  });
});

此时运行测试——会失败，因为 Cart 类还不存在。这就是 RED 阶段。

接下来，写最少的代码让测试通过：

// cart.tsexport interface CartItem {  id: string;  name: string;  price: number;
}export class Cart {  items: CartItem[] = [];  addItem(item: CartItem) {    this.items.push(item);
  }
}

运行测试——通过了。这就是 GREEN 阶段。

第二轮：测「购物车能计算总价」

it('calculates total price', () => {  const cart = new Cart();
  cart.addItem({ id: 'book-1', name: 'TypeScript 入门', price: 59 });
  cart.addItem({ id: 'book-2', name: 'React 实战', price: 79 });  expect(cart.totalPrice()).toBe(138);
});

运行测试——失败（totalPrice 方法不存在）。RED。

添加方法：

// cart.ts —— 在 Cart 类中添加totalPrice(): number {  return this.items.reduce((sum, item) => sum + item.price, 0);
}

运行测试——通过。GREEN。

然后进入第三轮、第四轮…… 每一轮都只做一小步，但每一步都是实打实能跑通的。

为什么要禁止水平切片？

重要提醒： 如果 AI 在 /tdd 中试图一次性写完所有测试，你要主动打断它——「只写第一个测试，实现它，然后再写下一个。」

第五步：用 /diagnose 做结构化调试

代码出了 bug，你的第一反应可能是「让 AI 帮我修」。但这样做的问题是：AI 在没有反馈信号的情况下修 bug，就像蒙着眼睛修车。

/diagnose 把调试变成了一个有章可循的工程流程。

六阶段调试循环

实战演示：支付接口突然报 500

假设你的 /api/checkout 接口突然返回 500 错误，执行 /diagnose 后：

阶段 1：构建反馈循环

先写一个失败测试，把问题锁定到具体接口：

import { describe, it, expect } from 'vitest';import { createHonoServer } from './server';import fetch from 'node-fetch';describe('Payment API', () => {  it('returns 200 for valid checkout', async () => {    const app = createHonoServer();    const response = await fetch('http://localhost:3000/api/checkout', {      method: 'POST',      headers: { 'Content-Type': 'application/json' },      body: JSON.stringify({        items: [{ id: 'book-1', quantity: 1 }],        userId: 'user-123',
      }),
    });    expect(response.status).toBe(200);    // 目前会失败——实际返回 500
  });
});

阶段 3：生成假设列表

AI 会列出可能的原因：

1. 库存服务超时，导致未捕获异常

2. 数据库事务未提交

3. 支付网关返回格式解析错误

阶段 4：逐一验证

AI 不会把三个修复方案全堆上去，而是每次只验证一个假设：

• 先 mock 库存服务返回成功 → 如果 500 消失了，说明是假设 1

• 如果没消失，再检查 transaction.commit() → 如果发现了问题，说明是假设 2

• 以此类推

这就是结构化调试的精髓：有依据地排查，而不是改代码碰运气。

第六步：用 /write-a-skill 创建自定义技能

当你在项目中摸索出一套自己的工作流，可以把它封装成一个 Skill，让 AI 以后直接调用。

怎么用？

/write-a-skill

AI 会依次问你：

1. 这个 Skill 覆盖哪个领域？ 比如「API 客户端生成」

2. 具体使用场景？ 比如「当用户提到 generate types、API client 时」

3. 需要附带脚本还是纯指令？

4. 有没有参考材料？

然后它会生成标准的目录结构：

my-custom-skill/
├── SKILL.md              # 主指令文件（必选）├── REFERENCE.md          # 详细文档（内容多时拆分）├── EXAMPLES.md           # 使用示例└── scripts/
    └── helper.ts         # 工具脚本（可选）

SKILL.md 的 description 怎么写？

这是 AI 感知你这个 Skill 的唯一入口，格式很重要：

---
name: my-custom-skill
description: 从 JSON Schema 生成类型安全的 API 客户端，并注入 Mock 数据。              Use when user mentions "API client", "generate types", or "mock data".
---

• 第一句： 说清楚「它做什么」

• 第二句： 说清楚「在什么场景下触发」

注意： description 最大 1024 个字符。写得太笼统（比如「帮助处理文档」）会让 AI 无法区分这个 Skill 和其他 Skill。越具体越好。

常见问题排查

问题 1：AI 不写测试，直接跳到写代码

现象： 你调用 /tdd，但 AI 直接开始写实现代码，跳过了 RED 阶段。

解决方法：

1. 确认 CONTEXT.md 中已定义测试框架（比如 Vitest、Jest）

2. 在 /tdd 开始时明确说：「只写一个测试，不要写其他代码」

3. 如果 AI 还是跳过，手动输入「先写一个失败的测试」

根本原因： AI 对 TDD 的字面理解是「写了测试就行」，它不理解「测试失败」本身才是关键信号。

问题 2：AI 一次写完全部测试

现象： AI 在 /tdd 中一次性生成 10 个测试文件，然后一次性写完所有实现。

解决方法：

1. 直接干预：「只写第一个测试，然后实现它。等我确认后再写下一个。」

2. 在 CONTEXT.md 中加一条规则：「禁止水平切片，每次只做一个垂直切片」

根本原因： AI 天然倾向于「一次性搞定」，因为这样看起来效率最高。但实际上恰恰相反。

问题 3：调试循环没有反馈信号

现象： 你调用 /diagnose，但 AI 只是反复改代码，没有先建立可重复的失败信号。

解决方法：

1. 第一阶段没通过，不要进第二阶段。告诉 AI：「还没有可重复的失败信号，继续构建反馈循环」

2. 优先用真实的 HTTP 请求来复现问题，而不是 mock 掉整个模块

根本原因： 反馈循环是调试的核心。没有它，后面所有的动作都是盲动。

问题 4：自定义 Skill 不被 AI 加载

现象： 你写了 Skill，但 AI 不加载它。

解决方法：

1. 检查 plugin.json 中是否已注册该 Skill

2. 确认 description 中包含用户实际会说的关键词

3. 确认 SKILL.md 的 YAML frontmatter 格式正确

根本原因： Skills 的加载依赖 description 中的关键词匹配。描述不精确就无法触发。

问题 5：/grill-me 访谈变成单方面倾诉

现象： /grill-me 执行时 AI 只在听你说，不主动追问。

解决方法：

1. AI 追问你的时候才说明它进入了访谈模式——继续回答就好

2. 如果 AI 超过 3 轮不追问，主动说：「继续追问，我还有更多信息」

3. 可以直接点明：「你觉得这个需求还有什么边界条件没覆盖到？」

根本原因： AI 倾向于快速收敛到「看起来理解了」的状态，而不是穷举所有可能的分支。

问题 6：CONTEXT.md 越来越大，AI 响应变慢

现象： 随着项目推进，CONTEXT.md 不断膨胀，AI 开始出现上下文溢出。

解决方法：

1. 定期重构 CONTEXT.md：保留「已稳定的通用术语」，把「临时决策记录」移到 docs/adr/ 目录

2. 用 /improve-codebase-architecture 帮助识别哪些内容应该拆出去

根本原因： CONTEXT.md 是动态增长的。不维护就会变成另一个 monorepo——塞满了但没几个人看得完。

进阶方向

1. 从 TDD 到架构改进

当你的代码库经过几轮 TDD 重构后，可以用 /improve-codebase-architecture 做架构诊断。它会：

• 读取 CONTEXT.md 中的领域语言

• 分析 docs/adr/ 中的决策记录

• 识别「浅模块」（接口复杂但功能少）和重构机会

2. 结合 Total TypeScript

Matt Pocock 本人是 TypeScript 类型体操的倡导者。他的 Total TypeScript 课程是理解类型驱动开发的绝佳补充，包含五个专业级工作坊：

• TypeScript Pro Essentials — 从环境搭建到应用开发模式

• Type Transformations — 类型变换的进阶技巧

• TypeScript Generics — 泛型的深度理解

如果你的项目使用 TypeScript，Total TypeScript + mattpocock/skills 会是一套强力组合。

3. 只装你需要的

mattpocock/skills 的设计哲学是「小而可组合」。你不需要全装——可以先只装 /tdd 和 /diagnose，在日常开发中渐进引入其他技能。

FAQ

mattpocock/skills 支持哪些 AI 工具？

目前主要支持 Claude Code，理论上任何支持 Skills 机制的 AI 编程工具都可以使用。

安装会不会影响我的项目代码？

不会。Skills 存储在 AI 工具的配置目录中，与你的项目完全隔离。

需要 TDD 经验才能用吗？

不需要。/tdd 技能本身就是为零 TDD 经验的人设计的——AI 会引导你走完 RED-GREEN-REFACTOR 循环，你只需要跟着做。

CONTEXT.md 和 README.md 有什么区别？

README.md 是给人看的项目说明；CONTEXT.md 是给 AI 看的「语言词典」，定义了项目中所有术语的含义和使用约定。

可以在多个项目中共享 Skills 吗？

可以。Skills 是全局安装的，安装一次就能在所有项目中使用。但 CONTEXT.md 是项目级别的，每个项目需要单独配置。

/tdd 和 /diagnose 可以一起用吗？

当然可以，而且建议这样做。/tdd 负责写代码时的质量保障，/diagnose 负责出了问题后的排查流程。两者结合，覆盖了从开发到维护的完整生命周期。

最后的建议： 不要试图一次学完所有技能。从 /grill-me + /tdd + /diagnose 这三个核心技能开始，用熟了再逐步引入其他。工具是手段，工程思维才是目的。