上周帮一个团队做代码评审连续点了三个问题订单状态字段更新缺少事务边界、分页查询在循环里触发N1、新加的接口没做越权校验。团队里的小朋友很惊讶问我是不是在代码里装了雷达。其实哪有什么雷达无非是多年踩坑踩出来的条件反射。这件事让我一直在想如果这种评审直觉可以被量化、被沉淀、被随时调用团队是不是就不需要每次都仰仗某个资深工程师在场后来我把这套直觉做成了一个可安装的 skill 包结构很简单25个技能9条命令。平时它就安静地躺在你的开发工具里需要的时候一条命令拉起来按维度把代码过一遍输出的问题清单和评审意见基本就是资深工程师坐在你旁边时脑子里在转的东西。这篇就聊聊我怎么拆的、怎么装的、以及实际用下来踩过的坑。1. 为什么要把评审直觉做成一个可安装的 skill1.1 资深工程师的评审直觉到底是什么先说个容易误解的点评审直觉不是玄学也不是第六感。它本质上是一种高度压缩的模式识别。你看到状态字段在 service 层被直接 update脑子里就会自动弹出事务边界呢看到 for 循环里面嵌套了一条查询就会自动标记N1 嫌疑看到接口没有校验当前用户和资源归属关系就会自动想到越权。这些条件反射看起来是直觉其实是大量经验沉淀后的 pattern matching。问题在于这种能力长在人的脑子里没法复制。团队里有个资深工程师代码质量就有保障这个人一休假评审质量就断崖式下降。我一直在琢磨能不能把这套 pattern 显性化、结构化让工具也能具备这种评审嗅觉。一个偶然的机会我开始用 AI 编程助手做辅助评审。最初效果很不稳定——直接丢一段代码让它帮我看看有什么问题它也能说几句但特别散有时候抓着命名规范说半天真正的并发隐患没看见有时候在各种细节里打转架构层面的问题一句不提。换个问法结果又不一样。这种感觉就像你让一个实习生去评审代码他每次都能说出点东西但每次说的重点都不一样。问题出在提问方式上。AI 本身有很强的代码理解能力但它不知道一个资深工程师在面对一段代码时脑子里会按什么顺序、从哪几个维度、用什么样的标准去扫描。那些隐含的经验没有变成显式的流程。所以我的方案很直接把评审拆成 25 个具体技能再用 9 条命令调度它们相当于把资深工程师的思考清单原封不动地搬进了工具。1.2 从口头经验到可执行技能的关键转换市面上其实不缺代码评审规范文档几乎每个团队都有一份。但文档是静态的评审是动态的。文档里写着注意事务边界AI 看到这句话不知道该怎么做——什么叫注意在哪个环节注意注意成什么样算合格这就是文档和工具之间最大的鸿沟。可安装的 skill 解决的正是这个转化问题。它把一句抽象的原则变成了一条条可执行的检查规则。比如注意事务边界这条原则在 skill 里会被拆成检查方法内是否存在多次写操作、检查是否存在原子性要求、检查事务注解的作用范围、检查事务是否可能被自调用绕过。这么一层层拆下去AI 才真正知道注意两个字意味着什么。这次做的是 25 个技能、9 条命令的规模。不多不少刚好覆盖了日常评审中最常见、误报率最低、ROI 最高的那些维度。核心思路是把资深工程师脑袋里看一眼就知道有问题的那些模式一个不漏地变成可调用的规则。这篇文章会把整个设计思路、命令分布、安装方式以及实际使用中踩过的坑全部摊开来讲。2. 25个技能怎么拆出来的2.1 技能拆分的两个原则按风险域分、按评审阶段分设计技能列表的时候我给自己定了两条原则。第一条按风险域划分保证每个技能都有一个清晰的靶子第二条按评审阶段组织保证多个技能同时运行时不会乱。先解释第一条。代码评审最忌讳的就是大杂烩。安全问题和性能问题混在一起说架构问题和代码风格问题混在一起说最后开发者根本不知道先改哪个。所以我按风险域把技能分成了五组架构设计、安全防护、性能效率、可靠性健壮性、可维护性规范。每组下面对应若干具体技能每个技能只盯一类问题。第二条原则解决的是多个技能一起干活时的编排问题。比如跑一次全面评审如果25个技能同时启动、各自输出结果就是一堆碎片根本没法看。所以我把技能分成不同阶段先做全局扫描再做定向深挖最后汇总输出。这样既保证了覆盖面又避免了信息轰炸。最终拆出来的结果是一个五组二十五项的技能矩阵。架构组管模块关系和扩展性安全组管越权和注入这类高危项性能组管数据库访问模式和复杂度可靠性组管事务和异常处理规范组管可读性和维护成本。指标不贪多每个技能都能说清楚查什么、为什么查、什么算问题这就够了。2.2 技能矩阵5大类25项全览分类技能名称核心检查目标架构设计模块边界检查跨层调用、循环依赖、模块职责模糊架构设计扩展性预判新增需求时是否需要改动现有结构架构设计接口契约一致性接口入参出参是否前后端对齐架构设计技术选型合理性是否引入了不匹配当前架构的组件架构设计耦合度扫描模块间依赖方向是否合理安全防护越权访问检测接口是否校验资源归属安全防护注入风险扫描动态拼接的SQL、命令、模板是否可控安全防护敏感信息泄露排查日志、接口响应、注释中是否泄露密钥安全防护认证与会话安全会话管理、token过期、密码存储安全防护安全配置基线框架默认配置是否有已知风险性能效率N1查询扫描循环内的数据库访问性能效率索引使用预判查询条件是否命中索引性能效率大结果集加载是否一次性拉取过量数据性能效率缓存滥用识别缓存粒度、过期时间、穿透问题性能效率复杂度热点分析高复杂度函数导致的性能瓶颈可靠性健壮性事务边界审查原子性操作是否有完整事务可靠性健壮性并发控制检查共享资源的并发读写是否有保护可靠性健壮性异常吞没检测catch块是否丢弃关键错误信息可靠性健壮性资源泄漏排查连接、流、文件是否正常关闭可靠性健壮性错误处理一致性错误码、异常类型、提示信息是否统一可维护性规范命名语义检查变量、函数、类名是否表意准确可维护性规范函数粒度建议长函数拆分的具体建议可维护性规范重复代码识别可抽取公共逻辑的重复片段可维护性规范注释与文档质量必要注释是否缺失、注释是否误导可维护性规范日志规范检查日志级别、关键埋点是否合理2.3 关键技能的设计细节矩阵是骨架真正让这些技能活起来的是细节。我在设计每个技能的时候都不只是写一句检查XXX而是会给AI配上一套完整的决策逻辑触发条件、判断标准、误报抑制规则。这里拿三个典型技能展开说说。事务边界审查这个是可靠性组里最重要的技能。核心检查点有三个第一方法里是否存在多次写操作比如先 insert 再 update这种场景必须有事务第二事务注解的作用范围是否够用是不是只盖住了其中一条写操作第三是否存在自调用绕过问题也就是同类内部调用导致AOP代理失效MySQL 里的 Transactional 就这么静悄悄失效过。设计这个技能时最关键的是误报抑制有些团队会故意用最终一致性方案允许先写库再发MQ这种不能报。所以我在规则里加了一条如果代码中有补偿机制或重试机制需要降低置信度。越权访问检测这是安全组里性价比最高的一个技能。检查逻辑比较直白接口从请求参数或Session中拿用户标识时是否做了当前用户与资源归属方的比对。但实际设计时有个细节很关键——很多越权漏洞不是没比对而是比对的是前端传过来的用户ID等于没比。所以这个技能不仅查有没有比对还要查比对的数据来源是否可信。像从请求体里直接取 userId 然后传给 service 层查询这种模式基本可以判定为高危。复杂度热点分析关于这个技能有个认知需要纠正复杂度高不代表代码有问题。很多核心业务逻辑天然复杂硬要拆反而破坏可读性。所以这个技能输出的是热点提示而不是问题警告。判定标准是优先看圈复杂度和循环嵌套深度但最终报告里会提醒开发者优先关注那些又复杂又被高频调用的函数。低频冷门函数复杂度高可以放一放热门口径的核心方法复杂度高建议重构。这种分级思路能显著降低误报率。3. 9条命令的设计与调度逻辑3.1 命令即入口为什么不用自然语言技能拆好了AI才知道查什么但如果每次都要打一大段提示词去描述需求效率还是上不来。我决定加一层命令封装把25个技能编排成9条命令作为调用入口。为什么用命令而不是直接自然语言对话两个原因。第一是确定性命令的语义是固定的你输入 /review-security 就一定是安全专项评审结果不会因为提问方式的变化而漂移第二是效率命令可以带参数比如指定文件路径、指定评审深度、指定是否输出Markdown一条命令把参数说清楚AI直接开跑。这有点像 Linux 命令行的哲学把复杂操作封装成简洁的入口。git 命令之所以好用因为每个子命令都有明确的语义边界这套评审命令的设计思路完全一样。命令就是用户与技能之间的接口层它不承载具体评审逻辑只负责把用户的指令翻译成一组技能的调用。3.2 命令总览表9条命令的用途和参数命令功能主要参数/review全面评审按标准流程执行全部相关技能paths路径、depth深度/review-security安全专项评审仅执行5项安全技能paths、severity/review-perf性能专项评审仅执行5项性能技能paths、detail/review-diff增量评审只检查Git改动部分since提交/分支、paths/review-file单文件深度评审适合逐文件精读file/review-focus定向评审指定任意技能名称skill、paths/review-report生成或刷新评审报告formatmd/json、output/review-priority只输出P0/P1级问题适合快速收口paths/review-skills列出全部技能清单和最近使用记录无这9条命令覆盖了日常评审的核心场景。我最常用的是 /review-diff测下来效率提升最明显。以前人工评审一个MR要翻半天diff现在一条命令把改动文件过一遍直接在逐行审查前就能标记出高风险区域。实际跑一次大概能替代45分钟的机械走查把时间留给真正需要判断力的部分。3.3 命令背后的执行逻辑一条命令如何编排技能命令不是把技能简单堆在一起而是有编排逻辑的。拿 /review 全面评审举例它内部是一个三层流水线第一层为全局感知。快速扫描项目结构和关键文件识别出技术栈、分层方式、核心模块位置。这个阶段不会深入代码细节目的是建立全局上下文让后续技能知道自己站在什么位置看代码。第二层为分组执行。25个技能按矩阵中的分组依次运行。架构组先跑因为它看的是整体架构问题会直接影响安全和性能的判断口径。然后是安全组、性能组可靠性组合规范组放在后面。每个技能独立输出自己的发现带置信度标记。第三层为汇总排序。所有技能的结果汇总后做融合处理跨技能关联的问题会合并为一条例如N1查询和大结果集加载实际指向同一个代码段时合并成一条高优先级问题。最后按严重程度排序P0是必须阻塞发布的P1是应该在本迭代内修复的P2是建议优化项。这个编排逻辑参考的正是人工评审时的真实流程先通读了解全局再分模块细看最后汇总排序。把人的思维方式映射成流水线输出质量会稳定得多。3.4 自定义命令的扩展思路9条命令是内置的但实际用的时候难免有定制需求。比如有的团队希望评审时强制带上团队规范检查有的团队想把新增依赖审计独立成一条命令。这套结构支持扩展自定义命令其实就是重新组合技能设定固定参数。给个示例。假设团队要求所有MR合并前必须过安全评审和数据库变更检查可以自定一条命令把 /review-security 和索引使用预判这个技能绑定固定输出Markdown格式报告并只显示P0和P1问题。实现上就是在命令配置里声明两段内容调用哪些技能、以什么格式输出。不需要写额外代码纯粹是声明式配置。这里有个经验供参考一开始不用急着定制太多命令先把内置的9条用熟。用一段时间后你会发现高频场景就那么两三个这时候再沉淀自定义命令也不迟。过早定制容易把命令集搞得臃肿反而失去了命令简洁入口的意义。4. 安装与实操全过程4.1 安装前要准备的清单这套 skill 的使用环境是支持自定义技能机制的 AI 编程助手目前主流的几款都已支持。安装前需要准备的东西不多但有一个点很容易被忽略版本兼容。建议先把开发工具升级到较新版本然后确认技能目录的约定路径。之前遇到有人装了之后命令一直不生效最后排查下来是因为目录层级放错了。另一个建议是准备一个专门用来试验的项目。不要直接在核心业务仓库上首次跑全面评审因为大概率会输出几十条问题容易被信息淹没。用一个中型项目做试验田既能验证技能覆盖率又不会惊吓到团队。最后建议先跑一下 /review-skills 确认当前可用的技能列表。这样能提前发现哪些技能没有正确加载而不是等到正式评审时才暴露问题。4.2 安装步骤详解整个安装过程大致分四步下载技能包、放置目录、配置命令、初始化验证。最核心的配置文件结构如下review-skill/ ├── SKILL.md # 技能包主描述文件 ├── skills/ │ ├── architecture/ # 架构设计5项 │ ├── security/ # 安全防护5项 │ ├── performance/ # 性能效率5项 │ ├── reliability/ # 可靠性健壮性5项 │ └── maintainability/ # 可维护性规范5项 ├── commands/ │ ├── review.md # /review 命令定义 │ ├── review-security.md │ ├── review-perf.md │ ├── review-diff.md │ ├── review-file.md │ ├── review-focus.md │ ├── review-report.md │ ├── review-priority.md │ └── review-skills.md └── config.yaml # 全局配置含阈值与输出格式# config.yaml 核心配置片段 global: severity_threshold: P2 output_format: markdown max_file_size_kb: 200 commands: review: pipeline: [global_scan, architecture, security, performance, reliability, maintainability, merge_report] max_issues: 30 review-priority: pipeline: [global_scan, architecture, security, performance, reliability, maintainability, merge_report] severity_filter: [P0, P1] skills: transaction_boundary: enabled: true confidence_threshold: 0.7放置路径按工具的约定来处理。配置文件里两个参数我建议重点关注max_file_size_kb 用来避免单文件太大导致AI上下文溢出confidence_threshold 用来控制误报率如果发现某类技能报告的问题团队经常不认可调高对应阈值即可。4.3 跑一次完整评审从命令到输出安装完成后实际跑一次全面评审。这里给一段常见问题代码做演示def create_order(user_id, product_list, address_id): total_price 0 for item in product_list: product get_product_by_id(item.product_id) if product.stock item.quantity: raise StockNotEnough(库存不足) total_price product.price * item.quantity for item in product_list: update_stock(item.product_id, item.quantity) order Order(user_iduser_id, total_pricetotal_price, address_idaddress_id) db.session.add(order) db.session.commit() send_order_created_event(order.id)执行 /review-file 指向这个文件输出的重点问题如下严重级别问题摘要涉及技能P0事务边界不完整先扣减库存再创建订单两个写操作未在同一事务中中间失败会导致库存扣减但订单未创建事务边界审查P1N1查询循环内多次调用 get_product_by_id商品较多时产生大量DB查询N1查询扫描P1越权风险create_order 未校验 user_id 是否与当前登录用户一致存在越权下单风险越权访问检测P2send_order_created_event 在事务提交后调用失败时无补偿机制存在消息丢失风险异常吞没检测这份输出基本还原了资深工程师看这段代码时的脑内活动。它不是列出所有潜在问题而是按严重程度排序把最关键的三个点顶到最前面。P2那条虽然短期不影响线上但提示了可靠性隐患属于加分项建议。5. 实际使用中的常见问题与排查技巧5.1 命令不生效或者技能列表为空这是最常遇到的问题。排查路径其实很简单先确认技能包是否放在正确的目录下再确认配置文件的格式是否合法。很多文本编辑器会在保存时偷偷替换引号导致 YAML 解析失败这个问题我遇到不止一次。还有一个隐蔽的原因命令名称冲突。如果其他插件占用同名命令新装的命令可能会被覆盖。用命名前缀能避开这个问题比如把 /review 改成 /cr- 开头的形式冲突概率会显著降低。另外如果更新了技能包内容建议重启会话让技能重新加载直接热插拔偶尔会失效。5.2 AI 输出的问题太泛如果发现评审结果总是停留在建议增加参数校验建议优化代码结构这种正确的废话大概率是技能配置里的判定标准不够具体。每个技能除了描述查什么还要明确什么算问题、什么不算。越权访问检测之所以好用是因为它明确写了从请求参数获取用户标识且未做数据源信任校验是高危而不是笼统地写检查越权。还有一个常见原因阈值设置太宽松。confidence_threshold 设低了AI什么都会报宁可错杀不可放过设高了真正的严重问题被过滤掉的概率增加。建议从0.7起步跑两周看看误报率再微调。5.3 大项目评审结果过多代码规模一大哪怕是增量评审一次性输出的问题也可能有几十条超出人的处理能力。这种情况建议改变使用策略全面评审只在重要节点跑日常开发多依赖 /review-diff 和 /review-priority 两条命令做快速收口。另外为项目建一个豁免清单很实用。有些历史代码明知有问题但短期不想动在配置里标记豁免后后续评审就不会再反复报同一批问题。这能显著降低信息噪音。5.4 评审结果不稳定同一段代码上午跑和下午跑结果不完全一样。这个现象主要和模型本身的采样随机性有关也可能是因为会话上下文不同影响了判断。我的方案是用 /review-report 固定输出格式并要求只输出结构化问题清单不给建议措辞留太多发挥空间。想要更稳定的话可以在配置里把 temperature 相关的参数调低。如果工具允许设置采样参数建议优先调低来保证结果可复现性。实测下来调低之后评审输出的稳定性有明显提升虽然偶尔会少一点发散性建议但对评审场景来说稳定比发散重要得多。5.5 问题排查技巧速查表现象可能原因排查方向命令完全无法识别技能包路径错误核对目录结构与官方约定技能列表为空配置文件解析失败检查YAML引号是否被编辑器替换输出内容太泛技能判定标准模糊明确什么算问题的具体条件误报率高confidence_threshold过低调高阈值或加入豁免清单结果不稳定模型采样随机性调低temperature固定输出格式大文件无响应超出上下文窗口调低max_file_size_kb分文件评审坑踩了不少最有价值的一条经验是任何AI辅助工具都需要磨合期。第一周跑出来的结果需要人工校对一遍把误报记录反馈到配置里让工具越用越准。这套 skill 的本质不是替代评审工程师而是把资深工程师的判断框架分发到每个人手中。框架搭好了剩下的就是让团队在一次次实践中把工具打磨成自己的形状。我个人后期比较推荐的做法是把每个月的评审结果汇总一次看哪些技能命中率最高、哪些技能几乎从来不触发然后调整技能矩阵——把用不到的收缩把命中率高的强化。工具是死的经验是活的持续迭代才是真正把评审直觉沉淀下来的方式。