1. 从“能写”到“敢合”AI 编程真正的分水岭最近半年我身边几乎所有做开发的朋友都在用 AI 写代码。不管是补全一个函数、生成一段单元测试还是把一整个模块从零搭起来AI 的表现确实让人省心。但有意思的是聊到后来大家卡住的地方出奇一致代码是写出来了可到底敢不敢合并进主干这个问题听起来有点反直觉。AI 都帮你把代码写完了合并一下有什么难的但真正在团队里干过活的人都知道代码评审这道关卡从来不是“代码能不能跑”这么简单。它背后牵扯的是责任归属、变更风险、历史上下文、团队规范以及一个很现实的问题——当提交者是一个 AI Agent 时谁来为这次合并背书我自己踩过这个坑。有一次让 AI 帮我重构一个订单状态机它给出的代码逻辑清晰、测试也过了我扫了两眼就合了。结果上线第二天发现它悄悄改了一个边界条件的判断顺序导致某个极少触发的退款场景走了错误分支。问题不在于 AI 写得差而在于我评审时缺少一条能追溯“它为什么这么改”的证据链。所以当我看到“有证据链的代码评审 Skill”这个方向时第一反应是这才是 AI 编程真正缺的那块拼图。它解决的不是“AI 会不会写代码”而是“AI 写完代码之后人怎么高效、有依据地判断这次变更能不能合”。这篇文章我就围绕这个 Skill 的设计思路、核心机制、实操落地和踩坑经验完整拆一遍。适合正在用 AI Agent 参与开发、或者准备把 AI 编程引入团队流程的工程师和 Tech Lead 参考。2. 这个代码评审 Skill 到底在解决什么问题2.1 普通 git diff 评审为什么在 AI 场景下失效先说清楚传统评审的流程。我们平时看一个 MRMerge Request核心动作就是看git diff哪几行加了哪几行删了然后结合自己对业务的理解判断“这个改动合不合理”。这套流程在人写代码的时代是够用的因为写代码的人脑子里有一条完整的推理链评审时你问一句“这里为什么这么改”对方能立刻答上来。但 AI 生成的代码不一样。你拿到的是一个 diff可这个 diff 背后的推理过程是缺失的。AI 不会主动告诉你我读了哪几个文件、参考了哪些已有实现、为什么选择改这个函数而不是新增一个、我有没有考虑过某个边界情况。你看到的只是结果看不到过程。这就导致一个很尴尬的局面评审者被迫用“结果正确性”去反推“过程合理性”。代码能跑、测试能过就倾向于合并一旦出了问题回头再查发现根本不知道 AI 当时是基于什么信息做的决策。这不是评审这是赌博。2.2 “证据链”三个字到底指什么我给“证据链”下过一个自己的定义从需求到最终 diff 之间每一个关键决策点都能被追溯、被验证、被质疑。具体到这个 Skill它至少要能回答下面几个问题这次变更对应的是哪个需求或 issueAI 是从哪句话里理解出这个意图的AI 读了哪些文件作为上下文这些文件里哪些内容影响了它的判断它改了哪几个位置每个位置的改动理由是什么有没有它“考虑过但没改”的地方为什么没改这次改动可能影响哪些调用方有没有做影响面分析你看这些问题没有一个是git diff能直接回答的。它们需要 Skill 在 AI 生成代码的过程中同步采集推理痕迹然后在评审阶段以结构化的方式呈现出来。这就是“有证据链”和“裸 diff”的本质区别。2.3 为什么是 Skill而不是一个独立工具这里要区分两个概念Agent 和 Skill。Agent 是干活的主体Skill 是它调用的一套能力封装。把代码评审做成 Skill而不是做成一个独立的评审平台有几个很实际的好处。第一评审发生在生成现场。AI 写完代码的那一刻上下文还在它的工作记忆里这时候采集证据成本最低。如果等代码提交到远端再让另一个系统去分析很多推理细节已经丢了。第二Skill 可以被复用和组合。同一个评审 Skill既能挂在代码生成 Agent 后面做自动预审也能被人工评审流程调用做辅助分析。它是一块积木不是一栋楼。第三符合 Agent 协作的趋势。现在多 AI 协作越来越常见一个 Agent 写代码另一个 Agent 做评审中间靠 Skill 传递结构化的证据。这种模式下Skill 就是 Agent 之间的“交接文档”。3. 核心机制拆解证据链是怎么被采集和呈现的3.1 生成阶段的埋点让 AI 边写边“留痕”证据链的关键在于采集时机。如果等 AI 写完再让它回忆“你刚才为什么这么改”它给出的解释往往是事后编的可信度很低。所以这个 Skill 的第一个核心动作是在生成阶段就埋点。具体做法是在 Agent 的提示词里约定一套输出协议要求它在生成代码的同时输出一份结构化的“决策记录”。这份记录不需要很长但必须包含几个固定字段。我实测下来下面这套字段设计比较平衡既不会让 AI 输出负担过重又能覆盖评审需要的关键信息。字段含义示例intent本次变更要达成的目标修复退款金额计算在部分退款时多扣的问题context_files参考过的文件及关键片段order_service.py 第 120-180 行changes每个改动点的位置和理由修改 calc_refund() 的判断顺序alternatives考虑过但未采用的方案曾想新增函数但会破坏现有调用方impact可能影响的调用方或场景退款接口、对账任务这里有个经验字段不要贪多。我一开始设计了十几个字段结果 AI 为了填满它们开始编造内容反而污染了证据链。后来砍到五六个核心字段质量明显提升。字段的价值在于“每个都能被验证”而不是“看起来很全面”。3.2 评审阶段的呈现把证据链和 diff 对齐采集完证据下一步是呈现。这一步的难点在于证据是逻辑维度的diff 是行维度的两者怎么对齐我的做法是让 Skill 输出一份“带锚点的评审视图”。每个改动点在 diff 里有一个行号范围在证据链里有一条对应的决策记录两者通过一个稳定的 ID 关联起来。评审者看到某一行改动时可以立刻展开它背后的理由。举个具体的例子。假设 AI 改了calc_refund()里的一个判断# 改动前 if refund_amount order_amount: raise ValueError(退款金额超过订单金额) # 改动后 if refund_amount order_amount - already_refunded: raise ValueError(退款金额超过可退金额)裸看这个 diff你会觉得“哦改了个判断条件”。但配上证据链你能看到intent 是修复部分退款场景context 里引用了对账任务的历史 bug 记录alternatives 里提到“曾考虑在调用方做校验但会漏掉内部调用”。这时候你的评审就从“看代码”变成了“审决策”效率完全不一样。3.3 证据的可信度分级不是所有理由都同等可靠这里要泼一盆冷水AI 给出的理由可信度是分层的。我在实践中把它们分成三档评审时的关注度也不同。强证据能直接对应到代码事实的。比如“参考了 order_service.py 第 150 行的现有实现”这种可以去核对对得上就是真的。中证据逻辑自洽但无法直接验证的。比如“选择这个方案是因为改动面更小”需要评审者自己判断。弱证据纯主观表述。比如“这样写更优雅”基本可以忽略。Skill 在呈现时应该给证据标注可信度等级让评审者知道哪些需要重点核对哪些可以快速略过。这个设计看起来小但实际用起来能省很多时间。我见过太多评审者被 AI 一段漂亮的解释说服结果那解释根本站不住脚。4. 实操落地从零搭一个可用的评审 Skill4.1 环境与前置准备先说清楚这套东西的依赖。你不需要什么重型基础设施核心就是三样一个能调用大模型的 Agent 运行环境支持自定义提示词和工具调用代码仓库的读取权限让 Agent 能拿到上下文文件一个能展示结构化数据的评审界面最简单的就是一个 Markdown 渲染页面我自己的环境是基于常见的 Agent 框架搭的模型用的是支持长上下文的那一档。这里不展开具体框架选型因为不同团队的技术栈差异太大重点是提示词协议和数据结构的设计这部分是通用的。提示如果你的团队还在用纯人工评审可以先不上 Agent只把“证据链模板”作为 MR 描述规范推行。让写代码的人或 AI按模板填写评审者按模板核对。这一步不需要任何技术投入但能立刻提升评审质量。4.2 提示词协议的设计要点提示词是这个 Skill 的灵魂。我前后改了七八版总结出几个关键原则。第一把证据采集和代码生成绑定成同一个动作。不要让 AI 先写代码再补证据而是要求它在输出代码块的同时输出对应的决策记录。提示词里可以这样写在生成每个代码改动时同步输出一条决策记录包含 - 改动位置文件行号范围 - 改动理由一句话必须能对应到具体代码事实 - 参考的上下文文件行号 - 考虑过的替代方案及放弃原因第二要求 AI 标注不确定性。如果它对某个判断没把握必须显式说出来。这一点极其重要因为 AI 最危险的行为不是写错而是自信地写错。我在提示词里加了一句“如果你对某个改动的影响面不确定必须标注为待确认”效果立竿见影。第三限制证据的长度。每条决策记录控制在两三句话逼 AI 说重点。长篇大论的解释往往是废话短而具体的才可信。4.3 评审视图的生成流程有了证据和 diff接下来是生成评审视图。这一步我写了一个小脚本流程大致如下解析 AI 输出的代码块和决策记录按文件分组对每个文件生成 diff计算改动行号范围把决策记录按行号范围挂到对应的 diff 片段上输出一份 Markdown每个改动点下面折叠着它的证据生成出来的视图大概长这样### order_service.py **改动 1第 145-152 行** diff - if refund_amount order_amount: if refund_amount order_amount - already_refunded:决策记录理由修复部分退款场景下可退金额计算错误参考对账任务 bug 记录 #2231替代方案在调用方校验放弃会漏掉内部调用影响面退款接口、对账任务可信度强可核对 bug 记录这个视图的好处是评审者可以先扫 diff对某个改动有疑问时再展开证据。信息密度高但不干扰主流程。4.4 一个完整的实操案例我拿一个真实场景走一遍。需求是“修复优惠券叠加使用时金额计算错误”。AI 生成的改动涉及三个文件我按流程走下来。第一步Agent 生成代码和决策记录。它改了coupon_service.py的叠加逻辑、order.py的金额字段计算、以及一个测试文件。决策记录里提到它参考了coupon_service.py里已有的单券计算函数选择复用而不是重写。第二步生成评审视图。diff 显示coupon_service.py改动最大有 40 多行。展开证据后看到AI 把原来的嵌套判断拆成了两个独立函数理由是“降低圈复杂度便于测试”。第三步人工核对。我重点看了两处一是它复用的单券函数是否真的适用于叠加场景二是拆分后的函数有没有改变原有行为。核对下来发现复用是对的但拆分时漏掉了一个边界判断导致某类券在特定顺序下会重复计算。第四步把问题反馈给 Agent让它补充边界判断并更新决策记录。第二次生成的证据链里明确标注了“已补充边界判断参考测试用例 test_coupon_stack_edge”。整个过程下来评审时间比裸看 diff 少了大概一半而且发现了一个裸看 diff 很可能漏掉的问题。这就是证据链的价值它不保证 AI 不犯错但它让错误更容易被发现。5. 常见问题与排查技巧实录5.1 证据链造假怎么办这是被问得最多的问题。AI 会不会编造参考文件、编造理由会而且很常见。我的应对策略有三条。第一所有“参考文件”必须可核对。Skill 在呈现证据时自动去仓库里验证引用的文件是否存在、行号是否对得上。对不上的直接标红评审者一眼就能看出问题。第二理由必须能对应到代码事实。像“这样更优雅”这种主观理由Skill 直接过滤掉不展示。只保留能落到具体代码、具体测试、具体 issue 的理由。第三交叉验证。如果 AI 说“参考了 X 文件的实现”那就去看 X 文件的实现和当前改动是否真的一致。不一致的地方往往就是它编的。注意不要因为 AI 会造假就放弃证据链。裸 diff 时代评审者连造假的机会都没有因为根本没有信息。有证据链至少给了你一个可以质疑的靶子。质疑一个具体的说法比质疑一团空气容易得多。5.2 证据太多看不过来怎么办这是另一个极端。AI 有时候会输出一大堆决策记录每条都写得很详细评审者反而被淹没。我的处理方式是分级展示。改动类型证据展示策略核心逻辑变更完整展示证据链格式调整、重命名折叠证据默认不展开测试文件变更只展示覆盖了哪些场景配置文件变更高亮展示强制核对核心思路是把评审者的注意力引导到真正有风险的地方。格式调整这种改动证据再详细也没人看不如折叠起来。核心逻辑变更哪怕证据少也要强制展开。5.3 团队不配合怎么办推行任何新流程都会遇到阻力。我踩过的坑是一开始想一步到位要求所有 MR 都必须带证据链结果大家嫌麻烦阳奉阴违。后来改成渐进式推行。第一阶段只要求 AI 生成的代码带证据链人工写的代码不强制。第二阶段把证据链作为“加分项”而不是“必填项”在评审时优先看有证据链的 MR。第三阶段等大家尝到甜头再逐步变成规范。这个过程中最关键的是让评审者先受益。当评审者发现看带证据链的 MR 比看裸 diff 快很多、准很多时他们会主动要求写代码的人补证据。这种自下而上的推动比自上而下的强制有效得多。5.4 常见问题速查表问题现象可能原因排查方向证据链为空提示词未约定输出协议检查生成阶段的提示词参考文件对不上AI 编造上下文开启文件核对标红异常理由过于笼统提示词未限制长度和具体性要求理由必须对应代码事实评审视图加载慢证据未分级全量渲染引入折叠和分级展示影响面分析缺失未要求 AI 做调用方分析在提示词中增加影响面字段6. 我对这套方案的真实体会用到现在我最大的感受是AI 编程的瓶颈从来不在生成速度而在信任建立的速度。代码生成得再快如果每次合并都要人从头到尾重新理解一遍那省下来的时间又还回去了。证据链做的就是把“理解成本”从评审者身上转移一部分到生成阶段让 AI 自己把推理过程交代清楚。当然这套东西不是银弹。它依赖 AI 的诚实度依赖提示词的质量依赖团队的配合。但相比裸 diff 评审它至少把“敢不敢合并”这个问题从凭感觉变成了有依据。我现在的习惯是看到没有证据链的 AI 生成代码心里会本能地打个问号哪怕它测试全过。这个问号就是这套 Skill 给我带来的最大改变。最后分享一个我最近在试的扩展方向把证据链和代码覆盖率报告打通。让 Skill 在呈现证据时自动标注每个改动点有没有被测试覆盖、覆盖的是哪个用例。这样一来评审者不仅能看到“AI 为什么这么改”还能看到“这个改动被验证到什么程度”。两个信息一叠加合并决策的底气会足很多。这个方向我还在打磨等跑顺了再单独写一篇。