software-code-review

代码审查

此技能用于审查现有变更。它会将 Agent 引导至合适的检查清单、审查模式和平台工作流，而不会把 SKILL.md 变成工具目录。

快速参考

任务	使用内容	主要参考资料
常规 PR 或差异审查	基础审查流程和严重性标准	references/operational-playbook.md
AI 生成或 Agent 创建的变更	人机协作审查规则和平台控制	references/automation-tools.md
构建或调整 AI 审查工具／集成	预审确定性关卡、按规模门控的规划阶段、自我反驳过滤阶段	references/deterministic-vs-llm-routing.md
后端／API 审查	错误处理、契约、持久化、可运维性	assets/backend-api/api-review.md
前端审查	无障碍、响应式行为、Core Web Vitals	assets/web-frontend/frontend-review.md
移动端审查	平台模式、生命周期、权限、用户体验	assets/mobile/mobile-review.md
基础设施审查	CI/CD、IaC、密钥、部署安全性	assets/infrastructure/infrastructure-review.md
智能合约审查	访问控制、重入、不安全假设	assets/blockchain/crypto-review.md
数据／ML 审查	流水线、实验、模型、部署	assets/data-ml/ml-diff-review-overlay.md

何时使用此技能

当主要任务是以下内容时，请使用此技能：

• 审查 PR、合并请求或差异
• 查找正确性、安全性、可靠性或可维护性问题
• 评估测试缺口和回归风险
• 在合并前审查 AI 生成或 Agent 创建的变更
• 推荐保持行为不变的小型重构

何时不使用此技能

• 全新架构设计 → software-architecture-design
• 深入的 AppSec 设计或正式威胁建模 → software-security-appsec；此技能会标出污点传播路径和缺失的控制措施，相关技能则负责设计修复方案
• 经过测量的性能调查（性能分析、负载测试、容量评估）→ 使用 software-performance 进行优化，并使用 qa-testing-performance 设计测试；此技能会标出差异中可见的热点路径回归，并将任何需要测量的问题交由其他技能处理
• 从零开始编写新功能 → 使用特定技术栈的实现技能
• 选择或启动审查 Agent 团队（审查委员会、并行审查者、辩论）→ agents-subagents；此技能仍会提供每位审查者需应用的审查标准

工作流

1. 确认审查范围：差异、PR、合并请求、生成的代码或指定文件集。
2. 如果审查不是主要任务，则将仅涉及架构或正式安全设计的问题转交给相邻技能。
3. 跟踪变更的控制流和数据契约，然后依次应用以下审查模式：正确性、安全性、可靠性、性能和可维护性。
4. 仅当代码确实需要特定领域的审查视角时，才引入技术栈补充指南。
5. 提供有证据支撑的具体发现，然后通过导航资料核实任何特定于平台的说法。

审查路由

除非用户要求缩小范围，否则按以下顺序应用审查模式：

1. 正确性和边界情况
2. 安全与数据处理：追踪差异中每个接收点的可控输入（参见 security-focused-review-guide.md）；需要威胁模型而非补丁才能解决的问题，交由 software-security-appsec
3. 可靠性和可运维性
4. 性能与成本：仅关注差异中可见的热路径回归；测量相关问题交由 software-performance
5. 可维护性和测试覆盖率

技术栈覆盖指南：

• 前端：assets/web-frontend/frontend-review.md
• 后端/API：assets/backend-api/api-review.md
• 移动端：assets/mobile/mobile-review.md
• 基础设施：assets/infrastructure/infrastructure-review.md
• 区块链：assets/blockchain/crypto-review.md
• 数据/ML：assets/data-ml/ml-diff-review-overlay.md

平台覆盖指南：

• GitHub：Copilot 审查、仓库说明、排除文件、Code Quality、合并队列
• GitLab：Duo 审查说明、合并请求审批、审批规则
• Bitbucket：Code Insights、分支限制、必需检查

如果用户询问特定平台的自动化问题，请先打开 data/sources.json 中的官方条目，并使用 references/automation-tools.md。

AI 辅助审查规则

