code-review-axes-and-quality

代码审查维度与质量

使用此技能对提交范围、功能、模块或工作树进行结构化审查。此技能使用委派模式作为执行层，并生成持久化计划，而非仅在聊天中给出意见。

相关配套技能

将 delegation-mode 用作此技能的执行层。在创建或运行审查计划之前，请先阅读：

../delegation-mode/SKILL.md

遵循其工作者约定、稳定的任务 ID、.agents/plans/ 输出约定、串行／并行选择规则、已验证的结果文件标记，以及跨会话 DONE_IDS 恢复流程。此技能定义审查质量；delegation-mode 定义如何分派和恢复审查。可执行的审查模板还会验证每个维度的产物，并拒绝忽略未解决的 CRITICAL 或 HIGH 级问题的最终批准。

审查模板使用共享的 delegation-mode 验证核心来检查计划标识、安全路径、DONE_IDS、frontmatter、完成标记和持久化文件。各维度的审查要求以及结论／阻塞项检查仍由此模板本身负责。

审查标准

合并之前审查每项变更，但审批门槛应与变更相称：如果变更改善了整体代码健康状况，且没有未解决的阻塞问题，就应批准。不要因为个人风格偏好或追求完美代码而阻止合并。不要仅因测试通过或作者信心十足就草率批准。

每项发现都必须有证据、可采取行动，并按影响力排序：首先是正确性和安全性，其次是结构性回归和错失的简化机会，最后是影响较小的问题。如果报告了结构性问题，应提出能够解决问题的调整方案，而不只是描述代码复杂。

固定审查维度

运行全部十个维度，包括没有发现的维度：

#	维度	关注点
1	正确性	Bug、边界情况、错误假设、回归
2	性能	瓶颈、不必要的工作、延迟、内存、热点路径
3	可扩展性	在增长、并发或输入变大时发生的故障或性能下降
4	基础设施	现有项目接线、边界、运维
5	库使用规范	依赖项、受支持的 API、版本、用法
6	安全性	输入处理、身份验证、密钥、注入、SSRF、XSS、滥用
7	数据完整性与并发	原子性、幂等性、竞争、顺序、重试
8	可观测性	日志、指标、追踪、告警、诊断、故障可见性
9	可维护性	耦合、内聚、变更风险、重复、架构
10	可读性	命名、控制流、局部理解、认知负担

可维护性和可读性是不同的：可维护性评估未来的变更是否安全且局部化；可读性评估当前行为是否易于理解，而无需推断隐藏意图。

每项发现都包括：

• 问题所在；
• 文件与行号或符号；
• 问题的重要性；
• 建议的修复方案；
• 严重程度：CRITICAL、HIGH、MEDIUM 或 LOW。

每个维度的结果还必须包含精确的审查范围、分配的维度，以及实际验证证据。没有发现的维度必须明确说明未发现问题。只有标记的文件不算已完成的审查结果。

只有明确说明审查范围内未发现问题，空维度才算完成。

各维度审查指南

在审查各自负责的维度时，请遵循以下要点：

• 正确性： 对照规范和测试检查行为。检查 null、空值、边界、重试、超时和错误路径，而不仅是正常路径。留意状态不一致、差一错误和回归问题。
• 性能： 检查 N+1 查询、无界的处理或数据获取、可避免的同步操作、热点路径上的内存分配，以及 UI 重渲染开销。
• 可扩展性： 检查数据量、流量、租户数、并发度和负载大小增长时的行为。留意资源限制、队列／背压行为、争用和扇出。
• 基础设施： 检查项目接线、部署／运行时假设、配置、迁移、运维边界、回滚行为和故障恢复。
• 库依赖卫生： 优先使用现有技术栈和标准库。审查新增依赖的维护情况、许可证、漏洞、打包／运行时影响、受支持的 API、变更日志／迁移说明，以及 lockfile 变更。
• 安全性： 将边界处的用户输入、外部数据、日志和配置视为不可信。检查验证、授权、密钥、注入、XSS、SSRF、滥用控制和依赖供应链风险。
• 数据完整性与并发： 检查原子性、幂等性、顺序、重试、竞态、事务边界、重复工作和部分故障。
• 可观测性： 检查重要成功和失败路径是否具备实用的结构化日志、指标、跟踪、告警、诊断信息和错误可见性。
• 可维护性： 留意耦合、重复、共享模块中的功能逻辑、循环依赖，以及只是转移而未降低复杂度的抽象。质疑不清晰的类型边界和静默回退。
• 可读性： 检查命名、控制流、局部可理解性、死代码、注释、文件大小，以及附加在无关流程上的条件分支。

