Claude Code Skills：打造你的专属 AI 工作流 · Lesson 5 of 6

第 5 课：实战案例：构建代码审查 Skill

学习目标：

学习如何组织多步骤工作流

理解检查清单模式的应用

掌握 supporting files 的使用

创建一个生产可用的复杂 Skill

前置要求：<< 第 4 课 | 下一课第 6 课 >>

为什么选择代码审查作为案例

代码审查是典型的结构化工作流：¹

步骤固定：检查规范、查找问题、提出建议
标准可量化：每个检查项都能明确判断通过或不通过
重复性高：每次 PR 都要审查
适合 Skill：把团队的审查标准写进 Skill，保证每次审查质量一致

这个案例会展示：

如何把复杂工作流拆解成清晰的步骤
如何用检查清单组织 instructions
如何处理多个输出维度

第 1 步：明确审查范围

开始写之前，先确定这个 Skill 要检查什么。

我们的代码审查 Skill 检查三个维度：

代码规范：命名、格式、注释
潜在问题：错误处理、边界情况、安全风险
可维护性：重复代码、函数长度、逻辑复杂度

不检查的内容：

具体业务逻辑是否正确（这需要深入了解需求）
算法效率（需要性能测试）
UI/UX 设计（不在代码审查范围）

第 2 步：创建目录结构

这次我们用 supporting files 来组织审查规则：²

BASH

mkdir -p ~/.claude/skills/code-review
mkdir -p ~/.claude/skills/code-review/checklists

touch ~/.claude/skills/code-review/SKILL.md
touch ~/.claude/skills/code-review/checklists/naming.md
touch ~/.claude/skills/code-review/checklists/error-handling.md

为什么要拆分文件：

SKILL.md 保持简洁，只写核心流程
详细的检查规则放在单独文件里，按需加载²
团队可以独立维护各个 checklist，不用改主文件

第 3 步：编写主 SKILL.md

MARKDOWN

---
name: code-review
description: 审查代码变更，检查命名规范、错误处理、潜在 bug 和可维护性问题。用于 PR 审查或代码质量检查
---

# 代码审查助手

系统化审查代码变更，基于团队规范和最佳实践。

## 输入格式

接受以下任何格式：

- Git diff 输出
- 完整的代码文件
- 代码片段（函数或类）
- PR 链接（需要先用工具读取 PR 内容）

## 审查流程

按以下顺序执行审查：

### 1. 代码规范检查

参考 `checklists/naming.md`，逐项检查：

- **变量命名**：是否使用有意义的名字、是否符合团队命名约定（驼峰、下划线等）
- **函数命名**：动词开头、清楚表达意图
- **类命名**：名词、符合单一职责原则
- **常量命名**：全大写、下划线分隔

**标准：** 所有命名应该让不熟悉代码的人也能理解其用途

### 2. 错误处理检查

参考 `checklists/error-handling.md`，检查：

- **异常捕获**：是否有 try-catch、是否捕获了正确的异常类型
- **错误返回值**：函数是否正确处理和传播错误
- **边界情况**：空输入、null、undefined、空数组等是否处理
- **资源清理**：文件、连接、锁等是否正确释放

**标准：** 任何可能失败的操作都应该有错误处理

### 3. 潜在问题检查

- **空指针/未定义访问**：是否有可能访问不存在的属性或方法
- **类型安全**：是否有隐式类型转换风险
- **并发问题**：是否有竞态条件、死锁风险
- **安全漏洞**：SQL 注入、XSS、CSRF、敏感信息泄露

**标准：** 任何可能导致运行时错误或安全风险的代码都标记出来

### 4. 可维护性检查

- **函数长度**：超过 50 行的函数建议拆分
- **重复代码**：相似逻辑出现 3 次以上建议提取
- **嵌套深度**：超过 3 层嵌套建议重构
- **注释质量**：复杂逻辑是否有注释解释

**标准：** 代码应该容易被其他开发者理解和修改

## 输出格式

按以下结构输出审查结果：

### ✅ 通过的检查
- [检查项] - 符合标准

### ⚠️ 需要注意的问题
- **位置**：`文件名:行号`
- **问题**：具体是什么问题
- **影响**：可能导致什么后果
- **建议**：如何改进

