VibeCoding工程化实践之Matt Pocock Skills，软件工程经验的技能结晶

公众号名称：AgentBuff

作者名称：AgentBuff

发布时间：2026-05-14 17:44

你有没有遇到过这些场景？

让 AI 写代码，结果它写的和你想要的完全不一样
AI 生成了一堆代码，但你根本不知道它在说什么
代码跑不起来，AI 也帮不上忙
项目越写越乱，最后变成一坨泥巴球（Ball of Mud）

Matt Pocock（TypeScript 大神、Total TypeScript 作者）在日常使用 Claude Code、Codex 等 AI 编程工具时，总结了这四大典型失败模式，并针对性地构建了一套 Agent Skills（智能体技能）。

这套技能的核心理念是：

软件工程的基本功在 AI 时代比以往任何时候都更重要。

与 GSD、BMAD、Spec-Kit 等试图”接管整个流程”的框架不同，Matt Pocock Skills 的设计哲学是：

小而精：每个技能聚焦一个问题
可组合：技能之间可以灵活搭配
易适配：你可以随意修改、魔改
模型无关：适用于任何 AI 模型

快速安装

#第一步：运行安装器

npx skills@latest add mattpocock/skills

#第二步：选择技能和 Agent

安装器会让你选择想要安装的技能，以及在哪些编码 Agent 上使用。务必选择 /setup-matt-pocock-skills。

#第三步：运行初始化

在你的 Agent 中运行 /setup-matt-pocock-skills，它会依次问你三个问题：

Issue Tracker：你用什么管理任务？（GitHub Issues / GitLab / 本地文件）
Triage Labels：你用什么标签来分类 Issue（议题/任务）？推荐默认
就是贴在 Issue 上的分类标记，用来标识任务当前处于什么状态。默认推荐定义了 5 个标准标签，对应 /triage 状态机的 5 个状态
needs-triage → 待分诊（刚提交，还没人看）
needs-info → 待补充（信息不够，需要提问者补充）
ready-for-agent → Agent 就绪（描述清楚，AI 可以独立干）
ready-for-human → 人类就绪（需要人类来做）
wontfix → 不修复
Domain Docs：项目文档放在哪里？
大多数项目，一个 CONTEXT.md 就够了（默认推荐）
Monorepo 里多个子系统各有自己的术语表，通过 CONTEXT-MAP.md 关联

完成这三步，所有工程技能就能正常工作了。会自动在项目目录中做一些变更和新增操作，一是在项目的AGENTS.md中新增一些内容，告诉Agent Issue（议题/任务）跟踪什么目录，问题分类跟踪什么目录，以及领域语言术语文档跟踪什么目录：

到这里会发现有一丢丢DDD软件建模方法论的影子，接下来我们看下都有哪些技能。

技能全景：三大分类，18 个技能

整个技能库分为三类：

分类	定位	技能数量
Engineering（工程）	日常代码工作	10 个
Productivity（效率）	非代码工作流	4 个
Misc（杂项）	备用工具	4 个

工程技能详解（Engineering）

#`/grill-with-docs` —— 烤问式对齐 + 文档自动生成

解决的问题：AI 不知道你到底想要什么。

这是 Matt 最受欢迎的技能。它会对你进行”无情的拷问”，逐个追问你的计划，直到你们达成完全的共识。

独特之处：

会自动检查你的代码，发现你说的和代码实际做的不一致时立刻指出
会用具体场景来测试你的设计，暴露边界情况
自动更新 CONTEXT.md：当某个术语被确定下来，立刻写入项目术语表
自动创建 ADR：当做出难以逆转的决策时，记录架构决策记录

使用场景：每次开始新功能开发之前，都应该先跑一遍。

#`/grill-me` —— 纯烤问模式

解决的问题：同上，但不涉及代码。

/grill-with-docs 的轻量版，适用于非代码场景——比如你在做产品设计、技术方案评审时，让 AI 对你进行追问。

使用场景：写文档、做方案、讨论架构时使用。

#`/tdd` —— 测试驱动开发

解决的问题：AI 写的代码跑不起来。

传统的 TDD 流程：红（写失败测试）→ 绿（写最少代码通过）→ 重构。

核心原则：

测试行为，不测实现——测试应该描述”系统做什么”，而不是”怎么做”
垂直切片：一次写一个测试 → 一次写一个实现。绝对不要”先写所有测试，再写所有代码”
测试应该能经受住重构的考验

反模式警告：

错误（水平切片）：
  红：test1, test2, test3, test4, test5
  绿：impl1, impl2, impl3, impl4, impl5

