04 - 代码审查食谱

让 AI 成为你的代码审查搭档，从安全到性能多维度把关。

适用场景

场景	何时使用	典型触发
Diff 审查	功能完成后、提交前	git diff 输出需要逐行审查
安全审查	涉及用户输入、认证、数据操作	新增 API、修改权限逻辑
性能审查	数据量增长或响应变慢	新增数据库查询、大列表渲染
对抗性测试审查	AI 生成代码"看起来完美"时	审查未发现明显问题
方案对比评审	多种实现方案需要抉择	技术选型、架构变更
三会话隔离审查	高风险变更、核心模块重构	涉及认证、支付、数据迁移

---

食谱 1：Diff 审查

场景描述

功能开发完成后，将 git diff 输出交给 AI 逐行审查。最基础、最高频的审查场景，每次提交前都应执行。

核心模板

审查以下 git diff，按严重程度分类报告问题。

## 审查范围
{{diff_output}}

## 项目上下文
- 技术栈：{{技术栈}}
- 本次变更目的：{{变更目的}}

## 审查维度（按优先级）
1. 正确性：逻辑错误、边界条件遗漏、空值未防御
2. 错误处理：异步操作是否有 try/catch、错误是否被吞掉
3. 类型安全：是否有隐式 any、类型断言是否合理
4. 代码规范：命名一致性、函数职责单一、魔法数字

## 输出格式
- 必须修复：安全漏洞、逻辑错误、数据丢失风险
- 建议改进：代码异味、缺失错误处理、可读性问题
- 小建议：命名优化、风格统一
每条包含：文件名:行号、问题描述、修复建议。没有问题就说"审查通过"。

变量说明

变量	说明	示例
{{diff_output}}	git diff 或 git diff main..HEAD 的输出	直接粘贴或用 @ 引用
{{技术栈}}	项目核心技术栈	Next.js 14 + Prisma + TypeScript
{{变更目的}}	本次改动要完成什么	实现用户邮箱验证功能

好坏对比

❌ 坏：审查一下这些代码改动

✅ 好：审查以下 git diff，按严重程度分类报告问题。
   技术栈：Next.js App Router + Prisma。变更目的：新增用户邮箱验证 API。
   重点关注：输入校验、异步错误处理、数据库操作的事务性。
   按 必须修复 / 建议改进 / 小建议 三级输出，每条带文件名和行号。

实战案例

审查 @git diff main..feature/email-verify
技术栈：Next.js 14 + Prisma + NextAuth。变更目的：邮箱验证功能。
重点：token 生成校验逻辑、邮件发送失败处理、token 过期场景、与现有 auth 模块风格一致性。
输出：必须修复 / 建议改进 / 小建议，每条带文件名:行号。

Claude 增强 💡

在 Claude Code 中可直接使用 /review Skill 自动完成 Diff 审查，它会执行 git diff HEAD 并按正确性、安全性、性能、规范四个维度输出。复杂变更建议使用完整模板提供更多上下文。

---

食谱 2：安全审查

场景描述

基于 OWASP Top 10 清单系统检查注入、XSS、认证绕过等风险。适用于涉及用户输入、认证授权、数据操作的代码。

核心模板

对以下代码进行安全专项审查，基于 OWASP Top 10 逐项检查。

## 审查目标
{{代码范围}}

## 项目安全上下文
- 认证方案：{{认证方案}}
- 数据库 ORM：{{ORM}}
- 输入校验库：{{校验库}}

## OWASP Top 10 检查清单（标注 Pass / Fail / N/A）
1. **注入** — SQL/NoSQL/命令注入，是否参数化查询
2. **认证失效** — 密码存储、session 安全、登录频率限制
3. **敏感数据泄露** — API 响应多余字段、日志中的敏感信息、错误信息泄露内部细节
4. **XSS** — 用户输入转义、dangerouslySetInnerHTML、URL 参数校验
5. **访问控制** — 权限校验、IDOR（修改 ID 越权）、文件上传限制
6. **安全配置** — CORS 宽松度、环境变量硬编码、生产环境调试模式
7. **依赖漏洞** — npm audit 告警、已知 CVE、过时大版本依赖
8. **敏感数据日志** — 日志中是否泄露 token、密码、PII（个人身份信息）
9. **加密合规** — 密码哈希（bcrypt/argon2）、传输 TLS、静态数据加密

## 输出格式
| # | OWASP 项 | 状态 | 发现 | 修复建议 |
按风险从高到低排列。

