编程 TypeScript 巫师的 21 个 Claude 技能：当 AI 编程从"氛围"走向"工程"

2026-05-06 11:34:54 +0800 CST views 3

TypeScript 巫师的 21 个 Claude 技能：当 AI 编程从"氛围"走向"工程"

Matt Pocock 开源了个人 .claude 配置目录，24 小时内斩获 22,000 Star。这不仅是"配置分享"，更是 AI 编程领域的一场范式革命——从"生成更多代码"转向"把每个决策想透"。

一、一个目录引发的风暴

2026 年 4 月 26 日，GitHub Trending 出现了一个让很多工程师感到意外的项目。

它不是框架，不是库，甚至不是一个完整的应用。它只是 Matt Pocock 个人 .claude 目录里的技能文件夹集合——21 个 Markdown 文件夹，每个文件夹装着一套让 Claude Code 具备特定能力的指令。

就是这样看似"简单"的仓库，当日新增 1,700 颗 Star，总数迅速突破 23,500+，占据 GitHub Trending 高位。同一天，free-claude-code 拿了 1,701 个 Star，awesome-codex-skills 拿了 517 个——三个仓库霸占 Trending 前列，主题完全一样：如何调教你的 AI 编程助手。

GitHub 社区在用 Star 投票：我们太需要这个了。

二、Matt Pocock 是谁？

在深入理解这个项目之前，有必要认识一下作者。

Matt Pocock 在 TypeScript 社区的地位，大概相当于这个领域的"布道者"：

GitHub：10,300+ 关注者
身份：TypeScript 巫师（GitHub bio: "TypeScript wizard"），教开发者为生
代表项目：
- Total TypeScript：生产级 TypeScript 综合课程，其核心商业产品
- ts-reset（8,400 ⭐）：被称为"TypeScript 的 CSS Reset"
- evalite（1,500 ⭐）：用 TypeScript 评估 LLM 应用
- sandcastle（1,000 ⭐）：TypeScript 沙箱 coding agent 编排
AI Hero Newsletter：约 60,000 订阅者
前经历：前 Vercel 工程师、前 Stately 工程师

他不是一个"写工具给别人用"的人——他首先是一个每天认真用 AI 干活的工程师，然后才是一个教别人的人。这个仓库是他日常工作流的直接产物。

三、核心哲学：反氛围编程

README 开篇第一句话：

"给真正工程师的 Agent 技能，不是氛围编程。"

这是理解整个项目的钥匙。

3.1 什么是氛围编程（Vibe Coding）？

现在绝大多数人用 AI 写代码的思路是"生成"——让它帮你写函数、补样板、一键出页面，越快越好。业界称之为 Vibe Coding。

典型的氛围编程场景：

用户：帮我写一个用户登录功能
AI：好的，我给你生成了 500 行代码...
用户：看起来不错，commit！
（三天后）
用户：这代码 bug 太多了，AI 你帮我修一下
AI：我给你改了 200 行...
用户：又出问题了...

氛围编程的问题在于：AI 成了"更快的打字机"，而不是"更严谨的思考伙伴"。

3.2 Matt 的反向思路

Matt 的思路完全相反。他教 Claude 做的事，大部分不是生成代码，而是在写代码之前把问题想清楚。

四个失败模式诊断（来自 README）：

失败模式	症状	Matt 的修复方案
No-one knows exactly what they want	你以为 AI 懂了，结果做出来完全不是你要的	`grill-me` / `grill-with-docs` — 盘问式对齐
Agents are dropped into a project without context	AI 不懂你的项目术语，用 20 个词说一个概念	`ubiquitous-language` — 建立统一语言
Flying blind without feedback	没有测试、没有类型检查，AI 只能"猜"	`tdd` — 强制红绿重构循环
Codebases become balls of mud	AI 加速了软件熵，代码越来越乱	`improve-codebase-architecture` — 定期架构审视

这些失败模式不是 AI 的问题，是我们使用 AI 的方式的问题。

四、核心技能深度解析

4.1 `grill-me` — 最有用的技能

Matt 本人说这是他用过最有用的技能。

