从"Vibe Coding"到"工程级约束"：Agent Skills 如何重塑 AI 编码的生产力范式

前言：你的 AI 助手，真的在认真写代码吗？

2026 年的今天，用 Claude Code、Cursor、Windsurf 写代码已经是程序员的日常。AI 代码助手确实让编码速度飙升——一个功能，几分钟就给你生成出来了，代码看起来漂漂亮亮，一运行还真的能跑。

但如果你仔细复盘一下，会发现一个扎心的事实：AI 生成代码的速度越快，你收拾烂摊子的时间也越长。

技术债就这样一点一点积累起来：没有测试、文档残缺、架构混乱、安全漏洞被忽视。你让 AI 写登录功能，它给你蹦出来一个能跑的页面，但：

• 没有技术方案文档
• 没有单元测试覆盖
• 没有安全加固（明文密码？SQL 注入？）
• 没有 API 设计说明
• 代码风格和团队规范完全不同

更糟糕的是，当你质问 AI："怎么没写测试？"它会说："稍后添加。""这只是原型。""重构太复杂了，后续再处理。"

结果呢？原型直接上线，"后续"永远不会来。

这就是所谓的 "Vibe Coding"——感觉对了就行，质量随缘。

而 Google Cloud AI 总监 Addy Osmani，给这种现象泼了一盆冷水，也带来了一个开源项目，彻底改变了 AI 编码代理的工作方式。

这个项目叫 agent-skills，上线不到三周斩获 27,000+ Stars。它不是又一个 AI 模型，不是又一个 IDE 插件，而是一套给 AI 编码代理注入"资深工程师工作纪律"的生产级技能框架。

本文从架构设计、工程实践、代码实现三个维度，对 Agent Skills 进行全面深度拆解，告诉你它为什么能解决 AI 编程的质量问题，以及如何在自己的工作流中落地。

一、问题诊断：AI 编码助手最擅长的三件事

在聊 Agent Skills 之前，我们先搞清楚 AI 代码助手为什么会产出低质量代码。

1.1 上下文爆炸与信息过载

传统 AI 代码助手的逻辑是：把所有信息一次性塞进上下文，让 AI 自己判断该做什么、怎么做。

问题是，当上下文窗口里塞了几百行代码、几十条对话历史、多个文件引用之后，AI 的注意力就分散了。它可能记住了项目 A 的规范，但忘了项目 B 的要求；它知道要做测试，但忘了安全审查。

最终结果：AI 生成了代码，但每个环节都浅尝辄止——代码能跑，但离"生产级别"差着十万八千里。

1.2 跳步与借口文化

这是最严重的问题。AI 生成代码时，最擅长做的事就是跳过质量门禁：

人类工程师会因为时间压力而跳过质量检查，AI 更是如此——而且 AI 没有"职业责任感"，它只会执行 prompt 中的指令，prompt 没强调的，它就默认可以不做。

1.3 无标准化的工程流程

不同的 AI 代码助手，不同的项目，不同的开发者，AI 生成代码的流程完全不同：

• 有的先写代码再想测试
• 有的有 API 设计文档，有的直接开撸
• 有的会在提交前检查安全，有的完全忽略安全
• 有的有 Git 规范，有的随便 commit

这种混乱导致：AI 生成的代码质量完全取决于 prompt 的详细程度，而不是工程最佳实践。只要 prompt 稍微差一点，代码质量就塌方式的下降。

二、Agent Skills 的核心设计哲学

Addy Osmani 做 Agent Skills 的思路非常清晰：不给 AI 说教的提示词，而是给 AI 可执行的工作流。

这套框架有三大核心设计哲学，每一条都直指上述三个问题：

2.1 流程大于文本（Workflow > Text）

传统 Prompt 的逻辑是："你要做一个好工程师，注意代码质量，遵循最佳实践。"这听起来很有道理，但实际上毫无约束力——AI 可以忽略这些建议，可以跳步，可以找借口。

Agent Skills 的逻辑是：**流程本身就是质量门禁。**它不给 AI 描述性的要求，而是给 AI 一套必须执行的步骤。每个步骤都有明确的检查点（Checkpoint），AI 必须通过检查，才能进入下一步。

这就像给 AI 请了一个严厉的 Staff Engineer 担任监工，手里拿着《Google 软件工程规范》，强制 AI 按照 SOP 一步一步执行，不能跳步、不能借口、不能含糊。

2.2 反合理化机制（Anti-Rationalization）

这是 Agent Skills 最为精妙的设计。

AI 很擅长找借口。当它想跳步时，会自然地生成一些"合理"的解释："这只是小改动""原型不用测""后续再优化"。人类工程师有时会被这些借口说服，但 AI 更没有底线——只要 prompt 里没有明确的限制，它就会找一切理由减少工作量。

Addy 的反制手段是：**把 AI 常见的借口写进技能文件里，并附上反驳理由。**只要 AI 想说借口，技能文件就会自动触发反驳。

例如，在测试相关的技能中，会有这样的 Rationalizations 表：

# 反合理化（Anti-Rationalization）

## AI 常见借口与对应反驳

| AI 借口 | 技能反驳 |
|---------|----------|
| "我会稍后添加测试" | 稍后 = 永不。现在写测试。 |
| "这只是原型" | 原型也会被部署。 |
| "重构太复杂了" | 小步重构更安全，一步到位是幻觉。 |
| "这代码能跑就行" | 能跑 ≠ 可维护。 |
| "这个改动太小了，不需要审查" | 所有改动都需要审查。逻辑错误不看大小。 |
| "测试覆盖率 60% 应该够了" | 生产代码需要 > 80% 覆盖率。60% 意味着仍有 40% 的代码在裸奔。 |

AI 在执行任务时，只要产生类似的念头，就会看到这条反驳，无法绕过。

这种设计的聪明之处在于：它不是在禁止 AI 偷懒，而是让 AI 在想偷懒的时候，自己看到偷懒的代价。

2.3 渐进式信息披露（Progressive Disclosure）