• 人工审查具有最终决定权。AI 的发现仅供参考，须经确认后方可采纳。
• 将 AI 生成的代码和 Agent 创建的 PR 视为需要更多上下文的审查任务，而非更省力的审查任务：瓶颈从编写转移到了验证，因此应相应安排审查时间，而不是假定自动化会减少审查工作量。
• 根据此代码库的实际惯例评判 AI 生成的代码，而非抽象的风格指南——与周围代码保持一致，比“通常是否符合惯用写法”更有参考价值。
• 优先使用平台原生控制功能，而非第三方机器人：
  • 仓库或特定路径的审查说明
  • 排除文件 / 生成文件过滤器
  • 必需检查、审批规则和合并队列
• 不要凭记忆接受关于基准测试、定价或功能对比的说法。先核实工具的当前状态——此领域（GitHub Copilot 代码审查、CodeRabbit、Qodo/PR-Agent 及相关工具）的所有权、定价和功能经常变化；请参阅 references/automation-tools.md 和 data/sources.json，并在引用具体信息前再次核实。
• 切勿将特定 AI 模型版本/ID 固定为面向审查者的事实引用；其能力和行为变化太快，无法长期保持准确。
• Agent PR 数量较多时：按风险级别分流（身份验证、资金、迁移、基础设施、公共 API 应升级至 CODEOWNERS 进行完整人工审查），将 Agent PR 的接收量控制在审查者的处理能力范围内，大型 Agent 变更应采用分层审查，为每次合并指定一位负责的人工审查者，并依据 AI 审查者建议的实际采纳率和噪声，而非评论数量来评估。详情：AI-Volume Review Policy。

AI 生成代码审查清单

审查 AI 生成的代码或 Agent 创建的 PR 时，请执行以下检查：

检查项	关注内容
虚构的导入项	不存在的包或方法；使用 npm info / pip index 验证
过时的 API	已弃用的方法、旧版签名、已移除的功能
安全漏洞	缺少输入验证、硬编码的密钥、SQL 字符串拼接、未转义的输出
缺少错误处理	仅覆盖正常情况；没有 try/catch、空值检查或超时处理
冗余抽象	不必要的封装、过早泛化、过度设计的模式
复制粘贴偏差	不同文件中的相似代码块存在细微不一致
测试表演	断言实现细节、模拟所有内容或测试框架本身的测试
无障碍遗漏	缺少替代文本、ARIA 错误、没有键盘操作支持、div 滥用
违反设计系统规范	组件忽略现有的设计令牌、间距或组件模式
自信却错误的注释	文档字符串描述代码应该做什么，而非代码实际做什么

来源：幻觉检测、AI 设计反模式

严重性判定标准

问题报告的证据门槛。

报告阻断级或高严重性问题前，应提供与问题类别相适应的最小证据：可到达的执行路径或状态转换路径、失败示例或测试，或具体的契约不匹配。指出被违反的不变量及其对用户的影响，并说明任何无法核实的假设。只有在安全问题和受污染数据问题中，才需要追踪可控输入到数据接收端的路径。如果无法确认必要的可达性或契约证据，应提出疑问或报告条件性风险，而不是断言存在缺陷。

优先级	标签	标准	评审操作
P0	阻断级	数据丢失、安全漏洞、正确性错误、生产路径崩溃	合并前必须修复
P1	必须修复	缺少错误处理、回滚失效、行为未定义、违反 SLA	合并前必须修复
P2	建议修复	非关键路径的测试缺口、轻微低效、可读性问题	在此 PR 中修复或创建跟踪问题
P3	可选	风格偏好、命名偏好、未来改进	作者自行决定；不阻止合并

为每个问题标注其优先级和标签。不要在同一条评论串中混合 P0 和 P3 问题。

严重性校准规则（按顺序应用；命中第一条后即停止）：