审查流程

每次审查均按以下顺序进行：

1. 理解意图。 阅读任务／规范、相关计划、当前检出代码和近期提交。说明预期行为变更及确切范围。
2. 先读测试。 找出与变更相关的测试，确认它们测试的是行为而非实现细节，并记录缺失的回归或边缘情况覆盖。
3. 阅读完整实现上下文。 不要只审查差异片段。追踪调用方、规范辅助函数、类型边界、配置和依赖，以理解相关行为。
4. 检查全部十个维度。 各维度分别审查，包括没有发现问题的维度。除非影响确实不同，否则不要在多个维度重复报告同一问题；最终报告会合并重复项。
5. 核实验证情况。 记录实际运行过的测试、lint、类型检查、构建、手动检查、UI 变更截图、基准测试和依赖检查。不要声称运行过未执行的检查。
6. 给出结论。 只有在没有未解决的 CRITICAL 或 HIGH 问题时才予以批准。若推迟处理较低严重性的问题，请记录原因、负责人／后续行动（如已知）及剩余风险。

查找严重性和状态

请始终一致地使用以下严重性定义：

严重性	含义	默认决策
CRITICAL	可被利用的安全问题、数据丢失、核心功能故障，或导致生产环境无法继续运行的紧急问题	阻止批准
HIGH	可能存在的错误、严重的安全／契约问题，或造成实质影响的结构性回归	通常阻止批准
MEDIUM	影响范围有限，但在可维护性、性能、可扩展性、可观测性或正确性方面存在实质缺陷	若属于当前范围，应在合并前修复；否则记录延期处理
LOW	影响有限的改进、润色或局部清理	可选，除非项目规则另有规定

使用现有的 Status 列填写处理状态： required、recommended、optional、accepted-risk 或 resolved。除非审查范围内有证据表明问题已修复并验证，否则不得将发现标记为 resolved。

结构性修复方案

如果问题具有结构性，请指出具体的修复方案。优先选择能减少活动部件的方案：

• 用类型化模型或显式分发器替代条件链；
• 合并重复分支，形成清晰统一的流程；
• 将编排与业务逻辑分离；
• 将特定功能的逻辑移至负责该功能的程序包；
• 复用规范的辅助函数，而不是添加近似重复的实现；
• 明确类型边界，消除下游分支判断；
• 删除仅增加间接层、却未能明确 API 的透传包装器；
• 提取辅助函数，或将大型文件拆分为职责明确的模块。

不要仅因代码重复过一次就建议引入宽泛抽象。只有存在真正共享的不变量，或有第三种用例支持时，才应进行泛化。

变更规模与分解

审查最终文件大小和变更规模，而不只是检查差异是否通过测试：

~100 changed lines   → easy to review
~300 changed lines   → acceptable for one logical change
~1000 changed lines  → split the change
~1000 total lines in one file → inspection signal; consider decomposition

这些只是检查信号，并非自动拒绝规则。如果变更规模过大，应建议采用堆叠式、按文件组、横向或纵向分解。除非为确保功能安全而必须进行小幅清理，否则应将重构与新增行为分开。

死代码与依赖项卫生

