第 24 课:代码审查与安全审查工作流

前置:第 3 课(subagents)、第 5 课(自定义斜杠命令)、第 9 课(权限与沙箱)、第 12 课(无头模式与 CI)、第 21 课(调试工作流)。 本课讲的是代码写完之后、合并之前那一段——和第 21 课「怎么修 bug」不重叠。

今天的行业新闻是 OpenAI 把 Astra 标成了网络安全「Critical」级,同时给它套上生产级监控。放到我们自己的日常里,对应的问题很朴素:Claude 帮我写了一大堆代码,我怎么在合并前让它自己先审一遍? Claude Code 内置了这条路,而且比大多数人以为的深。

---

技巧 1(入门):/security-review —— 提交前的一条命令

Claude Code 内置 /security-review 斜杠命令,对当前所有待提交改动做一次安全分析,不需要任何配置。

# 会话里直接敲
/security-review

它检查的是 SQL 注入、XSS、认证与授权缺陷、不安全的数据处理、依赖漏洞这一类问题。和传统 SAST 的关键区别是:它不是跑模式规则,而是像人类审查者一样读代码、跨文件跟数据流,所以它能抓到需要上下文才能理解的问题——越权访问、业务逻辑漏洞、不安全反序列化、认证绕过。

配合 git 用最顺:

# 先看清自己改了什么,再让它审
git add -A && git diff --cached --stat

# 会话里:
#   /security-review
#   然后追问:"上面第 2 条,给我一个最小修复 diff,不要顺手重构别的"

小提醒:它是辅助不是保证。审出来的每一条都要自己判断,尤其是它对「这个输入是否可信」的假设——那通常来自你的架构而不是代码本身。

• 文档:Automated Security Reviews in Claude Code — Anthropic Help Center
• 文档:Code Review — Claude Code Docs

---

技巧 2(进阶):把 /security-review 改成你项目的审查清单

默认命令是通用的。你的项目大概率有自己特有的雷区——比如「所有对外接口必须过 authz.check()」「禁止直接拼 SQL,必须走 db.query() 的参数化接口」「任何写入 audit_log 的地方不能吞异常」。这些通用 prompt 是不知道的。

做法:把官方仓库里的 security-review.md 抄到你项目的 .claude/commands/ 下,然后在里面追加你自己的规则。

mkdir -p .claude/commands
curl -o .claude/commands/security-review.md \
  https://raw.githubusercontent.com/anthropics/claude-code-security-review/main/.claude/commands/security-review.md

然后编辑,在文件末尾追加项目特有的检查项:

## 本项目额外必查项(优先级高于通用规则)

1. **授权**:`src/api/` 下每个新增 handler,必须在进入业务逻辑前调用
   `authz.check(ctx, resource, action)`。缺失即为 HIGH。
2. **SQL**:禁止出现字符串拼接的 SQL。只允许 `db.query(sql, params)` 形式。
   发现 f-string / 模板字面量拼 SQL,一律 CRITICAL。
3. **审计日志**:写 `audit_log` 的调用不允许被 try/except 吞掉异常——
   审计失败必须让请求失败。
4. **不要报告**:测试文件(`tests/`、`*_test.go`)里的硬编码凭据不算发现,
   除非该文件会被打进生产制品。

## 输出格式
每条发现按:严重级别 / 文件:行号 / 一句话说清攻击路径 / 最小修复 diff。
不确定的放在「需要人工确认」区,不要混进确定发现里。

最后那两段是降噪的关键:明确告诉它什么不用报,以及把不确定的分开放。否则你会淹没在低价值发现里,几轮之后就不看了——这才是安全工具真正的死法。

改完之后 /security-review 就会走你这份定制版,团队成员 clone 仓库即可共享(.claude/commands/ 提交进 git)。

• 仓库:anthropics/claude-code-security-review
• 原始命令文件:.claude/commands/security-review.md

---

技巧 3(进阶):挂进 CI —— 每个 PR 自动审,结果直接贴成评论

