Claude Code Review 到底是怎么工作的：Diffs、Hooks 以及 Agent 能发现什么

Claude Code Review：Agentic PR 审查实用指南

Claude Code 可以像一位细致的资深工程师那样审查一个 pull request 或本地 diff——阅读改动的文件、追踪调用点、检查测试，并返回按严重程度排序的发现及修复建议。本指南专门讲解如何使用 Claude Code（Anthropic 的 agentic CLI 工具）进行代码审查：如何触发它、如何写出好的提示词、如何在每次提交或 PR 上自动运行它，以及如何将其接入团队流水线。

"Claude Code Review" 到底指什么

人们所说的"Claude 代码审查"其实是两种截然不同的东西。第一种是在聊天界面里让 Claude 查看你粘贴的代码片段。第二种——也是本指南的主题——是在你实际的代码仓库中，针对真实的 diff 或 pull request 运行 Claude Code，Anthropic 的 agentic CLI。

这个区别非常关键。当 Claude Code 审查一个 diff 时，它并不是孤立地对一段粘贴的摘录进行推理。它是一个自主的 agent，能够打开文件、追踪 import、阅读你的 CLAUDE.md 项目指令、检查相邻的测试，并在给出任何一条发现之前理解这次改动的完整上下文。这种跨文件的感知能力，正是让输出真正有用而非泛泛而谈的关键所在。

Claude Code 既可以作为本地安装的 CLI 使用（npm install -g @anthropic-ai/claude-code），也可以作为运行在云端沙箱中的 agent 使用——这两种方式后文会详述。Anthropic 的官方文档介绍了安装和初始设置。

逐步了解 /review 工作流

Claude Code 内置了专为此任务设计的 /review 斜杠命令。以下是从 diff 到可执行输出的完整工作流。

第一步——让 Claude Code 指向 Diff

有多种方式可以把你想审查的改动提供给它。

已暂存的改动（/review 命令）：

/review

在 Claude Code 会话内，/review 斜杠命令会启动对你改动的审查。这是最常见的本地工作流：暂存你的工作、运行 /review，在提交之前查看发现的问题。（具体命令行为会不断演进——请查阅 Anthropic 的 Claude Code 文档以获取当前语法。）

指定的 git 范围： 你也可以直接用自然语言向 agent 提问——例如，"审查 main 和这个分支之间的 diff，标出任何 bug 或回归问题。" 由于 Claude Code 能够自行运行 git 命令，它会为你指定的范围生成 diff 并进行审查。这在打开 PR 之前审查一个功能分支时很方便，也避免了依赖任何特定的命令行参数语法。

GitHub pull request 的 URL： 如果你的项目配置了 GitHub CLI，Claude Code 可以直接获取 PR 的 diff。你在提示词中提供 PR 的 URL 或编号，agent 会使用 gh 拉取 diff 以及 PR 描述，这为它提供了代码之外的意图上下文。

第二步——加载上下文

在给出发现之前，Claude Code 会阅读评估该 diff 所需的上下文：

• CLAUDE.md ——你项目的指令文件，可以定义审查重点领域、禁用模式、架构规则或团队约定。这是你自定义 agent 关注点的主要杠杆。
• 导入的模块和调用方——如果一个改动的函数被十个地方调用，agent 会阅读这些调用点，检查该改动是否向后兼容。
• 现有测试——它会阅读测试文件以理解改动代码的预期约定，并注意到新逻辑缺乏覆盖的情况。
• 配置文件——eslint、tsconfig、pyproject.toml 等文件帮助 agent 理解 CI 上已经强制执行的 lint 规则，这样它就不会重复报告你的工具链已经能捕获的问题。

第三步——分析

Claude Code 的分析过程会同时涵盖多个维度：

