Claude 代码审查不好用？试试这个我花了一周优化的 Skill

从 1774 行到 178 行：我如何重构一个 Claude Code Skill

起因

用 Claude Code 做代码审查，总觉得差点意思。

它能指出明显的 bug，也能给一些重构建议，但给的反馈太泛了------缺少系统化的审查流程，没有语言特定的深度检查，更别说什么"给建设性反馈的技巧"。

后来发现 marketplace 上有个 code-review-excellence skill，装上试了试，确实专业多了。但翻开源码一看：一个 SKILL.md 文件，1774 行。

这就有问题了。

问题在哪

Claude Code Skills 有个设计叫 Progressive Disclosure（渐进式加载）：

未激活时：只加载 skill 的 name + description（几十个 token）
激活时：加载完整的 SKILL.md

一个 1774 行的文件，一激活就是 15000+ tokens。如果我只是审查一段 Python 代码，却把 React 19 Server Components、Vue 3.5 defineModel、Rust Cancellation Safety 全加载进来------这不是浪费是什么？

更关键的是，这 1774 行里还引用了 references/ 和 assets/ 目录下的文件，但这些文件根本不存在。

重构思路

核心目标：把一个巨型文件拆成按需加载的模块化架构。

makefile 复制代码

重构前:
SKILL.md (1774 行，全量加载)

重构后:
SKILL.md (~180 行，核心内容，始终加载)
├── reference/
│   ├── react.md (~870 行，审查 React 时加载)
│   ├── vue.md (~920 行，审查 Vue 时加载)
│   ├── rust.md (~840 行，审查 Rust 时加载)
│   ├── typescript.md (~540 行，审查 TS 时加载)
│   └── python.md (~1070 行，审查 Python 时加载)
├── assets/
│   ├── pr-review-template.md (PR 审查模板)
│   └── review-checklist.md (快速检查清单)
└── scripts/
    └── pr-analyzer.py (PR 复杂度分析脚本)

总内容从 ~1774 行扩展到 ~6000 行，但 SKILL.md 反而缩减到 180 行。

这就是 Progressive Disclosure 的精髓：核心精炼，细节按需。

SKILL.md 怎么写

Frontmatter 规范

yaml 复制代码

---
name: code-review-excellence
description: |
  Provides comprehensive code review guidance for React 19, Vue 3, Rust, TypeScript, and Python.
  Helps catch bugs, improve code quality, and give constructive feedback.
  Use when: reviewing pull requests, conducting PR reviews, code review, reviewing code changes,
  establishing review standards, mentoring developers, architecture reviews, security audits,
  checking code quality, finding bugs, giving feedback on code.
allowed-tools:
  - Read
  - Grep
  - Glob
---

几个要点：

name 必须是 kebab-case，且与目录名一致
description 要包含触发词，"Use when:" 后面列出使用场景
allowed-tools 可选，预批准的工具列表，减少确认弹窗

触发词的重要性

description 里的触发词决定了 skill 何时被激活。写得太窄，很多场景触发不了；写得太宽，容易误触发。

yaml 复制代码

# ❌ 太窄
description: Use when reviewing pull requests

# ✅ 覆盖多种表达方式
description: |
  Use when: reviewing pull requests, conducting PR reviews, code review,
  reviewing code changes, establishing review standards, mentoring developers,
  architecture reviews, security audits, checking code quality, finding bugs

用户说"帮我 review 这段代码"、"检查下这个 PR"、"审查下安全性"都能触发。

内容组织

SKILL.md 只放"必须知道"的内容：

ini 复制代码

# Code Review Excellence

## When to Use This Skill
- Reviewing pull requests and code changes
- Establishing code review standards for teams
- ...

## Core Principles
[审查的核心原则，简明扼要]

## Review Process
[4 阶段审查流程：Context → High-Level → Line-by-Line → Summary]