变量说明

变量	说明	示例
{{代码范围}}	要审查的文件或 diff	@app/api/auth/ 或 git diff 输出
{{认证方案}}	认证方案	NextAuth.js + JWT
{{ORM}}	数据库访问方式	Prisma / 原生 SQL
{{校验库}}	输入校验方案	zod / joi / 无

好坏对比

❌ 坏：检查一下这段代码有没有安全问题

✅ 好：对 @app/api/auth/ 进行安全专项审查，基于 OWASP Top 10 逐项检查。
   项目使用 NextAuth.js + Prisma + zod。
   重点：注入风险、认证绕过、敏感数据泄露、IDOR。
   输出表格，每项标注 Pass / Fail / N/A，Fail 项附修复建议。

实战案例

安全审查 @app/api/users/[id]/route.ts @app/api/auth/login/route.ts @lib/auth.ts
认证：NextAuth.js + JWT。ORM：Prisma。校验：zod。
重点：login 频率限制、users/[id] 的 IDOR 风险、JWT 过期时间、响应中是否含 passwordHash。

Claude 增强 💡

安全审查建议在独立会话中进行，避免"确认偏差"——AI 刚写完的代码，同一会话审查容易"护短"。

---

食谱 3：性能审查

场景描述

识别数据库 N+1 查询、不必要的重复渲染、缺失分页等性能瓶颈。适用于数据量增长或响应变慢时的针对性排查。

核心模板

对以下代码进行性能审查，识别潜在瓶颈。

## 审查目标
{{代码范围}}

## 性能上下文
- 预期数据量：{{数据规模}}
- 当前表现：{{当前表现}}
- 部署环境：{{部署环境}}

## 检查维度
数据库层：N+1 查询、缺失索引、SELECT *、缺失分页、长事务锁行
前端层：缺少 memo/useMemo、大列表无虚拟滚动、图片未 lazy load、大依赖未 tree-shake
API 层：响应体冗余字段、缺缓存策略、可并行请求却串行、缺失 gzip 压缩

## 输出格式
每个问题：位置（文件:行号）、问题描述、复杂度（O 记号）、优化方案、预期收益（高/中/低）

变量说明

变量	说明	示例
{{代码范围}}	要审查的文件或模块	@services/order.service.ts
{{数据规模}}	当前和预期数据量	当前 1000 条，预期 10 万
{{当前表现}}	已知性能问题	订单列表 API 响应 > 2s
{{部署环境}}	服务器和数据库配置	Vercel Serverless + PlanetScale

好坏对比

❌ 坏：这段代码性能怎么样？

✅ 好：对 @services/order.service.ts 进行性能审查。
   订单量 1000→10 万，列表 API 响应 > 2s，目标 < 500ms。
   重点：N+1 查询、缺失分页、索引使用。每个问题标注复杂度和收益。

实战案例

性能审查 @services/order.service.ts @app/api/orders/route.ts @components/OrderList.tsx
数据量：1000→10万订单。部署：Vercel + PlanetScale（连接池 10）。
现象：列表页 > 3s，滚动卡顿。
重点：getOrders 是否 N+1、OrderList 是否缺 memo、是否有分页。

Claude 增强 💡

Claude Code 中可结合实测数据：先 curl -w "\n%{time_total}s" 测响应时间，再审查瓶颈，优化后重测对比，形成闭环。

---

食谱 4：对抗性测试审查

场景描述

以攻击者视角挑战 AI 生成的代码，找出所有可能导致崩溃、数据丢失或安全漏洞的边界场景。克服"确认偏差"的关键手段。

核心模板

请尝试打破以下代码。找到所有可能导致崩溃、数据丢失或安全漏洞的场景。

## 目标代码
{{代码范围}}

## 功能描述
{{功能描述}}

## 攻击维度
1. 边界输入：空值、超长字符串、特殊字符、Unicode、负数、零、MAX_INT
2. 并发场景：同一用户并发请求、竞态条件、双重提交
3. 状态异常：数据库断连、外部 API 超时、磁盘满、网络抖动
4. 权限绕过：未登录访问、篡改 userId、越权操作、伪造 token
5. 数据一致性：操作半途失败，数据是否处于中间状态
6. 资源耗尽：超大文件上传、无限循环、内存耗尽、连接池打满

## 输出格式
每个漏洞：攻击向量、影响（崩溃/数据丢失/泄露/拒绝服务）、严重程度、复现步骤、修复建议。
不要客气，越狠越好。找不到问题也如实说。