功能：让 Claude 扮演一个会追着你问的严苛面试官，盘问你的技术方案。

不是那种客客气气提两条建议的"AI 反馈"。 是追着你问——每个分支、每个边界条件、每个你没想到的 case，每次只问一个问题，一直问到你自己都觉得"操，这个我确实没想清楚"为止。

使用场景示例

你想要给项目加一个缓存层。

直接让 AI 写代码？且慢，先用 grill-me：

AI：你的缓存粒度是什么？函数级还是请求级？
你：请求级吧
AI：如果缓存键冲突，你的失效策略是什么？
你：...这个我没想过
AI：我推荐用版本号作为后缀，避免键冲突。你有 race condition 的场景吗？多个请求同时缓存未命中？
你：确实有...
AI：如果缓存服务挂了，降级方案是什么？
你：直接查数据库？
AI：那你的数据库能扛住缓存失效瞬间的流量洪峰吗？
你：...不能
AI：你的测试怎么 mock 缓存？用什么库？
...

磨完之后，你的设计要么变得更严密，要么你意识到这件事现在不该做。

技能实现原理

# grill-me SKILL.md 核心逻辑

## Steps
1. Interview me relentlessly about every aspect of this plan
2. Walk down each branch of the design tree, resolving dependencies one-by-one
3. For each question, provide your recommended answer
4. Ask questions ONE AT A TIME, waiting for feedback before continuing
5. If a question can be answered by exploring the codebase, explore instead of asking

关键设计决策：

每次只问一个问题：避免问题轰炸，强制逐步深思
给出推荐答案：不是光问，还会帮你想
主动探索代码库：能自己找答案的就不问你

4.2 `grill-with-docs` — 带文档的盘问

这是 grill-me 的增强版，增加了统一语言的概念。

核心创新：在盘问过程中，同步建立项目的"领域词汇表"。

统一语言的价值

Eric Evans 在《领域驱动设计》中写道：

"With a ubiquitous language, conversations among developers and expressions of the code are all derived from the same domain model."

问题场景：

你：课程的章节有个问题，当课程里面的一个节被"实化"之后...
AI：（懵了）"实化"是什么意思？

有了统一语言之后：

你：有个 materialization cascade 的问题
AI：哦，我懂了，你的 CONTEXT.md 里定义了：
    "Materialization: 将虚拟的课程节映射到实际文件系统位置的过程"
    具体是什么问题？

对比：

BEFORE	AFTER
"课程里面的一个节被'实化'"	"materialization cascade 问题"
AI 需要猜测你的意思	AI 从 CONTEXT.md 直接获取定义
每次对话都要重新解释	一次定义，永久复用

文档结构

/
├── CONTEXT.md          ← 统一语言词汇表
├── docs/
│   └── adr/            ← 架构决策记录
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/

如果项目有多个上下文：

/
├── CONTEXT-MAP.md      ← 上下文映射
├── docs/
│   └── adr/            ← 系统级决策
├── src/
│   ├── ordering/
│   │   ├── CONTEXT.md  ← 订单上下文词汇
│   │   └── docs/adr/   ← 订单上下文决策
│   └── billing/
│       ├── CONTEXT.md  ← 账单上下文词汇
│       └── docs/adr/   ← 账单上下文决策

ADR 创建条件

只有同时满足三个条件才创建 ADR：

Hard to reverse：改主意成本很高
Surprising without context：未来的读者会问"为什么这么做"
Result of a real trade-off：有真正的替代方案，你选了一个

如果缺少任何一个，跳过 ADR——不要为记录而记录。

4.3 `tdd` — 强制红绿重构循环

这个技能不让 Claude 一口气把功能写完。它强制执行严格的 TDD 工作流：

Tracer Bullet（先打通最简路径）
        ↓
增量循环：
  写一个会失败的测试
        ↓
  写刚好让这个测试通过的最少代码
        ↓
  重构（代码更干净，测试依然通过）
        ↓
  下一个测试...

关键约束

## Rules
- NO horizontal slicing: 不允许先写完所有测试再实现
- Tests verify behavior, not implementation: 通过公共接口测，而非内部细节
- Each test should be atomic and independent

