一、我们正站在一条危险的曲线上

2025 年，AI 编码助手已经深度嵌入无数开发者的日常工作流。它能 30 秒生成一个 CRUD 模块，一分钟搭完一个登录系统。但在真实的生产级项目中，一种现象正在蔓延。

Matt Pocock 把这种现象称为 “vibe coding”（氛围编码）——你凭感觉对 AI 说"我要一个用户管理系统"，AI 凭感觉给你一堆代码，你们双方都在一种模糊的共识幻觉中前进，直到某天一个边缘 bug 摧毁整个构建。

比单次失败更可怕的是趋势：AI 在三天内能把一个代码库搞乱，而人类团队需要三个月。 所有试图用 GSD、BMAD、Spec-Kit 这类流程框架来"拥有过程"的尝试，恰恰走向了反面——它们拿走了你的控制权，让流程中的缺陷极难解决。

Matt Pocock 的 skills 项目是我见过的对这一困境最冷静的回答。它不是一个工具，不是一套 prompt 模板合集，而是一份将软件工程基本原则映射到 AI 协作场景的系统性提案。

这个项目开源三周即获 23k Star，登顶 GitHub Trending #1，最终积累 55.6k Stars、4.7k Forks。但它最重要的价值藏在更深的层面——它不是另一个"AI 技巧合集"，它问的问题更根本：当编码速度不再是瓶颈，什么东西在阻止我们写出能活过三个 Sprint 的软件？

本文不会教你"五个让 AI 更听话的提示词"。我们会回到软件工程的根基，分析四种经典失败模式如何被系统性化解。

二、一个被长期忽视的事实：真正稀缺的从来不是代码

Matt Pocock 的身份本身就说明问题。他并非 AI 研究员或 prompt 工程师，而是 TypeScript 领域最具影响力的教育者之一——Total TypeScript 作者、前 Vercel 和 Stately 工程师，被社区称为"TypeScript wizard"。

一个 TypeScript 专家，把他自己日常配合 Claude Code 工作的 .claude 目录公开——他把自己反复验证过的工程判断流程拆解出来，变成了 21 个可安装的 Agent 技能。

这很关键：不是一位 AI 专家来教你怎么写 prompt，而是一位顶级工程师告诉你，他用什么方法让 AI 配合他写出能活过多个迭代的代码。

三、四个失败模式：对"AI 工程学"缺位的诊断

Pocock 在 README 中归纳了使用 AI 编码助手时四个高频失败模式。表面上它们各不相同，但底层都指向同一个核心问题：我们缺乏一套适用于 AI 协作场景的工程纪律。

四个模式不是孤立的抱怨，它们构成了一条因果链。

模式一：Agent 没做你想要的事

问题本质：这是使用 AI 编码最普遍的挫败感。你说"做个文件上传组件"，它做了——但没做拖拽排序、没做断点续传、没做格式校验。你说"没做全"，它诚恳道歉，然后改出一个新的不完整版本。

Pocock 引用了《程序员修炼之道》中 David Thomas 和 Andrew Hunt 的经典论断："没有人真正知道自己想要什么。"这句话在 AI 时代比以往任何时候都更致命：过去你面对的是一个能主动追问的人类开发者，现在你面对的是一个从不敢说"我不明白"的模型。

解决方案：强制开启结构化的追问环节（grilling session）——让 Agent 在写任何代码前，先变成一位挑剔的架构师，从功能范围、边界条件、错误处理、性能要求、技术栈约束、测试策略等维度连续追问，直到所有模糊地带被扫清。

对应技能：

技能	分类	定位
/grill-me	Productivity	通用需求深访，非代码场景
/grill-with-docs	Engineering	工程级深访，附带领域语言建模和 ADR

这两个是 Pocock 最常用的技能，他建议每次做任何改动前都先使用它们。

模式二：Agent 的表达过于啰嗦

问题本质：很多人以为这只是在说 token 浪费。Pocock 的问题在于认知负载。他引用 Eric Evans 在《领域驱动设计》中的概念：当开发者和领域专家说不同的语言时，沟通成本是线性的，但理解偏差是指数的。

他举了一个极有说服力的例子。在自己的 course-video-manager 项目中：

• 没有共享语言时：“课程中某个 section 下的 lesson 被赋予文件系统中的实际位置时出现问题”
• 有共享语言后：“物化级联（materialization cascade）出了问题”

