别再让 AI 写烂代码了：一套经过实战验证的 Agent 技能体系深度解析

真正的问题不是 AI 不够聪明，而是你给它的指令不够清晰。

---

前言：AI 编程助手的"生产率悖论"

过去两年，Claude Code、Codex、Cursor 等 AI 编程工具让写代码的速度提升了 5 到 10 倍。但一个令人不安的现实是——代码写得越快，烂得也越快。

你很可能已经经历过这种场景：

• Agent 洋洋洒洒写了 500 行代码，但没有一行是你真正想要的
• 一个简单的 CRUD 功能，Agent 用了 15 个文件、3 层抽象
• 修复一个 bug 引入了三个新 bug，而你完全不知道改了什么
• 三个月后回头看项目，发现它已经变成了一团没人敢碰的泥球

这些不是 AI 的"幻觉"问题，而是工程纪律的问题。本文将以 Skills For Real Engineers 这套开源技能体系为线索，深入剖析 AI 辅助编程中的四大核心挑战及其系统化解决方案。

---

一、AI 编程的四大失败模式

Matt Pocock 将 AI 辅助编程中最常见的翻车场景归纳为四类。这四个问题层层递进，恰好对应了软件工程的经典困境在 AI 时代的放大版。

模式一：对齐偏差——“这不是我想要的”

你心里的画面          Agent 理解的画面
┌─────────┐           ┌─────────┐
│  🏰     │           │  🏠     │
│ 城堡    │    ≠      │ 小木屋   │
└─────────┘           └─────────┘

《程序员修炼之道》中说："没有人确切地知道自己想要什么。"这句话在 AI 时代变得更加致命——人类开发者之间尚且需要反复沟通，人机之间的信息损耗只会更大。

核心矛盾：你脑子里的设计是一棵完整的树，但你说出口（或写进 prompt）的只是几片叶子。Agent 会用自己的"经验"填充剩余部分，而这些填充很可能与你的意图南辕北辙。

解决思路：在动手之前，让 Agent 反过来拷问你。这就是「Grilling Session」——Agent 会像一位严谨的架构师一样，针对你的需求提出一连串结构化的追问，直到把设计树上的每一个分支都确认清楚。

模式二：语言混乱——“为什么它总说不到点子上”

“With a ubiquitous language, conversations among developers and expressions of the code are all derived from the same domain model.”
—— Eric Evans，《领域驱动设计》

这是四个问题中最隐蔽、也最具破坏性的一个。

现象：Agent 被丢进一个项目，没有任何业务背景，只能靠代码中的变量名和注释来猜测术语的含义。于是它开始绕圈子——用 20 个词解释一个概念，而不是用 1 个精准的术语。

举个例子，假设你在做一个视频课程管理系统：

• 没有共享语言时：Agent 说 “there’s a problem when a lesson inside a section of a course is made real, meaning it’s given a spot in the file system”（啰嗦且模糊）
• 有共享语言时：Agent 说 “there’s a problem with the materialization cascade”（精准且可检索）

更深层的影响：

• 变量、函数、文件的命名缺乏一致性
• 代码库对 Agent 来说难以导航
• Agent 在"思考"上消耗更多 token，产出质量下降

解决思路：在项目中维护一个 CONTEXT.md 文件，作为 Agent 的"领域词典"。这不是文档，这是基础设施。

模式三：反馈缺失——“代码跑了才知道有问题”

“The rate of feedback is your speed limit.”
—— David Thomas & Andrew Hunt，《程序员修炼之道》

这里的讽刺在于：AI 写代码的速度越快，缺乏反馈带来的伤害就越大。

Agent 在没有运行时反馈的情况下工作，就像蒙着眼睛开车——每一步都是猜测。它不知道自己的代码能不能编译、测试能不能通过、边界条件是否覆盖。

解决思路：回归软件工程的基本功——快速反馈循环。

反馈层级	工具/方法	反馈速度
类型检查	TypeScript / mypy	秒级
单元测试	Vitest / Jest / Pytest	毫秒~秒级
浏览器预览	Playwright / Chrome DevTools	秒级
TDD 循环	红 → 绿 → 重构	分钟级

其中 TDD（测试驱动开发）的红-绿-重构循环 是给 Agent 提供稳定反馈的最有效手段。先写一个失败的测试，让 Agent 看到"红色"，再让它去修——这比任何 prompt 工程技巧都管用。