当上下文窗口里有几十个技能文件、几百条规则时，AI 会出现"信息过载"的问题——所有规则都同等重要，等于没有优先级；所有技能都同时激活，等于没有焦点。

Agent Skills 的解决方案是：按需加载，只在需要的阶段激活相关的技能。

具体来说，AI 在执行任务时，不会一次性加载所有技能文件，而是根据当前所处的开发阶段，按需加载：

用户输入需求
    ↓
AI 识别当前阶段（DEFINE / PLAN / BUILD / VERIFY / REVIEW / SHIP）
    ↓
只加载当前阶段所需的技能文件
    ↓
其他阶段的技能文件保持静默，不消耗上下文

例如，当 AI 处于 BUILD 阶段时，只会加载 incremental-implementation、test-driven-development、api-and-interface-design 等构建相关技能，REVIEW 阶段的代码审查规范和 SHIP 阶段的 CI/CD 规则都保持沉默，直到真正需要时才激活。

这种设计带来了两个好处：

1. 节省 Token：上下文窗口不会被规则填满，AI 的注意力始终集中在当前任务上
2. 降低认知负荷：AI 不会因为同时看到太多规则而感到混乱，每个阶段只有当前需要的指令

三、六阶段开发生命周期：AI 必须按顺序执行的工程流程

Agent Skills 把整个软件开发生命周期拆解为六个阶段，AI 必须严格按照顺序执行，不可以跳步：

DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP
  定义   规划   构建   验证   审查   发布

3.1 DEFINE 阶段：先想清楚，再动手

DEFINE 阶段包含两个核心技能：idea-refine 和 spec-driven-development。

idea-refine：从模糊想法到具体提案

这个技能解决的问题是：用户的需求往往是模糊的（比如"帮我做一个用户登录功能"），但 AI 直接根据模糊需求开始写代码，导致方向偏差、后期返工。

idea-refine 的流程是：

Step 1: 发散 — 列出所有可能的实现方向
  - 用户可能不知道的技术约束有哪些？
  - 有哪些边界情况需要考虑？
  - 竞品是如何实现的？

Step 2: 收敛 — 确定核心 MVP 范围
  - 这个功能的核心价值是什么？
  - 最小的可行版本包含哪些功能？
  - 明确"不做事项"（what we won't do）

Step 3: 假设验证 — 检查关键假设
  - 技术假设：当前架构能支持这个功能吗？
  - 产品假设：用户真的需要这个功能吗？
  - 安全假设：有哪些安全边界需要考虑？

Checkpoint（必须全部通过）：
  [ ] 明确了目标用户和使用场景
  [ ] 列出了 MVP 范围和不做事项
  [ ] 识别并记录了关键假设
  [ ] 假设需要技术验证的，验证后才继续

spec-driven-development：在编码前建立规格说明

这是 Agent Skills 中最核心的技能之一。它的核心思想是：写代码之前，必须先写 PRD（产品需求文档）。

PRD 必须覆盖以下内容：

# 规格说明书（SPEC.md）

## 1. 目标
- 功能目标：实现什么，解决了什么问题
- 非功能目标：性能、可用性、安全性要求

## 2. 接口设计
- 输入参数（类型、约束、默认值）
- 输出结果（成功/失败、格式、错误码）
- 依赖服务（调用关系、超时处理）

## 3. 数据结构
- 数据模型（字段、类型、关系）
- 持久化策略（数据库表设计、迁移脚本）

## 4. 代码风格
- 命名规范（变量、函数、文件）
- 错误处理规范（错误码、异常类型）
- 日志规范（级别、内容、格式）

## 5. 测试策略
- 单元测试覆盖率目标（> 80%）
- 边界条件测试用例
- 异常路径测试用例

## 6. 边界条件
- 输入合法范围
- 非法输入的处理方式
- 极限情况（空数据、超大数据量）

## 7. 安全考虑
- 身份验证（谁可以调用这个 API）
- 授权检查（用户是否有权限执行这个操作）
- 输入验证（防注入、防 XSS、防 CSRF）
- 敏感数据处理（是否需要加密、日志脱敏）

这个 SPEC.md 就是后续所有工作的"宪法"——AI 在 BUILD 阶段写代码时，必须严格对照 SPEC.md 执行，不能自己想当然。

3.2 PLAN 阶段：小步计划，逐步交付

PLAN 阶段的核心技能是 planning-and-task-breakdown，它解决的问题是：AI 拿到规格说明后，往往会一次性生成大量代码，导致：

• 代码质量控制困难
• 出问题后难以定位和回滚
• 上下文窗口迅速膨胀

planning-and-task-breakdown 的核心要求是：将规格拆解为小的、可排序的、可验证的任务单元。

## 任务拆解原则

### 原子化
每个任务应该可以在 1-2 小时内完成。
如果一个任务需要 8 小时，说明它太大了，需要继续拆解。

### 可验证
每个任务完成后，必须有一个明确的验证方式。
验证方式可以是：测试通过、构建成功、性能指标达标。

### 有依赖排序
明确每个任务的依赖关系，按依赖顺序排列。
没有依赖关系的任务可以并行开发。

## 输出格式

任务 ID | 任务描述 | 依赖任务 | 验收标准 | 预计工时

T-001 | 创建用户数据模型 | 无 | 模型符合 SPEC.md | 1h
T-002 | 实现密码哈希存储 | T-001 | 单元测试覆盖率 > 80% | 1h
T-003 | 实现登录 API | T-002 | API 测试通过 | 2h
T-004 | 实现登录前端页面 | T-002 | E2E 测试通过 | 2h
T-005 | 集成测试 | T-003, T-004 | 全量测试通过 | 1h

3.3 BUILD 阶段：增量实现，每步可回滚

BUILD 阶段是整个开发周期的核心，包含七个技能。这里重点介绍三个最关键的技能：

incremental-implementation：薄切片交付

这个技能的核心思想是：每次只实现一小块功能，每个增量都要可运行、可测试、可回滚。