为什么禁止水平切片？

❌ 水平切片（别这么做）：

Issue 1: 写完所有测试
Issue 2: 实现所有代码
Issue 3: 测试通过后重构

问题：你会过度设计测试，因为你不知道实现时会遇到什么问题。

✅ 垂直切片（Matt 的方式）：

Iteration 1: 写测试 A → 实现 A → 重构
Iteration 2: 写测试 B → 实现 B → 重构
Iteration 3: 写测试 C → 实现 C → 重构

优势：每个测试都是基于上一个实现的经验，测试驱动设计，而不是设计驱动测试。

参考文档

技能目录下有 6 个参考文档：

文档	内容
`deep-modules.md`	John Ousterhout 的"深模块"设计原则
`interface-design.md`	接口设计的最佳实践
`mocking.md`	Mock 的正确使用方式
`refactoring.md`	安全重构的步骤
`tests.md`	什么是好测试

4.4 `triage-issue` — 先诊断，再修复

拿到一个 bug 报告，大多数人（包括大多数 AI）的反应是：找到那行代码，改掉，提 PR。

Matt 的 triage-issue 技能在修复之前多加了一步：彻底诊断。

五阶段流程

1. 捕获问题（理解症状）
        ↓
2. 探索诊断（翻遍代码库，找根因）
        ↓
3. 确定修复方案（不是第一个可行方案，是最好的方案）
        ↓
4. 设计 TDD 修复计划（先写测试，再修复）
        ↓
5. 创建 GitHub Issue（诊断报告 + 修复计划 + 验收标准）

注意：这个技能的输出不是代码，是 GitHub Issue。

价值：当你（或另一个 Agent）去执行修复时，已经有了清晰的根因分析和测试驱动的路线图。

实战示例

Bug 报告：用户点击"导出 PDF"按钮，页面卡死。

直接修复（错误方式）：

// 找到导出函数，加个 loading 状态
exportButton.addEventListener('click', () => {
  showLoading();
  exportPDF();
});

triage-issue 方式：

捕获问题：
- 症状：点击导出按钮后 UI 无响应
- 复现步骤：打开大型文档 → 点击导出
- 环境信息：Chrome 120, macOS
探索诊断：
- 代码路径：handleExport → generatePDF → renderPages
- 发现：renderPages 在主线程同步渲染 1000+ 页
- 根因：主线程阻塞导致 UI 卡死
确定修复方案：
- 方案 A：加 loading 状态（治标不治本）
- 方案 B：Web Worker 异步渲染（真正解决问题）✓
- 方案 C：分块导出（用户体验更好，但复杂度高）

TDD 修复计划：

Test 1: 导出 1 页 PDF 应在 1 秒内完成
Test 2: 导出过程中 UI 应保持响应
Test 3: Web Worker 错误应优雅降级

GitHub Issue：

## 诊断结果
根因：`renderPages` 在主线程同步渲染大量页面

## 修复计划
使用 Web Worker 异步渲染，预计 4 小时

## 验收标准
- [ ] 导出 1000 页文档 UI 不卡顿
- [ ] Worker 错误时显示友好提示

4.5 `design-an-interface` — 强制多方案比较

这个技能实现了 John Ousterhout 在《A Philosophy of Software Design》中提出的 "Design It Twice" 原则：

"对任何重要决策，先生成至少两个真正不同的方案，再做选择。"

实现方式

启动多个并行子 Agent，每个被限制在不同维度：

子 Agent A：最少方法数（追求最简接口）
子 Agent B：最大灵活性（追求最强扩展性）
子 Agent C：优化最常见场景（追求最低使用摩擦）

评估维度

三个方案出来之后，从四个维度评估：

维度	问题
简洁性	新人能多快理解这个接口？
泛化能力	未来 3 年的需求变化能应对吗？
实现效率	开发成本是多少？
深度	接口隐藏了多少复杂性？

代码示例

假设你要设计一个"文件上传"接口：

方案 A（最简接口）：

interface FileUploader {
  upload(file: File): Promise<string>; // 返回 URL
}