当你每次都要用 20 个词去描述同一个概念时，你不仅仅在浪费 token——你在每一次交互中都要求 AI 重新进行领域建模。

解决方案：建立共享语言。通过 CONTEXT.md 文件构建领域术语表，让 Agent 从一开始就用高度压缩的语义编码理解你的项目。

Pocock 认为共享语言"可能是整个仓库中最酷的技术"——它带来的好处远超减少啰嗦本身：变量、函数和文件的命名会自动收敛到一致风格；代码库对 Agent 来说变得更可导航；更重要的是，Agent 花费更少的 token 在"思考"上，因为它拥有了一套更精炼的语言系统。

这个机制内建于 /grill-with-docs——它不是两个独立功能的拼接，而是一个统一流程：在需求深访的过程中，同步提炼领域术语并写入 CONTEXT.md，同时将难以从领域模型直接推导的技术决策记录为架构决策记录（ADR）。

模式三：代码跑不起来

问题本质：你和 Agent 在需求上完全对齐了，Agent 也使用了共享语言，信心满满地输出 200 行代码——运行时直接崩在第三行。

Pocock 的诊断直击要害：反馈回路断了。人类程序员写代码时有持续的多层反馈：IDE 的静态检查、浏览器 DevTools、单元测试、甚至"这行写完感觉不对劲"的直觉。Agent 没有这些——它看到的只有 prompt 和自己生成的文本。

他再次引用《程序员修炼之道》：“始终采取小而谨慎的步骤。反馈的频率就是你的速度上限。永远不要承担过大的任务。”

解决方案：显式重建多层反馈回路——静态类型 + 浏览器访问 + 自动化测试。在自动化测试层面，红-绿-重构循环是关键的纪律：Agent 必须先写一个会失败的测试，然后写最小的实现让它通过，再在有测试保护的前提下重构。

对应技能：

技能	分类	核心功能
/tdd	Engineering	红-绿-重构循环，按垂直切片推进，附 6 个参考文档
/diagnose	Engineering	结构化调试诊断循环：复现 → 最小化 → 假设 → 插桩 → 修复 → 回归测试

/tdd 的实现值得多说：它不是简单地说"请用 TDD"，而是内建了具体的工程判断——测试应该验证公共接口而非实现细节；禁止水平切片（一次性写完所有测试再写实现），必须垂直切片（一个测试 → 一个最小实现 → 循环）。

模式四：我们造了一团泥球

问题本质：这是前三个模式的总和与终局。Agent 没理解需求 → 反复修补 → 代码冗余堆积。Agent 没有共享语言 → 命名混乱 → 模块边界模糊。Agent 没有反馈回路 → bug 被埋在深处 → 越改越乱。

Pocock 引用了 Kent Beck 和 John Ousterhout 的两个核心观点来定义这个问题的两个维度：“每天都要投资于系统的设计”；“最好的模块是深的——它们允许通过简单的接口访问大量功能”。

他对 AI 时代的泥球有一个关键洞见：Agent 加速编码的同时也在加速软件熵增——代码库以史无前例的速度变得复杂。

解决方案：一个"激进的新方法"——真正关心代码的设计。这不是空洞的口号，而是一套嵌入技能体系每一层的防御机制：

• 进入时：/to-prd 在创建产品需求文档前，先质询你将要触及哪些模块
• 过程中：/zoom-out 强制 Agent 在理解某段代码时将其放在整个系统的上下文中阐释
• 恶化后：/improve-codebase-architecture 利用 CONTEXT.md 中的领域语言和 docs/adr/ 中的架构决策，从泥球中发现"深模块"机会并逐步重建架构边界。Pocock 建议每隔几天就运行一次

这三个维度——事前预防、事中感知、事后修复——构成了完整的架构健康防线。定期运行 /improve-codebase-architecture 的建议不是随意的经验之谈，背后是对"AI 让代码腐化不可逆"这一事实的诚实面对。

小结

四个失败模式逐级递进：从需求层面的错位，到沟通层面的冗余，到质量层面的缺失，最终到架构层面的腐化。每一个模式的解决方案对应一类技能，技能之间又通过共享的数据（CONTEXT.md、docs/adr/）相互关联。这不是巧合——这是一位有数十年工程经验的开发者，把问题树和解决方案树逐层对齐的结果。