1. 严重性取决于按当前状态合并后的影响，而非修复所需的工作量。一个会导致资金数据损坏的单字符差一错误属于 P0；一个有 200 行、写得糟糕但能正常工作的模块属于 P3。
2. 在生产环境中不可达（死代码路径、功能标志关闭、仅用于测试的代码）时，严重性降低一级，并以明确指出假设的问题形式报告；无法证明可达性的评审者不能宣称这是 P0。
3. 涉及身份验证、资金流转、迁移、密钥或公共 API 的问题，严重性提高一级，因为合并后需要通过回滚或数据修复来解决，而非打补丁。
4. 缺少测试的严重性取决于该测试本应捕获的行为：高风险路径上的修复缺陷为 P1，其他情况为 P2；代码改动少且缺口已有跟踪记录时为 P3。
5. 对不确定的问题，应按其若属实所对应的严重性标为 question:；不要为了避免争议而将不确定性降为 P3，也不要凭猜测断言为 P0。
6. 未经测量的性能问题最高为 P2，除非差异引入了明显无界的热点路径操作（请求循环中的 N+1、针对新查询的全表扫描、无界内存集合）；需要性能分析才能确认的疑似回归，应交由 software-performance 处理。

应跳过的内容，让评审时间集中于风险：格式问题（由代码检查工具负责，应改为启用该工具）、已确认不存在依赖或契约偏移的生成文件和锁文件、影响范围不涉及差异的既有问题（另行记录），以及在评论中复述 PR 描述。

何时不应阻止合并

阻止合并是有代价的：它会延迟价值交付，促使大家把后续更改攒在一起，以免再经历一轮审查；如果用在无关紧要的分歧上，还会损害审查者的公信力。以下情况不要阻止合并：

• 仅有 P3 级问题（风格、命名偏好、“更优雅”的抽象）——将其作为非阻塞建议提出，由作者决定。
• 方案正确，只是你会采用不同的写法，且没有发现缺陷或可维护性代价。
• 对于确实风险低、变更频率低的代码，缺少测试覆盖；作者已明确承认这一缺口，且问题已记录。
• diff 影响范围之外的既有问题——创建后续任务，而不是扩大本次审查范围。
• 实际上涉及产品或需求，而非代码的分歧——升级给合适的负责人，而不是在审查评论中反复争论。

对于 P0/P1 级问题、确实有风险的新行为缺少测试，以及任何合并后修复成本高昂或不安全的问题（数据迁移、公共 API 形态、安全边界），应阻止合并。如有疑问，应将阻塞问题与可选问题分开，不要让前者影响后者的优先级。

识别走过场的审查

快速、少评论的审查并不一定有问题——写得好、规模小、风险低的更改本就应该能快速审查。将以下情况视为值得再检查一次的警示信号，而非审查不力的证据：

• diff 远超 400 LOC（Cisco/SmartBear：审查量应少于 200，绝不超过 400），但审查耗时相对于其规模短得不合常理（有关此启发式依据的规模/速度数据，请参阅 references/large-pr-review-strategies.md 和 references/code-review-metrics.md）。
• 涉及身份验证、资金转移、迁移或公共 API 的更改，只得到一句“LGTM”，没有任何实质性评论。
• 某个团队或个人的缺陷逃逸率呈上升趋势，而审查周转时间却在缩短——速度提升很可能是以跳过审查为代价。
• 批准意见只是复述 PR 描述，没有提及具体代码行或行为。

将这些视为辅导信号（抽查、结对审查、询问实际阅读了哪些内容），不要把它们做成公开排行榜——有关如何跟踪这些信号而不造成激励机制被钻空子的情况，请参阅 references/code-review-metrics.md。

审查测试，而不只是代码

diff 中的测试通过了，但没有审查测试质量，这样的审查只完成了一半。对测试代码也应像对生产代码一样严格审查：

• 确认新增或变更的行为确实有对应测试，且没有修复时该测试会失败，而不只是恰好与修复同时通过。
• 留意那些断言实现细节而非可观察行为的测试（把所有内容都模拟掉、检查内部调用次数）；这类测试很容易通过，重构时却发现不了问题。
• 检查是否测试了错误路径和边界情况，而不只是正常流程。
• 将没有回归测试的缺陷修复视为不完整，而非风格问题。

常见陷阱