• 正确性——逻辑 bug、差一错误、空指针解引用、错误的算法假设
• 安全性——注入风险、暴露的凭据、不安全的反序列化、缺失的授权检查
• 可靠性——缺失的错误处理、未处理的 promise rejection、未捕获的边缘情况
• 可维护性——重复逻辑、命名不清晰、非显而易见行为缺少文档
• 测试覆盖率——新增代码路径缺少相应的测试

agent 不只是标出某一行；它会解释这个发现为什么重要，以及如果上线会造成什么影响。

第四步——结构化发现

输出是一份发现列表，每一条包含：

• 一个严重程度标签（通常为：critical / warning / suggestion）
• 文件和行号引用
• 对问题的通俗易懂的解释
• 一个建议的修复方案——通常是一段可直接应用的代码片段

默认情况下发现会输出到终端。对于团队使用，你可以进行重定向：输出到文件、通过 gh pr comment 作为 PR 评论发布，或使用 hook 将其写入共享的审查日志。

Claude Code 审查遵循一条结构化流水线——从 diff 输入，经过上下文加载和分析，到排序的发现和修复建议，hook 则支持完全自动化。

一个实例演练：真实 Diff，真实审查

为了让这一切更具体，下面是一个最简的 Python diff，以及 Claude Code 审查会揭示出的内容。

diff：

# Before
def get_user(user_id):
    result = db.query(f"SELECT * FROM users WHERE id = {user_id}")
    return result[0]

# After (in PR)
def get_user(user_id):
    result = db.query(f"SELECT * FROM users WHERE id = {user_id}")
    if result:
        return result[0]
    return None

PR 作者以为自己修复的问题： 找不到用户时的 KeyError。

Claude Code 在审查中揭示的问题：

1. Critical——SQL 注入（第 2 行）： f-string 将 user_id 直接插入到查询中。像 1; DROP TABLE users;-- 这样的值会被执行。修复方法：使用参数化查询——db.query("SELECT * FROM users WHERE id = ?", (user_id,))。

2. Warning——隐式的 None 返回值传播： 调用 get_user 但没有检查 None 的调用方现在会在别处出现故障。审查了三个调用点（按文件列出），它们都假设总会返回一个用户对象。

3. Suggestion——缺少类型注解： 返回类型应为 Optional[User]，这样 IDE 和类型检查器就能在调用点自动捕获 None 的情况。

4. Suggestion——新增测试但不完整： 新测试 test_get_user_not_found 只检查了返回 None 的情况；没有验证 user_id 为 0 或非整数时的行为。

原作者修复了 KeyError，但引入了隐蔽的 None 传播风险，也没有注意到已经存在的 SQL 注入问题。Claude Code 两个都发现了——之所以能发现，是因为它阅读了调用点，而不仅仅是 diff 本身。

让 Claude Code 给出更好的审查

审查的质量与你给 agent 提供的上下文质量直接成正比。以下这些提示词和技巧能持续产出更好的输出。

使用 CLAUDE.md 设置常驻指令

最大的杠杆在于你项目的 CLAUDE.md 文件。添加一个 ## Review Guidelines 部分：

## Review Guidelines
- We use parameterized queries everywhere. Flag any string interpolation in SQL.
- All public functions must have return-type annotations (Python) or JSDoc (JS).
- Security findings should always be severity: critical, not warning.
- We prefer explicit error returns over exceptions in the data layer.
- Do not flag import ordering — Black handles that automatically.

这样只需指示 agent 一次，项目中此后每一次审查都会继承这些规则，无需重复提示。

在提示词中提供意图

在交互式调用审查时，告诉 agent 这个 PR 想要实现什么：

/review This PR migrates our auth flow from JWT to session cookies. Focus on
session fixation, secure cookie attributes, and any places we might be leaking
the old JWT validation logic.

意图上下文让 Claude Code 能够优先给出相关的发现，而不是在所有维度上生成一份千篇一律的检查清单。

先请求一轮仅严重程度的扫描

对于大型 diff，两阶段方法更高效：

/review Pass 1: list only critical and warning severity findings with file+line.
No suggestions yet.