### 🔴 必须修复的问题
- **位置**：`文件名:行号`
- **问题**：具体是什么问题
- **风险**：为什么必须修复
- **建议**：具体的修复方案

### 📊 总体评估
- 代码质量：优秀 / 良好 / 需改进
- 主要问题：[总结最重要的 2-3 个问题]
- 建议优先级：[哪些问题应该先修复]

## 注意事项

- **上下文理解**：如果代码片段不完整，说明可能需要更多上下文
- **框架特性**：某些看起来的"问题"可能是框架的特定用法，标注为"需确认"
- **测试代码**：测试代码的标准可以适当放宽（如函数长度）
- **无问题时**：如果所有检查都通过，输出"✅ 代码审查通过，未发现明显问题"

第 4 步：编写 supporting files

checklists/naming.md：

MARKDOWN

# 命名规范检查清单

## 变量命名

**好的命名：**
- `userCount`：清楚表达是用户的数量
- `isAuthenticated`：布尔值用 is/has/can 开头
- `maxRetryAttempts`：常量说明了含义和单位

**不好的命名：**
- `x`, `temp`, `data`：太泛化
- `flag`, `status`：不说明具体是什么状态
- `getUserInfo2`：有数字后缀说明可能有重复

## 函数命名

**好的命名：**
- `calculateTotalPrice()`：动词+名词，清楚表达动作和对象
- `validateUserInput()`：说明了做什么和作用于什么
- `fetchUserProfile()`：fetch 表明这是异步操作

**不好的命名：**
- `process()`：太泛化，不知道处理什么
- `doStuff()`：完全不表达意图
- `handleData()`：handle 和 data 都太宽泛

## 类命名

**好的命名：**
- `UserRepository`：名词，表达了职责（用户数据存取）
- `PaymentProcessor`：清楚说明是处理支付的
- `EmailValidator`：说明了验证邮箱的职责

**不好的命名：**
- `Manager`, `Helper`, `Utility`：太泛化的后缀
- `DataClass`：不说明具体是什么数据

checklists/error-handling.md：

MARKDOWN

# 错误处理检查清单

## 必须检查的场景

### 1. 外部依赖调用
- API 请求（网络失败、超时、4xx/5xx 响应）
- 数据库查询（连接失败、查询超时、约束违反）
- 文件操作（文件不存在、权限不足、磁盘满）

### 2. 用户输入
- 空输入、null、undefined
- 格式不正确
- 超出范围的值

### 3. 数据转换
- JSON 解析（格式错误）
- 类型转换（字符串转数字失败）
- 日期解析（无效日期格式）

## 错误处理模式

**捕获并处理：**
```javascript
try {
  const data = await fetchUser(id);
  return processData(data);
} catch (error) {
  logger.error('Failed to fetch user', { id, error });
  return null; // 或抛出自定义错误
}
```

**检查后调用：**
```javascript
if (!user) {
  throw new Error('User not found');
}
const profile = user.getProfile(); // 安全，user 不是 null
```

## 常见错误

**问题：** 空 catch 块
```javascript
try {
  riskyOperation();
} catch (e) {
  // 什么都不做 - 问题：错误被吞掉了
}
```

**修复：** 至少要记录日志
```javascript
try {
  riskyOperation();
} catch (e) {
  logger.error('Operation failed', e);
  throw e; // 或返回错误状态
}
```

第 5 步：测试复杂场景

准备一段有多个问题的代码：

JAVASCRIPT

function process(data) {
  var result = [];
  for (var i = 0; i < data.length; i++) {
    var item = data[i];
    if (item.type == "A") {
      var x = item.value * 2;
      result.push(x);
    } else if (item.type == "B") {
      var y = item.value / 2;
      result.push(y);
    } else {
      result.push(item.value);
    }
  }
  return result;
}

调用 Skill：

预期输出应该包含：

⚠️ 命名问题：process, data, x, y 都太泛化
⚠️ 使用 var 而不是 const/let
⚠️ 使用 == 而不是 ===
⚠️ 没有检查 data 是否为 null 或不是数组
⚠️ 没有检查 item.value 是否存在
建议：函数可以拆分成更小的纯函数