## 增量实现流程

### 第一步：识别薄切片
根据 SPEC.md，识别最小的可交付切片。
薄切片 = 足够小，可以在 1-2 小时内完成
薄切片 = 足够完整，可以独立运行和测试

### 第二步：实现薄切片
按照 T-001 的顺序，每次只实现一个任务。
实现过程中，严格对照 SPEC.md 的要求。

### 第三步：测试验证
运行单元测试，确保新代码没有破坏已有功能。
测试覆盖率必须 > 80%，否则不进入下一阶段。

### 第四步：代码审查（轻量级）
提交前快速检查：
  - 命名是否符合规范
  - 错误处理是否完整
  - 是否有安全风险

### 第五步：提交并持续集成
提交到版本控制系统。
CI/CD 自动运行测试和构建。
任何一步失败，立即修复。

### Checkpoint（每轮增量必须通过）：
  [ ] 代码符合 SPEC.md 的接口设计
  [ ] 单元测试覆盖率 > 80%
  [ ] 所有测试通过（没有失败的测试）
  [ ] 没有硬编码凭证（API Key、密码等）
  [ ] 构建成功（CI/CD 通过）
  [ ] 依赖版本已锁定

### 反借口（Anti-Rationalization）：
"这次先不做测试，下次再补" → 测试就是本次的一部分，不是"下次"的一部分。
"这段代码后面会重构" → 现在的代码就是未来重构的基础，重构要从一开始就考虑。
"这个边界情况不太可能发生" → 所有 SPEC.md 中列出的边界情况都必须处理。

test-driven-development：测试驱动，不是测试滞后

这个技能对很多 AI 代码助手来说是最大的挑战——AI 很不愿意写测试，觉得是浪费时间。TDD 技能强制 AI 在写功能代码之前先写测试：

## TDD 流程（Red → Green → Refactor）

### Red 阶段：写一个会失败的测试
不要写功能代码，先写测试。
测试描述了这个功能"应该做什么"。

### Green 阶段：写最少的代码让测试通过
不要优化，不要扩展，只写让测试通过的代码。
这是"能工作"的最小实现。

### Refactor 阶段：改进代码质量
测试通过了，现在可以重构。
重构时保持测试始终通过。

## 示例：用 TDD 实现一个计算器

### 第一步：写测试（Red）

```python
# test_calculator.py

def test_add_two_numbers():
    """加法：两个正数相加"""
    result = add(2, 3)
    assert result == 5

def test_add_negative_numbers():
    """加法：负数相加"""
    result = add(-1, -2)
    assert result == -3

def test_add_mixed_numbers():
    """加法：正负混合"""
    result = add(-1, 3)
    assert result == 2

运行测试 → 全部失败（因为 add 函数还不存在）✓

第二步：写功能代码（Green）

# calculator.py

def add(a, b):
    return a + b

运行测试 → 全部通过 ✓

第三步：重构

# calculator.py

def add(a: int | float, b: int | float) -> int | float:
    """加法运算
    
    Args:
        a: 第一个加数
        b: 第二个加数
    
    Returns:
        两数之和
    """
    return a + b

测试仍然通过 ✓

测试覆盖率要求

Checkpoint：

[ ] 每个功能先写测试（Red → Green）
[ ] 测试覆盖率达标（核心逻辑 > 90%）
[ ] 所有测试通过
[ ] 无硬编码凭证在测试文件中
[ ] 边界情况有对应测试用例

反借口：

"这个函数很简单，不需要测试" → 简单函数更容易出错，因为会被大量复用。
"手动测试过了，不需要自动化测试" → 手动测试不能防止回归，下一次 PR 可能破坏这个函数。

#### source-driven-development：决策基于官方文档

这个技能解决的问题是：AI 生成代码时，经常使用"我认为正确"的方式实现，而不是查官方文档，导致使用了过时 API、错误配置或非推荐模式。

source-driven-development 要求：

1. **每个技术决策，必须有文档支撑**
   - 使用的 API 必须是官方文档推荐的版本
   - 配置参数必须来自官方文档
   - 错误处理方式必须参考官方示例

2. **禁止使用"凭经验"的技术方案**
   - AI 遇到不确定的技术问题时，必须先查文档
   - 文档与 AI 的认知冲突时，以文档为准

```markdown
## Source-Driven 检查清单

在实现任何技术点之前，必须确认：

[ ] API 版本：是否使用了当前 LTS/推荐版本？
[ ] 参数配置：是否参考了官方默认值和推荐配置？
[ ] 错误处理：是否参考了官方文档的错误处理模式？
[ ] 安全配置：是否应用了官方推荐的安全加固措施？
[ ] 依赖管理：依赖版本是否与官方兼容矩阵一致？

如果某个技术点没有官方文档支撑：
  → 在代码中标注 TODO 并说明原因
  → 添加风险说明
  → 提交 code review 时特别标注

3.4 VERIFY 阶段：证明它能工作，不只是看起来能跑

VERIFY 阶段包含两个核心技能：debugging-and-error-recovery 和 browser-testing-with-devtools。

debugging-and-error-recovery：五步调试法

AI 生成代码后，遇到错误时最常见的做法是：猜测原因、随便改、运行看结果——这不是调试，是碰运气。Agent Skills 定义了严格的五步调试法：

## 五步调试法

### Step 1: 复现问题
- 明确错误的具体表现（错误消息、返回结果、行为异常）
- 确定复现步骤（如何让问题稳定重现）
- 记录复现环境（版本、配置、数据状态）

### Step 2: 定位根因
- 查看完整错误堆栈，不只看最后一行
- 使用二分法隔离问题范围（注释代码、简化输入）
- 检查调用链，确认问题发生在哪个环节

### Step 3: 设计修复方案
- 确认根因后，不要立即修改
- 设计修复方案并评估影响
- 考虑回滚方案（如果修复后更糟怎么办）

### Step 4: 实现修复
- 只修改必要的代码，不扩大修改范围
- 修改后立即运行测试验证