然后，在拿到 critical 列表之后，再针对特定发现请求修复细节。这避免了在一份 200 行的审查输出中，关键 bug 被淹没在风格建议之间的问题。

请求确认理解

对于复杂的改动：

Before reviewing, summarize what this diff is trying to do in two sentences,
then proceed with the review.

如果摘要有误，你就知道 agent 误解了这个 diff，可以在浪费时间处理错误方向的发现之前先纠正它。

用 Hook 实现审查自动化

手动运行 /review 很有用，但真正的生产力提升在于让审查变成自动的——这样每次提交或每次打开 PR 都会触发审查，而不需要有人记得去做。Claude Code 的 hooks 系统让这成为可能。（hooks 系统在 Claude Code hooks 指南中有深入介绍——本节专门聚焦于审查这一使用场景。）

每次提交自动审查

在项目的 .claude/settings.json 中，添加一个 Stop hook：

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "claude -p 'Review the diff from the last commit (git diff HEAD~1 HEAD) and list any bugs, security issues, or regressions.'"
          }
        ]
      }
    ]
  }
}

设置好之后，每次 Claude Code 完成一个任务（包括以提交结束的编码任务），该 hook 就会触发并审查生成的 diff。发现的问题会在提交落地后立即出现在你的终端中。

PR 打开时自动审查

对于 CI 集成，可以在 GitHub Actions 任务中以无头模式（claude -p "<prompt>"）运行 Claude Code，并将结果作为 PR 评论发布。下面的模式仅作示例——Anthropic 也发布了官方的 Claude Code GitHub Action，请查阅 Claude Code 文档获取当前推荐的 CI 配置，而不要直接照搬参数：

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      - name: Run review
        run: |
          claude -p "Review the diff between origin/${{ github.base_ref }} and HEAD. \
          List bugs, security issues, and regressions, ranked by severity." > review.md
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      - name: Post review as PR comment
        run: gh pr comment ${{ github.event.number }} --body-file review.md
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

这会在每次 push 时自动将 Claude Code 的发现作为 PR 评论发布。你的人类审查者随后可以将注意力集中在 agent 已经发现的问题上，而不用把审查时间花在 Claude Code 能够可靠捕获的项目上。

Claude Code Review 能捕获什么——又会遗漏什么

对其能力边界保持清醒的认识很重要。AI 审查对特定类别的发现确实非常强大，而对另一些类别则始终不足以胜任。

Claude Code 擅长机械式的正确性、安全模式和一致性——而产品判断、新型威胁和合规签署仍然是人类的职责。

Claude Code 能可靠捕获的：

• 在 diff 及其直接上下文中可见的差一错误、空/未定义解引用，以及类型不匹配
• 已知的安全模式：SQL 注入、XSS、CSRF 缺口、不安全的直接对象引用、缺失的输入验证、代码中的密钥
• 违反 CLAUDE.md 和配置文件中定义规则的风格和约定问题
• 重复逻辑——agent 的跨文件感知能力意味着它能注意到你刚添加的函数其实已经存在于两个目录之外的某个工具模块中
• 缺失的错误处理——未处理的 promise rejection、裸露的 except 子句、可能返回 None 或 undefined 但调用方并未预期的函数
• diff 中新增代码路径的测试覆盖缺口

Claude Code 无法替代人类判断的方面：

• 产品和需求决策。 这个功能是否应该存在、用户体验是否合理、API 契约是否是正确的抽象——这些需要任何 agent 都不具备的业务背景。
• 新型安全威胁。 agent 了解已知的漏洞类别；它不会针对你应用的部署环境或业务逻辑发明新的威胁模型。
• 大规模性能表现。 静态分析无法替代性能剖析结果、负载测试结果，或对真实流量模式的理解。
• 法规合规。 GDPR、HIPAA、PCI-DSS 等要求人类签署，通常还需要法务审查。AI 审查无法替代它。
• 团队协作和架构治理。 "这段代码该放在这个模块里吗？"或"我们应该引入这个依赖吗？"这类问题需要组织层面的上下文。

