AAS 代码评审技能深度解析：code-review-and-quality 的五轴评审、严重度分级与结构性修复方法论

AAS 代码评审技能深度解析code-review-and-quality 的五轴评审、严重度分级与结构性修复方法论【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills在 agentic-awesome-skillsAAS的技能目录中code-review-and-quality 是一个risk: critical级别的社区技能它把合并前必须评审落地为一套可执行的多维评审流程五轴检查正确性、可读性、架构、安全、性能、按杠杆排序的发现分级、变更规模阈值、结构性修复建议与评审核对清单。读完全文你可以掌握一套同时适用于人类和 Agent 的代码评审标准作业流程并知道如何在 AAS 插件生态中调用该技能及与其配套的security-and-hardening、performance-optimization技能。技能定位与元数据该技能在仓库中同时存在于两处内容完全一致经diff验证逐字节相同主目录技能Claude 插件分发副本SKILL.md 的 YAML frontmatter 声明了它的身份与来源字段值说明namecode-review-and-quality技能标识description执行多维度代码评审在合并任何变更前使用适用于评审自己、其他 Agent 或人类编写的代码触发时机描述riskcritical风险级别最高档属于合并质量门source_repoaddyosmani/agent-skills上游社区来源source_typecommunity社区贡献技能date_added2026-07-01入库日期licenseMIT许可证在 技能索引 中该技能被归类为development类别插件目标为codex: supported和claude: supported且setup.type为none——即无需额外安装依赖或凭据即可在 Claude Code / Codex 插件中直接调用这与 使用指南 中插件分发一个固定的 plugin-safe 子集、通过 prompt 调用单个技能的模型一致。技能开宗明义地确立了审批标准approval standard只要一个变更确定能改善代码库整体健康度即使它不完美也应当批准。不存在完美代码目标是持续改进不要仅仅因为不是我会写的样子而阻塞一个遵循项目约定、改善了代码库的变更。何时使用该技能文档列出了五个典型触发场景合并任何 PR 或变更之前完成一个功能实现之后需要评估另一个 Agent 或模型产出的代码时重构现有代码时任何 bug 修复之后同时评审修复本身和回归测试。五轴评审The Five-Axis Review每次评审都必须沿以下五个维度评估代码。这是整个技能的核心骨架。1. 正确性Correctness代码是否做了它声称要做的事检查清单是否匹配规格或任务要求边界情况是否处理null、空值、边界值错误路径是否处理而不只是 happy path是否通过所有测试这些测试是否真的在测对的东西是否存在差一错误、竞态条件或状态不一致2. 可读性与简洁性Readability Simplicity判断标准是另一位工程师或 Agent能否在作者不解释的情况下理解这段代码命名是否有描述性且符合项目约定禁止无上下文的temp、data、result控制流是否直接避免嵌套三元、深回调代码是否逻辑化组织相关代码聚拢、模块边界清晰是否有关心聪明技巧应当简化的地方能否用更少的行数完成100 行能解决的地方写了 1000 行是失败抽象是否在挣得它的复杂度在出现第三个用例之前不要泛化注释是否有助于澄清非显而易见的意图但不要注释显而易见的代码是否存在死代码残留no-op 变量_unused、向后兼容垫片、// removed注释是否在无关流程上焊了一个新条件分支这是设计异味而非小问题——应把逻辑推入自己的 helper、状态或策略而不是纠缠既有路径。是否出现同一形状的重复条件判断它们暗示缺失的模型或分发器。临时的分支通常是永久性债务。3. 架构Architecture变更是否契合系统设计遵循既有模式还是引入了新模式若引入新模式是否被证明合理是否维护了干净的模块边界是否存在应当共享的代码重复依赖方向是否正确无循环依赖抽象层级是否恰当不过度设计、不过度耦合这次重构是降低了复杂度还是仅仅把它搬了个地方数一数读者为了跟住这个变更需要同时持有的概念数量。如果更干净的版本让这个数字没变它就不是更干净——优先选择让整条分支、整个模式或整层消失的重构而不是把同样的逻辑重新集中化的重构。优先删除一个抽象而不是打磨它。特性专属逻辑是否泄漏进了共享或通用模块让逻辑留在其归属层复用现有的规范 helper 而不是再造近重复实现不要规范化架构漂移。类型边界是否显式对随意的any/unknown/optional/强制转换以及掩盖不清晰不变量的静默回退保持质疑——把边界显式化往往让周边控制流变简单。4. 安全Security在 AAS 目录中与本文档同插件分发的 security-and-hardening 技能 提供了详细的加固方法威胁模型、STRIDE 边界分析等本技能侧重点在变更是否引入漏洞用户输入是否被校验和净化密钥是否远离代码、日志和版本库在需要处是否检查了认证/授权SQL 查询是否参数化禁止字符串拼接输出是否编码以防 XSS依赖是否来自可信来源且无已知漏洞来自外部源API、日志、用户内容、配置文件的数据是否被当作不可信外部数据流在进入逻辑或渲染之前是否在系统边界处被校验5. 性能Performance目录中的 performance-optimization 技能 强调先测量再优化覆盖 Core Web Vitals 目标与完整测量-剖析-修复循环本技能在评审侧检查变更是否引入性能问题是否存在 N1 查询模式是否存在无界循环或无约束的数据拉取是否有应当异步的同步操作UI 组件是否有不必要的重渲染列表端点是否缺少分页热路径上是否创建大对象结构性修复Structural Remedies这是该技能区别于普通找茬式评审的关键当你标记一个结构性问题时要提出具体的搬移方案而不只是描述问题。只说这里很复杂的评审让作者只能靠猜。应当给出具名的重构动作用类型化模型或显式分发器替换一连串条件判断把重复分支折叠为一条更清晰的流程把编排与业务逻辑分离让各自可以独立阅读把特性专属逻辑从共享模块移到拥有该概念的包中复用规范 helper而不是定制一个近重复实现显式化类型边界让下游分支消失删除一个透传包装器——它只增加间接层却不澄清 API抽取 helper或把大文件拆分成聚焦的模块。总原则优先选择移除活动部件的修复而不是把同样的复杂度摊到更多地方的修复。变更规模Change Sizing小而聚焦的变更更容易评审、合并更快、部署更安全。技能给出明确的规模目标~100 行变更 → 好。一次评审会话内可完成。 ~300 行变更 → 若是单一逻辑变更可接受。 ~1000 行变更 → 太大。拆分它。三条补充规则盯文件大小而不只是 diff 大小。一个小的 diff 也可能把文件推过健康边界——单文件约 1000总行区别于上面约 1000变更行的阈值是一个常见的检视信号而非硬上限。当一个变更显著增大一个已经很大的文件时先问是否应当抽取 helper、子组件或模块然后再继续堆积。先分解再添加。什么算一个变更一次自包含的修改解决一件事包含相关测试且提交后系统保持可用。是功能的一部分——不是整个功能。变更过大时的拆分策略策略做法适用场景Stack堆叠提交一个小变更基于它开始下一个顺序依赖按文件组为需要不同评审者的文件组分别提交横切关注点水平拆分先建共享代码/桩再接入消费方分层架构垂直拆分拆成更小的全栈切片特性开发大变更何时可接受完整文件删除和自动化重构——评审者只需验证意图无需逐行检查。重构与特性开发分开提交。一个既重构现有代码又新增行为的变更是两个变更——分开提交。小的清理变量重命名可以按评审者裁量包含在内。变更描述Change Descriptions每个变更都需要一段在版本历史中能够独立成立的描述。首行简短、祈使句、可独立理解。写删除 FizzBuzz RPC而不是正在删除 FizzBuzz RPC。信息量要足以让搜索历史的人不读 diff 就能理解变更。正文什么在变、为什么变。包含代码本身看不到的上下文、决策和推理。在相关处链接 bug 编号、基准测试结果或设计文档。当方案存在不足时明确承认。反模式Fix bug、Fix build、Add patch、Moving code from A to B、Phase 1、Add convenience functions。评审流程Review ProcessStep 1理解上下文看代码之前先理解意图这个变更要达成什么它实现了哪个规格或任务预期的行为变化是什么Step 2先评审测试测试揭示意图与覆盖度该变更有没有测试测试测的是行为而非实现细节吗边界情况覆盖了吗测试命名有描述性吗如果代码将来变化测试能捕获回归吗Step 3评审实现带着五个轴逐一走过代码对每个被修改的文件依次问正确性——代码是否做了测试声称它该做的可读性——不求助能否理解架构——是否契合系统安全——有没有漏洞性能——有没有瓶颈Step 4给发现分级给每条评论标注严重度让作者知道什么是必须的、什么是可选的前缀含义作者动作无前缀必须修改合并前必须处理Critical:阻塞合并安全漏洞、数据丢失、功能损坏Nit:轻微、可选作者可忽略——格式、风格偏好Optional:/Consider:建议值得考虑但不强制FYI仅信息无需行动——留作将来参考这能防止作者把所有反馈都当作强制项、在可选建议上浪费时间。先说最重要的。按杠杆排序发现正确性和安全第一其次是结构性回退和错失的简化机会然后才是其他。不要把真问题埋在表面 nits 之下——几条高置信度的评论胜过一长串清单。如果你有一个结构性问题和十条 nits那个结构性问题就是这次评审本身。Step 5验证验证本身检查作者的验证故事跑了哪些测试构建通过了吗变更做手工测试了吗UI 变更有截图吗有 before/after 对比吗多模型评审模式Multi-Model Review Pattern用不同模型覆盖不同评审视角Model A 写代码 │ ▼ Model B 评审正确性与架构 │ ▼ Model A 处理反馈 │ ▼ 人类做最终裁决这能捕获单一模型可能漏掉的问题——不同模型有不同的盲区。给评审 Agent 的示例提示词Review this code change for correctness, security, and adherence to our project conventions. The spec says [X]. The change should [Y]. Flag any issues as Critical, Required, Optional, or Nit.在 AAS 目录中还存在一个同源思路的社区技能 five-axis-code-review它以这段代码三个月内会不会变成别人的问题为单一判据同样按五轴正确性、安全、可读性、性能、测试覆盖走查并要求每个失败都附带具体修复——可作为该技能在评审提示词层面的互证。死代码卫生Dead Code Hygiene任何重构或实现变更之后检查孤儿代码三步走找出现在不可达或无用的代码显式列出清单删除前先问这些现在不再使用的元素是否应当移除[清单]不要留死代码——它会让未来的读者和 Agent 困惑但也不要静默删除你不确定的东西。拿不准就问。技能给出的示例输出格式DEAD CODE IDENTIFIED: - formatLegacyDate() in src/utils/date.ts — replaced by formatDate() - OldTaskCard component in src/components/ — replaced by TaskCard - LEGACY_API_URL constant in src/config.ts — no remaining references → Safe to remove these?评审速度Review Speed慢评审阻塞整个团队。切换上下文做评审的代价小于强加给别人的等待代价一个工作日内响应——这是上限不是目标理想节奏评审请求到达后尽快响应除非正处在深度编码中。典型的变更应在一天内完成多轮评审优先保证单条快速反馈而非快速最终批准。即使需要多轮快速的反馈也能减少挫败感大变更请作者拆分而不是评审一个巨型变更集。分歧处理Handling Disagreements评审争执的裁决层级技术事实与数据压倒意见和偏好风格指南是风格问题的绝对权威软件设计必须用工程原则评估而非个人偏好与代码库保持一致在不降低整体健康度的前提下可接受。不接受我回头再清理。经验表明延迟清理几乎从不发生。除非是真正的紧急情况要求在提交前完成清理如果周边问题无法在本次变更中处理要求开一个 bug 并自我指派。评审中的诚实Honesty in Review无论评审的代码出自你、其他 Agent 还是人类不要盖章放行。没有评审证据的 LGTM 帮不了任何人。不要软化真实问题。明明是会打到生产环境的 bug却说这可能只是个轻微担忧是不诚实。尽可能量化问题。这个 N1 查询会为列表里每项增加约 50ms优于这可能会慢。对有明显问题的方案顶回去。在评审中迎合sycophancy是一种失败模式。如果实现有问题直接说并给出替代方案。优雅接受 override。如果作者拥有完整上下文并不同意尊重其判断。评论代码而不是人——把针对个人的批评重构为聚焦代码本身。依赖纪律Dependency Discipline代码评审的一部分是依赖评审。添加任何依赖之前过五问现有技术栈能否解决通常能。依赖多大检查 bundle 影响。是否在积极维护看最后提交、未关闭 issue。有没有已知漏洞npm audit。许可证是什么必须与项目兼容。规则优先标准库和现有工具而非新依赖。每个依赖都是一笔负债。评审核对清单The Review Checklist技能提供了一份可直接复制到 PR 评论区的完整清单## Review: [PR/Change 标题] ### Context - [ ] 我理解这个变更做了什么、为什么做 ### Correctness - [ ] 变更匹配规格/任务要求 - [ ] 边界情况已处理 - [ ] 错误路径已处理 - [ ] 测试充分覆盖该变更 ### Readability - [ ] 命名清晰一致 - [ ] 逻辑直接 - [ ] 无不必要的复杂度 ### Architecture - [ ] 遵循既有模式 - [ ] 无不必要的耦合或依赖 - [ ] 抽象层级恰当 - [ ] 重构是降低复杂度而非转移复杂度 - [ ] 共享模块中无特性逻辑文件保持在健康尺寸内 ### Security - [ ] 代码中无密钥 - [ ] 输入在边界处被校验 - [ ] 无注入类漏洞 - [ ] 认证检查到位 - [ ] 外部数据源被当作不可信 ### Performance - [ ] 无 N1 模式 - [ ] 无无界操作 - [ ] 列表端点有分页 ### Verification - [ ] 测试通过 - [ ] 构建成功 - [ ] 已完成手工验证如适用 ### Verdict - [ ] **Approve** — 可以合并 - [ ] **Request changes** — 必须处理的问题常见自我合理化与红旗Common Rationalizations Red Flags技能用一张对照表击穿了评审中最常见的七种借口自我合理化现实能跑就够了能跑但不可读、不安全或架构错误的代码会制造复利式债务。我写的所以我知道它是对的作者对自己的假设是盲的。每个变更都受益于另一双眼睛。回头再清理回头从不到来。评审就是质量门——用它。合并前要求清理而不是合并后。AI 生成的代码大概率没问题AI 代码需要更多审视而非更少。它自信且貌似合理即使它是错的。测试都过了所以没问题测试是必要不充分条件。它们捕获不了架构问题、安全问题或可读性问题。重构让它更干净了转移复杂度不是降低复杂度。如果读者仍需持有同样多的概念结构就没有改善——去找分支消失的那个版本。只是往这个文件里加了一小点小 diff 照样把文件推过健康尺寸、往无关流程上焊分支。判断最终结构而不是 diff 大小。与之对应的红旗信号未经任何评审就合并的 PR只检查测试是否通过的评审忽略其他轴没有实际评审证据的 LGTM安全敏感变更没有安全聚焦的评审以太大没法好好评审为由放行的大 PR应当拆分没有回归测试的 bug 修复 PR不带严重度标签的评审评论——分不清必须项和可选项接受我回头修——它永远不会发生只是搬代码、没有降低读者概念数量的重构让已经很大的文件继续膨胀而不是分解的变更新条件分支散落在无关代码路径中缺失的抽象复制现有规范 helper 的定制实现或放进共享模块的特性逻辑。评审完成后的验证与推定阻塞项评审结束后的收尾检查所有 Critical 问题已解决所有 Required无前缀变更已解决或带理由显式延期测试通过构建成功验证故事已记录改了什么、如何验证的。推定阻塞项presumptive blockers对以下每一类先暴露问题并提出更简单的设计只有当变更主动让结构变坏时才升级为 Required——把复杂度转移而非降低的重构把文件推过尺寸边界且不做分解的变更加进共享模块的特性逻辑对现有规范 helper 的近重复实现掩盖不清晰不变量的静默回退。使用边界与配套技能技能的 Limitations 一节明确约束了使用前提仅当任务明确匹配其上游来源与本地项目上下文时使用该技能应用变更前先验证命令、生成代码、依赖、凭据和外部服务行为不要以文档中的示例替代环境特定测试、安全评审或对破坏性/高成本操作用户审批。文档末尾的 See Also 指向references/security-checklist.md与references/performance-checklist.md在当前仓库的目录结构中本技能目录 只包含 SKILL.md 本身没有随附 references 子目录——其安全与性能的深化检查内容由同插件分发的 security-and-hardening 与 performance-optimization 技能承担。可以推断这三个技能构成 AAS 中评审门 安全深化 性能深化的组合前者在合并前把关后两者在评审发现安全轴或性能轴的具体问题时提供方法纵深。在 AAS 的两种使用路径中该技能都可用通过 使用指南 所述的 AAS Core 工作流Agent 会用search_skills/get_skill在全量目录中检索并经由compose_stack把它选入项目堆栈或者通过 Claude Code / Codex 插件路径直接在 prompt 中按description描述的触发时机合并前、功能完成后、评审他者代码时调用它。配合 技能索引 中的元数据development类别、codex/claude双目标支持、无 setup 依赖该技能属于开箱即用的质量门技能。小结code-review-and-quality 把代码评审从看感觉变成可审计的流程五轴提供检查维度严重度分级消除必须项与可选项的模糊变更规模阈值与拆分策略控制评审成本结构性修复把指出问题升级为给出搬移方案而死代码卫生、依赖纪律与诚实条款约束评审者自身的行为。对 Agent 工作流而言它尤其值得注意的一点是面向 AI 生成代码的立场——AI 代码需要更多审视而非更少——这正好覆盖了 agentic 场景下评审的主要对象。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考