### Step 5: 验证修复
- 用相同步骤再次复现问题（应该失败）
- 确认修复后问题不再出现
- 确认没有引入新问题（回归测试）

## Evidence 要求

每一步调试，都必须有具体的输出证据：

| 步骤 | 需要的证据 |
|------|----------|
| 复现问题 | 错误日志、堆栈截图、输入数据样本 |
| 定位根因 | 隔离实验过程、最小复现案例 |
| 设计修复 | 修复方案说明、影响评估报告 |
| 实现修复 | 修复前后的代码 diff |
| 验证修复 | 测试结果截图、性能对比数据 |

### Checkpoint：
  [ ] 问题能够稳定复现
  [ ] 根因定位到具体文件和行号
  [ ] 修复后测试全部通过
  [ ] 回归测试全部通过（没有引入新问题）

3.5 REVIEW 阶段：强制检查，证据驱动

REVIEW 阶段包含五个技能，涵盖代码审查、安全、性能、依赖等多个维度。这里重点介绍 code-review-and-quality：

## 代码审查技能（五轴审查）

### 轴一：功能正确性
- 代码是否实现了 SPEC.md 中定义的功能？
- 边界条件是否全部处理？
- 错误处理是否完整？

### 轴二：代码可读性
- 命名是否清晰（变量名、函数名、文件名）
- 是否有必要的注释（为什么这么做，不是做什么）
- 函数长度是否合理（每个函数 < 50 行为佳）

### 轴三：架构合理性
- 依赖关系是否清晰（无循环依赖）
- 单一职责（一个函数只做一件事）
- 是否符合 SOLID 原则

### 轴四：安全性
- 是否有注入风险（SQL 注入、XSS、命令注入）？
- 是否有授权漏洞（越权访问）？
- 是否有敏感数据泄露（日志、错误消息、返回数据）？
- 是否使用了安全的加密算法和密钥管理？

### 轴五：性能
- 是否有 N+1 查询问题？
- 是否有大文件内存溢出风险？
- 缓存策略是否合理？

## Change Size 规范（防止 AI 一次性提交大量代码）

| 代码变更量 | 要求 |
|-----------|------|
| < 200 行 | 快速 review，1 小时内合并 |
| 200-500 行 | 标准 review，4 小时内合并 |
| 500-1000 行 | 分批 review，每次 < 500 行 |
| > 1000 行 | 必须拆分成多个增量，每个 < 500 行 |

AI 生成代码时，如果一次性变更超过 500 行，必须主动拆分。

## Review Speed 规范

- 首次 review 反馈：< 2 小时（保持开发者的上下文热度和）
- 二次 review 反馈：< 1 小时
- 长时间未反馈（> 8 小时）：自动触发提醒

### Checkpoint：
  [ ] 五轴审查全部通过
  [ ] 没有高危安全问题（OWASP Top 10）
  [ ] 代码变更量 < 500 行（需要拆分的已拆分）
  [ ] 所有 comment 已处理（resolve 或回复说明）
  [ ] CI 全部通过

3.6 SHIP 阶段：发布不是终点，是持续运营的开始

SHIP 阶段包含三个技能：git-workflow-and-versioning、ci-cd-and-automation 和 deprecation-and-migration。

## Git 工作流规范

### 提交规范（Conventional Commits）

每次提交必须遵循以下格式：

():

[optional body]

[optional footer]

类型（type）：
- feat: 新功能
- fix: 错误修复
- refactor: 重构（不影响功能）
- test: 测试相关
- docs: 文档更新
- chore: 构建/工具变更

示例：

feat(auth): add JWT-based login endpoint

• implement POST /api/login
• add password hashing with bcrypt
• add rate limiting (10 req/min)
• refs #123

Closes #123

### 原子提交原则

每次提交只做一件事。
一个 commit = 一个逻辑单元 = 可以独立回滚的最小单位。

✓ 正确：一次提交只改一件事

commit abc123: feat(auth): add login endpoint
commit def456: fix(auth): prevent timing attack on password check
commit ghi789: test(auth): add login endpoint tests

✗ 错误：把多个改动混在一个提交里

commit abc123: add login, fix bugs, update tests, refactor auth, update docs

## CI/CD 规范

### 必须包含的检查

每个 PR 必须通过以下 CI 检查才能合并：

1. 单元测试（覆盖率 > 80%）
2. 代码质量检查（lint/type check）
3. 安全扫描（依赖漏洞、硬编码凭证）
4. 构建验证（编译通过、镜像构建成功）
5. 集成测试（如果适用）

### Feature Flag 规范

所有新功能必须通过 Feature Flag 引入，禁止直接合并到 main 分支：

```python
# Feature Flag 示例

if feature_flags.is_enabled("new_auth_flow", user_id):
    return new_login_flow(request)
else:
    return legacy_login_flow(request)

这样可以实现：

• 灰度发布（新功能先对 1% 用户开放，逐步扩大）
• 快速回滚（关闭 Feature Flag 即可，不需要回滚代码）
• A/B 测试（不同用户看到不同的实现）

Checkpoint：

[ ] 提交信息符合 Conventional Commits 格式
[ ] 每个提交是原子性的（只做一件事）
[ ] 所有 CI 检查通过
[ ] 新功能通过 Feature Flag 引入
[ ] 文档已更新（CHANGELOG、README）

---

## 四、SKILL.md 技术架构解析：从文件格式到执行流程

理解了六大阶段的工作流之后，我们需要深入到 SKILL.md 的技术实现层面，理解 Agent Skills 是如何通过文件格式来实现上述所有设计目标的。

### 4.1 SKILL.md 的标准格式

每个 Skill 文件就是一个文件夹，文件夹里必须有 `SKILL.md` 文件，可选包含 `scripts/`、`references/`、`assets/` 等目录：

code-review/ # Skill 名称（自定义，见名知意）
├── SKILL.md # 必需：元数据 + 操作指南（AI 的执行依据）
├── scripts/ # 可选：辅助脚本
│ ├── security-scan.sh # 安全扫描脚本
│ └── lint-check.py # 代码检查脚本
├── references/ # 可选：参考资料
│ ├── owasp-checklist.md # OWASP 安全检查清单
│ └── coding-standards.md # 团队代码规范
└── assets/ # 可选：静态资源
└── review-template.md # 审查模板

SKILL.md 的标准格式包含两个部分：**YAML Frontmatter** 和 **Markdown 主体**。

#### YAML Frontmatter（技能元数据）

```yaml
---
name: code-review
description: |
  对代码进行深度审查，发现潜在问题和改进建议。
  在用户要求 review、审视、检查代码时激活。