正确（垂直切片）：
  红→绿：test1→impl1
  红→绿：test2→impl2
  红→绿：test3→impl3

使用场景：构建新功能或修复 Bug 时使用。

#`/diagnose` —— 纪律化调试

解决的问题：遇到难缠的 Bug，AI 瞎猜。

这是一个六阶段的调试纪律：

构建反馈循环（最关键！）—— 没有快速、确定性的复现信号，一切白搭
复现 —— 确认 Bug 确实存在
假设 —— 生成 3-5 个可证伪的假设
插桩 —— 每个探针对应一个假设，一次只改一个变量
修复 + 回归测试 —— 先写回归测试，再修复
清理 + 复盘 —— 清理所有调试代码，记录根因

构建反馈循环的 10 种方法（按优先级）：

在合适层面写失败测试
Curl/HTTP 脚本
CLI 调用 + 快照对比
无头浏览器脚本（Playwright/Puppeteer）
回放捕获的 Trace
最小化 Harness
属性/模糊测试
二分 Harness
差分测试
HITL Bash 脚本（最后手段）

使用场景：遇到 Bug 或性能回退时说”diagnose this”。

#`/improve-codebase-architecture` —— 架构改善

解决的问题：项目越写越乱。

这个技能会扫描你的代码库，找出”浅模块”——那些接口和实现一样复杂的模块，然后提出”深化机会”。

核心概念：

深度（Depth）：接口简单但功能强大的模块 = 深模块
浅度（Shallowness）：接口和实现一样复杂 = 浅模块
删除测试：想象删除这个模块，如果复杂度消失了，说明它是透传层；如果复杂度出现在 N 个调用方，说明它有价值

流程：

扫描代码库，找到摩擦点
呈现候选列表
进入烤问循环，深入讨论
同步更新 CONTEXT.md 和 ADR

使用场景：每隔几天跑一次，防止代码库腐化。

#`/to-prd` —— 生成产品需求文档

解决的问题：从对话到 PRD 的鸿沟。

直接从当前对话上下文中提取信息，生成一份完整的 PRD，包括：

问题陈述
解决方案
用户故事列表
实现决策
测试决策
范围外说明

使用场景：讨论完需求后，直接说”生成 PRD”。

#`/to-issues` —— 拆分为可执行 Issue

解决的问题：PRD 太大，不知道从哪里开始。

将计划/PRD 拆分为独立的”垂直切片”（Tracer Bullet），每个 Issue 都是一个端到端的完整路径。

两种类型：

HITL（Human In The Loop）：需要人类参与——比如架构决策、设计评审
AFK（Away From Keyboard）：AI 可以独立完成——不需要人类交互

核心原则：宁可多拆几个薄切片，也不要少拆几个厚切片。

使用场景：有了 PRD 后，拆分为 GitHub Issues。

#`/triage` —— Issue 分诊

解决的问题：Issue 太多，不知道先处理哪个。

通过状态机管理 Issue 的生命周期：

needs-triage → needs-info → ready-for-agent → ready-for-human → wontfix

五个状态角色：

角色	含义
`needs-triage`	需要维护者评估
`needs-info`	等待报告者补充信息
`ready-for-agent`	完全明确，AI 可独立完成
`ready-for-human`	需要人类实现
`wontfix`	不会修复

使用场景：日常管理 GitHub Issues。

#`/zoom-out` —— 拉远视角

解决的问题：看不懂某段代码在干嘛。

让 Agent 暂停当前视角，拉到更高层级，用项目的领域术语给你一个模块地图。

使用场景：遇到不熟悉的代码区域时。

#`/prototype` —— 快速原型

解决的问题：不确定设计方案是否可行。

两种模式：

逻辑原型：构建一个可交互的终端应用，用来测试状态机/业务逻辑
UI 原型：在同一路由下生成多个截然不同的 UI 变体，通过 URL 参数切换

核心原则：原型是”回答问题的可丢弃代码”，用完即删。

使用场景：设计阶段验证想法。

#`/setup-matt-pocock-skills` —— 初始化配置

解决的问题：其他技能需要知道你的项目配置。

一次性运行，为每个项目设置：

Issue Tracker 类型
Triage 标签映射
领域文档布局

使用场景：每个新项目第一次使用前。

效率技能详解（Productivity）

#`/caveman` —— 穴居人模式

解决的问题：AI 废话太多，浪费 Token。

开启后，AI 的回复会极度精简，砍掉所有废话（冠词、填充词、客套话），只保留技术实质。

效果对比：

普通模式：
"Sure! I'd be happy to help you with that. The issue you're
experiencing is likely caused by..."

穴居人模式：
"Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"

