1. 从“评审直觉”到“可安装技能”的工程化思路1.1 为什么要把评审直觉做成技能包做了十多年开发我越来越确信一件事资深工程师最值钱的能力不是写代码的速度而是评审代码时的那一眼。同样一段逻辑新人看半天觉得没问题老手扫一眼就能指出“这里并发会出问题”“这个边界没处理”“这个命名三个月后你自己都看不懂”。这种直觉不是玄学它是大量踩坑经验压缩成的模式识别能力。问题在于这种能力极难传递。你让一个资深工程师写文档讲评审要点他写出来的往往是“要注意代码可读性”“要关注边界条件”这种正确的废话。真正的评审直觉是场景化的、条件反射式的它藏在“我看到这个写法就觉得不对劲”的瞬间里。所以当我看到“把资深工程师的评审直觉做成可安装的 skill”这个思路时第一反应是这才是 AI 编码工具真正该干的事。不是让 AI 帮你写更多代码而是让 AI 帮你用资深工程师的标准审视代码。25 个技能、9 条命令这个组合的本质是把评审经验拆解成可复用、可组合、可安装的原子能力。1.2 技能与代理的分工逻辑这里必须先厘清一个概念skill 和 agent 到底有什么区别。很多人把这两个词混着用但在实际工程里它们的职责边界很清晰。Agent 是一个有自主决策能力的执行体它能规划任务、调用工具、根据结果调整策略。你可以把它理解成一个“会自己想办法的项目负责人”。而 skill 更像是一本“操作手册”或者“检查清单”它不负责决策只负责在特定场景下提供专业级的判断标准和操作步骤。打个比方agent 是那个拿着工具箱上门的师傅skill 是他脑子里“遇到这种墙面该怎么处理”的经验。师傅可以换但经验可以沉淀下来复用。把评审直觉做成 skill意味着这套经验不再绑定在某个人或某个 agent 上而是变成可安装、可卸载、可组合的标准化模块。这个设计的好处在于你可以给不同的 agent 装上同一套 skill保证评审标准的一致性也可以根据项目类型灵活组合不同的 skill比如前端项目装一套、后端服务装另一套。1.3 25 个技能与 9 条命令的架构考量为什么是 25 个技能而不是 5 个或 50 个这个数字背后其实有讲究。技能拆得太粗比如只做一个“代码评审”技能那它内部逻辑会极其复杂难以维护也无法针对具体场景做优化。拆得太细比如每个函数命名规则都做一个技能那组合起来会产生大量冗余调用反而降低效率。25 个左右是一个比较舒服的粒度每个技能聚焦一个明确的评审维度同时又能通过组合覆盖大部分常见场景。9 条命令则是操作层面的抽象。你不需要记住 25 个技能分别怎么调用只需要记住 9 个高频操作入口。这符合 CLI 工具的设计哲学底层能力可以很多但用户界面必须极简。就像 git 有几百个底层命令但你日常用的就那么十来个。这种“多技能 少命令”的架构本质上是在表达能力和使用成本之间找平衡。技能数量保证了评审的深度和覆盖面命令数量控制了学习曲线。2. 核心技能拆解与评审维度解析2.1 代码质量类技能的实际覆盖范围代码质量是评审直觉最集中的领域。我梳理了一下这类技能通常覆盖以下几个维度每个维度背后都对应着资深工程师的“条件反射”。命名与可读性资深工程师看到data、temp、flag这种命名会本能地皱眉。不是因为这些词不能用而是因为它们在不同上下文里含义完全不同三个月后没人记得flag到底标记的是什么。对应的技能会检查变量名是否表达了意图、函数名是否描述了行为、类名是否体现了职责。函数复杂度一个函数超过 50 行或者嵌套层级超过 3 层资深工程师就会开始警惕。这不是教条而是因为人脑的工作记忆容量有限超过这个复杂度后理解和修改的成本会指数级上升。技能会计算圈复杂度、识别过长的参数列表、标记出可以提取的重复逻辑。错误处理新人最容易忽略的就是错误处理。资深工程师看到try-catch里只写了个console.log就会问“然后呢出错了业务怎么继续”对应的技能会检查是否吞掉了异常、是否区分了可恢复和不可恢复错误、是否在错误信息里保留了足够的排查线索。注释与文档这里有个反直觉的点——资深工程师并不喜欢满屏注释。他们更在意的是“为什么这么做”而不是“做了什么”。技能会识别那些重复代码逻辑的废话注释同时标记出缺少关键决策说明的复杂逻辑。2.2 架构与设计类技能的判断标准架构评审比代码评审更依赖经验因为它涉及的是“取舍”而非“对错”。这类技能的核心价值在于把常见的架构坏味道模式化。耦合度检查模块之间是否直接依赖了对方的内部实现是否可以通过接口隔离来降低变更的连锁反应技能会分析 import 关系图标记出循环依赖和高扇入扇出的模块。单一职责验证一个类或模块是否承担了多个不相关的职责判断标准是“描述它的功能时是否需要用到‘和’字”。如果需要那大概率可以拆分。技能会分析类的方法集合识别出职责混杂的信号。扩展性评估新增一个类似功能时需要修改多少现有代码如果答案是“很多地方”那说明抽象层次不对。技能会检查是否存在硬编码的分支逻辑、是否使用了策略模式等可扩展结构。依赖方向高层模块是否依赖了低层模块的具体实现依赖是否指向了稳定的方向技能会分析包之间的依赖关系标记出违反依赖倒置原则的地方。2.3 安全与性能类技能的触发条件安全和性能问题有个共同特点平时不出事一出事就是大事。所以这类技能的设计思路是“宁可误报不可漏报”。输入验证所有外部输入是否都经过了验证验证是否在边界处完成技能会追踪数据从入口到使用点的完整路径标记出未经校验就直接使用的输入。敏感信息处理日志里是否打印了密码或令牌错误信息是否泄露了内部结构技能会扫描字符串常量和日志语句识别潜在的敏感信息泄露。资源管理文件句柄、数据库连接、网络套接字是否都有明确的释放路径技能会检查是否存在异常路径下资源未释放的情况。性能热点循环里是否有数据库查询是否在循环中重复创建了昂贵对象技能会识别嵌套循环中的 I/O 操作、标记出可以移到循环外的计算。2.4 技能之间的组合与优先级25 个技能不是孤立工作的它们之间有明确的优先级和组合规则。这个设计很关键因为如果所有技能同时触发评审报告会变成一团噪音。我的经验是优先级应该这样排安全 正确性 性能 可维护性 风格。安全问题是红线必须最先报告正确性问题次之因为它直接影响功能性能和可维护性可以根据项目阶段调整权重风格问题放在最后避免淹没真正重要的发现。组合规则方面有些技能是互斥的。比如“快速原型模式”下可维护性检查应该降级因为原型代码本来就不打算长期维护。而“生产发布模式”下所有技能都应该全量触发。这种模式切换通常通过命令参数来控制这也是 9 条命令存在的意义之一。3. 9 条命令的实操流程与配置方法3.1 环境准备与技能安装在开始之前你需要一个支持 skill 机制的 AI 编码环境。目前主流的 CLI 工具如 codex cli、claude cli 等都在逐步支持这类扩展机制。安装过程通常分为三步获取技能包、注册到环境、验证可用性。# 以常见的 skill 安装流程为例 # 第一步将技能包放到指定目录 mkdir -p ~/.ai-skills/review-skills cp -r ./review-skills/* ~/.ai-skills/review-skills/ # 第二步注册技能清单 # 通常需要在配置文件中声明技能路径 echo skill_paths: [~/.ai-skills/review-skills] ~/.ai-config.yaml # 第三步验证安装 ai-skill list --category review这里有个容易踩的坑技能包的目录结构必须符合规范。通常要求每个技能有独立的目录目录下包含skill.yaml元数据和prompt.md技能逻辑。如果结构不对环境加载时会静默跳过你以为是安装成功了实际一个技能都没生效。提示安装完成后一定要用list命令确认技能数量。25 个技能应该全部出现在列表里少一个都说明有问题。3.2 核心命令的使用场景与参数9 条命令覆盖了从全量评审到单点检查的完整场景。我按使用频率从高到低排列一下。第一条全量评审命令。这是最常用的入口对指定文件或目录执行所有已安装技能的检查。ai-review run --path ./src --skills all --output report.md参数说明--path指定评审范围--skills all表示启用全部技能--output指定报告输出位置。实测下来对一个中等规模的项目约 5000 行代码全量评审耗时在 30 秒到 2 分钟之间取决于技能数量和模型响应速度。第二条定向评审命令。当你只关心某个维度时使用比如只检查安全问题。ai-review run --path ./src --skills security --severity high--severity参数控制报告的详细程度high只输出高危问题适合在 CI 流程中做门禁检查。第三条增量评审命令。只评审最近变更的文件适合在提交前快速自查。ai-review run --diff HEAD~1 --skills all这个命令会解析 git diff只对变更部分执行评审。注意它评审的是变更后的完整文件而不是 diff 片段因为很多问题需要完整上下文才能判断。第四条技能管理命令。用于启用、禁用或更新技能。ai-review skill enable code-quality ai-review skill disable style-check ai-review skill update --all第五条报告查看命令。评审结果可以保存为多种格式这条命令用于重新渲染或过滤报告。ai-review report view --file report.md --filter severity:high第六条配置命令。调整技能的参数和阈值。ai-review config set complexity.threshold 15 ai-review config set naming.strict true第七条批量评审命令。对多个项目或目录批量执行。ai-review batch --config projects.yaml第八条对比评审命令。对比两次评审结果查看问题是否修复。ai-review compare --before report-v1.md --after report-v2.md第九条帮助命令。查看所有可用技能和命令的说明。ai-review help --skills3.3 评审流程的完整实操记录我拿一个真实的项目片段来演示完整流程。假设有一个用户注册模块代码大概 200 行。第一步先跑全量评审看看整体情况ai-review run --path ./src/user --skills all --output ./reports/user-review.md报告出来后我习惯先看摘要部分。摘要会按严重程度分类高危 3 个、中危 7 个、低危 12 个。高危问题必须立即处理中危问题排期修复低危问题可以批量处理。第二步针对高危问题做定向深入。比如报告指出“密码字段在日志中明文输出”我用定向命令确认ai-review run --path ./src/user --skills security --severity high --verbose--verbose会输出完整的代码上下文和修复建议而不只是问题描述。第三步修复后做增量验证ai-review run --diff HEAD --skills security确认高危问题已消除且没有引入新的问题。第四步把评审命令集成到提交钩子里。这样每次提交前自动跑一遍增量评审把问题拦截在本地。# .git/hooks/pre-commit #!/bin/bash ai-review run --diff HEAD --skills security,correctness --severity high if [ $? -ne 0 ]; then echo 评审发现高危问题提交已阻止 exit 1 fi3.4 参数调优与阈值设置技能里的很多检查项都有阈值参数这些参数需要根据项目实际情况调整。默认值通常是通用场景下的保守估计直接用在你的项目上可能会产生大量误报。复杂度阈值默认圈复杂度阈值是 10。对于业务逻辑复杂的项目可以放宽到 15对于基础库项目建议收紧到 8。文件长度阈值默认单文件不超过 500 行。前端组件文件可以放宽到 800 行因为 JSX 模板占行数较多。函数参数数量默认不超过 5 个。如果项目大量使用配置对象模式可以放宽到 7 个。重复代码块大小默认检测 6 行以上的重复。对于模板代码较多的项目可以提高到 10 行避免误报。调优的方法论是先跑一遍全量评审统计各类问题的数量。如果某类问题超过总数的 30%说明阈值太松或太紧需要调整。调整后重新跑直到问题分布合理。4. 常见问题排查与避坑经验4.1 技能不生效的排查思路这是最高频的问题。你装好了技能跑了命令但报告里空空如也。排查顺序应该是这样的先确认技能是否被正确加载。用ai-review skill list查看已激活的技能列表。如果列表为空说明技能路径配置有问题。检查配置文件里的skill_paths是否正确路径是否用了绝对路径相对路径在不同工作目录下会失效。再确认技能是否匹配当前文件类型。有些技能只对特定语言生效比如 Python 的命名规范技能不会对 JavaScript 文件触发。检查技能的skill.yaml里的file_patterns字段。最后确认命令参数是否正确。--skills all和--skills是不同的后者需要跟具体的技能名。如果技能名拼写错误命令会静默忽略而不是报错。注意技能加载失败时通常不会中断命令执行而是跳过该技能继续。所以报告为空不一定是没发现问题可能是技能根本没跑起来。4.2 误报与漏报的平衡技巧任何静态检查工具都面临误报和漏报的权衡。评审技能也不例外。我的经验是宁可接受一定程度的误报也要避免漏报。因为漏报的代价是线上事故误报的代价只是多看一眼。但误报太多会让人麻木最终导致真正的问题被忽略。所以需要一些技巧来平衡。对于高频误报的技能可以设置白名单。比如某些工具类函数确实需要多个参数可以在配置里排除这些函数名。对于低频但高危的检查项保持严格模式。比如 SQL 注入检查即使误报率较高也不应该放宽因为漏报的代价太大。定期回顾误报记录。如果某个技能连续多次误报同一类问题说明它的判断逻辑需要调整可以考虑禁用或替换。4.3 与现有工作流的集成要点评审技能不应该是一个孤立的工具它需要嵌入到现有的开发工作流中才能发挥最大价值。本地开发阶段配置编辑器插件在保存文件时自动跑增量评审。这样问题在写代码的过程中就被发现修复成本最低。提交阶段通过 git hook 做门禁检查。高危问题阻止提交中低危问题只警告不阻止。CI 阶段在流水线里跑全量评审生成报告归档。同时对比上次评审结果追踪问题修复进度。发布阶段发布前跑一次全量评审确认没有新增高危问题。这一步可以作为发布检查清单的一项。集成的关键是不要追求一步到位。先从一个环节开始跑顺了再扩展到下一个环节。我见过太多团队一上来就搞全流程集成结果因为误报太多导致流程卡死最后整个方案被废弃。4.4 常见问题速查表问题现象可能原因排查方法解决方案报告为空技能未加载运行 skill list 确认检查技能路径配置报告为空文件类型不匹配查看技能 file_patterns调整技能适用范围误报过多阈值过严统计误报类型分布放宽对应阈值漏报严重技能未覆盖对比已知问题清单补充或启用相关技能执行超时项目规模过大查看评审文件数量分批评审或增量评审结果不一致技能版本不同对比技能版本号统一技能版本集成失败命令返回码异常检查退出码定义调整 hook 判断逻辑4.5 实操心得与避坑建议最后分享几条我在实际使用中总结的经验都是踩过坑之后才明白的。第一条不要一次性启用所有技能。25 个技能全开报告会长到没人看。建议分阶段启用先开安全和正确性稳定后再加性能和可维护性最后加风格检查。第二条评审报告要有人负责跟进。工具只能发现问题解决问题还得靠人。如果报告出来没人看那这个工具就是摆设。建议指定专人负责评审报告的跟进每周回顾一次问题修复情况。第三条技能配置要纳入版本管理。技能配置文件和项目代码一样应该提交到代码仓库。这样团队成员的评审标准才能保持一致新人入职也能快速对齐。第四条定期更新技能包。评审直觉本身也在进化新的坑不断出现技能包也需要持续更新。建议每月检查一次技能更新把新版本拉下来。第五条不要完全依赖工具判断。评审技能是辅助不是替代。它帮你发现模式化的问题但架构决策、业务逻辑正确性这些需要人类判断的领域还是得靠资深工程师的经验。工具的价值在于把资深工程师从重复的检查工作中解放出来让他们专注于真正需要人类智慧的部分。这套东西我用了大半年最大的感受是它确实能把评审的基线水平拉高。以前新人提交的代码资深工程师要花半小时指出一堆基础问题现在基础问题被技能拦住了评审时间可以花在更有价值的讨论上。但前提是你要愿意花时间调优配置忍受初期的误报噪音。没有一劳永逸的工具只有持续打磨的流程。