变量说明

变量	说明	示例
{{代码范围}}	要攻击的代码	@app/api/upload/route.ts
{{功能描述}}	功能简述	用户头像上传，jpg/png，限 5MB

好坏对比

❌ 坏：这段代码有什么问题吗？

✅ 好：请打破 @app/api/upload/route.ts（头像上传，jpg/png，5MB）。
   攻击：畸形文件、超大文件、并发上传、路径穿越、MIME 伪造。
   每个漏洞给出复现 curl 命令和修复建议。越狠越好。

实战案例

打破 @app/api/upload/route.ts @lib/storage.ts
功能：头像上传，multipart/form-data，jpg/png，5MB，存 S3。
攻击：1) .exe 伪装 image/jpeg 2) 10GB 文件 OOM 3) 文件名 ../../../etc/passwd
4) 1s 内 100 次上传 5) 上传成功写 DB 失败→孤儿文件 6) Content-Length 伪造
每个给复现 curl 和预期后果。

Claude 增强 💡

建议在独立会话中做对抗测试。可链式执行：对抗测试→按严重程度修复→重新攻击确认→跑测试防回归。每个漏洞都应转化为测试用例永久保留。

---

食谱 5：方案对比评审

场景描述

多种实现方案时用结构化维度对比分析，避免凭直觉选择。适用于技术选型、架构变更等需要客观决策的场景。

核心模板

对比以下实现方案，帮我做出技术决策。

## 问题背景
{{问题描述}}

## 候选方案
### 方案 A：{{方案A名称}}
{{方案A描述}}

### 方案 B：{{方案B名称}}
{{方案B描述}}

## 对比维度
| 维度 | 权重 | 说明 |
|------|------|------|
| 正确性 | 高 | 是否能完整解决问题 |
| 实现复杂度 | 高 | 开发时间和代码量 |
| 维护成本 | 中 | 半年后修改的难度 |
| 性能 | {{性能权重}} | 响应时间、资源消耗 |
| 可测试性 | 中 | 是否容易写测试 |
| AI 友好度 | 中 | AI 辅助开发时是否容易出错 |

## 输出格式
1. 对比表格（每个维度打分 1-5）
2. 各方案优缺点（不要和稀泥）
3. 明确推荐一个方案 + 理由
4. 推荐方案的风险点和缓解措施

变量说明

变量	说明	示例
{{问题描述}}	要解决的问题	订单状态管理，需支持复杂状态流转
{{方案A名称}}	方案名称	XState 状态机
{{方案A描述}}	方案概要或代码片段	描述思路或贴代码
{{方案B名称}}	方案名称	switch-case + 转换表
{{方案B描述}}	方案概要或代码片段	描述思路或贴代码
{{性能权重}}	性能重要度	高 / 中 / 低

好坏对比

❌ 坏：XState 和手写 switch 哪个好？

✅ 好：对比订单状态管理：A) XState 状态机，声明式 + 可视化；B) switch-case + 转换表，零依赖。
   维度：正确性、复杂度、维护成本、可测试性、AI 友好度。每维度打分 1-5，明确推荐。

实战案例

对比实时通知方案。用户量 500→5000，部署在 Vercel。
A) WebSocket（Socket.io）：全双工，需维护连接状态
B) SSE（Server-Sent Events）：单向推送，基于 HTTP，实现简单
C) Polling（5s 间隔）：最简单，实时性差
维度权重：实时性（高）、实现复杂度（高）、Serverless 兼容性（高）、维护成本（中）。

Claude 增强 💡

可链式执行：方案对比→为推荐方案写最小 PoC（< 50 行）→将决策记录为 ADR。技术决策留下文档痕迹，半年后不忘"当时为什么选了这个"。

---

食谱 6：三会话隔离审查

场景描述

本项目方法论的核心审查模式（参考 doc-10 可靠性保障体系）。实现、审查、仲裁分别在三个独立 AI 会话中进行，通过信息隔离打破"确认偏差"。AI 在同一会话中既写代码又审查，会不自觉地"护短"忽略问题。

工作流程

会话 1：实现者 → 完成功能，提交到 feature 分支
        │ git diff main..feature/xxx
        ▼
会话 2：审查者（全新会话）→ 只看 diff，以资深开发者角度找问题
        │ 实现者不同意审查意见时
        ▼
会话 3：仲裁者（全新会话）→ 看 diff + 审查意见 + 反驳，做最终裁决