Token 节省：约 75%。

使用场景：想要快速、精准的回复时说”caveman mode”。

#`/handoff` —— 工作交接

解决的问题：对话太长，想开新会话但不想丢失上下文。

将当前对话压缩为一份交接文档，让新 Agent 可以无缝继续工作。

使用场景：对话即将到达上下文限制时。

#3. `/write-a-skill` —— 创建新技能

解决的问题：想创建自己的技能。

引导你完成技能创建流程：

收集需求
起草 SKILL.md
审查迭代

使用场景：想扩展技能库时。

杂项技能详解（Misc）

#`/git-guardrails-claude-code` —— Git 安全护栏

设置 Claude Code Hooks，拦截危险的 Git 命令：

git push（所有变体）
git reset --hard
git clean -f
git branch -D
git checkout .

使用场景：防止 AI 意外执行破坏性 Git 操作。

#`/setup-pre-commit` —— 预提交钩子

一键设置 Husky + lint-staged + Prettier + 类型检查 + 测试。

使用场景：新项目初始化时。

#`/migrate-to-shoehorn` —— 迁移类型断言

将测试代码中的 as 类型断言迁移到 @total-typescript/shoehorn 的类型安全方案。

使用场景：TypeScript 项目测试代码优化。

#`/scaffold-exercises` —— 练习脚手架

创建课程练习目录结构，包含问题、解答和讲解。

使用场景：技术培训课程开发。

核心工作流：从想法到上线

一套完整的工程工作流是这样的：

┌─────────────────────────────────────────────────────────┐
│                    想法 / 需求                            │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│  /grill-with-docs  或  /grill-me                        │
│  烤问式对齐，确保你和 AI 完全理解彼此                       │
│  同时自动生成 CONTEXT.md 和 ADR                          │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│  /prototype（可选）                                      │
│  用快速原型验证设计可行性                                  │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│  /to-prd                                               │
│  将对话上下文转化为正式的 PRD                              │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│  /to-issues                                            │
│  将 PRD 拆分为独立的垂直切片 Issue                        │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│  /triage                                               │
│  管理 Issue 生命周期，决定哪些可以交给 AI                   │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│  /tdd                                                  │
│  红→绿→重构，逐个垂直切片实现                             │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│  /diagnose（遇到 Bug 时）                                │
│  纪律化调试：复现→最小化→假设→插桩→修复→回归测试           │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│  /improve-codebase-architecture（定期运行）               │
│  找出浅模块，提出深化机会，防止代码库腐化                   │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│  /handoff（对话过长时）                                   │
│  压缩上下文，交接给新 Agent 继续                           │
└─────────────────────────────────────────────────────────┘

场景示例

#场景一：开发一个新功能

你：我要给课程管理系统添加"批量导出学生作业"功能

AI（/grill-with-docs）：
→ 你说的"作业"是指 StudentSubmission 还是 Assignment？
→ 导出格式是 PDF 还是 ZIP？
→ 需要包含评分信息吗？
→ 大批量导出时要不要异步处理？
→ ...（持续追问直到所有细节明确）

你：（逐一回答）

AI：已更新 CONTEXT.md，PRD 已生成。要拆分为 Issues 吗？

你：拆吧

AI：已创建 5 个 Issues：
  #1 [AFK] 数据库查询优化（被 #2 阻塞）
  #2 [AFK] 导出服务核心逻辑
  #3 [AFK] API 端点
  #4 [AFK] 前端 UI
  #5 [HITL] 异步任务队列设计（需要你确认方案）

#场景二：调试一个诡异 Bug

你：用户反馈有时候登录后会显示别人的头像

AI（/diagnose）：
→ Phase 1：我需要构建反馈循环。让我先写一个测试来复现这个问题。
→ Phase 2：已复现！问题出在并发登录时 Session 缓存未清理。
→ Phase 3：三个假设：
  1. Session 缓存污染（最可能）
  2. CDN 缓存问题
  3. 数据库查询错误
→ Phase 4：添加 DEBUG 日志验证假设 #1
→ Phase 5：确认是假设 #1，修复 + 回归测试
→ Phase 6：清理调试代码，记录根因

#场景三：代码库体检

你：帮我看看项目架构有没有问题

AI（/improve-codebase-architecture）：
→ 扫描完成，发现 3 个深化机会：

1. OrderService 是浅模块
   - 问题：接口有 15 个方法，但每个方法都是简单透传
   - 方案：合并为 3 个深度模块
   - 收益：测试覆盖率可从 40% 提升到 85%

