1. 为什么“敢不敢合并”成了 AI 编程时代的新瓶颈过去一年我身边几乎所有写代码的朋友都在用 AI 辅助编程。从最初的代码补全到后来整段函数生成再到现在 Agent 直接改多个文件、跑测试、提 PR效率提升是肉眼可见的。但有意思的是一个奇怪的现象开始普遍出现代码写得越来越快合并却越来越慢。我自己的团队就经历过这个阶段。一个中等规模的重构任务以前人工写大概两天现在 AI 半小时就能产出一版看起来像模像样的改动。可真正卡住我们的不是生成而是评审。打开git diff几百行改动铺满屏幕逻辑看着对风格也统一测试也过了但你就是不敢点那个 Merge 按钮。为什么因为你不知道这些改动里有没有藏着“看起来合理但实际错误”的东西——比如边界条件被悄悄改掉、异常处理被简化、某个副作用被遗漏。这就是标题里说的核心问题AI 写代码之后真正难的是“敢不敢合并”。生成能力已经过剩信任能力才是稀缺资源。而信任不是靠感觉是靠证据。所以我想聊聊一个我实际用下来很顺手的思路给代码评审配一个带证据链的 Skill让每一次合并都有据可查而不是靠“我觉得应该没问题”。这篇文章适合三类人看一是已经在用 AI 写代码但评审环节还很随意的开发者二是正在搭 Agent 工作流、想把评审自动化的团队三是对“Skill”这个概念还比较模糊、想知道它和普通脚本有什么区别的人。我会从设计思路讲到具体实现再到踩过的坑尽量把能直接抄的部分都写清楚。2. 先搞清楚这里的 Skill 到底指什么2.1 Skill 和普通脚本、Agent 的区别热词里出现了很多相关词skill、agent、agent skill、codex skill、skill 脚本。很多人第一次听到“Skill”会以为是某个平台的插件其实在 AI 编程语境下它更像是一种封装好的能力单元。我自己的理解是这样的脚本输入固定输出固定逻辑写死比如一个 lint 脚本。Agent有自主决策能力能根据目标自己规划步骤、调用工具。Skill介于两者之间它定义“在什么场景下、按什么流程、产出什么证据”的一套可复用能力。Agent 可以调用 SkillSkill 内部也可以调用脚本和模型。打个生活化的比方Agent 是一个会自己想办法的实习生Skill 是他手里的一本“操作手册加检查清单”。手册告诉他遇到代码评审该看哪些点、该留下什么记录但具体怎么判断还是靠他的能力。这样既保留了灵活性又保证了流程不跑偏。我推荐的这个评审 Skill核心不是让 AI 替你决定合不合并而是让它产出一条可追溯的证据链把“为什么可以合”这件事变成看得见的东西。2.2 为什么评审需要“证据链”先说一个我踩过的坑。早期我们让 AI 直接给评审结论提示词大概是“请评审这个 diff 并告诉我能不能合并”。结果它经常给出一段很自信的话“改动逻辑清晰未发现明显问题建议合并。”听着挺舒服但有一次合并后线上出了个空指针回查发现 AI 根本没注意到某个分支下变量可能为 null。它不是故意漏而是这种“结论式评审”没有强制它去核对每一个风险点。证据链的思路正好相反不直接给结论而是先收集证据再让结论从证据里长出来。具体来说一次评审要留下这些东西这次改动涉及哪些文件、哪些函数、哪些行为发生了变化每个变化点对应的原始代码和新代码对比针对风险点的检查记录边界、异常、并发、副作用等测试覆盖情况哪些路径被验证过哪些没有最终结论以及支撑这个结论的具体证据编号有了这条链合并的人不需要盲信 AI他可以顺着证据一条条看。哪怕 AI 判断错了你也能快速定位是哪一环出的问题。这比“AI 说没问题”可靠太多了。3. 评审 Skill 的整体设计与思路拆解3.1 核心设计原则先取证后判断我在设计这个 Skill 的时候给自己定了三条原则后来发现每一条都对应着实际踩过的坑。第一条证据和结论分离。模型很容易在生成证据的同时就把结论带出来然后为了自圆其说后面的证据会不自觉地偏向结论。所以我把流程拆成两个阶段第一阶段只做信息提取和风险扫描禁止下结论第二阶段才基于第一阶段的结构化输出做判断。这样能明显减少“先有结论再找理由”的情况。第二条每个风险点都要有明确的检查动作。不能只说“检查了边界条件”而要具体到“检查了第 42 行数组访问的索引范围输入为空时返回默认值”。动作越具体越难糊弄。第三条证据要能被机器和人都读懂。我用结构化的 JSON 存证据方便后续 Agent 消费同时生成一份 Markdown 摘要方便人快速浏览。两者内容一致只是呈现方式不同。3.2 为什么选 git diff 作为切入点热词里有git diff这其实是整个评审的起点。AI 改代码之后变化都体现在 diff 里。diff 有几个天然优势它是增量的只关注变化部分信息密度高它是结构化的有明确的文件、行号、上下文它还是版本化的可以精确对应到某次提交。但直接用原始 diff 有个问题上下文太少。一个函数被改了中间几行diff 只显示周围三行评审者很难判断这个改动对整体逻辑的影响。所以我在 Skill 里加了一步“上下文扩展”对每个改动块自动拉取所在函数的完整定义、相关的类型声明、被调用的地方。这样证据链才完整。我试过只给模型原始 diff它经常误判因为看不到函数全貌。加上上下文扩展之后判断准确率提升很明显。这一步看起来不起眼但它是整个 Skill 能不能用的关键。3.3 方案选型为什么不用现成的评审工具市面上有不少静态分析和代码评审工具我为什么还要自己搭 Skill原因有三个。第一通用工具不懂业务语义。比如我们有个字段叫status取值 0 到 5其中 3 表示“已取消”。静态工具看到if (status 3)不会觉得有问题但如果 AI 把判断改成了if (status 3)语义就完全变了。这种问题只有结合业务上下文才能发现而 Skill 可以把业务规则作为知识注入。第二通用工具不产出证据链。它们给的是告警列表不是“为什么可以合”的论证过程。而我要的恰恰是后者。第三Skill 可以随团队演进。今天发现一类新风险明天就能加进检查清单不用等工具厂商更新。这种灵活性在快速迭代的团队里特别重要。当然我不是说通用工具没用。我的做法是把它们作为 Skill 的一个环节先跑 lint 和类型检查把结果作为证据的一部分再由模型做语义层面的判断。两者互补而不是替代。4. 核心细节解析与实操要点4.1 证据链的五个组成部分我把证据链拆成五个部分每一部分都有明确的产出格式。这里详细说一下因为这是整个 Skill 的骨架。第一部分变更清单。列出所有被修改的文件每个文件里被改动的函数或类以及改动的类型新增、删除、修改。这一部分相对机械用脚本就能提取但要注意重命名和移动的情况否则会误判为删除加新增。第二部分行为差异。这是最关键的部分。对每个改动点描述“改动前是什么行为改动后是什么行为”。注意这里说的是行为不是代码。比如“原来在用户不存在时抛异常现在返回 null”。行为差异写清楚了风险自然就浮现了。第三部分风险扫描记录。针对几类常见风险逐项检查边界条件、空值处理、异常路径、并发安全、资源释放、副作用顺序。每一项都要写清楚检查了什么、结论是什么。没检查的也要写明“未覆盖”不能留空。第四部分测试证据。哪些测试跑了、通过了哪些新增路径没有测试覆盖。这一部分我特别看重因为 AI 生成的代码经常测试通过但覆盖不全。第五部分结论与置信度。基于前四部分给出结论并标注置信度。置信度低的时候明确写出“建议人工重点看哪几处”。4.2 提示词设计的关键技巧Skill 的核心是提示词。我调了很多版总结出几个关键点。技巧一用角色和约束开头。比如“你是一名严格的代码评审员你的职责是找出风险而不是确认正确。在收集完所有证据之前禁止给出合并建议。”这句话能明显改变模型的行为倾向。技巧二强制结构化输出。我要求模型按固定 JSON schema 输出每个字段都有明确含义。这样后续处理方便也逼着模型把话说清楚不能含糊。技巧三给反例。在提示词里放几个“错误评审”的例子比如“仅凭测试通过就建议合并”“忽略空值分支”。模型看到反例后会主动避开这些模式。这一招我觉得特别有效。技巧四分步执行。不要让模型一步到位。我把它拆成“提取变更 → 扩展上下文 → 扫描风险 → 汇总证据 → 生成结论”五步每步单独调用上一步的输出作为下一步的输入。虽然调用次数多了但质量稳定得多。4.3 上下文扩展的具体做法前面提到上下文扩展很重要这里说下具体怎么做。对 diff 里的每个改动块我会做三件事拉取所在函数的完整源码。通过解析 diff 的 hunk header 拿到行号范围再从文件里截取整个函数。拉取相关的类型和接口定义。如果改动涉及某个对象把它的类型定义也带上。拉取调用方。用简单的文本搜索找出哪些地方调用了这个函数列出调用点。这三步做完模型看到的就不再是孤立的几行代码而是一个有上下文的改动。实测下来误判率能降不少。当然调用方搜索可能不准所以我在证据里标注了“调用方列表基于文本匹配可能有遗漏”让评审者心里有数。注意上下文扩展会增加 token 消耗。我的经验是对小型 diff 全量扩展对大型 diff 只扩展高风险改动块比如涉及条件判断、异常处理、资源操作的部分。这样能在成本和效果之间取得平衡。5. 实操过程与核心环节实现5.1 环境准备与依赖先说下我用的技术栈不复杂都是常见工具。语言Python 3.10 以上版本控制git模型调用任意支持结构化输出的模型接口辅助工具gitpython用于读取 diffpydantic用于定义证据结构安装依赖就一行pip install gitpython pydantic我选 Python 是因为生态成熟处理文本和调用模型都方便。如果你团队用 Node 或 Rust思路一样只是实现细节不同。热词里提到“基于 rust 语言 ai agent”其实用 Rust 写性能更好但对这个场景来说 Python 足够了开发效率更重要。5.2 第一步提取变更清单先写一个函数从 git 仓库读取指定提交范围的 diff解析出变更清单。import git from pydantic import BaseModel class ChangeItem(BaseModel): file: str change_type: str # add / delete / modify symbol: str # 函数或类名 start_line: int end_line: int def extract_changes(repo_path: str, base: str, head: str): repo git.Repo(repo_path) diff repo.git.diff(base, head, unified0) # 解析 diff提取文件和 hunk 信息 # 这里省略具体解析逻辑核心是按 行号定位改动块 changes [] # ... 解析过程 ... return changes解析 diff 的时候有个细节要注意unified0只给改动行不给上下文这样解析更简单上下文我们后面单独扩展。如果直接用默认的unified3反而容易把上下文行误当成改动行。5.3 第二步扩展上下文拿到变更清单后对每个改动块扩展上下文。def expand_context(repo_path: str, change: ChangeItem): with open(f{repo_path}/{change.file}, encodingutf-8) as f: lines f.readlines() # 向上向下查找函数边界 func_start find_function_start(lines, change.start_line) func_end find_function_end(lines, change.start_line) func_body .join(lines[func_start:func_end]) # 查找调用方 callers find_callers(repo_path, change.symbol) return { function_body: func_body, callers: callers, }find_function_start和find_function_end的实现依赖语言。对 Python 可以用ast模块对 Java 或 Go 可以用简单的括号匹配。我一开始想做得通用后来发现按语言分别处理更靠谱因为缩进和括号规则差异太大。5.4 第三步风险扫描这一步是调用模型的核心环节。我把提示词分成系统提示和用户提示两部分。系统提示大致是这样你是一名严格的代码评审员。你的职责是发现风险而不是确认正确。 在收集完所有证据之前禁止给出合并建议。 对每个改动点你必须检查以下风险类别 1. 边界条件数组越界、循环边界、数值范围 2. 空值处理可能为 null 的变量、可选参数 3. 异常路径异常是否被吞掉、错误码是否正确传递 4. 并发安全共享状态、锁的使用 5. 资源释放文件、连接、内存 6. 副作用顺序多个副作用之间的依赖关系 对每一类明确写出检查了什么、结论是什么。未检查的写未覆盖。用户提示里放上变更清单和扩展后的上下文要求模型按 JSON 输出风险扫描结果。这里有个经验风险类别不要太多。我一开始列了十几类结果模型每类都写得很浅。后来精简到六类每类的检查质量明显提升。少即是多这个道理在提示词设计里同样成立。5.5 第四步汇总证据并生成结论风险扫描完成后把所有证据汇总再调用一次模型生成结论。这次提示词的重点是“结论必须引用证据编号”。def generate_conclusion(evidence: dict): prompt f 基于以下证据给出评审结论。 要求 1. 结论只能是建议合并、建议修改后合并、不建议合并三者之一 2. 每个结论必须引用至少两条具体证据 3. 标注置信度高/中/低 4. 置信度为中或低时明确指出需要人工重点检查的位置 证据{evidence} # 调用模型 return conclusion我特意加了“引用证据编号”这个约束因为不加的话模型容易写空话。加了之后它必须回到证据里找支撑结论的可信度就上来了。5.6 第五步输出可读报告最后把结构化证据和结论渲染成 Markdown 报告。我用的模板大概长这样## 评审报告 ### 变更概览 - 文件数3 - 改动函数5 - 新增行120删除行45 ### 风险扫描 | 风险类别 | 检查结论 | 证据编号 | |---------|---------|---------| | 边界条件 | 第 42 行索引未做上界检查 | E-003 | | 空值处理 | 已覆盖返回默认值 | E-005 | | ... | ... | ... | ### 结论 建议修改后合并置信度中 依据E-003 显示存在越界风险E-007 显示该路径无测试覆盖。 需人工重点检查第 42 行附近的数组访问逻辑。这份报告可以直接贴到 PR 评论里评审者扫一眼就能抓住重点。我团队现在基本形成了习惯AI 提的 PR先看这份报告再决定要不要细看 diff。6. 常见问题与排查技巧实录6.1 模型误判怎么办这是最常见的问题。我遇到过的误判主要有三类。第一类把正确改动判成风险。比如 AI 把某个冗余判断删掉了模型却认为“删除了必要的检查”。这种情况通常是因为上下文不够模型不知道那个判断确实是冗余的。解决办法是在证据里加上“该判断的历史提交记录”或者“相关注释”让模型有更多依据。第二类漏掉真正的风险。比如某个改动引入了微妙的并发问题模型没看出来。这种最难防。我的做法是维护一个“历史踩坑清单”把团队过去出过的问题整理成检查项定期更新到提示词里。相当于让 Skill 带着经验成长。第三类结论摇摆。同样的 diff 跑两次结论不一样。这通常是温度参数太高。我把温度调到 0.2 以下稳定性明显改善。对评审这种任务确定性比创造性重要得多。6.2 大型 diff 怎么处理改动超过 500 行的时候一次性塞给模型效果很差它会顾此失彼。我的策略是分块处理再汇总。具体做法按文件或按函数把 diff 切成若干块每块单独做风险扫描最后把所有块的证据合并再生成整体结论。这样每块都能得到充分关注不会因为量大而稀释。但分块有个副作用跨块的关联风险可能被漏掉。比如 A 文件改了函数签名B 文件改了调用方式分开看都没问题合起来才看得出是否匹配。所以我在汇总阶段加了一步“跨块一致性检查”专门看接口和调用是否对齐。6.3 常见问题速查表问题现象可能原因排查方向结论总是“建议合并”提示词偏向确认加强“找风险”的角色设定加入反例证据空洞没有具体行号输出格式约束不够强制 JSON schema要求引用行号上下文扩展失败语言解析规则不匹配按语言分别实现边界查找报告太长没人看证据粒度太细摘要层只保留高风险项详情折叠调用成本过高全量扩展上下文只对高风险改动块扩展结论前后矛盾温度过高或分步不一致降低温度固定分步流程6.4 几个我踩过的坑坑一过度依赖模型判断。我一开始想让 Skill 全自动决定合不合并后来发现不行。模型再强也有盲区尤其是业务语义。现在的做法是 Skill 给建议人做最终决定。这个边界一定要划清楚否则迟早出事。坑二证据链太长导致没人看。第一版报告动辄几千字结果没人读。后来我改成两层顶层是摘要只列高风险项和结论详情放在折叠区需要时再展开。阅读率一下就上来了。坑三忽略测试证据。有段时间我只关注代码逻辑没管测试覆盖。结果合并了几次“逻辑看着对但没测试”的改动后来出了问题。现在测试证据是必填项没有覆盖的路径必须显式标注。提示Skill 的价值不在于替代人而在于把人从重复的核对工作中解放出来让人专注于真正需要判断力的部分。想清楚这个定位很多设计取舍就清晰了。7. 让评审 Skill 持续进化的几个做法Skill 不是写完就完了它需要跟着团队一起成长。我目前的做法有这么几个。定期回顾误判案例。每次出现评审失误我都会把那个 diff 和当时的证据链存下来分析是哪一环没做好然后更新提示词或检查清单。积累几个月后Skill 的准确率会有肉眼可见的提升。把团队规范编码进去。每个团队都有自己的编码习惯和禁忌比如“禁止在循环里做数据库查询”“所有外部调用必须设超时”。这些规范写进 Skill 的检查项评审时自动核对比靠人记靠谱。和 Agent 工作流打通。现在我的流程是Agent 生成代码 → 自动触发评审 Skill → 产出证据链报告 → 人看报告决定。整个链路跑通后从生成到合并的时间缩短了不少而且心里更有底。热词里提到的“多 ai 协作”“agent 开发”其实最终都要落到这种具体的协作环节上光有生成能力不够还得有验证能力。保留人工复核入口。不管 Skill 多完善我都会在流程里留一个“人工复核”的开关。高风险改动、涉及核心模块的改动强制走人工。这不是不信任 AI而是对线上负责。我个人在实际操作中的体会是AI 编程带来的最大变化不是写代码变快了而是评审的权重变高了。以前评审是走个流程现在评审是真正的质量关口。把评审做成一个有证据链的 Skill本质上是在为“敢合并”这件事建立信任基础。信任不是靠感觉是靠一条条看得见的证据堆出来的。这个思路我觉得不只适用于代码评审任何 AI 参与决策的场景都值得配一条这样的证据链。