模式四：架构熵增——“这代码已经没人敢改了”

“Invest in the design of the system every day.”
—— Kent Beck，《解析极限编程》

这是 AI 编程最危险的副作用。Agent 可以以空前的速度生产代码，也就意味着它可以让代码库以空前的速度腐烂。

经典症状：

• 同一个逻辑散落在 7 个文件中
• 一个 2000 行的"上帝类"承担了所有职责
• 模块之间互相引用，牵一发动全身
• 没有测试，修改任何代码都是一场赌博

解决思路：这不是靠一个指令能解决的。它需要渗透到整个开发流程中——从需求分析（Spec）、到模块设计（Deep Modules）、到代码审查（Code Review），形成一条完整的质量防线。

---

二、技能体系全景：不是工具，是工作方法

这套体系包含约 20 个技能，分为两个梯队：

用户调用技能（你主动触发）

这些是"指挥型"技能，你发出指令，Agent 执行一个完整的流程。

技能	一句话说明	使用时机
/grill-me	Agent 反向拷问你，直到需求清晰	开始任何新功能前
/grill-with-docs	同上 + 自动构建领域模型	新项目或复杂需求的起点
/triage	按状态机管理 Issue	日常 Issue 管理
/improve-codebase-architecture	扫描代码库的"加深"机会	每隔几天跑一次
/to-spec	把对话内容转成正式 Spec	讨论清楚后，正式化
/to-tickets	把 Spec 拆成可执行的子任务	Spec 完成后
/implement	按 Spec/Tickets 执行开发	开发阶段
/wayfinder	规划超大工作量的路线图	跨多个 Session 的大型任务

模型可调用技能（Agent 自动或手动触发）

这些是"执行型"技能，封装了经过验证的最佳实践。

技能	一句话说明
prototype	快速构建可丢弃的原型
diagnosing-bugs	结构化的 Bug 诊断循环
research	基于高可信源的调研
tdd	红-绿-重构的 TDD 循环
domain-modeling	主动构建和打磨领域模型
codebase-design	深度模块设计的共享词汇和方法
code-review	双轴代码审查（规范轴 + Spec 轴）
resolving-merge-conflicts	结构化解决合并冲突

---

三、最值得深入理解的三个技能

3.1 /grill-with-docs——对齐与建模的二合一

这是整个体系中最具创新性的技能。它做了两件事：

第一层：Grilling（拷问）

Agent 不会直接开始写代码。它会像一个严格的架构师一样，针对你的需求提出一系列结构化的问题：

• “这个功能的数据流是怎样的？”
• “有哪些边界条件需要考虑？”
• “如果 X 失败了，系统应该如何响应？”
• “这个模块和现有模块的关系是什么？”

这些问题不是随机的，而是沿着设计树逐层深入，直到每个分支都有明确的答案。

第二层：领域建模

在拷问的过程中，Agent 会自动提取和定义领域术语，写入 CONTEXT.md 和 ADR（Architecture Decision Records）：

# CONTEXT.md（示例）

## 领域术语

**Materialization Cascade**：
将逻辑课程结构（章节、课时）映射到物理文件系统的过程。
当一节课被标记为 "real" 时触发，级联创建所有父级目录。

**Seat**：
用户对某一课程内容的访问许可。不是购买关系，
而是授权关系——同一用户可以对同一课程持有多个 Seat。

有了这份共享词汇表，后续所有对话的精准度和效率都会显著提升。

3.2 /tdd——给 Agent 装上反馈回路

TDD 在 AI 时代的价值被严重低估了。很多人觉得"让 AI 写测试太慢了"，但恰恰相反——没有测试的 AI 开发才是真正的慢。

这套 TDD 技能做了几件关键的事：

1. 强制红-绿-重构循环：Agent 必须先看到测试失败（红），再修改代码让测试通过（绿），最后重构（保持绿色）
2. 指导什么是好测试：内置了测试质量的判断标准，避免 Agent 写出一堆无意义的测试
3. 一次一个垂直切片：不追求一次性写完所有代码，而是按功能切片逐步推进