健康的定位是：Claude Code 审查消除了代码审查中枯燥的部分——捕获机械性错误、强制执行约定、标出已知的坏模式——这样你的人类审查者就能把有限的注意力花在真正需要人类判断的决策上。

将 Claude Code Review 整合进团队流水线

让团队真正持续使用 agentic 审查，需要把它当作工作流的核心部分，而不是可有可无的附加项。

三层模型

一个运转良好的团队流水线有三层：

1. 本地 pre-commit——开发者在推送前运行 /review。上文所述的 hook 设置可以让这一步自动化。这一层发现的问题修复成本最低。
2. CI 关卡——GitHub Actions 工作流在指派任何人类审查者之前，将 Claude Code 的发现作为 PR 评论发布。只有在 CI 审查通过（没有 critical 发现）之后，才会指派人类审查者。
3. 人类审查焦点——人类审查者将 Claude Code 的评论用作分诊指南。他们的工作是评估需要判断的事项——架构契合度、产品正确性、性能权衡——而不是逐行重新检查拼写错误。

共享 CLAUDE.md 约定

你的 CLAUDE.md 是 agent 审查行为的配置层。把它当作代码对待：提交它、对它进行版本管理、在 PR 中审查对它的改动。当团队一致同意 Claude Code 应该停止标记某个模式（因为你已经有对应的 linter）时，更新 CLAUDE.md，这个改动就会应用到未来的每一次审查中。

校准严重程度阈值

团队常常发现默认的严重程度校准在早期显得过于嘈杂。在 CLAUDE.md 中添加明确的指令来控制它：

## Review Severity Rules
- Only flag console.log as a warning if it is in a non-test, non-debug file.
- Import ordering is never a finding; Prettier handles it.
- Treat any hardcoded credential as critical regardless of context.
- Performance suggestions are informational only unless they affect O(n²) loops.

使用几周之后，大多数团队发现，一旦 agent 的注意力被调整到真正在其代码库中重要的模式上，噪音水平会显著下降。

处理误报

Claude Code 偶尔会给出错误的标记。正确的应对方式不是整体否定这次审查——而是在 CLAUDE.md 中添加一条针对该模式的项目专属指令。随着时间推移，这会形成一套越来越精准、反映团队实际标准的项目专属审查配置。

不安装本地环境也能运行 Claude Code Review

到目前为止的描述都假设你已经安装并在终端中运行 Claude Code。对许多团队来说——尤其是使用受限企业电脑、没有 WSL 的 Windows 环境的团队，或者想直接在浏览器标签页中进行审查的开发者——本地安装是一个阻碍。

Happycapy 在浏览器中直接以安全的云端沙箱运行 Claude Code。你能获得完整的 agentic 审查能力——包括跨文件上下文加载、CLAUDE.md 支持，以及 /review 命令——而无需安装任何东西。这在以下场景尤其有用：

• 在浏览器中审查 pull request 的代码，无需将分支拉取到本地
• 正在接入 Claude Code 审查的团队，希望在推广本地安装之前先拥有一个共享的、一致的环境
• 受限的机器，安装全局 npm 包需要 IT 审批
• 审查不熟悉的代码仓库，你希望获得 agent 的上下文加载能力而无需克隆整个仓库

如果你好奇 Claude Code 在 agentic 能力方面与其他替代方案相比如何，可以参阅 Claude Code vs. GitHub Copilot 和 Claude Code vs. Cursor。如果你想了解 Happycapy 是如何在浏览器环境中运行 Claude Code 的，Claude Code on the web 介绍了其架构。

在 happycapy.ai 免费开始

常见问题

问：Claude Code 审查适用于任何语言吗？