2. PaymentGateway 缺少 Seam
   - 问题：直接依赖 Stripe SDK，无法测试
   - 方案：引入 PaymentProvider 接口
   - 收益：可 Mock 测试，支持多支付网关

3. UserContext 跨模块泄漏
   - 问题：7 个模块直接访问 UserContext
   - 方案：通过中间件注入
   - 收益：模块间解耦

要深入讨论哪个？

软件工程经验的技能结晶

把经典书籍中的软件工程经验总结成技能，站在巨人的肩膀上思考问题。

#对齐问题 → `/grill-with-docs`

“没有人确切知道自己想要什么。” ——《程序员的修炼》

通过结构化的追问，消除你和 AI 之间的理解偏差。

#废话问题 → `CONTEXT.md` + `/caveman`

“有了统一语言，开发者之间的对话和代码表达都来自同一个领域模型。” —— Eric Evans,《领域驱动设计》

项目术语表让 AI 用最少的词表达最精确的意思。

#质量问题 → `/tdd` + `/diagnose`

“始终采取小而谨慎的步骤。反馈的频率就是你的速度上限。” ——《程序员的修炼》

红绿重构循环 + 纪律化调试，给 AI 持续的反馈信号。

#架构问题 → `/improve-codebase-architecture`

“每天都在投资系统的设计。” —— Kent Beck,《极限编程》

定期体检，防止 AI 加速代码熵增。

横向对比：Matt Pocock Skills vs OpenSpec vs Superpowers

当前 AI Agent 技能领域有三大主流方案，它们解决的问题相似，但哲学和路径截然不同。

#各自定位

框架	一句话定位	作者
Matt Pocock Skills	给工程师的日常工具箱——小而精、可组合、即插即用	Matt Pocock（TypeScript 大神）
OpenSpec	规范驱动开发框架——在代码之前先写规范，用 DAG 管理产物依赖	Fission AI
Superpowers	完整的软件开发方法论——从头脑风暴到代码审查的全自动化流水线	Jesse Vincent（obra）

#核心设计哲学对比

维度	Matt Pocock Skills	OpenSpec	Superpowers
设计理念	工程纪律的模块化封装	规范先行，产物驱动	端到端方法论，自动触发
控制权	用户手动调用每个技能	用户通过 slash 命令驱动	Agent 自动判断何时触发
粒度	单个技能解决单个问题	产物依赖图管理整个流程	技能链自动串联
灵活性	极高——随意挑选、魔改	高——Schema 可自定义	中——流程固定但可配置
学习曲线	低——每个技能独立可用	中——需理解产物图和 Schema	中高——需理解完整方法论
侵入性	低——不改变你的工作流	中——需要维护规范文件	高——接管你的开发流程

#功能矩阵对比

能力	Matt Pocock Skills	OpenSpec	Superpowers
需求对齐	`/grill-with-docs` 烤问式	`/opsx:propose` 规范生成	`brainstorming` 苏格拉底式
设计文档	通过烤问自动生成 CONTEXT.md + ADR	proposal.md + specs/ + design.md	自动保存设计文档到 docs/
任务拆分	`/to-issues` 垂直切片	tasks.md + DAG 依赖	`writing-plans` 2-5 分钟粒度
TDD	`/tdd` 红绿重构	无内建（依赖 AI 工具）	`test-driven-development` 铁律级
调试	`/diagnose` 六阶段纪律	无内建	`systematic-debugging` 四阶段
架构改善	`/improve-codebase-architecture`	无内建	无内建
Issue 管理	`/triage` 状态机	无内建	无内建
代码审查	无内建	`/opsx:verify` 三维度验证	`requesting/receiving-code-review`
并行开发	无内建	支持并行变更	`using-git-worktrees` + `dispatching-parallel-agents`
子代理执行	无内建	无内建	`subagent-driven-development` 双阶段审查
工作交接	`/handoff` 压缩上下文	无内建	无内建
术语管理	`CONTEXT.md` 项目术语表	specs/ 行为契约	无内建
架构决策记录	ADR 自动创建	无内建	设计文档
领域无关工具	`/caveman` Token 压缩	无内建	无内建

#工作流对比

Matt Pocock Skills：手动编排，按需调用

/grill-with-docs → /to-prd → /to-issues → /tdd → /diagnose
     ↑ 手动触发     ↑ 手动触发   ↑ 手动触发   ↑ 手动触发

你决定什么时候用什么技能，像使用瑞士军刀一样。

OpenSpec：产物驱动，状态流转

/opsx:propose → 审查产物 → /opsx:apply → /opsx:verify → /opsx:archive
     ↑ 创建 DAG      ↑ 人工审查     ↑ 按 tasks 实现    ↑ 三维度验证    ↑ Delta 合并