方案 B（最大灵活性）：

interface FileUploader {
  upload(options: {
    file: File;
    chunkSize?: number;
    onProgress?: (percent: number) => void;
    metadata?: Record<string, string>;
    encrypt?: boolean;
    compress?: boolean;
  }): Promise<UploadResult>;
}

方案 C（优化最常见场景）：

interface FileUploader {
  // 最常用：单文件上传
  upload(file: File): Promise<string>;
  
  // 批量上传
  uploadMany(files: File[]): Promise<string[]>;
  
  // 大文件分片（自动判断是否需要）
  uploadLarge(file: File, onProgress?: (p: number) => void): Promise<string>;
}

评估结果：方案 C 在"常见场景简单，边界场景有路"之间达到了最佳平衡。

4.6 `to-issues` — 垂直切片分解

把一个功能计划拆解成 GitHub Issues——听起来很普通，但关键在于拆分原则：垂直切片（Vertical Slice）。

水平切片 vs 垂直切片

❌ 水平切片（别这么做）：

Issue 1: 数据库 Schema
Issue 2: API 层
Issue 3: 前端 UI
Issue 4: 测试

问题：

Issue 1 完成后，用户什么都看不到
Issue 2 完成后，用户还是什么都看不到
Issue 3 完成后，终于能看了，但一测试全是 bug
Issue 4 写测试时发现，前面三层的设计都有问题

✅ 垂直切片（Matt 的方式）：

Issue 1: 用户可以创建基础草稿（schema + API + UI + tests 全穿透）
Issue 2: 草稿可以添加富文本内容
Issue 3: 草稿可以发布
Issue 4: 发布后可以分享链接

优势：

每个 Issue 完成后，用户可见价值
测试在第一时间写，问题在第一时间发现
每个 Issue 都是一个可部署的增量

HITL vs AFK 分类

每个 Issue 被标记为：

类型	含义	例子
HITL (Human In The Loop)	需要人工决策	"确认订单状态流转规则"
AFK (Away From Keyboard)	可以无人值守	"实现订单状态枚举"

这让你可以批量处理 AFK 任务，在 HITL 任务上集中精力。

4.7 `git-guardrails-claude-code` — 防 AI 删库

通过 Claude Code 的 PreToolUse hook 拦截危险 git 命令。

被拦截的操作：

git push --force
git reset --hard
git clean -f / -fd
git branch -D
git checkout .
git restore .

当 Claude 尝试执行这些命令时，它会收到消息：

"it lacks authority to access these commands"

配置方式

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": ["git-guardrails"]
      }
    ]
  }
}

可以配置为项目级或全局级。强烈建议全局配置——不要相信 AI 的自我约束。

4.8 其他技能一览

技能	作用
`to-prd`	对话上下文 → 结构化 PRD，直接提交为 GitHub Issue
`request-refactor-plan`	创建带细小 commit 的重构计划，通过用户访谈细化
`improve-codebase-architecture`	结合 CONTEXT.md 和 ADR 文档，寻找架构"深化"机会
`setup-pre-commit`	配置 Husky + lint-staged + Prettier + 类型检查
`ubiquitous-language`	从对话中提取 DDD 风格的统一语言词汇表
`write-a-skill`	按规范结构创建新 skill（技能生成技能！）
`edit-article`	通过重组章节、提升清晰度来改进文章
`obsidian-vault`	在 Obsidian vault 中搜索、创建和管理笔记

五、Skill 文件的技术架构

5.1 目录结构

每个技能是一个独立文件夹，以 tdd 为例：

skills/tdd/
├── SKILL.md           ← 主技能定义（任务目标、执行步骤、约束条件）
├── deep-modules.md    ← 参考资料：深模块设计原则
├── interface-design.md
├── mocking.md
├── refactoring.md
└── tests.md

5.2 SKILL.md 标准结构

---
name: tdd
description: Build features one vertical slice at a time using TDD...
---

# TDD

## Goal
Build features one vertical slice at a time using TDD...

## Steps
1. Tracer Bullet: First, write the minimal...
2. Increment: For each behavior to implement...
   a. Write a failing test
   b. Write minimal code to pass the test
   c. Refactor if needed

