把资深工程师评审直觉封装成可安装的AI skill包

把资深工程师的评审直觉做成可安装的 skill这句话在我脑子里转了很久。起因很简单我们组那位写了十几年后端的老师傅每次 code review 都能一眼看出一堆问题——缓存穿透、事务边界、并发下的数据竞争、接口设计的扩展性隐患。这些不是靠工具扫描出来的而是靠多年踩坑形成的直觉。最近半年 AI agent 生态爆发尤其是我一直在用的 Claude Code 这类工具开始支持 skill 机制我才意识到这种评审直觉并不是只能留在脑子里的私有资产它可以被结构化、被打包、被安装变成团队里任何人都能调用的公共能力。我花了两周时间把这位老师傅的评审经验拆成了 25 个技能又花了一周设计了一套 9 条命令的管理管线最终做成一个可以直接安装的 skill 包。这篇博文就记录一下这件事的完整过程25 个技能怎么拆、9 条命令怎么设计、实际跑 review 是什么效果、中间踩了哪些坑。如果你想把自己或团队里的隐性经验变成可复用的 AI 资产这篇东西应该能帮你省下不少弯路。1. 经验被困在脑子里是所有评审体系的共同瓶颈1.1 评审直觉的本质是模式识别但模式无法传递写代码这件事从入门到熟练最大的变化不是打字速度而是看一眼就知道哪里会出事的能力。资深工程师看一段代码脑子里会同时跑好几条线索这个接口的入参校验够不够这个循环体里有没有可能累积内存这条 SQL 的索引走了没有这个事务里有没有跨网络 IO这些判断其实都是模式识别——过去的某次线上故障在脑子里留下了一个隐患特征下次看到相似代码直觉就被触发了。问题在于这种模式识别能力高度依赖个人经验而且很难用文档传递。我们组之前也做过评审 Checklist写得挺细分门别类列了 50 多条检查项。结果呢新人 review 时对着 checklist 逐条打勾照样发现不了核心问题老师傅依然靠直觉扫一眼就知道哪里不对。原因很简单checklist 只告诉你要检查什么没告诉你问题长什么样。真正的模式是案例、特征、上下文三者绑在一起的这种东西表格无法承载。1.2 skill 这种形态恰好补上了经验传递的缺口AI agent 里的 skill 概念通俗讲就是给大模型装上一套可随时调用的领域能力包。它区别于普通 prompt 文档的地方在于skill 是有触发逻辑、有执行步骤、有输入输出规范的结构化技能插件。你告诉 agent用 review 模式帮我看这次提交它会加载对应的技能集按照预设的检查路径逐项扫描甚至能把发现的问题按严重程度整理成报告。这其实是把评审直觉转化成可执行资产的机会老师傅脑中的模式识别可以变成 skill 里明确的检测步骤和判断规则而 skill 本身又支持安装、卸载、升级、分享正好解决经验只在一个人脑子里的问题。动手之前我专门确认了三件事这套 skill 包能不能在常见 agent 环境下安装命令体系能不能覆盖日常的增删改查25 个技能是不是真能覆盖我们团队 80% 的评审场景三件事都有明确答案之后就开工了。1.3 目标定得很克制不追求替代人只追求拉高下限在正式拆解技能之前我必须先把边界讲清楚。做这套东西我的目标不是让 AI 替代资深工程师做评审而是把评审能力的下限拉高。团队里不是每个人都有十年经验新人提交的代码如果能在合入之前被一套可靠的经验库扫一遍把明显的架构隐患、安全漏洞、性能问题挡下来人工评审就能把时间花在更高级的设计讨论上。这个定位直接影响了我后续的所有设计技能的数量不用多到吓人但要覆盖高频高危害的问题命令的数量也不求大而全9 条足够覆盖整个生命周期的管理。想清楚这一点后面所有的取舍都变得非常简单。2. 25 个技能是怎么拆出来的从评审清单到可执行规则2.1 切分维度按缺陷类别切而不是按项目模块切拆技能之前最纠结的就是按什么维度切。一开始我参考常见的代码分析工具SonarQube、CodeScene 之类的分类打算按代码规范、bug 检测、安全漏洞、测试覆盖率切。但跟老师傅聊了两次之后发现他脑子里的分类完全是另一套逻辑他关心的是运行时数据流、资源生命周期、并发边界、接口契约这套分类更接近系统运行时的风险面而不是静态代码的坏味道。最终我选择了按缺陷类别切而不是按项目模块切。原因很简单一个 skill 如果绑定在具体模块上换个项目就废了而按缺陷类别切无论前端后端、新项目老项目同一套检查逻辑都能用。25 个技能里每一条对应一类高频且高危害的缺陷模式彼此之间尽量不重叠这就是我理解的正交性。2.2 每条 skill 的骨架触发条件、检查点清单、证据分级、修复建议25 个技能不是 25 段 prompt而是一套统一的技能模板。每条 skill 包含四个固定部分触发条件什么样的代码场景会激活这个技能。例如数据库事务在循环体内开启触发事务检查技能外部输入直接拼入 SQL触发注入检查技能。检查点清单5-8 个明确的检查步骤每一步都对应一种可识别的问题特征。证据与严重级别发现问题后要给出具体的代码位置、上下文摘要并按严重程度分级——P0 是必然导致故障的P1 是高概率出事的P2 是建议改进的。修复建议不是丢一句请优化而是给出针对这个场景的推荐写法最好附一个代码片段级的方向。这套骨架设计来源于一个朴素的观察让 AI 评审最怕的就是正确的废话。如果只输出这段代码存在风险不指出风险的确切位置和触发路径那它只相当于一个没写过多少代码的新人说了句我觉得这里有隐患没有任何实操价值。所以每条 skill 内部证据链比结论更重要。2.3 25 个技能的完整清单与分组这里直接把 25 个技能的清单列出来按六个组归类方便大家对照自己的场景做取舍。我刻意保留了最初迭代时的分组逻辑你可以看到它不是按技术栈分的而是按出问题的时刻分的。分组技能名称核心检查对象典型缺陷示例架构架构分层校验包依赖方向、模块引用业务模块直接依赖 DAO 实现架构状态机完整性状态枚举迁移订单状态缺少取消分支数据事务边界审计事务内 IO、锁事务里发 HTTP 请求数据慢查询特征识别SQL、索引使用无索引的全表扫数据连接与资源释放连接池、流关闭try 中取连接不归还并发共享状态竞争静态变量、全局缓存无锁的并发计数并发锁顺序一致性嵌套锁、两把锁加锁顺序不一致导致死锁接口接口契约校验入参出参、版本兼容删除不兼容字段未标弃用接口鉴权覆盖检查白名单、权限注解新接口漏配权限校验接口数据校验完备外部入参、边界值金额字段可传负数性能循环内副作用循环内的 IO、计算for 循环内调远程服务性能大对象生命周期大内存对象持有局部大对象被全局引用性能缓存设计与一致性缓存 key、过期、穿透缓存只绕开了一半路径安全注入类风险SQL、命令、模板参数拼接执行命令安全敏感信息暴露日志、响应体将 token 打进日志安全越权路径探测水平/垂直越权仅靠前端隐藏按钮控制权限可维护性错误处理完整性吞异常、空 catchcatch 后无任何日志可维护性魔法值规范硬编码数值/字符串状态码直接写死为 3可维护性重复代码识别同构逻辑跨方法复制复制粘贴三份校验代码可维护性命名与意图一致性命名、注释命名是 A 实现是 B测试关键路径覆盖检查核心分支是否可测支付成功分支无用例测试测试断言质量断言强度只断言不为空不断言值兼容性序列化兼容对象字段增删新字段破坏旧数据反序列化兼容性对外契约演进接口内部变化换了实现类型影响外部调用方工程配置与环境隔离硬编码环境、密钥配置测试环境地址写进代码这个清单前后迭代了三轮。第一轮 40 多个太多很多技能之间互相覆盖第二轮砍到 20 个发现有些高频场景漏了第三轮才稳定到 25 个。我的感受是数量不重要覆盖率和技能的正交性才重要。宁可 20 个完全正交也不要 35 个重叠度高的。2.4 优先级与技能间依赖25 个技能不能每一条都一视同仁。扫描一份提交时我会按严重级别配置默认权重P0 级缺陷能确认会直接导致故障的优先输出P1 次之P2 作为建议放置末尾。每一条 skill 里也内置了一个星标字段它决定这条技能在资源受限时是否优先执行。技能之间的依赖也要处理。比如数据校验完备多半会引出接口契约校验共享状态竞争往往会引出缓存设计与一致性。我在每个技能的事件输出里都会带上相关技能建议字段这样 agent 不是机械地跑完 25 个独立检查而是能从一个问题跳转去验证相关联的问题。这个设计在后面的实际 review 中非常有用它让 AI 的评审更像人——发现一个可疑点后顺着往下挖而不是孤立地打勾。3. 9 条命令怎么管理这一整套技能3.1 为什么非要一套命令体系技能拆好了问题是它们怎么被安装、验证、更新、回滚。如果你只是本地调试把文件放进 skills 目录就完事了不需要命令。但一旦你要把 25 个技能交给团队其他成员让别人在一个陌生的环境里快速启用就必须有一套可习得的命令。9 这个数字我纠结了很久太少了覆盖不住管理需求太多了增加学习成本。最后敲定的 9 条刚好覆盖安装-查看-验证-更新-回滚-发布这一整条生命周期。3.2 命令总览命令作用对应场景skill install 来源安装技能包或单个技能新环境首次部署skill list [组名]列出已安装技能及版本随时确认本机技能清单skill show 技能名查看单条技能的完整内容排查某个技能行为异常skill verify [--all]校验技能包结构与依赖完整性安装后、提交前自检skill update 技能名升级某个技能到新版本规则调整后的同步skill rollback 技能名回滚到上一个可用版本新版本效果变差skill pack 输出目录将技能包打成可分发的压缩包发布给团队或社区skill publish 远端地址推送到团队私有仓库团队统一同步skill doctor体检环境目录、鉴权、版本兼容性安装失败或行为异常时这套命令全部走一个同名 CLI 入口skill子命令的写法参考了我们后端同事最熟悉的工具链习惯git、npm 这类保证零认知负担。命令执行完都有统一的输出格式成功或失败、影响的技能清单、当前版本号、所耗时间。3.3 三条最核心的命令install、verify、rollbackinstall 是使用频次最高的命令。它要做的事情不只是把文件复制进指定目录而是要解决三个问题第一检查目标环境里 agent 的 skill 加载路径路径不对直接报错提示第二检查技能包内每条技能的结构是否符合模板规范不符合就标记为 failed 并回滚整个安装事务第三在 install 完成后自动跑一遍 verify确保装完即可用。verify 是这套体系里我最建议你在正式使用前跑一遍的命令。它会对整个技能包做三重校验结构校验每个技能是否包含触发条件、检查点、证据、修复建议四件套、引用校验技能之间的相关建议字段是否指向存在的技能名、环境校验当前 agent 版本是否兼容技能包声明的版本要求。我在把技能包交给团队其他成员时全部依赖这份校验报告来兜底避免别人一装就报错的尴尬。rollback 则是那个希望永远用不上但必须得有的命令。因为规则类技能在迭代时很可能会出现新版本误报率突然上升的情况。rollback 的设计很简单每次 update 前系统会把旧版本快照存入一个隐藏的备份目录执行 rollback 时自动恢复上一个完整快照同时输出新旧版本的差异摘要。整个过程不依赖外部存储完全是幂等的可以反复执行。3.4 目录规范与命名约束命令要有效底层必须有一套严格的目录规范。每一条技能在我的体系里是一个独立目录命名为review-组名-技能名比如review-data-connection。目录内部固定包含skill.json元信息、prompt.md检查逻辑主体、examples/正例反例作为 few-shot 示例、version/版本号与变更记录。目录名和文件名的约束是整个体系的骨架install 和 verify 都依赖这个约定来解析技能包结构。这套命名规则不是拍脑袋定的。它参考了业界常见的 plugins 目录组织方式同时加入了一个非常关键的约束技能名必须用短横线分词禁止用驼峰。原因很简单命令行的参数解析、agent 的路径引用、日志输出里短横线比驼峰的跨平台一致性更好不会出现大小写在不同系统下行为不一致的问题。4. 真实跑一次评审从提交到产出报告的完整链路4.1 接入方式让技能包自动参与评审整个体系设计完毕之后最难的不是写技能而是让它融入团队现有的工作流。我们团队日常用 agent 辅助编程所以在构建过程里增加了一个 review 环节新代码提交后用skill install安装好的技能包调用 agent 的 review 能力扫描本次改动文件。我会在调用指令的最前面告诉 agent基于你的代码评审技能针对本次 git diff 执行检查只报告确认的问题按严重级别排序输出。这一步的关键点在于不要试图让技能包替 agent 做所有推理而是让技能包给 agent 提供评审的框架。25 个技能在 prompt.md 中为 agent 提供了明确的检查路径和判据agent 是根据这些判据去分析代码而不是让模型空想。4.2 一次输入输出的实际例子我拿一个典型的提交来演示这个提交给订单服务加了一个导出功能导出一个 CSV 文件。变更大概 200 行触发了一系列技能。最终输出的报告经过整理大概是这样的结构P0导出接口没有做数据范围限定调用方传入用户 ID 后任意登录用户可导出他人订单数据 —— 直接触发了越权路径探测技能。P1导出逻辑执行期间持有数据库连接且每遍历 1000 条数据就查一次用户表 —— 触发事务边界审计与循环内副作用两个技能。P1CSV 字段直接拼接用户输入的过滤条件未做转义存在公式注入风险 —— 触发注入类风险技能。P2导出的文件名固定为export.csv没有区分批次 —— 触发魔法值规范技能。这份报告出来之后负责的同事非常惊讶因为前三个问题恰恰是人工评审时最容易漏掉的功能本身是对的、代码也能跑但这些问题的共性都是在特定数据量或特定用户下才暴露。老师傅的直觉在这里被技能包还原成了系统性的检查路径。4.3 与人工评审的配合方式skill 包跑完不是结束而是人工评审的起点。我们内部的流程是机器先跑一轮输出 P0/P1 级别的报告人工评审盯着报告里的问题逐条确认同时把注意力放在机器不擅长的部分——业务语义是否匹配、方案取舍是否合理、长期维护的扩展性。这套分工基本复刻了先让新人按清单扫一遍资深工程师看核心问题的人工模式只不过清单现在是真的会深入代码细节的 agent。实测下来我最满意的一点是误报确实在可接受范围内。按 25 个技能的阈值调优后一个 300 行左右的提交平均输出 3-5 个问题其中确认率大概在七成以上。这个体验是能真正用起来的分水岭。5. 踩过的坑与迭代记录5.1 坑一规则写得太死误报率高到没人愿意看第一版技能包我几乎把每条规则都写成绝对化表述禁止在事务中调用远程服务禁止在循环中执行查询。结果实测误报率接近一半——有些代码是在事务里确需调用外部配置中心的只读接口有些循环内查询其实是利用连接池预热的偶发操作。规则一旦绝对化AI 就会机械地报人工评审还得逐条驳斥。解决方案是把判定标准升级为场景例外结构明确的检查点保留但为每一条典型例外补充上下文。比如事务边界审计里增加了一个判断前置仅当事务体内存在跨网络的阻塞调用且无超时熔断机制时才报告 P1。这样技能变成了有经验的评审者而不是较真的自动机。5.2 坑二技能之间互相打架重复报问题25 个技能独立写的时候还没发现问题联调后发现有两条技能会互相触发导致同一处代码被报了两次问题。缓存设计与一致性和共享状态竞争就是典型一个全局缓存字段被并发写入时两条技能都会命中输出两份重复报告。这个问题逼我引入了问题去重机制每条技能报告问题时必须附带一个指纹字段指纹由文件路径行号缺陷类别组成汇总阶段按指纹去重。这个方法简单粗暴效果立竿见影。5.3 坑三团队同步与版本管理混乱最开始我只把技能包放到本地目录团队其他人各自复制结果很快出现了我改了版本 1.2他们还在跑 1.0的情况。尴尬的是有人基于旧版本报出的问题发起讨论新版本其实已经修复了那个误报。后续引入packpublish两条命令把技能包推向团队私有仓库同时强制在每次skill show的输出里附上版本号让所有人对当前跑的是哪个版本这件事有绝对共识。5.4 一点经验和建议整套方案从设计到可用大概花了三周。如果让我重新走一遍我会把时间分配往两个地方倾斜一是技能拆解前先收集至少 30 条本团队真实的历史评审案例让技能内容从案例里长出来二是在技能数量上保持克制新增一条技能之前必须回答它是否覆盖了现有技能覆盖不到的高频缺陷回答不了就不加。技能的维护是一个持续过程每有新的事故复盘我都会思考能否沉淀为一条新的检查点或一个新技能这种事故驱动迭代的方式比我一开始靠想象设计要高效得多。最后再分享一个小技巧调试单条技能时不要直接跑完整套先用skill show 技能名看它当前的触发条件和检查点再在受限的测试目录里放一小段刻意构造的缺陷代码跑一次 verify 看它能不能命中。这比我反复修改 prompt 再全量测试的效率高一个数量级。