## Language-Specific Guides
| Language | Reference File | Key Topics |
|----------|----------------|------------|
| React | [React Guide](reference/react.md) | Hooks, React 19 Actions, RSC |
| Vue 3 | [Vue Guide](reference/vue.md) | Composition API, Vue 3.5 特性 |
| ...

详细的语言特定内容，通过 Markdown 链接引用 reference/ 目录下的文件。

关键点 ：使用 [React Guide](reference/react.md) 这种 Markdown 链接格式，而不是 reference/react.md 反引号格式。前者能被 Claude Code 识别并按需加载。

Reference 文件怎么写

以 reference/react.md 为例，专注于 React 代码审查的深度内容：

scss 复制代码

# React 代码审查指南

> React 审查重点：Hooks 规则、性能优化的适度性、组件设计、以及现代 React 19/RSC 模式。

## 目录
- [Hooks 规则与常见错误](#hooks-规则与常见错误)
- [useEffect 深度审查](#useeffect-深度审查)
- [React 19 Actions & Forms](#react-19-actions--forms)
- [Server Components](#server-components)
- [TanStack Query v5](#tanstack-query-v5)

## Hooks 规则与常见错误

### 条件调用 Hooks

```tsx
// ❌ 条件调用 Hooks --- 违反 Hooks 规则
function BadComponent({ show }) {
  if (show) {
    const [value, setValue] = useState(0);  // Error!
  }
  return <div>...</div>;
}

// ✅ Hooks 必须在顶层无条件调用
function GoodComponent({ show }) {
  const [value, setValue] = useState(0);
  if (!show) return null;
  return <div>{value}</div>;
}

更多内容...

markdown 复制代码


每个 reference 文件都有：
1. 开头的定位说明（这个文件是干什么的）
2. 清晰的目录结构
3. 大量的 ✅ / ❌ 对比示例
4. 审查清单（Checklist）

## Token 开销对比

重构前后的 token 开销变化：

重构前：

激活 skill: ~15000 tokens（全量加载）

重构后：

激活 skill: ~1500 tokens（仅 SKILL.md）
审查 React 代码: +7000 tokens（加载 react.md）
审查 Python 代码: +8500 tokens（加载 python.md）
审查 Vue 代码: +7500 tokens（加载 vue.md）

shell 复制代码


如果我只审查 Python 代码，现在只需要 ~10000 tokens，而不是之前的 15000 tokens。

更重要的是，这 6000 行的内容比原来 1774 行**更深入**------每个语言都有完整的审查指南，而不是蜻蜓点水。

## 实际效果

### 没有 Skill 时

问：审查这段代码的安全性

Claude：这段代码看起来有几个潜在问题... [泛泛的建议，缺少系统性]

shell 复制代码


### 有 Skill 后

问：审查这段代码的安全性

Claude：

安全审查报告

🔴 严重问题 (Blocking)

SQL 注入风险 - 第 23 行直接拼接用户输入

建议使用参数化查询：cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))

🟡 重要改进 (Important)

缺少输入验证 - user_id 未校验类型和范围

安全检查清单

参数化查询
输入验证
错误信息脱敏 ...

yaml 复制代码


结构化、可执行、有优先级。这才是专业的代码审查。

---

## code-review-skill：一个真正可用的代码审查 Skill

经过多轮迭代，这个 skill 已经从最初的"修复别人的 bug"变成了一个**完整的代码审查解决方案**。

### 为什么用这个 Skill

| 痛点 | 原生 Claude | 使用 code-review-skill |
|------|------------|----------------------|
| 审查流程 | 想到哪说哪 | 4 阶段系统化流程 |
| 问题分级 | 混在一起 | 🔴 Blocking / 🟡 Important / 🟢 Nit |
| 语言深度 | 泛泛而谈 | 框架特定的最佳实践和陷阱 |
| 反馈方式 | 直接指出问题 | 提问式引导 + 建设性建议 |
| 版本覆盖 | 可能过时 | React 19、Vue 3.5、TanStack Query v5 |

### 支持的语言和框架

┌─────────────────────────────────────────────────────────────┐ │ Language/Framework Version Key Topics │ ├─────────────────────────────────────────────────────────────┤ │ React 18.x, 19.x Hooks, Actions, │ │ RSC, Suspense │ ├─────────────────────────────────────────────────────────────┤ │ Vue 3.4+, 3.5+ Composition API,│ │ defineModel, │ │ useTemplateRef │ ├─────────────────────────────────────────────────────────────┤ │ TanStack Query v5.x useSuspenseQuery│ │ Optimistic UI │ ├─────────────────────────────────────────────────────────────┤ │ TypeScript 5.x Generics, Strict│ │ Mode, ESLint │ ├─────────────────────────────────────────────────────────────┤ │ Python 3.10+ async/await, │ │ typing, pytest │ ├─────────────────────────────────────────────────────────────┤ │ Rust 2021 Edition Ownership, Async│ │ Cancellation │ │ Safety │ └─────────────────────────────────────────────────────────────┘

scss 复制代码


每个语言都有独立的深度指南，不是简单的 checklist，而是**真正能帮你发现问题的审查要点**。

### 特色功能

**1. React 19 Actions 完整指南**

```tsx
// skill 会帮你识别这种错误：
const [state, action] = useActionState(async (prev, formData) => {
  setSomeState(newValue);  // ❌ 不应该在 Action 中 setState
}, initialState);

// 并建议正确做法：
const [state, action] = useActionState(async (prev, formData) => {
  const result = await submitForm(formData);
  return { ...prev, data: result };  // ✅ 返回新状态
}, initialState);

2. Vue 3.5 新特性审查

xml 复制代码

<!-- skill 知道 Vue 3.5 的 Reactive Props Destructure -->
<script setup>
// Vue 3.5 之前：这样会丢失响应性
const { count } = defineProps<{ count: number }>()

// Vue 3.5+：skill 会告诉你这样是安全的
const { count } = defineProps<{ count: number }>()  // ✅ 保持响应性
</script>

3. Rust Cancellation Safety

rust 复制代码

// skill 会识别取消不安全的代码：
async fn not_cancel_safe(conn: &mut Connection) -> Result<()> {
    let data = read_data().await?;           // 如果这里被取消
    conn.write_data(data).await?;            // 数据可能部分写入
    conn.send_ack().await?;
    Ok(())
}

// 并解释为什么这是问题，以及如何修复

4. TanStack Query v5 最佳实践

包括 useSuspenseQuery 的限制（不支持 enabled、placeholderData）、乐观更新的正确姿势、queryKey 设计等。

5. PR 复杂度分析脚本

bash 复制代码

git diff main...HEAD | python scripts/pr-analyzer.py

# 输出：
# ============================================================
# PR ANALYSIS REPORT
# ============================================================
# 📊 SUMMARY
#    Files changed: 12
#    Additions: +450
#    Deletions: -120
#    Total changes: 570
#
# 📏 SIZE: M (Medium)
#    Complexity score: 0.45/1.0
#    Estimated review time: ~25 minutes
#
# ⚠️  RISK FACTORS:
#    • Security-sensitive file: src/auth/jwt.ts
#    • Low test ratio (<20%) - consider adding more tests
#
# 💡 SUGGESTIONS:
#    • Check for proper type usage (avoid 'any')

安装方法

方式 1：直接克隆（推荐）

bash 复制代码

# 克隆到 skills 目录
git clone https://github.com/tt-a1i/code-review-skill.git ~/.claude/skills/code-review-excellence

# 验证安装
ls ~/.claude/skills/code-review-excellence/SKILL.md

方式 2：作为符号链接

bash 复制代码

# 克隆到任意位置
git clone https://github.com/tt-a1i/code-review-skill.git ~/projects/code-review-skill

# 创建符号链接
ln -sf ~/projects/code-review-skill ~/.claude/skills/code-review-excellence

方式 3：项目级安装

bash 复制代码

# 在项目根目录
mkdir -p .claude/skills
git clone https://github.com/tt-a1i/code-review-skill.git .claude/skills/code-review-excellence

# 提交到项目仓库，团队共享
git add .claude/
git commit -m "Add code-review-excellence skill"

使用场景

安装后，这些场景会自动触发 skill：

arduino 复制代码

✅ "帮我审查这段代码"
✅ "review 这个 PR"
✅ "检查下有没有安全问题"
✅ "这段代码有什么问题"
✅ "帮我 code review"
✅ "看看这个函数写得怎么样"
✅ "给些改进建议"

与其他 Skill 的区别

市面上也有其他代码审查相关的 skill，这个有什么不同？

特性	其他 Skills	code-review-skill
架构	单文件 1000+ 行	Progressive Disclosure
内容深度	通用建议	框架特定深度指南
版本更新	可能滞后	React 19 / Vue 3.5 / TQ v5
资源文件	通常缺失	完整的 reference + assets
Token 效率	全量加载	按需加载
可维护性	难以更新	模块化，易于迭代

开发过程中的坑

1. 目录名是 reference/ 不是 references/

最初照着其他 skill 写，用了 references/（带 s）。结果 Claude Code 找不到文件。

翻了官方规范才发现，标准目录名是 reference/（不带 s）。

2. 文件引用格式

bash 复制代码

# ❌ 错误：反引号格式
See `reference/react.md` for details.

# ✅ 正确：Markdown 链接格式
See [React Guide](reference/react.md) for details.

反引号只是展示路径，不会触发加载。Markdown 链接才是按需加载的触发器。

3. Frontmatter 的 allowed-tools

这个字段是可选的，但加上后体验更好：

markdown 复制代码

allowed-tools:
  - Read
  - Grep
  - Glob

这些工具会被预批准，Claude 读取代码时不用反复确认权限。

源码

完整实现在 GitHub：tt-a1i/code-review-skill

目录结构：

bash 复制代码

code-review-skill/
├── SKILL.md              # 核心文件 (~180 行)
├── reference/            # 深度指南 (按需加载)
│   ├── react.md          # React 19 + TanStack Query v5
│   ├── vue.md            # Vue 3.5 + Composition API
│   ├── rust.md           # 所有权、async、Cancellation Safety
│   ├── typescript.md     # 泛型、strict 模式
│   ├── python.md         # 类型注解、async/await、pytest
│   ├── common-bugs-checklist.md
│   ├── security-review-guide.md
│   └── code-review-best-practices.md
├── assets/               # 模板文件
│   ├── pr-review-template.md
│   └── review-checklist.md
├── scripts/              # 工具脚本
│   └── pr-analyzer.py    # PR 复杂度分析
├── README.md
├── CONTRIBUTING.md       # Skill 开发规范
└── LICENSE

总结

重构这个 skill 的过程，让我对 Claude Code Skills 的设计有了更深的理解：

Progressive Disclosure 不是口号------它是实实在在的 token 优化策略
SKILL.md 要精炼------控制在 200 行以内，只放必须知道的内容
深度内容放 reference/ ------按需加载，用 Markdown 链接引用
触发词要全面------覆盖用户的各种表达方式
实际内容要深入------既然是按需加载，就不用吝啬内容深度

一个设计良好的 skill，应该是"激活成本低、使用价值高"。

希望这篇文章能帮到也想开发 Claude Code Skill 的你。

Claude 代码审查不好用？试试这个我花了一周优化的 Skill

从 1774 行到 178 行：我如何重构一个 Claude Code Skill

起因

问题在哪

重构思路

SKILL.md 怎么写

Frontmatter 规范

触发词的重要性

内容组织

Reference 文件怎么写

安全审查报告

🔴 严重问题 (Blocking)

🟡 重要改进 (Important)

安全检查清单

安装方法

使用场景

与其他 Skill 的区别

开发过程中的坑

1. 目录名是 reference/ 不是 references/

2. 文件引用格式

3. Frontmatter 的 allowed-tools

源码

总结

相关资源