triggers:
  - "review"
  - "code review"
  - "审查代码"
  - "/review"
version: 1.0.0
compatibility:
  - claude-code
  - cursor
  - gemini-cli
allowed-tools:
  - read_file
  - search_code
  - execute_command
  - write_file
metadata:
  author: addyosmani
  license: MIT
  stage: REVIEW
---

关键字段说明：

• name：Skill 的名称，全局唯一
• description：AI 在决定激活哪个 Skill 时使用的描述，触发条件
• triggers：触发词列表，当用户的输入匹配这些词时，AI 会自动激活这个 Skill
• stage：这个 Skill 属于哪个开发阶段（用于渐进式加载）
• allowed-tools：这个 Skill 允许使用的工具列表（安全隔离）

Markdown 主体（工作流指令）

# 代码审查技能

## Overview

这个技能指导 AI 对代码进行系统性审查，覆盖功能正确性、代码可读性、架构合理性、安全性和性能五个维度。

## When to Use

- 用户要求审查代码（review, /review）
- 代码提交前（pre-commit hook）
- Code Review 阶段（REVIEW stage）
- 主动发现问题时

## Process

### Step 1: 理解代码上下文

在开始审查之前，先理解代码的功能背景：
- 这个代码的作用是什么？
- 它在整个系统中处于什么位置？
- 主要的使用场景是什么？

### Step 2: 功能正确性审查

逐文件审查，检查：
- [ ] 代码是否实现了 SPEC.md 中定义的功能
- [ ] 边界条件（空值、超大值、异常值）是否处理
- [ ] 错误处理是否完整（try/catch、fallback）
- [ ] 日志是否足够（方便排查问题）

### Step 3: 代码质量审查

- [ ] 命名是否清晰（变量、函数、文件）
- [ ] 注释是否必要且有效（解释"为什么"，而非"做什么"）
- [ ] 函数长度是否 < 50 行（超过则建议拆分）
- [ ] 是否有重复代码（DRY 原则）

### Step 4: 安全性审查

- [ ] 输入验证（防注入、防 XSS、防 CSRF）
- [ ] 授权检查（用户是否有权限）
- [ ] 敏感数据处理（加密、脱敏、日志过滤）
- [ ] 依赖安全（已知漏洞检查）

### Step 5: 性能审查

- [ ] 数据库查询是否有 N+1 问题
- [ ] 是否有不必要的循环或递归
- [ ] 缓存策略是否合理
- [ ] 大文件/大数据处理是否有内存溢出风险

## Checkpoint（必须全部通过）

- [ ] 五轴审查全部完成（功能/可读性/架构/安全/性能）
- [ ] 无高危安全问题（注入、越权、敏感数据泄露）
- [ ] 变更量 < 500 行（超出的已拆分）
- [ ] 所有发现的问题已记录（建议/严重/阻塞）

## Anti-Rationalization（反借口表）

| AI 可能的借口 | 反驳 |
|---|---|
| "这个改动太小，不需要 review" | 所有改动都需要审查，逻辑错误不看大小 |
| "这个文件我之前 review 过" | 代码随时可能被修改，每次 PR 都需要独立 review |
| "这只是格式调整，不需要详细检查" | 格式调整也可能引入逻辑错误 |
| "看起来没问题，我先合并了" | "看起来"不是证据，必须有具体的检查结果 |
| "安全问题太理论，实际不会发生" | 注入和越权是最常见的真实攻击向量 |

## Evidence（输出要求）

审查完成后，必须输出：

```markdown
## 审查报告

### 文件清单
- `src/auth/login.py` - ✅ 通过（有轻微建议）
- `src/auth/session.py` - ⚠️ 需要修改（发现 XSS 漏洞）
- `src/utils/validator.py` - ✅ 通过

### 发现的问题

#### 🔴 严重（必须修复）
1. **XSS 漏洞** - `src/auth/login.py:42`
   - 原因：用户输入未转义直接输出到 HTML
   - 修复：对用户输入使用 HTML 转义
   
#### 🟡 建议（推荐修复）
2. **N+1 查询** - `src/auth/session.py:15`
   - 原因：循环内查询数据库
   - 修复：使用 JOIN 预加载

### Checkpoint 状态
- [x] 五轴审查全部完成
- [x] 无高危安全问题
- [x] 变更量 < 500 行
- [x] 所有问题已记录

退出条件

只有在以下条件全部满足时，才能结束审查并进入下一阶段：

1. 五轴审查全部完成并记录
2. 所有严重（🔴）问题已修复或明确计划修复时间
3. Checkpoint 全部通过
4. 审查报告已输出并记录

### 4.2 技能的调度机制

Agent Skills 如何决定在什么时机激活什么技能？这涉及到 Skill 的调度机制：

**基于上下文的自动激活：**
- AI 在处理任务时，根据当前任务内容自动识别需要的技能
- 例如：当用户在讨论 API 设计时，自动激活 `api-and-interface-design` Skill

**基于命令的显式激活：**
- 用户输入 `/spec`、`/plan`、`/build` 等斜杠命令时，强制激活对应阶段的所有技能
- 这种方式适合有明确流程意识的用户

**基于触发词的模糊激活：**
- 当用户输入包含特定词汇时（如"review"、"debug"、"test"），激活相关技能
- 这种方式适合自然语言交互场景

### 4.3 技能的版本管理

每个 Skill 都有版本号（semver 格式），这对于 AI 编码代理非常重要：

```yaml
version: 1.0.0
# 1.0.0 = major.minor.patch
# major: 不兼容的架构变更
# minor: 向下兼容的功能新增
# patch: 向下兼容的 bug 修复

