我自己每天都在用 AI 写代码最近这一个月最深的感触不是 AI 写得有多快而是合代码有多慢。需求方催得再紧我心里那道坎也过不去AI 给的这段逻辑我真的敢合并吗后来我找到一套解法把“有证据链的代码评审 Skill”接进日常流程让每次审查都落在可验证的事实上而不是“我感觉有问题”这种直觉上。这篇文章就把整套思路、配置和实操记录摊开讲给还在合并焦虑里的团队做个参考。这套 Skill 能解决的事情其实很具体AI 生成完代码之后由谁来评审、按什么标准评审、评审意见怎么让人信服。它不替代人工评审而是把评审这件事从“人肉通读 diff”变成“对照证据逐条核验”把主观判断变成可回溯、可验证、可修复的工程动作。适合正在用 AI 编程工具写业务代码的工程师也适合想给团队建立 AI 代码准入机制的负责人。1. AI 写代码之后评审环节为什么成了真正的瓶颈1.1 写代码与合并代码之间的信任赤字放在两年前“代码写不出来”是大多数项目的真实瓶颈。现在情况完全反过来了只要你把需求描述得够清楚AI 能在几分钟内给你一版能跑的实现。生成成本被拉得很低但一个新的瓶颈浮出水面——你可以让 AI 快速写出代码却没办法快速相信它是对的。这种不信任不是没来由的。我自己在 AI 生成的代码里踩过三类典型问题几乎每类都让你在合并前犹豫半天第一类是“看起来对但边界不对”。AI 非常擅长处理主路径但对空值、超时、并发、重复调用这些边界条件经常漏掉。比如一个用户注销接口AI 会先删数据库记录再清缓存看起来顺序合理但极端情况下删库成功、清缓存失败用户数据没了 token 还在后续所有鉴权请求都会带着一个幽灵身份。第二类是“能通过编译但逻辑冲突”。代码签名、类型定义都对得上陷阱藏在语义层面。你原来的模块假设getUser()永远不返回nullAI 新加的代码在某种情况下会返回null还顺手给调用点加了空值兜底。这一加等于悄悄改变了模块契约旧代码里所有跳过空值检查的路径全部变成潜在空指针。第三类是“局部正确但全局耦合”。AI 只改了你指定的那个文件但一个接口变更牵动五个调用方它不会主动帮你同步排雷。你合并后才发现 README 里记录的接口行为、类型声明里的注释、另一个模块的 mock 数据全成了过期信息。这三种问题的共同点是你光靠“读一遍代码”根本发现不了。它们藏在变更文件之外藏在调用链深处藏在某个你没跑到的测试路径里。所以我对 AI 生成的代码天然带着一股不信任这种不信任不是情绪问题是信息不足导致的理性判断。要消除它不是靠“多读几遍”而是要有可验证的证据。1.2 传统代码评审流程在 AI 时代悄然失效传统评审依赖人的经验评审者看过足够多的代码知道哪种写法容易出问题于是对照 diff 逐行扫。这套方式在纯人工开发时代够用但放到 AI 编程场景里有三个结构性短板。第一个短板是人的注意力有上限。一个 PR 动辄几百上千行AI 生成速度快变更规模也跟着膨胀。靠人眼逐行扫要么漏掉真正危险的一行要么被大量轻微风格问题淹没评审质量随 diff 规模快速下降。第二个短板是 AI 生成的逻辑模式不稳定。同一个问题今天生成的实现和明天生成的实现可能差异很大甚至同一个版本的代码里两种优雅程度完全不同的写法并存。人脑靠“以前踩过的坑”来识别风险但 AI 不按历史套路出牌它踩坑的方式可以千奇百怪远超个人经验库的覆盖范围。第三个短板是上下文压缩。AI 在工作时记忆窗口是有限资源它处理一个跨文件的改动时经常把早期看到的旧代码“压缩”成摘要。这个摘要与实际仓库状态经常对不上。于是你会在评审时看到一种诡异现象AI 自信地写了某个兼容逻辑但那个兼容对象在仓库里早就不存在了。“凭经验抓错”这套逻辑在 AI 时代已经不成立评审标准必须从审美判断升级为可验证判断——每条意见都能给出证据每个结论都能被快速复核。1.3 从“敢不敢写”到“敢不敢合并”的变化现在团队里的分工重心已经变了。“敢不敢写”是 IDE 补全时代的问题只要打开 AI 工具你基本敢写因为写错了可以改。但“敢不敢合并”是工程问题合进去之后代码进入主干影响的是整个团队的稳定性和维护成本。合并得越随便后面解线上问题的成本就越贵。放到成本账上看这件事评审其实是风险前置的折价工具。同样是发现 bug在评审阶段发现改三行代码十分钟解决到测试阶段发现要重新走一轮提测流程到线上发现那就是故障要背事故要写复盘。越早发现代价越低。代码评审 Skill 要做的就是把这个“前置发现”的能力自动化让人把精力花在真正需要判断的地方。所以当我开始搭建评审 Skill 的时候核心目标不是“找出所有 bug”而是“为每一次合并决策提供可靠的证据包”让工程师合并得好也合并得明白。2. “有证据链”的代码评审 Skill思路与核心设计2.1 什么是证据链为什么评审需要证据链先解释一下我理解的“证据链”。它借鉴的是案件调查的思路定一个结论必须有物证、人证、逻辑链支撑光说“我觉得他可疑”不能定罪。代码评审也一样一条评审意见如果只是“这段逻辑有问题”那和没说区别不大。但如果你给出“这句调用和基线的假设冲突冲突点在这里”说服力就完全不一样。具体到代码评审里证据链就是一组可以让任何人独立复核的事实组合。它至少包含三部分代码位置在哪个文件、第几行、什么片段这是最基础的锚点。逻辑关联这个位置为什么和风险相关和仓库里其他哪些代码形成矛盾。运行表现有没有对应的测试结果、日志输出或命令执行结果来证明影响。为什么证据链能解决信任问题因为它的特性是可回溯、可验证、可修正。可回溯意味着每条意见都能找到源头可验证意味着任何一个人包括被评审者都可以花 30 秒定位到问题现场可修正意味着如果证据本身有误双方可以基于事实讨论而不是基于立场吵架。这三条合在一起远比“评审者权威”更能赢得团队信任。我在实际使用中还有一个体会有了证据链之后跨级评审变得顺畅很多。以前资深工程师评审新人的代码新人不理解“为什么要这么改”容易觉得是“过来人的偏见”。现在意见里带着证据新人自己顺着证据走一遍就能理解沟通成本直线下降。2.2 证据链的四种核心证据类型在设计这个 Skill 时我把证据分成了四类对应代码评审中最常遇到的四种事实来源。评审意见可以挂靠其中一类或几类但每一条意见至少要有一类证据落地。代码位置证据是最基础的。任何问题都要给出准确的文件路径、行号和代码片段不能只说“某个模块有问题”。行号是评审交流的通用语言没有位置证据的意见第一轮就会被打回。差异对照证据针对的是“这个改动和既有现状的冲突”。AI 经常忽略仓库原有的设计假设所以评审时要主动去找基线代码、老版本逻辑、历史注释把“原来是什么样现在改成什么样中间有哪些矛盾”摆出来。这种证据特别适合发现隐性契约破坏。测试与运行证据直接回应“它会不会真的出问题”。光说“这里可能有并发 bug”不如附上一条并发测试的输出结果或者找一个触发路径。哪怕没有完整测试至少给出一个可复现的命令序列让评审者能自己在本地跑。实测结论比理论推演更有说服力。依赖关系证据用来看变更的影响面。改一个函数签名至少要列出所有调用方改一个配置项至少要说明哪些环境会读到它。AI 的局部视角经常漏掉这一层所以要专门把“谁调用了你、你调用了谁、谁依赖你的输出”拉出来审一遍。四类证据各有分工。位置证据解决“在哪里”差异对照解决“冲突点”测试运行解决“会不会真的炸”依赖关系解决“炸的范围有多大”。一个完整的证据链最好能同时覆盖“位置 冲突点 运行影响”这样评审意见才是立体的而不是拍脑袋的。2.3 输出规范与置信度机制光有证据还不够报告格式也得设计。我把 Skill 的输出定义为结构化报告每个问题都带固定字段让评审结果能进入团队的工作流继续流转。报告里每个问题包括以下字段问题编号、严重级别、所属模块、简要描述、证据链多行、建议修复方向、置信度。严重级别我分成三级阻塞级、警告级、提示级。阻塞级必须有测试失败、明确运行时风险或可复现路径不能凭感觉给警告级是潜在风险需要人工确认提示级是代码风格、可读性、防御性建议不影响合并。置信度机制是我特意加上的。AI 最怕的是什么是它自信满满地给你一个错误结论你信了结果上线出问题。所以我在 Skill 里明确要求低置信度的问题必须标注“低置信度”并且给出为什么不够确定——比如“这段逻辑依赖的远端调用我无法在当前上下文看到完整实现”。这种做法相当于给评审报告加了一个“可靠性声明”反而提升了整体可信度。敢于承认自己不确信的评审者比永远嘴硬的评审者更值得信任。3. 落地实现手把手搭建代码评审 Skill3.1 准备Skill 的目录结构与元数据现在 AI 编程工具普遍开始支持“Skill”机制不同工具叫法略有差异有的叫 Command有的叫 Agent有的叫 Rule但底层逻辑是一样的把一段高频使用的复杂指令、以及它依赖的脚本和静态资源打包成可复用的单元。我建议的目录结构是这样组织的~/.claude/skills/ └── code-review-with-evidence/ ├── SKILL.md └── scripts/ ├── diff_analyzer.py └── find_callers.shSKILL.md是核心定义文件里面先用 YAML front-matter 写好元数据告诉工具这个 Skill 什么时候该被触发、怎么被调用。我用的模板大概是下面这样--- name: code-review-with-evidence description: 对当前分支或指定 diff 进行代码评审。每个结论必须附文件路径、行号、冲突代码片段等可验证证据禁止无依据的主观意见。 triggers: - review - 评审 - 代码评审 ---这段元数据的作用相当于给 Skill 挂了个“名牌”让 AI 工具能在合适的时候主动调用它。scripts/目录下放辅助脚本用于提取调用关系、搜索关键引用点、做简单的静态检查后面会在工作流里用到。3.2 评审工作流的设计与提示词模板Skill 的核心是提示词但绝不是一段“请你做代码评审”这么简单。我在 SKILL.md 的工作流部分把评审过程拆成了五个步骤每一步都有明确的输入和输出要求。## 执行流程 ### 第 1 步定位变更范围 读取用户提供的 diff 或分支对比结果列出修改文件清单、新增行数、删除行数。 输出变更文件清单。 ### 第 2 步逐文件静态审查 对每个变更文件逐段理解变更意图检查空值、边界、并发等风险标注可疑点。 输出可疑点列表每个可疑点必须有具体行号。 ### 第 3 步构建证据链 对每个可疑点使用以下方式获取证据 - 打开对应文件定位实际代码片段 - 使用 scripts/find_callers.sh 查找调用方与依赖方 - 使用 grep 搜索仓库中相关常量、配置、历史逻辑 - 如有测试运行针对性测试用例记录输出。 输出证据列表每个证据包含来源、内容、与可疑点的关联说明。 ### 第 4 步生成结构化报告 按下方输出格式整理问题编号从 R1 开始递增。只有第 2 步的可疑点 第 3 步的证据完备时才允许写入报告证据不足的问题标注低置信度并说明原因。 ### 第 5 步给出修复建议 每个问题必须附一条具体的修复方向不得使用“请自行调整”这类空话。这个流程设计的关键在于第三步强制 AI 在给结论之前先找证据。对很多模型来说让它“评审”它容易直接给出一堆泛泛而谈的建议但只要加上“打开文件、定位行号、搜索调用方”这些动作词它就会按工具调用的方式真正去翻代码产出质量完全不一样。3.3 在 Claude Code 中部署与调用配置在主流的命令行 AI 编程工具里Skill 的部署一般就是建目录、放文件、重启会话。我以我实际用的方式为例先在终端执行mkdir -p ~/.claude/skills/code-review-with-evidence/scripts然后把写好的SKILL.md放进目录把辅助脚本丢进scripts/再在配置里加上权限声明允许这个 Skill 执行读取文件、运行 grep、执行测试等操作。配置完成后新会话里输入“评审当前分支”工具就会自动加载这个 Skill 并按里面定义的工作流执行。实际调用时我最常用的命令是把当前分支和主干的差异直接喂给 Skillgit diff main...HEAD --stat git diff main...HEAD /tmp/pr.diff然后对 AI 说一句“请使用 code-review-with-evidence 技能评审 /tmp/pr.diff”。它会先读 diff再沿着变更点去翻代码构建证据链整个过程基本不需要我干预。实测下来一个改动量在 300 行以内的 PR完整评审一轮在几分钟内可以完成。3.4 在 IDE 场景中的补充用法不是所有人都在命令行里工作很多团队主力用的是图形化 IDE。这种情况下Skill 的部署形态稍有不同但核心思路一致把“评审 证据链”这套提示词存成可复用的片段绑定到快捷键或右键菜单。做法很简单把 SKILL.md 里的“执行流程”和“输出格式”两段抽出来改成 IDE 命令的提示词然后在编辑器里选中一段 diff 或一个文件触发命令让它跑评审。IDE 插件的上下文更丰富AI 可以直接获取当前打开的多个文件构建证据链时反而不容易因为看不到关联文件而漏判。这里我给个建议IDE 场景下优先做“单文件深度评审”CLI 场景下优先做“跨文件全量评审”两种形态搭配用覆盖的场景更完整。4. 实操记录用该 Skill 评审一个真实 Pull Request4.1 待评审的 PR 场景描述为了讲清楚实际效果我构造一个很典型的场景某个 Node.js 服务需要新增“刷新令牌”接口。AI 在一个下午生成了完整实现主逻辑看起来没有语法问题测试也能通过。但在合并之前我用刚搭好的 Skill 跑了一轮评审。这个 PR 的变更范围包括新增src/auth/refresh.ts实现刷新逻辑修改src/session/token_store.ts增加令牌删除方法新增tests/refresh.test.ts覆盖基本流程。总计 3 个文件新增 112 行删除 38 行。4.2 评审执行过程与关键输出Skill 先定位了变更范围然后逐文件审查第三步开始构建证据链。它在refresh.ts里发现了一个不太对劲的顺序问题并给出了这样一份报告## 评审摘要 变更范围src/auth/refresh.ts, src/session/token_store.ts, tests/refresh.test.ts 总评分6.5/10 ### R1 [阻塞] 令牌刷新路径存在竞态条件 - 描述refreshToken 方法先删除旧令牌、再写入新令牌两步之间没有原子保护。两个并发请求携带同一旧令牌时第二个请求会在删除操作后取得空值。 - 证据链 1src/auth/refresh.ts:18-21执行顺序为 await store.remove(oldToken)然后才调用 await store.set(newToken)。 - 证据链 2src/session/token_store.ts:45get() 在 key 不存在时返回 Promisenull。 - 证据链 3tests/refresh.test.ts 目前只覆盖了顺序调用场景未覆盖并发场景手动模拟双并发请求可复现第二个请求返回 500。 - 影响路径POST /v1/auth/refresh - controllers/auth.js:52 - refreshToken() - store.remove() - 建议修复调整顺序为先写入新令牌、再删除旧令牌同时在存储层引入原子操作或分布式锁杜绝并发刷新导致的空窗口。 - 置信度高这份报告我看了之后直接去核实了三个证据点都在它标注的位置找到了对应代码复现路径也确实存在。随后它又给了两个提示级问题一个是错误码语义不够明确另一个是新增方法缺少 JSDoc。这两个只是建议不阻塞合并。4.3 证据链如何把“怀疑”变成“结论”收到报告的那一刻我的感受很明确以前我自己审这个 PR大概率也能看出顺序有问题但我不敢打包票因为我看不到所有并发路径。而 Skill 给出的证据链把“这里有隐患”变成了“这里在第 21 行有空窗口第二个并发请求会在这里拿到 null”。真正让我觉得这套方法有效的是后面发生的动作。我把报告转给写代码的 AI让它按证据链里的位置去修复。AI 看到的是一个带行号的事实清单而不是含糊的“有竞态风险”它很快锁定了问题点改了顺序、补了并发测试。整个过程从评审到修复完成只花了十分钟左右。搁在以前这种跨源码搜索、跨函数比对、再复现验证的活儿靠人手动做怎么也要折腾小半天。我还留意到一个细节证据链里给出的“影响路径”特别有用。它把问题从底层实现一直关联到对外接口评审者不用自己去捋调用链直接就能判断影响面。这也是为什么这份报告我能放心作为合并决策依据——它不是一句结论而是一整套可以复核的卷宗。5. 常见问题与排查技巧实录5.1 误报频繁评审结果没有说服力用了一段时间之后我遇到的第一个问题是误报。Skill 经常把“风格不一致”“变量命名不够好”这类主观意见标成警告级甚至阻塞级导致真正重要的问题被噪音淹没。这种情况如果持续团队很快就不再信任评审报告。我调整了两个地方。第一在提示词里明确“阻塞级”的判定标准——必须满足“影响路径可到达运行时 有测试失败或可复现路径 有明确数据损坏或功能错误风险”三个条件之一否则不得标阻塞。第二增加一个“提示级”兜底把风格建议全部归到这一类不参与合并阻塞。修改之后报告质量立刻清爽了不少团队也愿意认真看阻塞项了。5.2 上下文窗口不够评审大 PR 时被截断AI 编程工具的上下文窗口始终是物理上限。评审一个几百行的 PR 没问题但遇到上千行的大变更AI 翻着翻着就开始遗忘早期看到的代码证据链变得残缺甚至开始编造位置。我的解法是分而治之。变更大的时候先只让 Skill 读取 diff 的“变更文件清单”做一轮粗筛找出高风险的几个文件然后针对每个高风险文件单独做深度评审。每个文件单独开一轮评审会话把该文件的完整内容和相关依赖都放进上下文。这相当于把一次大评审拆成多次小评审虽然次数多了但每次质量都稳。5.3 如何与 CI 流程结合让 Skill 自动触发手工触发终究是有遗漏的。后来我把这套 Skill 接进了团队的 CI 流程在每次 PR 更新时自动跑一轮评审把报告以评论形式发回 PR。用的方式不复杂大致是这样的思路name: ai-review on: pull_request: types: [opened, synchronize] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Collect diff run: git diff ${{ github.event.pull_request.base.sha }}...HEAD /tmp/pr.diff - name: Run review skill run: claude -p 请使用 code-review-with-evidence 技能评审 /tmp/pr.diff /tmp/report.md - name: Post report run: gh pr comment ${{ github.event.pull_request.number }} --body-file /tmp/report.md这里的定位要拎清楚它给人工评审提供的是“证据包”不是“最终裁决”。我会在报告开头加一句提示说明这是 AI 辅助评审所有阻塞级问题仍需维护者确认后才会真正阻拦合并。这样既提高了评审效率也不至于出现“AI 说不行就不让合”的失控感。5.4 推理成本过高控制 token 消耗跑一轮全量评审尤其是带着多个辅助脚本跨文件搜索的时候token 消耗很快就上来了。我一开始没在意直到某个月账单涨得有点夸张。后来我按需设了几个限制策略。场景限制策略效果单文件评审只读目标文件 直接调用方上下文可控成本低多文件全量评审最多审 5 个关键文件其余仅列清单避免 token 爆掉只找阻塞问题忽略提示级扫描重点放运行时路径成本降一半大 PR 评审两阶段粗筛 精修总消耗低于一次性全量控制 token 不是为了省钱而省钱是因为 token 一超限AI 就开始“丢三落四”评审质量直线下滑。与其让它硬撑着看完整份大 diff 然后给你一堆半真半假的意见不如限定它在能驾驭的范围内给出扎实的证据结论。这个取舍非常重要。这套玩法走到现在我的真实体会是AI 写代码时代的评审核心不是管住 AI而是管住信息质量。你给评审者提供的证据越完整合并决策就越稳你逼着 AI 先找证据再下结论它的输出就越可靠。把“有证据链”这件事做进 Skill 里你就不再是“信不信 AI 写的东西”而是“信不信一组可以自己核实的证据”。如果一定要给一个建议先让 AI 做“挑问题的评审员”别急着让它当“自动提交代码的代理”。等证据链在你团队里跑顺了再谈更高阶的自动化也不迟。