• 先看 PR 描述，再看 diff。应将描述视为主张，而非证据。
• 把大部分精力花在风格上，几乎不关注行为风险、迁移风险或回滚安全性。
• 将生成文件、快照或 lockfile 的大量变动视为噪声，却不检查它们是否掩盖了契约或依赖项的变动。
• 只审查变更行，而忽略问题可能出在周边不变量、调用方预期或清理路径中。
• 泛泛地指出 needs tests，却不说明缺少的场景、边界情况或回归测试。
• 未进行实时验证，就接受 diff 评论中关于基准测试、安全性或框架的说法，尤其是在这些说法与版本有关时。

常见反模式

• 将评审当作走过场的审批：只对命名提出浅显意见，却不检查正确性和发布风险。
• 在评审中重写作者的架构，而真正的问题只是一个更小的 bug、缺失的防护措施或薄弱的约定。
• 混淆偏好与缺陷。将个人喜好标为可选，并仅针对正确性、安全性或可维护性风险提出阻塞性评论。
• 将多个彼此独立的问题合并到一个冗长的评论串中，而不是基于证据分别列出具体问题。
• 将 AI 评审结果视为权威结论，而不根据实际差异和本地上下文逐项核实。

默认评审输出

默认包括：

• 简短概述意图和风险
• 按 P0 / P1 / P2 / P3 分组的问题
• 标注 REQUIRED 与 OPTIONAL
• 提供具体的修复方案：最小差异、测试用例或配置修复
• 仅在需求确实不明确时提出后续问题

措辞请参考 assets/core/review-comment-guidelines.md，最终审查判断请参考 assets/core/review-checklist-judgment.md。按照 Conventional Comments 约定标注评论意图（suggestion:、issue:、question:、nitpick:、praise:），确保阻塞与非阻塞意图清晰明确，不依赖语气判断。

导航

核心参考资料：

• references/operational-playbook.md
• references/automation-tools.md
• references/review-checklist-comprehensive.md — 按关注点组织的完整检查清单，以及来自“Looks Good To Me”和“Implementing Effective Code Reviews”的评审流程实践
• references/security-focused-review-guide.md
• references/large-pr-review-strategies.md
• references/code-review-metrics.md
• references/psychological-safety-guide.md
• references/dotnet-efcore-crypto-rules.md
• references/adversarial-review-protocol.md — 剥离上下文后的交接与固定优先级的问题协调、双评审者关卡，以及用于提交前决策评审的批次抽样
• references/complexity-only-review-pass.md — 范围狭窄、有标签、仅关注过度工程的评审流程，可快速补充完整检查清单
• references/deterministic-vs-llm-routing.md — 评审前的确定性文件关卡、按规模设定的规划阶段阈值，以及 AI 评审工具的自我反驳筛选流程

模板：

• assets/core/pull-request-description-template.md
• assets/core/review-comment-guidelines.md
• assets/backend-api/api-review.md
• assets/web-frontend/frontend-review.md
• assets/mobile/mobile-review.md
• assets/infrastructure/infrastructure-review.md
• assets/blockchain/crypto-review.md

来源：

• data/sources.json - 已验证的来源集合，包含平台状态及已失效链接的替代链接

时效性协议

当用户询问以下内容时：

• 最佳或最新的代码审查工具
• 当前的 PR 自动化实践
• GitHub Copilot、CodeRabbit、Qodo 与平台原生选项的对比
• 某个工具是否仍然适用

你必须：

1. 使用网络搜索。
2. 优先参考官方文档和版本发布／状态页面，而非供应商的对比博客。
3. 将 data/sources.json 作为起始来源集。
4. 除非经过独立验证，否则将供应商指标和案例研究中的性能数据视为仅供参考。

如果无法访问网络，请说明这一点，并根据 data/sources.json 作答，同时明确标注时效性建议未经验证。

经验总结循环

当过往决策或注意事项与当前任务相关时，请查阅 learnings.consolidated.md（如果存在）；只有在需要了解历史记录或它是唯一可用来源时，才查阅 learnings.md。否则跳过两者。

应用经验后，如果遇到值得记住的模式、值得避免的错误，或出乎意料的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的要点。不要修改 SKILL.md 本身。