AI写的代码也要过审:claude-code-workflows的code-reviewer独立审查机制实战指南

原创2026-11-03 15:00:281,392 阅读

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 编程补上了最关键的一环——独立审查。它用独立上下文、只读权限、结构化结论和收敛闭环,确保:

  1. ✅ AI 的探索不跑偏你批准的结果
  2. ✅ 冗余的机制不被白写(scope_excess)
  3. ✅ 测试真打到点子上(coverage_gap)
  4. ✅ 发现的问题被真正修正,而非停留在报告里

当你让 AI 交付的不是玩具、而是要上线的功能时,「AI 写的代码也要过审」不是一句口号,而是一条可以落地的机制。

📚 延伸阅读:README.md 的「Design Rationale」章节,收录了关于「为什么验证比生成更可靠」等设计哲学的完整说明。

登录后查看全文
claude-code-workflows