┌──────┐    ┌──────┐    ┌──────────┐
│  RED  │ →  │GREEN │ →  │REFACTOR  │
│ 写失败 │    │ 写代码 │    │ 重构优化  │
│ 的测试 │    │ 让测试 │    │ 保持绿色  │
│       │    │ 通过  │    │          │
└──────┘    └──────┘    └──────────┘
     ↑                                │
     └────────────────────────────────┘
              下一个切片

这个循环的价值在于：每一步都有明确的成功/失败信号，Agent 不再"猜测"自己的代码是否正确。

3.3 /improve-codebase-architecture——给代码做定期体检

这个技能的理念很朴素：每隔几天扫描一次你的代码库，找出可以改进的地方。

它不是自动化重构工具（不碰代码），而是一个诊断工具：

1. 扫描代码库，识别"深度不够"的模块（接口太宽、职责太多、抽象太薄）
2. 生成一份可视化的 HTML 报告，展示候选改进点
3. 让你选择其中一个进行深入分析和重构

这解决了一个核心痛点：在 AI 高速开发的环境下，你很容易失去对代码质量的全局感知。定期体检让你在问题还小时就发现它。

---

四、这些技能为何有效：三个设计原则

仔细研究这套体系后，可以发现背后有三个反复出现的设计原则：

原则一：小而可组合

每个技能只做一件事，但可以被组合使用：

/grill-with-docs → /to-spec → /to-tickets → /implement
   (对齐+建模)     (正式化)    (拆分任务)     (执行开发)
                                           ├── 自动调用 /tdd
                                           └── 自动调用 /code-review

你不需要一次性学习全部技能。从 /grill-me 和 /tdd 开始，其他的按需添加。

原则二：任何模型都能用

这些技能是纯 Markdown 文件，没有绑定任何特定模型或平台。同样的技能可以在 Claude Code、Codex、Cursor 或任何支持 Skill 机制的 Agent 上使用。

原则三：可修改、可定制

技能文件安装后是普通文件——你可以随便改。删掉不需要的步骤、添加团队特有的规范、调整 prompt 风格。这不是一套"最佳实践教条"，而是一套可以被 fork 和修改的基础设施。

---

五、实践建议：从哪里开始

如果你在运营一个使用 AI 编程助手的团队，以下是我的建议路径：

第一周：建立反馈循环

# 1. 安装技能
npx skills@latest add mattpocock/skills

# 2. 配置项目
/ setup-matt-pocock-skills

# 3. 强制使用这两个技能：
#    - 任何新功能开始前，先跑 /grill-with-docs
#    - 任何代码修改，都必须走 /tdd 的循环

这是性价比最高的两个改变。它们分别解决了"做什么"和"怎么做对"的问题。

第二周：引入质量门禁

# 4. 开始使用 /to-spec 和 /to-tickets
#    - 任何超过 30 分钟的任务，先写 Spec 再拆分

# 5. 每次提交前跑 /code-review
#    - 双轴审查：规范是否符合 + Spec 是否完整实现

第三周：建立长期健康机制

# 6. 每周跑一次 /improve-codebase-architecture
#    看看代码库里有没有悄悄长出的"烂代码"

# 7. 维护 CONTEXT.md
#    这是整个体系的核心资产，值得持续投入

---

六、写在最后：AI 时代的工程素养

2025~2026 年，AI 编程工具已经从"能不能用"进化到了"怎么用好"的阶段。工具本身的能力差异在缩小，真正拉开差距的是使用工具的方法。

这套技能体系给出的答案非常明确，也非常"老派"：

• 沟通要先于编码（Grilling）
• 语言要先于逻辑（Domain Modeling）
• 反馈要先于信任（TDD）
• 设计要先于速度（Architecture Review）

这些不是什么新鲜的概念。它们是软件工程几十年来反复验证的真理。AI 没有让它们过时——恰恰相反，AI 让它们变得比任何时候都更加重要。

工具在变，原则不变。写代码的速度可以交给 AI，但写好代码的判断力，永远是你自己的。

---

参考资源

• Skills For Real Engineers - GitHub
• skills.sh - 技能安装工具
• Claude Code Plugin Marketplace
• The Pragmatic Programmer (20th Anniversary Edition)
• Domain-Driven Design - Eric Evans
• A Philosophy of Software Design - John Ousterhout

---

本文基于 Matt Pocock 的 Skills For Real Engineers 项目编写，结合了作者在实际工程中的使用经验。技能会持续更新，建议关注官方 Newsletter获取最新动态。