是的。Claude Code 并非针对特定语言——它可以阅读任何基于文本的 diff，并对其中包含的代码进行推理。它在 Python、TypeScript、JavaScript、Go 和 Rust（训练数据占比较大的语言）上往往最为精准，但在 Ruby、Java、C# 以及大多数其他主流语言上也能给出有用的发现。对于特定领域的语言或不常见的框架，在 CLAUDE.md 中添加上下文能显著提升输出质量。

问：/review 与在聊天中让 Claude 查看我的 diff 有什么不同？

关键区别在于 agentic 工具使用和代码仓库上下文。在聊天中，Claude 只能看到你粘贴的内容。Claude Code 的 /review 命令让 agent 能够打开文件、追踪 import、检查测试，并阅读你的项目约定——从而给出基于实际代码库、而非仅基于摘录的发现。对于大型或相互关联的改动，这种差异是相当显著的。

问：Claude Code 审查会捕获安全漏洞吗？

它可靠地捕获知名的漏洞类别：SQL 注入、XSS、CSRF 缺口、不安全的直接对象引用、硬编码密钥、缺失的输入清理。对于需要理解你部署环境的新型、特定于应用的攻击向量，它的可靠性较低。可以把它当作一次彻底的第一轮安全扫描，而非渗透测试。

问：我该如何阻止审查标出我的 linter 已经处理的问题？

在你的 CLAUDE.md 中添加明确的排除项："Do not flag import ordering — isort handles this." 或 "Do not flag trailing whitespace — Prettier enforces it."。大多数团队在使用两到三周后建立起这份清单，并发现信噪比显著提升。

问：我能在包含多种语言的 monorepo 中使用 Claude Code 审查吗？

可以。你可以用路径参数或只覆盖你所改动子目录的 git diff 范围来限定审查范围。你也可以在 CLAUDE.md 中维护特定于语言的审查章节，agent 会在加载上下文时读取它们。

问：如果 diff 非常大——比如一个 3000 行的 PR——会怎样？

对于非常大的 diff，可以考虑两阶段方法：先只请求 critical 和 warning 级别的发现（不要建议），对其进行分诊，然后针对特定文件或子系统请求完整分析。对于极大规模的重构，拆分 PR 是更好的解决方法——无论是对人类还是对 AI 的可审查性都是如此。

问：审查输出是确定性的吗？我两次会得到相同的发现吗？

不会——像所有大语言模型的输出一样，不同运行之间会有差异。对于高风险的审查，运行两次命令并比较结果是合理的做法。大多数 critical 发现会稳定出现；细微的建议差异更大。使用较低的 temperature（如果你的工作流支持配置）或更具指令性的提示词可以降低这种差异。

问：Claude Code 审查与现有的 linter 和静态分析工具如何配合？

它是对它们的补充，而非替代。你的 linter 能快速、机械地捕获强制执行的风格规则；Claude Code 增加了语义层面的理解——它能评估一个函数是否做了正确的事，而这是任何 linter 都做不到的。理想的流水线两者都用：linter 在 pre-commit hook 中运行（快速、确定性），Claude Code 审查在 CI 中运行（较慢、语义化）。/review 命令能感知你的 linter 配置，避免重复给出你的工具已经产生的发现。

问：我能自定义审查输出的格式，以便发布到 Slack 或工单系统吗？

可以。你可以提示 agent 以特定格式输出发现——JSON、Markdown，或与你团队 PR 评论风格相匹配的模板。将其与 hook 系统和一个小的 shell 脚本结合，你就能拥有一条完全自动化的审查流水线，将结构化的发现发布到团队跟踪问题的任何地方。

相关阅读：Claude Code hooks 深度解析 —— 自动化 pre-commit 检查、lint，以及审查之外的自定义工作流。

相关指南

• Claude Code Hooks: The Power-User Guide to Automating Your Agent
• Build Autonomous Agents with the Claude Code SDK: A Practical Developer's Guide
• Claude Code vs GitHub Copilot: Autonomous Agent or In-Editor Assistant?
• Claude Code Web: How to Run Claude Code in Your Browser (No Install)