版本管理的意义在于：

1. AI 可以识别 Skill 的稳定性：major 版本变化时，AI 会更谨慎
2. 团队可以控制 Skill 的升级节奏：不影响现有工作流的情况下引入新技能
3. 调试更方便：当 AI 的行为异常时，可以检查 Skill 版本是否兼容

五、七大斜杠命令：AI 编码的标准化操作界面

Agent Skills 提供七个斜杠命令，每个命令对应开发流程中的一个环节，激活后自动加载对应技能：

/spec   定义要构建什么   → 先写需求再写代码
/plan   规划如何构建     → 小的原子化任务
/build  增量式构建       → 一次只做一块
/test   证明能工作       → 测试就是证明
/review 合并前评审      → 提高代码健康度
/code-simplify 简化代码 → 清晰胜过聪明
/ship   发布到生产       → 越快越安全

5.1 /spec 命令：需求即宪法

当用户输入 /spec 我需要一个用户登录功能 时，AI 自动执行：

[1/3] idea-refine → 分析需求背景，明确 MVP 范围
[2/3] spec-driven-development → 撰写完整 SPEC.md
[3/3] Checkpoint → 验证 SPEC.md 的完整性
    [ ] 目标用户和使用场景已明确
    [ ] 接口设计已确定
    [ ] 测试策略已规划
    [ ] 安全考虑已覆盖

5.2 /build 命令：增量而非瀑布

当用户输入 /build 时，AI 按照任务计划逐个实现：

[T-001] 创建用户数据模型 → 单元测试通过 → Checkpoint ✅
[T-002] 实现密码哈希存储 → 单元测试通过 → Checkpoint ✅
[T-003] 实现登录 API → 集成测试通过 → Checkpoint ✅
[T-004] 实现登录前端页面 → E2E 测试通过 → Checkpoint ✅

每个任务完成后，AI 必须：

1. 运行测试，验证功能正确
2. 检查覆盖率是否达标
3. 确认没有引入安全问题
4. 提交并通过 CI 检查

只有全部通过，才能进入下一个任务。

5.3 /review 命令：证据驱动，不是感觉驱动

当用户输入 /review 时，AI 执行五轴审查：

轴1: 功能正确性 → 发现 0 个问题 ✅
轴2: 代码可读性 → 发现 2 个建议，记录中 ✅
轴3: 架构合理性 → 发现 0 个问题 ✅
轴4: 安全性 → 发现 1 个 XSS 漏洞 🔴
轴5: 性能 → 发现 1 个 N+1 查询 🟡

严重问题必须修复后才能合并。
建议问题记录到后续迭代中。

六、深度对比：Agent Skills vs 传统 Prompt vs MCP

为了更好地理解 Agent Skills 的价值，我们从多个维度对比它与传统 Prompt Engineering 和 MCP（Model Context Protocol）的关系。

6.1 与传统 Prompt Engineering 的对比

关键区别：

• 传统 Prompt 告诉你"要做什么"（写好代码），Agent Skills 告诉你"怎么做"（先写测试、再写实现、每步验证）
• 传统 Prompt 的质量完全取决于 prompt 的详细程度，Agent Skills 的质量由技能本身的工程设计决定，不依赖用户的 prompt 技巧

6.2 与 MCP（Model Context Protocol）的对比

MCP 是 Anthropic 在 2025 年推出的模型上下文协议，用于标准化 AI 与外部工具的连接。两者解决的问题不同，但可以互补：

两者结合的最佳实践：

用户需求 → Agent Skills（规划工作流）
    ↓
DEFINE 阶段 → SPEC.md（需求文档）
    ↓
PLAN 阶段 → 任务拆解（小型可验证任务）
    ↓
BUILD 阶段 → 
  - incremental-implementation（增量实现）
  - MCP 连接数据库（工具调用）
  - MCP 调用代码搜索（工具调用）
    ↓
VERIFY 阶段 → 
  - MCP 运行浏览器测试（工具调用）
  - MCP 执行安全扫描（工具调用）
    ↓
REVIEW 阶段 → 代码审查（基于 Agent Skills 规范）
    ↓
SHIP 阶段 → MCP 触发 CI/CD 部署（工具调用）

MCP 让 AI 有能力调用各种外部工具，Agent Skills 让 AI 有纪律地使用这些工具——这是一个完整的 AI 工程化闭环。

七、落地实践：在 Claude Code 中使用 Agent Skills

理论讲完了，接下来是最实用的部分：如何在实际工作中使用 Agent Skills。

7.1 一键安装（最简单的方式）

# Claude Code
npx skills add addyosmani/agent-skills

# 安装后验证
npx skills list

7.2 手动安装（更多控制）

# 1. 创建全局 skills 目录
mkdir -p ~/.claude/skills

# 2. 从 GitHub 下载所需 Skill
cd ~/.claude/skills
git clone https://github.com/addyosmani/agent-skills.git

# 3. 在 Claude Code 中验证安装
# 输入 /skills 查看已安装的技能

7.3 项目级安装（团队共享规范）

如果团队希望所有成员使用统一的 AI 编码规范，可以在项目目录中安装：

# 项目目录
mkdir -p .claude/skills
cd .claude/skills
git clone https://github.com/addyosmani/agent-skills.git agent-skills

# 在 .claude/skills/agent-skills/skills/ 中选择需要的技能
# 删除不需要的技能，只保留团队规范所需的

7.4 实际使用示例

场景：开发一个 RESTful API

用户：/spec 实现一个获取用户列表的 API，支持分页和过滤

AI 自动执行：
[DEFINE] idea-refine → 分析需求
  - MVP：返回用户列表，支持 page/size 参数，支持 name 过滤
  - 不做：排序、复杂过滤、批量操作
  - 假设验证：数据库有索引，支持高效分页
  