第 6 步：迭代改进

第一次运行可能会发现：

漏报（有些问题没检测到） → 补充检查规则
输出太冗长 → 调整输出格式，只报告重要问题
误报（把正常代码标记为问题） → 加"需确认"类别

持续改进：

每次审查后，记录哪些问题被漏掉了
更新 checklists
重新测试
一个月后，这个 Skill 会变得相当精准³

小结

代码审查是 Skill 的典型应用场景：步骤固定、可量化、重复性高
用检查清单组织审查流程：代码规范、错误处理、潜在问题、可维护性
supporting files 让 Skill 更易维护：主文件保持简洁，详细规则拆分到独立文件
输出分级很重要：通过、需注意、必须修复，让审查者知道优先级
持续迭代改进：每次审查后补充遗漏的检查项，一个月后会相当精准

下一课，我们学习进阶技巧：personal vs project skills、版本控制、团队协作。

>> 第 6 课：进阶技巧

Anthropic 工程博客：Agent Skills 实战指南 — https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills ↩
Anthropic Platform 文档：Agent Skills 概述 — https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview ↩ ↩²
Claude Code Skills：.NET 工作流与可复用提示 — https://codewithmukesh.com/blog/skills-claude-code/ ↩

Exercises

选择一个你熟悉的领域（前端代码、API 设计、SQL 查询、文档写作），创建一个审查 Skill。

Level 1：创建你自己的审查 Skill

要求：

至少包含 3 个检查维度
每个维度有 3-5 个具体检查项
输出格式清晰（通过、需注意、必须修复）
测试至少 2 个实际案例

Done criteria · checked locally

检查维度明确且有意义每个检查项具体可执行（不是"检查代码质量"这种泛化描述）输出格式让人一眼能看出问题的严重程度测试了真实的代码/文档，并记录了结果

- URL 是否使用名词而不是动词（✓ /users ✗ /getUsers）

1. RESTful 规范

HTTP 方法是否正确（GET 查询、POST 创建、PUT 更新、DELETE 删除）
状态码是否合理（200/201/400/404/500）

- 参数命名是否清晰（用 snake_case 或 camelCase，统一风格）

2. 参数设计

必需参数和可选参数是否明确
参数验证规则是否文档化

- 是否有统一的错误响应格式

3. 错误处理

错误信息是否包含足够的上下文
是否有错误码便于客户端判断

输出格式

- [检查项]

✅ 符合规范

- 问题：[具体问题]

⚠️ 建议改进

建议：[如何改进]

- 问题：[具体问题]

🔴 违反规范

影响：[为什么这是严重问题]
修复：[必须如何改]

选一段代码，分别用：

Level 2：对比人工审查和 Skill 审查

你自己手动审查
用 code-review Skill 审查

对比两者发现的问题，记录：

Skill 发现了哪些你遗漏的问题
你发现了哪些 Skill 遗漏的问题
哪些是误报（Skill 认为是问题但实际不是）

Done criteria · checked locally

同一段代码用两种方式审查了记录了双方发现的问题对比分析了 Skill 的优势和不足提出了改进 Skill 的具体建议

My note

Jot down thoughts, sticking points, things you didn't get. Written to this course's appendix only — the lesson file is never touched.

Also distill into learning memory (so the agent knows me next time)

第 5 课：实战案例：构建代码审查 Skill

为什么选择代码审查作为案例

第 1 步：明确审查范围

第 2 步：创建目录结构

第 3 步：编写主 SKILL.md

第 4 步：编写 supporting files

第 5 步：测试复杂场景

第 6 步：迭代改进

小结

Footnotes

Exercises

选择一个你熟悉的领域（前端代码、API 设计、SQL 查询、文档写作），创建一个审查 Skill。

- URL 是否使用名词而不是动词（✓ /users ✗ /getUsers）

- 参数命名是否清晰（用 snake_case 或 camelCase，统一风格）

- 是否有统一的错误响应格式

输出格式

- [检查项]

- 问题：[具体问题]

- 问题：[具体问题]

选一段代码，分别用：

My note