Claude Code 代码审查清单: 团队风险分级 PR Review

不要只说“帮我 Review 一下”

把差异贴给 Claude Code，然后只说“review this PR”，通常会得到一些有用但很泛的建议。

团队真正需要的是风险判断: 哪些数据会被碰到，失败会影响谁，测试证据在哪里，哪些问题必须在 merge 前阻止。

这篇文章给出一套可以复制使用的代码审查清单、Claude Code review prompt、GitHub PR 模板，以及一个用 GitHub Actions 执行的 CI 守卫。

Claude Code 不是替代 reviewer 的工具。它更像第二双眼睛，用来减少遗漏，让团队的 review 口径更稳定。官方资料建议同时参考 Claude Code 的代码审查设置说明、Claude Code GitHub Actions 文档、GitHub 的PR 模板文档、protected branches和Actions workflows。安全部分可以用OWASP Secure Code Review Cheat Sheet作为基准。

什么是风险分级 Review

风险分级 review 的意思是，不要用同一个流程审查所有 PR。文案修改、样式调整、支付 webhook、数据库迁移，这些变更失败后的影响完全不同。如果全部用重流程，小改动会被拖慢；如果全部用轻流程，真正危险的改动会被放过。

可以先用三个等级:

风险	例子	必需 review
Low	文案、简单 CSS、文档、无害日志文案	1 人 review，说明差异或附截图
Medium	表单、UI 状态、搜索、API response shape、只读数据访问	1 人 review，测试证据，Claude Code review
High	认证、授权、计费、个人数据、migration、删除、webhook	2 人 review，rollback plan，必需 CI，安全/隐私 review

这里的 migration 指数据库结构或数据形状的变更。代码通常可以 revert，但删除的列、重写的数据、失败的 backfill 不一定能轻松恢复。因此 migration review 应先问“能不能回滚”，再看代码是否优雅。

给 Claude Code review 时，必须明确风险等级。模糊的请求会让它偏向命名、格式、可读性这种通用建议。明确说“High risk: billing webhook and customer email changed”，它更容易检查签名验证、幂等性、重试、隐私日志和测试证据。

Masa 的团队经验是，只有“质量”“安全”“可维护性”这些抽象词还不够。它们适合做标题，不适合做问题。好的 PR 模板应该要求作者写清文件、数据类型、风险原因、测试证据和 rollback 步骤。

可复制的 Review Checklist

下面可以放到 .github/review-checklist.md、团队 Wiki 或 CLAUDE.md 的 review 章节。清单故意写得具体，是为了让人和 Claude Code 都能检查事实，而不是检查态度。

# Code Review Checklist

## 0. PR scope
- [ ] This PR has one clear purpose.
- [ ] Changed files match the stated purpose.
- [ ] Generated or AI-written files are marked in the PR description.
- [ ] No unrelated formatting, dependency, or config changes are mixed in.

## 1. Risk level
- [ ] Risk level is marked as low, medium, or high.
- [ ] High-risk PRs have two human reviewers.
- [ ] High-risk PRs include rollback or recovery steps.

## 2. Security and privacy
- [ ] User input is validated on the server side.
- [ ] Authorization is checked near the data access point.
- [ ] Secrets are not printed, committed, or sent to Claude prompts.
- [ ] Logs do not include email, tokens, addresses, payment IDs, or private content.
- [ ] OWASP-relevant risks such as injection, XSS, broken access control, and SSRF were considered.

## 3. Tests
- [ ] Unit or integration tests cover the changed behavior.
- [ ] Regression tests cover the bug that motivated the PR.
- [ ] Manual verification steps are written with actual result, not "works locally".
- [ ] Snapshot changes are explained.

## 4. Performance
- [ ] New loops, queries, and network calls are bounded.
- [ ] N+1 queries were checked.
- [ ] Large lists, images, and bundles have a budget.
- [ ] Metrics or before/after evidence are attached for performance-sensitive changes.

## 5. Accessibility
- [ ] Keyboard operation works for interactive UI.
- [ ] Focus order and visible focus state are preserved.
- [ ] Form fields have labels and errors that screen readers can understand.
- [ ] Color contrast and reduced-motion behavior are checked where relevant.

## 6. Migration and data risk
- [ ] Migration is backward compatible during rollout.
- [ ] Destructive changes have backup or recovery steps.
- [ ] Old and new app versions can run during deployment.
- [ ] Data cleanup jobs are idempotent.

## 7. AI-generated diff hygiene
- [ ] AI-generated code was read by a human before approval.
- [ ] The diff does not remove tests, monitoring, analytics, or CTA links by accident.
- [ ] New dependencies are justified.
- [ ] Comments do not claim verification that was not actually done.

重点是每一项都能验证。“考虑过安全”太弱；“日志里没有 email、token、地址、payment ID、私有内容”才可以检查。“无障碍没问题”也太弱；“键盘可操作、focus 可见、错误信息可被读屏理解”才适合 review。