围绕规范文件的生命周期组织工作，产物之间有依赖关系。

Superpowers：全自动流水线，Agent 主导

brainstorming → writing-plans → subagent-driven-development → code-review → finishing
     ↑ 自动触发       ↑ 自动触发          ↑ 自动派发子代理          ↑ 自动审查     ↑ 自动收尾

Agent 自动判断何时触发哪个技能，你只需要审批关键节点。

#适用场景

场景	最佳选择	原因
日常写代码，想要更好的 AI 辅助	Matt Pocock Skills	低侵入，按需调用，不改变工作流
存量项目，需要规范化 AI 开发流程	OpenSpec	Brownfield-first 设计，Delta 规范适配已有代码
新项目，想要 AI 全自动开发	Superpowers	端到端方法论，子代理并行执行
团队协作，需要统一规范	OpenSpec	规范文件可版本控制，团队共享
个人项目，追求效率极致	Matt Pocock Skills	最轻量，75% Token 节省（caveman）
复杂系统，需要长时间自主运行	Superpowers	子代理可自主运行数小时
需要调试难缠 Bug	Matt Pocock Skills	`/diagnose` 六阶段纪律最完善
需要管理 Issue 生命周期	Matt Pocock Skills	`/triage` 状态机是独有的
需要架构持续改善	Matt Pocock Skills	`/improve-codebase-architecture` 是独有的

#能否共存？

还没完整实践，但是理论上完全可以。 三者解决的是不同层面的问题：

OpenSpec 管”做什么”——规范层
Superpowers 管”怎么做”——执行层
Matt Pocock Skills 管”做得好”——质量层

你可以在 OpenSpec 管理规范的同时，用 Matt Pocock Skills 的 /diagnose 调试 Bug，用 Superpowers 的子代理并行执行任务。它们不是互斥的，而是互补的。

最后

Matt Pocock Skills 不是一个”让 AI 帮你写代码”的魔法工具。

它是一套工程纪律的数字化封装——把几十年的软件工程最佳实践，转化成了 AI 可以执行的标准化流程。

核心价值：

让 AI 不再”碰运气”，而是按工程纪律行事
让你和 AI 之间建立真正的”共同语言”
让代码质量不因 AI 的加速而下降
让调试从”瞎猜”变成”科学实验”

适合谁：

每天用 Claude Code / Codex 写代码的开发者
受够了 Vibe Coding 想要工程化的人
想要提升 AI 编程效率和质量的团队

软件工程的基本功，在 AI 时代比以往任何时候都更重要。这些技能，是你和 AI 之间最好的翻译器。

VibeCoding工程化=合理的目录规划+软件方法论提示词设计+渐进式披露的技能

相信你已经了解过很多VibeCoding工程化工具，希望你能参透这些工具之后的本质。OpenSpec，Superpowers，Gstack这些都是工具但又不仅是工具，但最重要的是软件工程的本质。使用、探究找寻最适合你自己的使用之道吧。

如果你看到这里，那这篇文章对你还是有点帮助的，希望得到你的关注，获取更多有见解的内容，你的点赞，收藏，转发是我坚持的动力。

末尾：最近我拉了个纯技术交流群，欢迎各路大牛坐镇，群目前还处于起步阶段。

欢迎探讨云原生，云计算，agent开发，看过我之前文章的都知道最近一直在做英文技术网站的翻译（AI），目前已经发布了langchain4j，claude sdk 官方课，claude-mem插件，cubesandbox等，注意啊，纯技术交流群，推文引流营销目的谢绝，非诚勿扰

先加我微信好友：coderbuffer

Original AgentBuff AgentBuff

内容效果不满意？点此反馈

快速安装

#​第一步：运行安装器

#​第二步：选择技能和 Agent

#​第三步：运行初始化

技能全景：三大分类，18 个技能

工程技能详解（Engineering）

#​/grill-with-docs —— 烤问式对齐 + 文档自动生成

#​/grill-me —— 纯烤问模式

#​/tdd —— 测试驱动开发

#​/diagnose —— 纪律化调试

#​/improve-codebase-architecture —— 架构改善

#​/to-prd —— 生成产品需求文档

#​/to-issues —— 拆分为可执行 Issue

#​/triage —— Issue 分诊

#​/zoom-out —— 拉远视角

#​/prototype —— 快速原型

#​/setup-matt-pocock-skills —— 初始化配置

效率技能详解（Productivity）

#​/caveman —— 穴居人模式

#​/handoff —— 工作交接

#​3. ​/write-a-skill —— 创建新技能