四、技能体系全景

以下是 skills 项目的完整技能清单，严格按照官方 README 的分类和描述整理。

Engineering（工程类——日常编码）

技能	核心功能
/diagnose	结构化调试循环：复现 → 最小化 → 假设 → 插桩 → 修复 → 回归测试
/grill-with-docs	需求深访 + 建立 CONTEXT.md + 生成架构决策记录（ADR）
/improve-codebase-architecture	从泥球代码中发现"深模块"机会，依据 CONTEXT.md 和 ADR
/setup-matt-pocock-skills	一次性脚手架配置（issue tracker、标签词汇、文档位置），首次使用前必须先运行
/tdd	红-绿-重构循环的 TDD，按垂直切片推进
/to-issues	将计划/规格/PRD 拆分为可独立领取的 GitHub issue（垂直切片原则）
/to-prd	将当前会话上下文合成为 PRD 并提交为 GitHub issue
/triage	将 issue 按分类角色状态机进行分诊处理
/zoom-out	让 Agent 在系统整体视角下解释不熟悉的代码段落

Productivity（生产力类——通用工作流）

技能	核心功能
/caveman	超压缩沟通模式，削减约 75% token 同时保持技术准确性
/grill-me	对计划或设计进行穷尽式追问，直到决策树每个分支都被解决
/write-a-skill	创建结构规范的新技能，含渐进式披露和资源打包

Misc（杂项类——偶尔使用）

技能	核心功能
/git-guardrails-claude-code	设置 Claude Code hooks 拦截危险 git 操作（push、reset --hard、clean 等）
/migrate-to-shoehorn	将测试文件中的 as 类型断言迁移至 @total-typescript/shoehorn
/scaffold-exercises	创建含 sections、problems、solutions、explainers 的练习目录结构
/setup-pre-commit	配置 Husky pre-commit hooks（lint-staged、Prettier、类型检查、测试）

以上信息均来源于官方 README 的 Reference 章节。

技能间的协作关系

这些技能不是孤立的独立工具，而是通过共享数据形成协作链。一个典型的完整工作流如下：

/setup-matt-pocock-skills（首次初始化，配置项目级参数）
           ↓
/grill-with-docs（深访需求，建立共享语言，产出 CONTEXT.md + ADR）
           ↓
/to-prd（将澄清后的需求合成为正式 PRD）
           ↓
/to-issues（按垂直切片拆分为多个独立 GitHub issue）
           ↓
/tdd（逐个 issue 以红-绿-重构方式实现）
           ↓
/diagnose（遇到难啃的 bug 时切换到诊断模式）
           ↓
/improve-codebase-architecture（每几天运行一次，防止架构腐化）

每一步都有明确的输入、输出和质量门禁。这不是理论推演——/setup-matt-pocock-skills 作为链的起点，会在初始化时配置好 issue tracker（GitHub / Linear / 本地文件）、issue 标签词汇和文档产出位置，后续所有 Engineering 类技能（/to-issues、/to-prd、/triage、/diagnose、/tdd、/improve-codebase-architecture、/zoom-out）都依赖这些配置运行。Pocock 设计这个链的意图很明确：从模糊想法到可维护代码的全流程，每一步都有工程纪律在守护。

五、落地指南

最简部署（官方 Quickstart）

Pocock 提供了标准化的安装方式，30 秒即可完成：

npx skills@latest add mattpocock/skills

然后选择你想安装的技能和目标编码 Agent。务必勾选 /setup-matt-pocock-skills，这个脚手架技能会引导你完成一次性的项目级初始化——配置 issue tracker（GitHub / Linear / 本地文件）、issue 标签词汇、以及文档产出目录。配置完成后，直接在 Agent 中输入技能名即可调用。

团队适配

技能文件是 Markdown 格式，天然具备可定制性。你可以、也应该基于团队实际情况进行二次定制：

• 领域词库注入：将团队已有的术语表写入 /grill-me 或 /grill-with-docs 中，让 Agent 从一开始就用你们的语言说话
• 技术栈约束补充：在技能文件中添加如"默认使用 PostgreSQL + Prisma"等团队约定
• 自定义技能扩展：基于 /write-a-skill 创建符合团队规范的专有技能，如安全审查、可访问性检查等