前两步是「我记得审」。这一步是「忘了也会审」。官方提供了 GitHub Action,对 PR 做 diff-aware 扫描(只看改动的文件),把发现按严重级别 + CWE 分类 + 有问题的代码片段 + 可直接用的修复方案贴成 PR 评论。

# .github/workflows/security-review.yml
name: Security Review
on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: write   # 贴评论需要

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0        # diff-aware 扫描需要完整历史
      - uses: anthropics/claude-code-security-review@main
        with:
          claude-api-key: ${{ secrets.CLAUDE_API_KEY }}

这里有一个必须知道的安全前提:这个 Action 没有针对提示注入做加固,只应该用于审查可信的 PR。一个恶意的外部 PR 完全可以在代码注释或文件名里塞指令,试图操纵审查者。官方的建议是在仓库设置里开启 "Require approval for all external contributors",让工作流只在维护者过目之后才跑。

Settings → Actions → General → Fork pull request workflows
  → 勾选 "Require approval for all external contributors"

这条不是可选的最佳实践——2026 年 6 月就出过 Claude Code GitHub Action 相关的漏洞,一个恶意 issue 就能劫持仓库。在 CI 里跑 Agent,输入边界就是你的攻击面。

• 博客:Automate security reviews with Claude Code — Anthropic
• 相关阅读:Securing CI/CD in an agentic world — Microsoft Security Blog, 2026-06

---

技巧 4(高阶):用「审查型 subagent」隔离上下文,避免自己审自己

前三条有一个共同的弱点:审查者和作者是同一个会话。刚刚写完这段代码的 Claude,对自己的实现有强烈的先验——它知道「我本来打算怎么做」,于是很容易把「我打算做对的事」当成「代码做对了」。这跟人类 review 自己的 PR 是一样的问题。

解法是把审查交给一个上下文干净的 subagent(第 3 课),它只看得到 diff,看不到你们刚才的讨论过程。

在 .claude/agents/reviewer.md 里定义:

---
name: reviewer
description: 独立代码审查。只看 diff,不参与实现决策。
tools: Read, Grep, Glob, Bash
model: opus
---

你是一个独立的代码审查者。你**没有**参与这些代码的编写,
也不知道作者的意图——这是刻意的,不要去猜。

流程:
1. 跑 `git diff main...HEAD` 拿到改动。
2. 对每个改动的函数,先读它的**调用方**(用 Grep 找),
   再判断改动是否破坏了调用方的假设。
3. 只报告你能指出**具体触发路径**的问题。
   写不出"什么输入会让它出错"的,归到「疑问」区,不算发现。

禁止:
- 不要提"建议加注释"、"可以更 Pythonic"这类风格意见。
- 不要修改任何文件。你只读、只报告。

用法:

# 会话里
"用 reviewer subagent 审一下当前分支相对 main 的改动"

再进一步,可以并行派两个视角不同的 subagent——一个只看安全,一个只看「这个改动会不会破坏现有调用方」——然后你只读两份报告的交集与分歧。分歧的地方通常就是真正需要你做判断的地方。

最后,把这套纪律固化进 CLAUDE.md(第 1 课),之后每个会话自动生效:

## 合并前纪律
- 任何超过 3 个文件的改动,合并前必须跑一次 reviewer subagent。
- 触及 `src/api/` 或 `src/auth/` 的改动,额外跑 /security-review。
- 审查发现不允许由写这段代码的同一个会话直接修复——
  先 /clear,再基于审查报告重新开一轮。

最后那条最反直觉也最有用:让修复发生在一个没有辩护动机的上下文里。

---

一句话总结

/security-review 是随手可用的下限;定制 .claude/commands/security-review.md 把它变成你项目的;GitHub Action 让它不依赖你的记性(但要先关上外部 PR 这个口子);而独立上下文的 reviewer subagent 解决的是最根本的问题——审查者不该是作者。

---

第 24 课 · 2026-09-03 · 上一课:第 23 课「新功能速用 —— Fable 5.1 与 v2.1.257 / v2.1.258」(2026-09-02)