Claude Code 审查提示词

Claude Code 的 prompt 要包含角色、风险、上下文和限制。最重要的限制是先输出 findings，不要直接改代码。否则 review 和 implementation 混在一起，diff 会越来越大，团队也难判断哪些问题是真正必须修的。

You are reviewing a pull request for a production team.

Goal:
- Find concrete risks before merge.
- Prioritize correctness, security/privacy, tests, performance, accessibility, migration/data risk, and AI-generated diff hygiene.
- Do not rewrite code yet. Produce review findings first.

Context:
- Risk level: <low | medium | high>
- Business area: <auth | billing | content | search | admin | analytics | other>
- Sensitive data touched: <none | email | payment | address | health | private content | other>
- Rollout plan: <flag | migration | immediate deploy | other>

Review method:
1. Read the PR summary and changed files.
2. List the top risks by severity.
3. For each finding, include file, line or function, why it matters, and a minimal fix.
4. Separate "must fix before merge" from "follow-up".
5. Check whether tests prove the changed behavior.
6. Check whether any AI-generated code, dependency, config, or formatting change is unrelated to the PR goal.

Output format:
- Findings first, ordered by severity.
- Then missing evidence.
- Then questions for the author.
- Then a short merge recommendation: block, approve with fixes, or approve.

它和代码库导航、测试策略配合很好。正式 review 前，可以先让 Claude Code 用三分钟解释这个 PR 触碰的业务域。这样 review 不容易只停留在命名和格式。

GitHub PR 模板

在仓库中放 .github/pull_request_template.md 后，GitHub 会在创建 PR 时自动填入模板。模板的目标不是增加文书工作，而是把 reviewer、Claude Code、CI 都需要的证据放在同一个地方。

## Summary
- TODO

## Risk
Risk level: low | medium | high

Risk reasons:
- Data touched:
- Users affected:
- Rollout:

## Review focus
- [ ] Correctness
- [ ] Security/privacy
- [ ] Tests
- [ ] Performance
- [ ] Accessibility
- [ ] Migration/data risk
- [ ] AI-generated diff hygiene

## Test evidence
- Automated:
- Manual:
- Not tested because:

## Security and privacy notes
- Secrets changed: no | yes
- Personal data in logs: no | yes
- Authorization boundary changed: no | yes

## Migration / rollback
- Migration included: no | yes
- Backward compatible: no | yes | not applicable
- Rollback plan:

## Claude Code review prompt
Paste this into Claude Code after the PR is ready:

Review this PR as risk level "<low|medium|high>".
Focus on correctness, security/privacy, tests, performance, accessibility, migration/data risk, and AI-generated diff hygiene.
Return findings first with file/function references and minimal fixes.

不要只堆 checkbox。太多 checkbox 会让大家机械打勾。Risk reasons、Test evidence、Rollback plan 这类字段必须写证据，也方便后续用 CI 守卫检查。

GitHub Actions CI 守卫

下面的 workflow 和 Node script 会检查 PR body 与变更文件。它不能证明代码正确，但可以在 reviewer 开始读代码前拦住“没有风险等级、没有测试证据、没有 rollback plan”的 PR。

name: PR review guard

on:
  pull_request:
    types: [opened, edited, synchronize, reopened, ready_for_review]

permissions:
  contents: read
  pull-requests: read

jobs:
  review-guard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Check PR review evidence
        run: node scripts/pr-review-guard.mjs
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}

import { execSync } from "node:child_process";
import { readFileSync } from "node:fs";

const eventPath = process.env.GITHUB_EVENT_PATH;
if (!eventPath) throw new Error("GITHUB_EVENT_PATH is missing.");

const event = JSON.parse(readFileSync(eventPath, "utf8"));
const pr = event.pull_request;
const body = pr?.body ?? "";
const base = process.env.BASE_SHA ?? pr?.base?.sha;
const head = process.env.HEAD_SHA ?? pr?.head?.sha;

function safeRef(value, name) {
  if (!value || !/^[a-f0-9]{40}$/i.test(value)) throw new Error(`${name} must be a full git SHA.`);
  return value;
}

const changedFiles = execSync(`git diff --name-only ${safeRef(base, "BASE_SHA")} ${safeRef(head, "HEAD_SHA")}`, {
  encoding: "utf8",
}).split(/\r?\n/).filter(Boolean);

const hasRisk = /Risk level:\s*(low|medium|high)/i.test(body);
const hasTests = /## Test evidence[\s\S]*(Automated|Manual):\s*\S/i.test(body);
const hasRollback = /Rollback plan:\s*\S/i.test(body);
const highRisk = /Risk level:\s*high/i.test(body);
const migrationChanged = changedFiles.some((file) => /migrations?|schema|prisma|drizzle/i.test(file));
const sensitiveChanged = changedFiles.some((file) => /auth|session|permission|billing|payment|webhook/i.test(file));
const failures = [];

