AI写的代码也要过审:claude-code-workflows的code-reviewer独立审查机制实战指南
AI写的代码也要过审:claude-code-workflows的code-reviewer独立审查机制实战指南
📌 一句话概要:
claude-code-workflows的code-reviewer是 AI 编程里的「独立审查员」。它在独立上下文中逐行核对 AI 写的代码是否守住了你批准的边界,并把发现的问题收敛成一条可修正的闭环。
为什么 AI 写的代码也要「过审」?
用 AI 写代码,最大的坑不是它写不出来,而是它看起来对,却悄悄跑偏。
想象一下:你让 Claude 加一个「账号找回流程」,它探索代码库时,偶然发现了一个令牌处理的隐患,于是把大半设计都花在了那个隐患上——最后你要的「找回行为」反而含糊不清。
这就是 claude-code-workflows 要解决的问题:让 AI 的广泛探索,始终收敛在你批准的那个结果上。 而 code-reviewer,就是这套机制里的最后一道独立审查。
它的核心理念藏在一句话里:
测试通过,只能说明「测试和代码意见一致」,并不能证明两者都是对的。
所以,claude-code-workflows 让一个独立的、没参与写代码的审查员,重新读一遍改动,判断它是否真的交付了你批准的结果。
code-reviewer 是什么?独立审查机制拆解
code-reviewer 是一个子代理(subagent),它的定义在 agents/code-reviewer.md。它在四个插件里都提供:
| 插件 | 适用场景 |
|---|---|
dev-workflows |
后端 / 通用 |
dev-workflows-frontend |
React / TypeScript 前端 |
dev-workflows-fullstack |
后端 + 前端一起 |
它有三个关键特征,决定了它和「让 AI 自己检查自己」有本质区别:
| 特征 | 说明 |
|---|---|
| 🔒 独立上下文 | 每次调用都是一个全新的 Agent,不复用写代码时的上下文,所以它能「以新人视角」完整读完整个改动 |
| 📖 只读不写 | 它的工具集是 Read, Grep, Glob, LS, Bash——没有 Edit 和 Write,只负责审查、给结论,绝不动代码 |
| 📋 结构化输出 | 最终返回一个 JSON,包含 verdict(结论)、acceptanceCriteria(验收标准逐条核对)和 findings(发现) |
💡 关键洞察:写代码的人,不该同时当裁判。这正是 README.md 里「Why LLMs Are Bad at "First Try" and Great at Verification」这条设计理据的落地——外部反馈和全新上下文,比让同一个会话生成又自评更可靠。
快速上手:安装与触发审查
一键安装插件
code-reviewer 随插件一起分发。启动 Claude Code 后,添加市场并安装对应插件:
# 1. 启动 Claude Code
claude
# 2. 添加插件市场
/plugin marketplace add shinpr/claude-code-workflows
# 3. 按你的项目类型安装其一
/plugin install dev-workflows@claude-code-workflows # 后端 / 通用
/plugin install dev-workflows-frontend@claude-code-workflows # 前端
/plugin install dev-workflows-fullstack@claude-code-workflows # 全栈
⚠️ 只安装一个工作流插件即可,
dev-workflows-fullstack已包含后端和前端的工作流。
想先翻源码?克隆仓库
如果你想先浏览 code-reviewer 的完整定义,可以克隆仓库:
git clone https://gitcode.com/gh_mirrors/cla/claude-code-workflows
两种触发审查的方式
| 方式 | 命令 | 什么时候用 |
|---|---|---|
| 🎯 独立审查已有实现 | /recipe-review |
代码已经写完,你想让它对照「批准的结果」过审 |
| ⚙️ 完整实现流程内置审查 | /recipe-implement "…" |
从头开发,流程会在实现完成后自动跑独立审查 |
定义见 skills/recipe-review/SKILL.md。
code-reviewer 到底审查什么?六大维度
code-reviewer 不是泛泛地「看看代码好不好」,而是对照你批准的治理来源(Design Doc 或 Work Plan)逐条核对。它的发现被严格归入六类(来源:agents/code-reviewer.md 的 Findings Boundary):
| 类别 | 含义(用大白话说) |
|---|---|
dd_violation |
🔴 实现违反了已批准的需求或设计契约 |
scope_excess |
🟡 多写了不必要的机制 / 抽象 / 测试,不值得它的维护成本 |
reliability |
🟠 改动的某条路径,在给定条件下仍可能失败 |
coverage_gap |
🟣 必需的可观测行为没被真正证明(测试没打到点子上) |
quality_rule |
🟦 仓库自定义的 quality.yaml 里某条 pass 条件不满足 |
adjacent_residual |
🟩 同一个已验证的问题,还在旁边相邻的代码里躺着 |
🎯 注意这里的克制:每条发现只有在「不修就会出错 / 违反契约 / 含重大冗余」时才输出。可选的加固、锦上添花的建议,统统不出现在结果里。这保证了审查报告短小、可执行,不会淹没在噪音里。
它还读取仓库里的 docs/project-context/quality.yaml(如果存在),把你项目特有的质量维度也纳入审查。
审查结果怎么读?四种 verdict
code-reviewer 只返回四种结论,直接决定了下一步怎么走:
| verdict | 含义 | 下一步 |
|---|---|---|
✅ pass |
没有需要修正的发现 | 通过,进入报告 |
🔧 needs-improvement |
发现的问题能在批准范围内修好 | 进入修正闭环 |
🏗️ needs-redesign |
修正需要更新技术设计或责任边界 | 回到设计侧更新 |
⛔ blocked |
必需的输入或证据不可用 | 走「结果接受」流程,记录受阻原因 |
每个 findings 项都带 id、category、location(精确到 文件:行号)、description、basis(依据哪条治理来源)和 suggestion(最小充分的修正)。
完整审查流程:从审查到修正闭环
这是整篇文章的核心。code-reviewer 的审查不是一个孤立动作,而是嵌在一条收敛闭环里。完整流程如下(来源:skills/recipe-review/SKILL.md):
graph TD
A[1. 前置检查] -->|从 diff 推导改动文件| B[2. code-reviewer 初审]
B --> C[3. security-reviewer 安全审查]
B --> D[4. Review Resolution 判定]
C --> D
D -->|apply| E[5/6. 修正路由]
D -->|decline| H[记录理由]
E --> F[7. quality-fixer 质量门]
F --> G[8. 复审判和 reconciliation]
G -->|未收敛| E
G -->|收敛| I[9. 最终报告]
H --> I
关键机制:发现不会自动变成工作。 主会话(orchestrator)按 Review Resolution 协议,对每一条发现做 apply(采纳修正)或 decline(附理由拒绝)的裁决,然后按「修正路由」分发给对应的负责人:
| 发现模式 | 修正路由 | 由谁执行 |
|---|---|---|
| 实现需改动才能达到验收状态 | c(代码侧修正) |
task-executor |
| 设计文档过时/多余,代码本身没问题 | d(设计侧更新) |
technical-designer |
| 删除设计里选中的某个多余机制 | d + c |
先改设计,再删代码 |
修正完成后,code-reviewer 会带着 prior_feedback(上一轮发现)重新审查,对每条发现标记 resolved(已解决)/ withdrawn(撤回)/ maintained(仍需处理)。只有当所有发现收敛,闭环才结束。
🔁 这种「初审 → 裁决 → 修正 → 复审」的循环,就是「实战」的意义:不是审查一次就完事,而是逼着问题真正被解决。完整协议见 skills/subagents-orchestration-guide/references/review-resolution.md。
独立上下文:最巧妙的设计
为什么 code-reviewer 一定要在独立上下文跑?这背后是项目的一条设计哲学:
每次子代理调用都是全新的 Agent 工具调用,以隔离每个阶段的上下文。
好处很实在:
- 完整读改动:因为不背写代码时的上下文包袱,它能一次性细读整块改动,而不受「我刚才是这么想的」这种自我偏差影响。
- 单一职责:它明确声明「跑测试和质量检查属于工作流的质量门,不属于本次审查」——它只负责读代码 + 读测试并判断对错,把「跑起来是否通过」交给 quality-fixer。
- 可复现:同一个输入,独立上下文让审查结论更稳定,不被前序对话污染。
🧠 一句话总结:写代码追求「发散探索」,审查追求「收敛对齐」——两者必须分开的上下文,才能各司其职。
Lite 模式:更省,但审查不缺席
想省一点?在任何 recipe 的请求里加上「Lite mode」即可:
/recipe-implement "Lite mode. Add rate limiting to the public API"
Lite 模式会跳过若干中间检查(如 code-verifier、security-reviewer、逐任务的质量检查),但——
⚡
code-reviewer仍然会跑。 它保留了独立实现审查,只是省掉了独立安全审查。
Lite 模式行为见 skills/subagents-orchestration-guide/references/lite-mode.md。所以即便追求速度,「AI 写的代码要过审」这条底线没有被砍掉。
实战:一个 42 文件变更如何被拦下
code-reviewer 和 security-reviewer 的独立审查,是真抓到过「AI 以为做完了、其实有洞」的案例的。
以 mcp-local-rag 的增量同步功能为例:一个横跨文件系统扫描、存储、CLI 和 MCP 四个面的 42 文件改动。独立的安全审查两次把实现打回去,抓出了:
- ⚠️ 在验证之前就发生了文件读取(顺序错了)
- 🕳️ 通过符号链接父目录的「路径逃逸」(路径包含检查被绕过)
这正是独立审查的价值:写代码的会话可能根本没意识到这两条路径,而全新上下文的审查员能盯到。
常见问题 FAQ
Q:code-reviewer 会直接帮我改代码吗?
不会。它只有 Read/Grep/Glob/LS/Bash,没有写权限。改代码的是 task-executor,跑检查的是 quality-fixer,code-reviewer 只负责给结论。
Q:审查发现的每条问题都会照单全收吗?
不会。主会话按 Review Resolution 逐条裁决 apply/decline,被拒绝的发现会带上理由记录在最终报告里,绝不悄悄消失。
Q:后端、前端、全栈三套的 code-reviewer 有区别吗? 机制一致,都会随对应插件分发。区别在于配套的技能(前端版带 React/TypeScript 检查)。
Q:我只要「最佳实践指南」,不要整套工作流行吗?
可以单独装 dev-skills 插件获得编码/测试/设计/文档的最佳实践(含 coding-principles、testing-principles)。但想要 code-reviewer 这套独立审查闭环,请装工作流插件,且不要和 dev-skills 同时安装。
小结
claude-code-workflows 的 code-reviewer 给 AI 编程补上了最关键的一环——独立审查。它用独立上下文、只读权限、结构化结论和收敛闭环,确保:
- ✅ AI 的探索不跑偏你批准的结果
- ✅ 冗余的机制不被白写(
scope_excess) - ✅ 测试真打到点子上(
coverage_gap) - ✅ 发现的问题被真正修正,而非停留在报告里
当你让 AI 交付的不是玩具、而是要上线的功能时,「AI 写的代码也要过审」不是一句口号,而是一条可以落地的机制。
📚 延伸阅读:README.md 的「Design Rationale」章节,收录了关于「为什么验证比生成更可靠」等设计哲学的完整说明。