1. 先想清楚AI 代码审查到底替你扛哪部分活我算过一笔账过去三个月我平均每天要花一个小时左右看同事的 PR还不算 review 意见来回沟通的时间。时间久了你会发现大部分 review 意见其实是重复劳动——要么是低级 bug 没人发现要么是代码风格、错误处理方式不统一。真正需要人深度思考的架构层意见可能一周也就那么一两条。于是我开始尝试用 Claude Code 做自动化代码审查把 AI 当成一个 7×24 小时在线的初筛审查者。这篇文章我会把整套实践过程完整讲一遍从最开始的定位思考到环境配置、审查提示词设计、接入 Git 工作流再到跑了三个月之后看到的真实效果和踩过的坑。内容主要面向有过基本代码审查经验、想用 AI 减轻日常负担的开发者和技术团队负责人也适合刚接触 Claude Code、想找一个正经落地场景的新手。1.1 人工审查的三种痛恰好都是 AI 的强项我印象特别深的一次某次上线前一个同事在讨论区问这个字段会不会是 null大家各自埋头看代码半小时后才发现问题确实存在——而那个改动其实已经合并三天了。这类低级问题流失在人工审查里太常见了因为人的注意力会被更复杂的东西占满。你看到一段写得漂亮的算法时很容易忽略旁边那个空 catch 块。人的注意力是有限的这不是态度问题。AI 审查正好补在点上。它不会因为这段代码看起来熟就跳过检查不会因为写代码的人是你朋友就不好意思提意见更不会看了十行就开始惦记午餐。同一份 diff 你让它审十次它的标准基本稳定。这三个特性——不疲劳、无情绪、标准一致——恰好就是代码审查最需要的品质。1.2 AI 看不懂业务所以别让它做架构决策但也有非常明确的天花板。Claude Code 看一段 diff能判断这里可能抛异常这里并发计数会丢但它判断不了这个支付流程为什么要拆成两个服务。业务上下文、历史包袱、产品决策这些信息散布在几十个文件的注释里、几年前的讨论记录里甚至只在某个老同事的脑子里。指望 AI 理解这些是把工具用错了方向。所以我的定位很明确AI 负责第一遍初筛专注缺陷层和一致性人负责第二遍专注架构层和业务语义。人这一遍因为不用再花时间找低级 bug效率反而高了很多。为了方便团队理解我把两类审查拆成了对比表。审查维度人工Claude Code低级缺陷空值、资源、吞异常容易漏靠经验稳定覆盖不疲劳命名与风格一致性依赖个人标准需在提示词里明确规则架构与业务语义核心价值不可替代基本无效甚至会给出危险建议审查速度慢受时间碎片影响秒级出结果情绪与关系因素会下意识顾虑完全不受影响这张表也直接决定了后面的所有配置方向凡是有客观标准的检查都可以交给 AI凡是需要业务判断的地方都要留给人。1.3 哪些 PR 适合先上 AI哪些不适合我建议从中小型、自包含的改动开始试点。比如一个新增的接口、一个工具函数库的补充、一次内部重构这种改动范围在几个文件以内逻辑相对独立AI 的审查准确率会高很多。跨模块的大改动、带着复杂迁移的 PRAI 容易只见树木不见森林——它看每个文件都合理但组合起来可能把整个架构带偏。这类大 PR 我现在的做法是拆成多次小 PR或者至少让 AI 按文件逐个给意见然后人来做全局整合判断。一句话AI 审查最适合diff 小、上下文清晰、规则明确的场景。2. 从零跑通第一条审查命令环境配置与最小脚本2.1 安装与授权真正卡住人的通常是这一步Claude Code 的安装本身不算复杂装好命令行工具后终端里执行claude命令它会引导你完成登录授权。授权通过之后同一个账号下的对话历史、项目配置都会同步。这里我想提醒的是自动化审查和你自己手敲命令的场景不太一样——手动用的时候出了错你还能现场改自动化的脚本里如果授权过期了CI 任务会在半夜悄悄红掉你得第二天早上才发现。所以我把授权相关的检查写成了脚本第一步每次审查前先执行claude --version和一次极短的连通性请求确认工具可用再继续。这个检查成本几乎为零但能避免大量脚本跑了一半才报错的尴尬。另外如果团队成员比较多建议把账号策略提前定好别让每个人用自己的个人额度去跑团队流水线否则月底账单出来的时候负责的同事会非常被动。2.2 第一条审查命令从随便聊聊到按标准审 diff装好后先在仓库里手动跑一次找感觉。我最开始直接用最朴素的问法cd my-project claude -p 请审查当前工作区的代码变更给出问题清单这个命令能跑通但结果基本没法用。它会东聊一句西聊一句甚至给出代码整体质量不错这种正确的废话。原因很简单你没有告诉它审查的标准是什么、输出格式是什么、关注点在哪里。AI 不是你肚子里的蛔虫你不把什么叫一次合格的审查讲清楚它就只能凭通用常识瞎猜。正确的第一步是先把审查规则写明白用一条完整指令去测。我把我们团队的第一版审查提示词写成了单独文件然后用命令直接读取文件内容加上 diff 一起丢给它。这样改规则不用改脚本维护起来舒服得多。2.3 最小可用的审查脚本能放进 crontab 的那种经过几轮迭代我在本地用的是一个很朴素的 bash 脚本。它的逻辑只有四件事确认工具可用、取到基线分支与当前分支的 diff、拼接提示词和 diff、把结果输出到终端或文件。#!/bin/bash # review-diff.sh - 审查目标分支相对基线分支的代码变更 set -euo pipefail BASE_BRANCH${1:-main} OUTPUT_FILE${2:-review-report.md} # 1. 环境自检 if ! command -v claude /dev/null; then echo claude 命令不存在请先安装并完成授权 2 exit 1 fi # 2. 取 diff git fetch origin $BASE_BRANCH --quiet DIFF_BODY$(git diff origin/$BASE_BRANCH...HEAD -- .) if [ -z $DIFF_BODY ]; then echo 没有检测到代码变更退出 2 exit 0 fi # 3. 拼接提示词 REVIEW_PROMPT$(cat docs/review-prompt.md) FULL_PROMPT执行一次代码审查。\n\n【审查要求】\n${REVIEW_PROMPT}\n\n【代码 diff】\n${DIFF_BODY} # 4. 调用 claude 并输出 claude -p $FULL_PROMPT --output-format text $OUTPUT_FILE echo 审查报告已写入$OUTPUT_FILE第一次看到自己的 diff 被 AI 审出问题的时候你会产生一种微妙的感觉这不是那种帮你把代码格式化的玩具工具它是真的在按你的规则做事。但注意我上面这个脚本能跑通不代表审查质量就达标了——真正的分水岭在提示词也就是下一节内容。提示git diff origin/main...HEAD用的是三点语法表示基线分支合并到当前分支之后当前分支独有的变更。如果习惯用两点语法会把基线分支上别人已经合并的改动也带进来审查报告会多出一堆莫名其妙的噪音。3. 审查质量的关键三层审查提示词的设计思路3.1 一次审查不是一次提问而是三件事我最开始犯的错误是希望一次提示词里塞进所有要求既要查 bug又要管风格还要看架构顺便把注释补上。结果就是每项都浅尝辄止报告看起来很全面实际上真正能落地的问题没几条。后来我把审查拆成三个层次让 AI 分层输出效果立刻不一样。层次检查什么典型例子缺陷层必然导致 bug 的问题空指针、资源未释放、异常被吞、并发计数丢失逻辑层改动与周边代码的一致性新方法名和既有命名风格不符、接口契约被破坏设计层结构与可维护性重复代码、职责不清、缺少必要测试分层的好处有两个。第一AI 不会把精力浪费在低价值问题上缺陷层的意见永远优先级最高。第二人看报告的时候可以按层跳过我自己基本只看缺陷层和逻辑层设计层偶尔瞄一眼架构师同事则会重点读设计层把 AI 的观察当作一种统一视角的输入。审查从人盯代码变成了人盯 AI 的意见效率完全是两个量级。3.2 给足上下文diff、项目约定、输出格式三件套层分好了接下来是上下文。AI 审查质量高低一半取决于你给了它什么。我固定给三样东西代码 diff、项目约定、输出格式要求。diff 是最核心的上下文不用多说。项目约定是很多人会忽略的你的团队里正确的标准和别的团队可能完全相反。比如有的项目要求所有对外方法做 null 校验有的项目默认调用方保证非空有的团队严格要求 try-with-resources有的项目因为历史原因全是手动 close。这些约定如果不在提示词里说明AI 就会拿通用最佳实践硬套结果就是一堆与现有代码风格冲突的建议。输出格式要求也很关键。如果不要求标注文件行号AI 会给你一堆某处存在潜在风险这种没法定位的描述如果不要求分级它会平均用力把严重问题和轻微建议混在一起。我上面脚本里引用的docs/review-prompt.md核心内容就是下面这份模板。3.3 一份可复用的审查提示词模板你是一位有十年经验的后端代码审查工程师。请根据下方给出的代码 diff 和项目约定完成一次代码变更审查。 审查分三个层次按优先级输出 1. 缺陷层空值处理、资源释放、异常吞掉、并发安全、边界条件、敏感信息硬编码。 2. 逻辑层重复代码、命名一致性、接口契约是否被破坏、该改动对既有调用方的影响。 3. 设计层职责是否清晰、耦合是否可控、是否缺少必要的单元测试。 项目约定团队规范 - 对外方法必须做 null 校验内部方法不做重复校验 - 资源操作一律使用 try-with-resources 或等价写法 - catch 块禁止为空必须记录日志或抛出可追踪异常 - 不允许在本次改动中做与需求无关的重构 - 数据库查询必须走预编译禁止字符串拼接 SQL。 输出格式 - 先输出严重问题清单再输出改进建议清单 - 每一条必须标注文件路径和大致行号 - 每一条必须说明为什么这是问题和建议怎么改 - 如果某一层未发现问题明确写未发现问题 - 禁止输出泛泛的赞美、鼓励性话术和与代码无关的评论。 以下是代码 diff这份模板可以直接抄走改改。这里我要特别强调禁止输出泛泛的赞美这一条。AI 天生倾向于讨好如果不明确禁止它会在一堆无害评论里夹杂整体实现清晰、逻辑完整之类的废话人看报告时还得花时间过滤。把这条写死之后报告的信息密度立刻上来了。3.4 审查提示词与项目说明文件的配合除了每次拼接的提示词Claude Code 本身支持在项目里放一个说明文件让它在每次运行时自动读取项目背景。我会把仓库的技术栈、目录结构、常见约定写进去这样提示词里就不用重复一大堆背景信息。比如# 项目背景示例 - 技术栈Java 17 Spring Boot 3构建工具 Maven - 包结构controller - service - repository 严格分层禁止跨层调用 - 异常处理统一由全局异常处理器捕获service 层禁止吞异常 - 测试要求新增业务方法必须配套单元测试。把这类信息沉淀在项目文件里比每次在 prompt 里现写要靠谱得多。团队新成员加入时这份文件本身就是很好的规范文档AI 审查时自动遵守人也顺手受益。我见过不少团队给 AI 写了几百字 prompt 却从没整理过团队规范这个顺序其实可以反过来——先整理规范再把它翻译成 prompt。4. 自动化落地Git Hook 与 CI 流水线两条路径4.1 路径一pre-push Hook留一块后悔药脚本跑通之后第一个自然的想法就是让它自动触发。最简单的方式是 Git 的 pre-push 钩子每次git push之前自动执行一遍审查脚本发现问题就提示你甚至可以选择中断推送。我的第一版实现非常粗暴#!/bin/bash # .git/hooks/pre-push BRANCH$(git rev-parse --abbrev-ref HEAD) if [ $BRANCH main ]; then exit 0 # 主干分支不做阻塞检查 fi DIFF_BODY$(git diff origin/main...HEAD) REPORT$(echo $DIFF_BODY | claude -p $(cat docs/review-prompt.md) --output-format text) echo $REPORT if echo $REPORT | grep -q 严重问题; then echo 发现严重问题推送已中止。请先修复或人工确认。 2 exit 1 fi这个方案的好处是反馈链路极短问题在提交阶段就被拦住不用等到 CI 跑完。坏处也很明显如果提示词写得严格那么任何一个标为严重问题的项都会让整个分支推不上去哪怕其中两条其实是误报。我第二天就因为这个被堵了一次——某位同事改了配置文件的格式AI 把没有使用 try-with-resources当成了严重问题输出。从那以后Hook 版本我只保留提示不中断模式把是否拦截的判断完全留给 CI 阶段。本地 Hook 的定位就是给开发者的第一道提醒而不是门禁。4.2 路径二CI 流水线任务把报告贴到 PR 评论里真正作为团队门禁的是 CI 流水线。思路是在 CI 里新增一个独立的审查任务拉取代码后计算 diff调用 claude 生成报告然后把报告发布到 PR 的评论区。整个过程无人值守合并代码的人打开 PR 就能看到 AI 的审查意见。# CI 审查任务的关键步骤以常见的 Git 托管平台流水线语法为例 # 步骤1检出代码并获取目标分支 git fetch origin main --depth1 # 步骤2计算当前分支相对 main 的 diff DIFF_BODY$(git diff origin/main...HEAD -- .) # 步骤3调用 claude 生成审查报告 REPORT$(echo $DIFF_BODY | claude -p $(cat docs/review-prompt.md) --output-format text) # 步骤4把报告写入文件作为构建产物 echo $REPORT ai-review-report.md # 步骤5通过托管平台的 API把文件内容发布到 PR 评论 # ci:api-comment $REPORT实际落地时平台差异主要集中在最后一步有的托管平台提供现成的评论 API有的需要借助机器人账号发帖。我们最终用的是平台自带的应用市场里一个现成的自动评论插件把审查报告以 Markdown 格式贴到 PR 下同时保留构建日志里的原始输出。4.3 门禁怎么设严重级别才需要卡合并关于是否要卡合并我和团队讨论过很久。第一种极端AI 意见只是参考不设任何拦截靠人自觉去看。这种大概率会变成没人看——报告挂在 PR 下面忙碌的开发者扫一眼标题就合并了。第二种极端AI 发现严重问题就阻止合并。这种又会被误报折磨需要反复调整提示词团队沟通成本极高。最后的折中方案是按级别分流严重问题作为 CI 检查项之一如果存在必须人工确认改进建议只作为评论展示不参与合并门禁。实现上不复杂因为提示词里已经要求输出分级清单CI 脚本只要在报告中检测严重问题小节下是否有内容即可。这里我想说一个容易被忽略的点自动化审查的门禁强度必须要和团队的纠错能力匹配。人少的小团队、快速迭代的项目卡得太死会让 AI 审查变成新的瓶颈规模上来之后再逐步加严反而是更平滑的路径。我们是从完全不卡到严重问题需确认再到运行稳定后把这条规则写进团队流程一共花了大概三周。5. 实测三个月高价值命中、误报清单与调优过程5.1 高价值命中三类 AI 比人眼更稳的问题三个月的运行记录里AI 真正确实帮我们拦住过几次问题的类型我总结成三类给想评估效果的人一个参照。第一类是改动波及型。一个方法签名变化AI 能顺着 diff 和相关文件把所有调用方过一遍找出这里会编译失败这里的判断逻辑失效了。人看 diff 的时候容易只看改动点本身而 AI 是按整个仓库的上下文来校验的。这类问题在我记录里占了大概四成。第二类是资源与异常型。文件流没关、数据库连接在异常分支没释放、catch 块空着——这类问题 AI 的命中率出奇地高因为它不是靠记得而是靠模式匹配。人的大脑特别容易在复杂逻辑里忽略这种例行公事的细节AI 不会。第三类是静默错误。最典型的是把一个函数的返回值直接丢掉了someService.doUpdate(user)返回值表示更新是否成功调用方没接收也没判断。这类 bug 不影响编译、不影响测试但会在特定数据下悄悄出错。人类审查很难发现AI 在提示词点明注意被忽略的返回值之后命中率提升非常明显。5.2 高发误报AI 最容易较真的三个地方诚实地说误报也不少。我刚接上前两周报告里超过一半的严重问题其实是误报。最常见的是三类。一类是风格判断当缺陷。比如我们团队变量命名用驼峰某个历史文件用了下划线AI 会把命名不一致列为严重问题而实际上那个文件是外部接口的映射类根本不该改。这类误报的解法是把这类豁免规则写进项目约定。第二类是过度重构建议。AI 倾向于在小改动里建议你是否应该提取一个工厂类这两个方法应该合并成一个抽象接口。对于大型重构这类建议有价值对于只有三十行的工具方法它就是在制造噪音。我在提示词里加了不进行与本次改动无关的重构建议压下去不少但偶尔还会冒出来因为模型总是倾向于表现得更聪明。第三类是上下文错位。最常见的是把测试代码当生产代码审或者把一个兼容性代码块当成新逻辑。这种误报很难完全消除我们的处理方式是在 PR 描述里加一个审查范围说明字段让作者注明哪些文件无需 AI 审查。5.3 调优过程从第一版到稳定版的四个关键改动结合上面的问题我把提示词迭代了四个版本。第一版只有请审查代码并给出问题效果最差。第二版加了缺陷/逻辑/设计分层和输出格式要求可用性大幅提升。第三版加入了团队约定和豁免规则误报率开始明显下降。第四版增加了审查范围说明机制允许 PR 作者标注跳过哪些文件到这里才真正达到团队可接受的标准。版本关键改动误报表现v1裸提示词意见泛泛几乎无有效发现问题v2三层审查 输出格式有效问题可定位误报仍高v3团队约定 豁免规则误报下降偶发风格噪音v4审查范围说明达到可日常使用的稳定状态这里说一句从结果倒推的体会不要在第一天就追求完美提示词先跑起来把真实的误报收集起来再逐条喂回去调。AI 提示词迭代和数据标注有点像真实样本永远比猜重要。5.4 成本与速度数字层面到底值不值最后说点现实的。自动化审查不是免费的每次调用都要消耗 tokenCI 上跑一次完整审查通常消耗量不小同时审查时间也从秒级上升到了分钟级取决于 diff 大小和模型负载。我们当时的实测一个五百行以内的 diff大约要一到三分钟出完整报告费用按调用量计算每个月加起来相当于一个中等价位午饭的开销。比起人工审查的几个小时这笔账怎么算都划算。但我要提醒一点凡是把 diff 一次性塞进去的用法都有上下文长度上限。超过一定行数的 diffAI 会开始截断或者忽略中段内容给出的意见质量明显下降。所以现在超过一定规模的大 PR我会强制提示作者拆分。这是自动化审查在生产环境里真正需要面对的工程问题不只是提示词问题。6. 团队落地前必须想明白的几件事6.1 自动化审查是纪律问题不是工具问题我见过几个团队兴致勃勃地接了 AI 审查两周之后又默默关掉原因几乎都是同一种报告没人看或者意见没人改。AI 把问题找出来了但修复仍然需要人来做需要人来跟踪、验证、关闭。如果团队本身没有审查意见必须逐条回复的纪律那么再强的审查工具也只是在制造一份注定被忽略的报告。我们团队的做法是把处理 AI 审查意见写进 PR 的完成标准里和跑通单元测试并列。不需要每条都采纳但每条都需要给出处理结论。这个流程很朴素但有它之后报告的完成率从不到三成提升到了接近九成。6.2 人看报告的方式也要变先 AI 后人是种新节奏自动审查真正改变的是审查节奏。以前同事们开 PR 之后会等着人来看节奏以人为中心。现在 AI 在 PR 打开十几分钟内就会给出一版初审意见人再来看的时候等于带着一份问题地图读代码。有经验的同事告诉我现在看 PR 会先花两分钟把 AI 报告过一遍然后只挑那些AI 没看明白的地方重点研究整个人的注意力使用效率完全不同。这个转变听着简单实际上需要团队里的所有人都调整习惯。最开始的几周总有同事不看报告就直接点合并后来把报告作为 CI 产物并默认展示在 PR 评论区才慢慢扭转过来。6.3 从试点到铺开先挑一个团队跑一个月顺带提一句如果你想在公司里铺开这套东西我的建议是先挑一个对工具接受度高的团队试点跑满一个月再开会复盘。复盘的核心问题就两个AI 帮你省了多少时间AI 给你添了多少麻烦这两个数字都诚实的话铺不铺开就很好决策了。我自己从第一版裸提示词跑到现在的稳定配置最大的感触是AI 代码审查不是装个工具就行它是一个不断调提示词、调流程、调人的协作方式。工具今天能用明天模型更新了、团队规范变了都得跟着再调。但只要把流程想清楚让 AI 去干那些重复的、费眼睛的、不该由人来做初筛的活整个团队的审查效率提升是肉眼可见的。