[DEFINE] spec-driven-development → 撰写 SPEC.md
  - 接口设计：GET /api/users?page=1&size=20&name=xxx
  - 响应格式：{ data: [...], total: 100, page: 1, size: 20 }
  - 安全：需要认证 token，无越权风险
  - 性能：使用数据库索引，避免全表扫描
  - 测试策略：单元测试覆盖率 > 80%，边界测试（空数据、超大 page）
  
Checkpoint 通过 ✅

用户：/build

AI 按任务计划增量实现：
  [T-001] 创建用户数据模型 → 测试通过 ✅
  [T-002] 实现 API 路由 → 测试通过 ✅
  [T-003] 实现分页逻辑 → 测试通过 ✅
  [T-004] 实现过滤逻辑 → 测试通过 ✅
  
用户：/review

AI 执行五轴审查：
  功能 ✅ | 可读性 ✅ | 架构 ✅ | 安全 ✅ | 性能 ✅
  发现 1 个轻微建议（函数名可以更清晰），记录中
  
用户：/ship

AI 执行发布流程：
  → 生成符合 Conventional Commits 的提交信息
  → Feature Flag 开启（初期 1% 用户）
  → 监控错误率和性能指标
  → 逐步扩大用户范围

7.5 在 Cursor 中使用

对于 Cursor 用户，Agent Skills 可以作为 .cursorrules 文件来集成：

# 方式一：直接使用 agent-skills 的 skill 内容
cp ~/.claude/skills/agent-skills/skills/spec-driven-development/SKILL.md .cursor/rules/spec-driven-development.md
cp ~/.claude/skills/agent-skills/skills/test-driven-development/SKILL.md .cursor/rules/test-driven-development.md

# 方式二：在 .cursorrules 中引用关键规范
# .cursorrules
# 使用 Agent Skills 规范进行开发：
# - /spec 定义需求 → SPEC.md 是唯一标准
# - /plan 拆解任务 → 小步验证
# - /build 增量实现 → 每次增量都测试
# - /review 五轴审查 → 安全第一

八、三大铁律与反借口机制：Agent Skills 的精髓

从 Agent Skills 的设计中，我们提炼出三条铁律，适用于任何 AI 编码场景：

8.1 铁律一：Process not Prose（流程优于文本）

技能是工作流，不是阅读材料。每一步都要可执行、可检查。

反面例子：

"请注意代码质量，确保安全，遵循最佳实践。"
→ AI 可以忽略

正面例子：

Step 1: 写测试
Checkpoint: 测试覆盖率 > 80%，所有测试通过
未通过？停止执行，修复后重试。

→ AI 必须执行，有检查点约束

8.2 铁律二：Checkpoint 必过（不妥协的质量门禁）

每步骤有检查清单，不通过就停止。不能"差不多"就继续。

反面例子：

"测试应该跑过了吧？看起来没问题。"
→ AI 可能跳过测试

正面例子：

Checkpoint（必须全部通过）：
[ ] 测试覆盖率 > 80%
[ ] 所有测试通过（0 failures）
[ ] 无硬编码凭证
[ ] 构建成功

未通过？执行 /test 重新运行测试。

→ 有明确标准，AI 无法含糊

8.3 铁律三：Evidence 不妥协（拒绝"看起来对了"）

完成要有证据，不能说"看起来对了"。要有输出文件、测试结果、运行数据。

反面例子：

AI："这个功能完成了，看起来没问题。"
→ 没有证据，无法验证

正面例子：

审查报告：
- 单元测试覆盖率：87.3%（通过 ✅）
- 所有测试通过：24/24（通过 ✅）
- 构建状态：成功（通过 ✅）
- 安全扫描：无高危问题（通过 ✅）

证据截图：[build-log-20260516-143022.png]

8.4 反借口机制的实际效果

让我们看一个具体的场景，感受反借口机制的实际效果：

用户：实现一个文件上传功能

AI（没有 Agent Skills）：
  → 直接开始写代码
  → 写完了，测试？没有。文档？没有。
  → 用户："怎么没写测试？"
  → AI："这个功能简单，后面再补。"
  → 结果：没有测试，技术债积累

AI（使用 Agent Skills）：
  → /spec 定义需求 → SPEC.md 生成
  → /plan 拆解任务 → T-001 ~ T-005
  → /build 开始实现

  T-001: 实现基础上传
    Checkpoint: 
      [ ] 测试覆盖率 > 80% → AI 必须写测试
      [ ] 所有测试通过 → AI 必须让测试跑通
    Anti-Rationalization 触发：
      "这个功能简单，不需要测试" → 反驳：简单函数更容易出错，因为会被大量复用
      
  T-002: 实现文件类型验证
    Checkpoint:
      [ ] 安全扫描通过 → AI 必须检查安全
    Anti-Rationalization 触发：
      "安全验证太严格了" → 反驳：文件上传是最常见的攻击向量，验证不能省
      
  T-003: 实现大小限制
    Checkpoint:
      [ ] 边界测试通过（空文件、超大文件）→ AI 必须处理边界情况
      
  ... (继续直到所有 Checkpoint 通过)

  /review 代码审查
  /ship 发布上线

  结果：完整的、有测试的、有安全验证的、可维护的功能代码

九、Agent Skills 的局限性与适用边界

Agent Skills 是一套强大的工程规范，但它不是万能的。了解它的局限性，可以帮助我们更好地使用它。

9.1 不适合的场景

1. 一次性脚本或简单任务

如果只是让 AI 写一个简单的脚本（比如批量重命名文件），使用 Agent Skills 反而增加了不必要的复杂度。这时候直接对话反而更高效。

2. 快速原型探索

在探索性阶段，目标是验证想法的可行性，而不是工程规范。这时可以使用轻量级的方法，不需要完整的六阶段流程。

3. 极度时间压力下的紧急修复

在紧急修复生产问题时（如凌晨两点处理线上故障），Agent Skills 的一些流程（如完整的 SPEC.md）可以暂时简化，但事后必须补上文档和测试。