if (!hasRisk) failures.push("Add Risk level.");
if (!hasTests) failures.push("Add automated or manual test evidence.");
if ((highRisk || migrationChanged) && !hasRollback) failures.push("Add rollback plan.");
if (sensitiveChanged && !/Security and privacy notes/i.test(body)) failures.push("Add security/privacy notes.");

if (failures.length) {
  console.error("PR review guard failed:");
  for (const failure of failures) console.error(`- ${failure}`);
  process.exit(1);
}

console.log("PR review guard passed.");

先让它以 advisory 方式运行几天，再把它加到 protected branch 的 required checks。最开始只对 high risk 和 migration 严格，low risk 保持轻量，流程才会被团队接受。

安全、隐私、测试、性能和无障碍

安全 review 可以拆成输入、授权、输出、日志、外部通信。输入是否在 server 侧验证？授权是否靠近数据访问点，而不是只在 UI 判断？输出是否会造成 XSS？日志是否泄露个人信息？外部 URL、webhook、代理路径是否会带来 SSRF 或签名绕过风险？

隐私不只是 secret。邮箱、支付 ID、地址、咨询内容、analytics ID、私有内容都需要谨慎处理。不要把真实 API key、客户邮箱、合同、支付 ID 贴进 prompt。需要说明问题时，屏蔽值，只给 Claude Code 数据结构。

测试部分要证据，不要口头承诺。“works locally”不是证据。好的 PR 会写明跑了哪个自动化测试、手动检查了哪个流程、实际结果是什么。没有测试时也要说明原因。

性能 review 要看无边界循环、N+1 query、重复网络请求、bundle 增长、大图、客户端渲染开销。对性能敏感的改动，最好附前后对比数字。

无障碍 review 不应只看截图。检查键盘操作、focus 顺序、可见 focus、表单 label、错误信息、dialog focus trap、reduced motion。Claude Code 生成的 UI 往往视觉上整洁，但这些细节容易漏。

实务用例

用例一是认证和管理后台。用户列表、角色变更、审计日志必须在 API 或数据访问层保护。review 时要看 authorization、审计记录、日志中的个人信息、未授权访问测试。

用例二是计费和 webhook。支付 webhook 要关注签名验证、幂等性、重试、重复 event、取消状态、隐私日志。可以让 Claude Code 专门回答: 同一个 event 到两次，状态会不会坏？

用例三是数据库 migration。加一列也可能破坏生产，因为部署期间旧版本和新版本应用可能同时运行。review 要看 default、not null、index、backfill、rollback，以及 expand-contract 顺序。

用例四是 AI 生成的大 UI diff。Claude Code 一次生成页面、表单、modal、table 时，review 要检查 CTA 是否被误删、analytics event 是否改名、无障碍是否遗漏、snapshot 是否解释清楚、依赖是否必要。

用例五是有收入路径的内容站。文章页、商品页、lead form 的 review 也要保护转化路径。如果变更移除了产品列表链接、破坏免费 PDF 表单或停止咨询埋点，即使页面能渲染，也属于业务级 bug。

常见陷阱与收尾

第一个陷阱是直接相信 Claude Code 的判断。AI 可能产生看似合理的结论。每个 finding 都要回到 diff、测试、官方文档或复现结果。

第二个陷阱是 review 和修复同时进行。先要 findings，再决定必须修什么。否则 PR 在 review 中继续膨胀，责任边界会变模糊。

第三个陷阱是 AI 生成的“顺手清理”。格式、依赖、配置、删除测试都可能藏在大 diff 里。prompt 中要明确要求列出 unrelated changes。

第四个陷阱是把数据库 rollback 当作代码 revert。revert commit 不会恢复被删除的数据。high risk migration 需要备份、恢复 SQL、feature flag 或分阶段计划。

代码 review 也保护收入。计费、商品页、免费 PDF、Gumroad、咨询 CTA、analytics event 都是系统的一部分。个人练习可以从免费清单开始；团队要沉淀 PR 模板、Claude prompt、CLAUDE.md 和 CI guard，可以看产品和模板；真实仓库落地则适合培训与咨询。

我把这套格式套到三个小场景: Next.js UI 修改、数据库 migration、Claude Code 生成 UI diff。最有用的不是增加更多 checkbox，而是强制写 Risk level 与 Rollback plan。当 prompt 包含风险等级和数据类型时，Claude Code 的发现也更具体。

总结

Claude Code 代码审查清单不是一个 prompt，而是一套把风险分级、PR 证据、人类 review、CI 和 protected branch 连起来的团队流程。

先小规模开始: 加 PR 模板，让 CI guard 以提示模式运行，再对 high risk 设为必需检查。再结合AI 结对编程和CLAUDE.md 最佳实践，把 review 标准写进仓库，而不是只存在某个资深工程师脑子里。