但警惕一个常见陷阱：不要过早定制。先用原版技能跑通两三个完整特性，感受流程节奏，再根据实际摩擦点做调整。原版技能本身就反映了 Pocock 数十年的工程经验沉淀，过早修改很可能是在"优化"一个你还没真正理解的东西。

适用场景

强烈推荐使用完整技能流：

• 团队协作的中大型项目，需要统一工程标准
• 涉及多模块交互、复杂业务逻辑的特性开发
• 技术债务严重、需要系统性重构的老项目

可选择性地使用关键技能：

• 个人项目或快速原型——跳过 /to-prd 和 /to-issues，但保留 /grill-me 的需求深访环节
• 探索性编程——不需要完整 TDD，但 /diagnose 在 debug 时仍然有独立价值

不太适用：

• 一句话就能说清的单文件代码片段生成
• 一次性数据转换脚本等"写完就扔"的代码

选择标准的底层逻辑很简单：这段代码需要活多久，就投入多少工程纪律。

六、局限与诚实评估

它不解决的

模型能力上限。 技能是对 Agent 行为的"约束层"和"流程层"，但不提升底层模型的推理上限。如果模型本身无法完成某项任务，技能无法补全这个缺口——它只能确保模型在它能做的事情上不跑偏。

领域知识的冷启动。 如果你的项目涉及高度专业的领域（医疗合规、金融风控、特定工业协议），CONTEXT.md 中的术语表需要你手动填充冷启动知识。技能不替代你的领域专长，只是让专长被更高效地使用。

它需要的付出

前期学习成本。 从"直接对话"切换到"技能驱动流程"需要适应期。第一次完整跑通一条链可能需要两小时，而直接让 AI 写代码只需五分钟。核心问题是：这 115 分钟的额外投入，能否避免后期 10 小时的返工？ 对于任何生命周期超过一个 Sprint 的项目，答案是显然的。

定制技能需要维护。 自定义技能须随项目演进持续更新。你的安全审查技能可能因新的合规要求需要修改，你的术语表可能因架构重构需要刷新。这不是一次性投入。

一个值得注意的问题

技能体系擅长将已知的工程实践固化为流程——但过度标准化可能带来创造力隐性的代价。AI 真正的潜力或许在于你没想到的那个怪异的解法。过早在流程上投入过重，是否会过滤掉一些"看起来不对但实际天才"的输出？这个代价目前无法量化，但值得标记。

同样值得警惕的是"流程安全感"的幻觉风险。你跑了 /grill-me、写了 ADR、用了 /tdd——这些规范性能给你强烈的安全感，让你误以为质量已被流程自动保证。但流程掩盖不了细节层面的疏忽：一个通过的测试可能测错了东西，一份精致的 ADR 可能记录了错误的前提。技能降低出错的概率，但不消灭错误本身。

诚实结论

这不是一套魔法，是一套工程纪律。它不会让 AI 变聪明，但会让 AI 在你事先圈定的框架内变得可靠。如果你的项目规模已经大到无法承受"氛围编码"的后果，skills 是你目前能找到的最系统、最务实的解法之一。如果你的项目是一个周末 hackathon，它有可能是过度杀伤。

知道什么时候该用，什么时候不用，本身就是一种工程判断。

七、从"咒语工程"到"AI 工程学"

2023 年，“提示词工程"这个词还很新鲜，大家热衷于分享各种"魔法咒语”。到了 2026 年，我们应该诚实地承认：大部分"咒语"都是对模型偶然行为的事后合理化，缺乏可重复性和系统性。

Matt Pocock 的 skills 项目指向了一条不同的路。它不再追问"什么 prompt 能让 AI 变好"，而是问"什么样的工作系统能让 AI 持续产出可预期的结果"。它的灵感来源不是 AI 研究论文，是《程序员修炼之道》、是《领域驱动设计》、是《软件设计的哲学》、是极限编程。当代码的生成成本趋近于零，代码的理解成本、维护成本和腐化速度反而在飙升——这个悖论定义了 AI 时代的真正挑战。

skills 的意义不在单个技能文本里，而在它提出的新范式：将软件工程基本原则映射为 AI Agent 可执行的操作规程。它不会消失，因为软件工程的基本原则不会消失。它一直在底层运转，等你需要的时候，你自会理解它。

转载自CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/Chen__2024/article/details/160741612