核心模板

会话 2 - 审查者模板：

你是资深开发者，审查一个同事提交的代码变更。你没有参与实现。

## 变更内容
{{diff_output}}

## 项目上下文
- 技术栈：{{技术栈}}
- 变更目的：{{变更目的}}
- 项目规范：{{规范文件路径}}

## 审查要求
1. 质疑每一个不明显的决定（你不知道实现者的思路）
2. 重点：是否有更简单的实现、边界条件是否完整、错误路径是否遗漏、不必要的复杂度
3. 分类：必须修复 / 建议改进 / 疑问（需实现者解释）
4. 每条给出具体改进建议，不要只说"有问题"

客观审查，不要因为代码整洁就放松标准。

会话 3 - 仲裁者模板（仅争议时用）：

你是技术仲裁者，裁决一段代码变更的审查争议。

## 代码变更
{{diff_output}}

## 审查者意见
{{审查意见}}

## 实现者反驳
{{实现者反驳}}

## 仲裁要求
1. 逐条分析，判断谁的理由更充分
2. 每条明确结论：采纳审查意见 / 维持现状 / 折中方案
3. 最终行动清单：必须改 / 可不改 / 待讨论
4. 发现双方都没注意到的问题也要指出

变量说明

变量	说明	示例
{{diff_output}}	git diff main..feature/xxx	完整 diff 输出
{{技术栈}}	项目技术栈	Next.js 14 + Prisma
{{变更目的}}	变更需求描述	实现支付回调处理
{{规范文件路径}}	项目规范文件	@CLAUDE.md
{{审查意见}}	会话 2 的输出	从审查会话复制
{{实现者反驳}}	对审查意见的回应	逐条回应理由

好坏对比

❌ 坏：（同一实现会话中）审查一下刚才写的代码

✅ 好：（新开全新会话）你是资深开发者，审查同事提交的代码，你没参与实现。
   @git diff main..feature/payment-callback
   变更目的：支付回调处理。技术栈：Next.js + Prisma。
   质疑每个不明显的决定，按三级分类输出。

实战案例

步骤 1（实现会话完成后）：
  git diff main..feature/payment-callback

步骤 2（新开审查会话）：
  审查 @git diff main..feature/payment-callback
  技术栈：Next.js 14 + Prisma + Stripe。目的：Stripe Webhook 处理。规范：@CLAUDE.md
  重点：签名验证、幂等性、事务性（付款成功但更新订单失败）、错误日志
  找问题，不要因为代码完整就放松。

步骤 3（争议时新开仲裁会话）：
  审查者要求加幂等性键去重；实现者认为用 Stripe event ID + 数据库唯一约束即可。
  请仲裁，考虑复杂度和可靠性。

Claude 增强 💡

在不同终端窗口开三个 claude 会话，每个命令启动独立会话，上下文完全隔离：

# Terminal 1 — implementation (done)
# Terminal 2 — review (paste reviewer template)
# Terminal 3 — arbitration (only if disagreement)

高风险模块（认证、支付、数据迁移）强烈建议三会话模式，日常改动用食谱 1 即可。 进一步强化：可在审查会话中引入 Codex MCP 做异构复审，获取跨模型族视角（详见 doc-05 §4.3 Codex MCP）。

---

组合技巧

渐进式审查流水线

Level 1: Diff 审查（每次提交）→ 通过则提交
Level 2: 安全 + 性能审查（敏感变更时）→ 通过则提交
Level 3: 对抗测试（代码"太完美"时）→ 通过则提交
Level 4: 三会话隔离（核心模块变更）→ 通过则提交

审查→测试联动

审查发现的"必须修复"项→转化为测试用例→修复后测试变绿→永久保留（回归保护）。审查发现的问题不应该只修一次，要用测试锁住。

审查清单固化

反复出现的同类问题→写入 CLAUDE.md 的 MUST/NEVER 规则→AI 自动遵守→减少审查负担：

MUST: validate all user input with zod schema before processing
NEVER: return passwordHash or internal IDs in API responses

方案对比 + 三会话隔离

重大技术决策：会话 1 分析推荐→会话 2 审查合理性→会话 3 仲裁（仅分歧时）。

---

相关资源

• doc-10 可靠性保障体系 — 三会话隔离设计背景
• doc-15 Prompt 工程实战 — 进阶技巧与个人积累
• /review Skill — Claude Code 中的自动审查指令
• 03-测试验证食谱 | 05-调试排错食谱