## Rules
- NO horizontal slicing...
- Tests should verify behavior, not implementation...

## Resources
@deep-modules.md
@interface-design.md

5.3 渐进式加载机制

Claude Code 的 skills 采用 Progressive Disclosure（渐进式披露）加载方式：

Layer 1: Claude 读取 available_skills 列表中的 name + description
         ↓
Layer 2: 自行判断是否需要触发该 skill
         ↓
Layer 3: 触发后，用 view 工具读取完整的 SKILL.md
         ↓
Layer 4: 按需加载 Resources 中引用的其他文件

这意味着：只有真正需要时才加载完整指令，节省 context window。

六、安装与定制

6.1 一键安装

# 安装整个技能库
npx skills@latest add mattpocock/skills

# 安装单个技能
npx skills@latest add mattpocock/skills/tdd
npx skills@latest add mattpocock/skills/grill-me

工具会把 SKILL.md 复制到你的 .claude/ 目录。

6.2 初始化设置

安装后，运行 /setup-matt-pocock-skills，它会：

问你用哪个 issue tracker（GitHub / Linear / 本地文件）
问你用哪些标签来分类 issue（/triage 会用到）
问你把文档存放在哪里
完成配置

6.3 定制你的技能

Matt 的技能是"活样本"——你可以根据自己需求修改：

<!-- 原 skill -->
## Rules
- NO horizontal slicing

<!-- 你的定制 -->
## Rules
- NO horizontal slicing
- 每个测试必须在 5 秒内完成（我的项目 CI 有时间限制）

6.4 创建自己的技能

用 write-a-skill 技能来创建新技能：

# 在 Claude Code 中
/write-a-skill

# Claude 会问你：
# 1. 技能名称？
# 2. 技能目标？
# 3. 执行步骤？
# 4. 约束条件？
# 然后自动生成标准格式的 SKILL.md

七、为什么这是 AI 编程的"npm 时刻"？

7.1 同一天三个仓库霸榜意味着什么？

仓库	当日 Star	主题
`mattpocock/skills`	1,700+	个人 Claude 技能库
`free-claude-code`	1,701	Claude Code 免费/开源替代方案
`awesome-codex-skills`	517	Codex 技能大全

这不是巧合。GitHub 社区在说：我们需要共享 AI 配置的规范。

就像当年 npm 让 Node.js 社区能共享工具包，Skills 让 Claude Code 社区开始共享工作流配方。

7.2 JetBrains 的跟进

这个事件之后，JetBrains 等大厂开始发布官方 skills 包。这标志着：

AI 编程助手配置从"个人秘方"走向"行业规范"
企业开始意识到：AI 配置是工程资产，需要版本管理和团队共享

7.3 "你的 .claude 目录是空的吗？"

这是这个项目引发的最有价值的问题。

如果你的 .claude 目录（或 .cursorrules、AGENTS.md）是空的，那你每次都在从零开始。你的 AI 不记得你上次踩过什么坑，不知道你项目的架构约定，不清楚你团队的代码规范。

每次都是一个什么都不知道的新人。

答案应该是：不空，而且持续演进。

八、实战案例：用 Matt 的技能重构一个模块

让我们通过一个完整案例，看看这些技能如何协同工作。

8.1 需求背景

假设你的项目有一个"用户通知"模块，代码已经变成"泥球"：

src/notifications/
├── index.ts           ← 800 行"上帝文件"
├── email.ts           ← 耦合了业务逻辑
├── push.ts            ← 耦合了业务逻辑
└── sms.ts             ← 还没实现，但已经有人在问了

8.2 Step 1: grill-with-docs

/grill-with-docs

AI 的第一个问题：

"你用'通知'这个词，但我看到代码里同时处理了邮件、推送、短信——它们在你的系统里是同一件事吗？收到邮件和收到推送，用户体验有什么区别？"

你的回答：

"嗯，它们都是'触达用户的方式'，但确实不同。邮件适合不紧急的内容，推送适合即时提醒。"

AI 更新 CONTEXT.md：