9.2 适合的场景

1. 生产环境的核心功能开发

对于任何会进入生产环境的代码，Agent Skills 的流程都是值得遵循的。它确保了代码质量、可维护性和安全性。

2. 团队协作的 AI 辅助开发

当团队使用 AI 编码助手时，Agent Skills 可以作为团队的"AI 编码规范"，确保所有成员使用一致的开发流程，而不是各自为战。

3. 需要长期维护的代码库

对于需要长期维护的代码（如开源项目、企业内部服务），Agent Skills 的规范可以大大降低维护成本，因为代码始终有文档、测试和审查。

9.3 定制化建议

Agent Skills 是一个通用框架，实际使用时可以根据团队情况进行定制：

## 定制化策略

### 策略一：按需选用技能

不需要安装全部 22 个技能，选择团队最需要的：

推荐优先安装：
1. spec-driven-development（需求规范）
2. test-driven-development（测试保障）
3. code-review（质量把控）
4. security-hardening（安全加固）

可选安装：
5. incremental-implementation（大型项目）
6. git-workflow（版本管理）
7. ci-cd（自动化部署）

### 策略二：调整 Checkpoint 标准

如果团队有不同的质量要求，可以调整 Checkpoint 阈值：

默认：
- 测试覆盖率 > 80%

严格模式（金融/医疗）：
- 测试覆盖率 > 90%
- 强制安全扫描通过
- 强制性能基准测试

宽松模式（快速迭代）：
- 测试覆盖率 > 60%
- 核心功能必须有测试

### 策略三：自定义反借口表

根据团队常见的问题，添加团队特有的反借口：

| AI 可能的借口 | 团队反驳 |
|---|---|
| "这个代码我同事写的，不需要 review" | 所有人写的代码都需要 review |
| "这个改动太小，不需要写测试" | 微小改动更容易引入回归，必须有测试 |
| "接口已经约定好了，不需要文档" | 文档是其他团队理解接口的唯一途径，必须写 |

十、展望 2026：Agent Skills 引领的 AI 工程化趋势

10.1 从"提示词工程"到"技能工程"

Agent Skills 的出现，标志着 AI 开发领域的一个重大转变：从"提示词工程"（Prompt Engineering）到"技能工程"（Skill Engineering）。

• 提示词工程关注的是：如何用更好的文字描述任务，让 AI 理解
• 技能工程关注的是：如何设计一套系统，让 AI 遵循正确的流程工作

技能工程的优势在于：

1. 可复用：一个 Skill 可以被不同的 AI 工具使用，不绑定特定模型
2. 可演进：Skill 可以随着最佳实践的演化而升级版本
3. 可协作：团队可以共享 Skill，形成统一的工程规范
4. 可验证：每个 Skill 都有明确的检查点，输出质量可验证

10.2 Agent Skills 的生态扩张

截至 2026 年 5 月，Agent Skills 生态已经覆盖了主流 AI 编码工具：

社区也在积极贡献新的 Skills：

• 安全审查技能：OWASP Top 10 检查、依赖漏洞扫描
• 性能优化技能：数据库查询优化、前端渲染优化
• 可访问性技能：WCAG 2.1 合规检查
• 文档技能：API 文档生成、README 规范

10.3 未来展望

2026 年下半年值得关注的趋势：

1. Skill 市场出现：类似于 npm 的 Skill 注册中心，开发者可以发布、发现和安装社区 Skills
2. Skill 验证工具标准化：类似于 ESLint 的 Skill Linter，自动验证 Skill 文件的格式和内容正确性
3. 多模态 Skill 出现：不仅包含文本指令，还包含视觉示例、代码模板、测试用例等多媒体资源
4. 企业级 Skill 规范：大型团队可以创建符合自己业务场景的 Skill 套件，作为组织级的 AI 编码规范

结语：AI 编程的新范式

回到最初的问题：AI 代码助手最大的问题是什么？

**是它太快了。**快到我们来不及检查质量，快到它可以跳过所有工程流程，快到它可以找任何借口来减少自己的工作量。

Vibe Coding 的本质，不是 AI 不够聪明，而是没有足够的约束让 AI 做正确的事。

Agent Skills 给了我们一套解决方案：不是告诉 AI 要做什么，而是强制 AI 按正确的方式做。

• 六阶段流程 → 防止跳步
• Checkpoint 检查 → 防止偷懒
• 反借口表 → 防止找理由
• 证据要求 → 防止"看起来对了"

当你用 Claude Code 或 Cursor 时，加上 Agent Skills，你就拥有了一个真正有纪律的 AI 协作者——它不会偷懒，不会跳步，不会找借口，它会按照资深工程师的标准，一步一步地完成工作。

这就是 Agent Skills 带给我们的价值：不是让 AI 更聪明，而是让 AI 更有章法。

附录：快速参考

A. 安装命令

# Claude Code
npx skills add addyosmani/agent-skills

# 手动安装
git clone https://github.com/addyosmani/agent-skills.git ~/.claude/skills/agent-skills

B. 七大斜杠命令速查

C. SKILL.md 快速模板

---
name: your-skill-name
description: 技能的简短描述，说明何时激活
triggers:
  - "触发词1"
  - "触发词2"
version: 1.0.0
stage: BUILD  # DEFINE/PLAN/BUILD/VERIFY/REVIEW/SHIP
---
# 技能名称

## Overview
简要说明这个技能做什么。

## Process
### Step 1: ...
### Step 2: ...

## Checkpoint
- [ ] 检查项1
- [ ] 检查项2

## Anti-Rationalization
| 借口 | 反驳 |
|------|------|
| "..." | "..." |

## Evidence
输出要求说明。

D. 项目地址

Agent Skills: github.com/addyosmani/agent-skills

维护者: Addy Osmani，Google Cloud AI 总监，Chrome 团队工程主管

协议: MIT License

当前版本: 0.5.0+

Star 数: 27,000+（2026 年 5 月）