重构后，明确指出无法到达或未使用的代码。各工作轴负责人不得悄然删除用途不确定的代码；应列出符号及其看似未使用的原因，然后建议单独移除，或经验证后再决定是否清理。

对于依赖项变更，请检查现有技术栈是否已能解决问题、程序包的维护情况和许可证、已知漏洞、对打包产物或运行时的影响、受支持的 API、变更日志／迁移说明，以及锁文件差异。每项逻辑变更优先只升级一个依赖项，绝不要手动编辑锁文件。

派发任务前确定范围

制定计划前：

1. 阅读 .agents/chats/current.md（如存在）。
2. 阅读相关的有效计划或参考计划。
3. 检查当前检出内容和近期提交。
4. 确定确切的审查范围，即提交区间或工作树范围。
5. 阅读项目规则和相关记忆主题。

根据当前检出内容核验已保存的交接信息。切勿轻信过时的分支、文件、提交或验证声明。

运行可复用计划

将 scripts/review-plan.template.js 复制到：

.agents/plans/YYYY-MM-DD-<slug>.js

填写 DATE、SLUG、PROJECT_CONTEXT 和审查范围。选择：

const MODE = "sequential"; // or "parallel"

每个维度都会写入一个独立的计划文件：

YYYY-MM-DD-<slug>-01-correctness.md
...
YYYY-MM-DD-<slug>-10-readability.md
YYYY-MM-DD-<slug>-FINAL.md

维度工作者必须使用 config: { $kind: "general" }，因为它们需要写入文件。 它们必须读取所有相关文件的完整内容，避免修改应用源代码，并且 在文件中写入确切标记后才能结束：

FILE_WRITTEN: <exact-path>

如果缺少标记，运行器会将其视为未解决，并且只有在全部十个维度确认后才会汇总。

每个维度的结果必须包括：

• 确切的审查范围和相关证据；
• 指定的维度；若无发现，须明确声明无发现；
• 包含严重性、位置、影响、建议修复方案和状态的发现；
• 已执行或无法执行的验证；
• 相关的结构性补救措施、死代码说明或依赖项说明；
  • FILE_WRITTEN: <exact-path> 必须作为文件和响应中的最后一个非空行。调度器会检查文件本身，而不只检查响应。

跨会话恢复

运行中断后：

ls .agents/plans/YYYY-MM-DD-<slug>-*.md 2>/dev/null

检查输出文件，并仅将已确认的维度 ID 更新到 DONE_IDS：

const DONE_IDS = [
  "01-correctness",
  "02-performance",
];

重新运行完整计划。它会跳过这些 ID，只分派缺少的维度。只有在确认最终报告存在且完整后，才将 FINAL_DONE = true。不要根据聊天没有回复或不完整文件来推断任务已完成。

最终报告

最终计划会去重发现，按严重性对主表排序，将具体的优先工作项分组，并为下一个 Agent 提供足够的上下文以便采取行动。它还必须包括：

• 简洁的上下文和意图摘要；
• 判定结果：APPROVE、APPROVE_WITH_FOLLOW_UP 或 REQUEST_CHANGES；
• 未解决的阻塞项和延期处理的较低严重性风险；
• 验证证据和明确的缺口；
• 适用时，对变更规模／拆分、依赖项和死代码的结论。

它不会更改应用代码。

审查后：

1. 确认全部十个维度文件和最终报告均已存在。
2. 检查 frontmatter 和相对链接。
3. 运行适用的测试、lint、类型检查、编译和构建。
4. 运行 git diff --check。
5. 在最终计划中记录验证结果和未解决的风险。
6. 确认没有任何标记为 resolved 的 CRITICAL 或 HIGH 发现缺少证据。
7. 如果仍有未解决的 CRITICAL 或 HIGH 发现，不要声称已通过审批。 模板会强制执行此后置条件；最终报告必须包含一行可供机器读取的 **Verdict:**。