## 通知渠道

- **Email**: 异步触达，适合摘要、报告等非紧急内容
- **Push**: 即时触达，适合告警、互动等紧急内容
- **SMS**: 紧急触达，适合安全验证、关键告警（未实现）

## 统一术语

- **Notification**: 用户可感知的消息实体
- **Channel**: 触达渠道（Email/Push/SMS）
- **Delivery**: 一次具体的发送行为

下一个问题：

"我看到代码里有 sendEmail() 和 sendPush() 两个函数，但它们共享了同一个 getUserPreferences()——如果用户关闭了邮件通知但开启了推送，你的代码怎么处理？"

你发现了一个 bug。

8.3 Step 2: design-an-interface

/design-an-interface

AI 启动三个并行 Agent：

方案 A（最简接口）：

interface NotificationService {
  send(userId: string, message: string): Promise<void>;
}

方案 B（最大灵活性）：

interface NotificationService {
  send(options: {
    userId: string;
    message: string;
    channels?: ('email' | 'push' | 'sms')[];
    priority?: 'low' | 'normal' | 'high';
    templateId?: string;
    metadata?: Record<string, any>;
  }): Promise<DeliveryResult[]>;
}

方案 C（优化常见场景）：

interface NotificationService {
  // 最常见：自动选择渠道
  send(userId: string, message: string): Promise<void>;
  
  // 指定渠道
  sendVia(userId: string, message: string, channel: Channel): Promise<void>;
  
  // 批量发送
  broadcast(userIds: string[], message: string): Promise<void>;
}

评估：方案 C 胜出——简单场景一行代码，复杂场景有路。

8.4 Step 3: to-issues

/to-issues

AI 生成垂直切片：

## Issue 1: 用户可以查看通知历史 [HITL]
- [ ] 设计通知数据模型
- [ ] 实现 NotificationRepository
- [ ] 添加 GET /notifications API
- [ ] 前端通知列表页
- [ ] 测试：用户可以看到自己收到的通知

## Issue 2: 系统可以发送邮件通知 [AFK]
- [ ] 实现 EmailChannel
- [ ] 集成 SendGrid SDK
- [ ] 测试：可以发送邮件到真实邮箱

## Issue 3: 系统可以发送推送通知 [AFK]
- [ ] 实现 PushChannel
- [ ] 集成 FCM SDK
- [ ] 测试：可以发送推送到测试设备

## Issue 4: 系统可以智能选择渠道 [HITL]
- [ ] 实现渠道选择策略
- [ ] 添加用户偏好设置
- [ ] 测试：关闭邮件后系统自动使用推送

8.5 Step 4: tdd

对每个 Issue 执行 TDD：

/tdd

AI 执行 Issue 1 的 TDD 流程：

=== Test 1 ===
写测试：未登录用户访问 /notifications 返回 401
运行测试：FAIL
写代码：添加认证中间件
运行测试：PASS
重构：无

=== Test 2 ===
写测试：登录用户访问 /notifications 返回自己的通知列表
运行测试：FAIL（数据库还没数据）
写代码：实现 NotificationRepository.findAllByUserId
运行测试：PASS
重构：提取数据库连接到单独模块

=== Test 3 ===
写测试：通知列表按时间倒序排列
运行测试：FAIL
写代码：添加 ORDER BY createdAt DESC
运行测试：PASS
重构：无

...

8.6 Step 5: improve-codebase-architecture

一周后，运行：

/improve-codebase-architecture

AI 发现的问题：

"你的 EmailChannel 和 PushChannel 都有 retry() 方法，但实现不同。Email 用指数退避，Push 用固定间隔。建议统一为 RetryPolicy 接口。"

AI 建议的 ADR：

# ADR-001: 统一重试策略

## 背景
不同渠道的重试策略不一致，维护成本高。

## 决策
引入 `RetryPolicy` 接口，所有渠道实现统一接口。

## 后果
- 优点：重试逻辑可复用，测试更简单
- 缺点：需要重构现有代码

九、总结：AI 编程的两条路

Matt Pocock 在 README 写的那句话值得反复读：