rmsaitam/代码审查

代码审查 是做什么的？

作为高级审查者，审查 HEAD 与用户提供的固定基础之间的差异。生成一个可追溯的工件：

• CODE-REVIEW.md：审查上下文、摘要、规范维度、标准维度、建议的验证、证据、假设、开放性问题以及可追溯性。

独立审查两个维度：

• 标准：代码是否遵循本仓库的约定、安全策略、测试标准和架构决策？
• 规范：代码是否忠实地实现了问题、PRD 或规范？

永远不要混淆两个维度的结果。一个变更可以遵循所有约定，但仍然实现了错误的需求。

不要发出自动批准。仅报告风险和所需的验证。

何时使用

当用户以下情况时使用此技能：

• 请求审查分支、PR、合并请求或进行中的工作；
• 要求审查自某个分支、提交、标签、日期或 HEAD~N 以来的变更；
• 想要知道变更是否遵循了仓库标准；
• 想要知道变更是否实现了问题、PRD 或规范；
• 想要一个包含证据和建议验证的可追溯审查工件。

何时不使用

不要将此技能用于：

• 带有 CVSS、CWE 和 OWASP 映射的全面安全审计；请使用 security-audit；
• 产品发现、PRD、SPEC、里程碑或任务分解；请使用 techlead；
• 设计令牌、组件库或可访问性审计；请使用 design-system；
• 没有差异也没有固定基础的单行变更；直接审查它或询问基础；
• 运行测试、构建、代码检查或部署。此技能审查并建议验证；除非用户明确要求，否则不执行。

不可妥协的规则

• 在审查之前固定基础。当基础缺失时询问用户。永远不要假设 main。
• 使用 git rev-parse --verify 验证引用，并审查 git diff <base>...HEAD。
• 当基础不存在或差异为空时停止并报告。不要继续到专门的审查。
• 在分析、发现和报告中保持规范和标准维度分离。
• 仓库中记录的仓库标准优先于通用启发式规则。
• 忽略 lint、格式化器、类型检查器或 CI 已经检测并阻止的问题。
• 区分客观违反和改进建议。
• 不要在差异之外提议重构，除非涉及安全性、正确性或回归风险。
• 每个发现必须有证据：差异片段、文件和行、规范要求或可重现的观察。
• 不要捏造行、行为或需求。如果证据不足，写一条注释或开放性问题。
• 编辑掉机密、令牌、个人数据和客户数据。将值替换为 [REDACTED]。
• 默认只读：不要修改应用程序代码、依赖项、配置、提交或拉取请求。
• 除非用户明确要求，否则不要运行测试、代码检查、构建或部署。
• 不要为了放行发布而降低严重性。记录风险即可。
• 不要发出自动批准结论。报告风险和仍然需要的验证。
• 默认用英语编写工件。保持 ID、标记、严重性值、维度值和状态值为英语。
• 保留报告模板中的每个机器可读标记。
• 当剩余问题不会改变发现、严重性或验证计划时停止审查。

模式

在开始前选择模式并记录在工件中。

• 审查：固定基础，读取差异，审查两个维度，并编写或更新 CODE-REVIEW.md。
• 验证：验证现有的 CODE-REVIEW.md 是否符合报告合同，而不重新进行审查。

工作流程

按顺序遵循以下门控。不要跳过任何门控。

门控 1：固定审查基础

1. 确定固定点：分支、提交 SHA、标签、main、origin/main、HEAD~N 或其他显式引用。

2. 如果用户没有提供基础，询问必须使用哪一个基础。不要猜测。

3. 验证引用：

   git rev-parse --verify <base>
   

4. 检查仓库是否浅拷贝，当合并基础可能缺失时：

   git rev-parse --is-shallow-repository
   

5. 生成相对于合并基础的差异：

   git diff <base>...HEAD
   

6. 列出包含的提交：

   git log <base>..HEAD --oneline
   

7. 收集差异大小和更改的文件：

   git diff --stat <base>...HEAD
   git diff --name-status <base>...HEAD
   

8. 检查工作树：

   git status --short
   

9. 如果存在未提交的更改，询问它们是否在范围之内。如果是，包含 git diff 和 git diff --cached 作为额外的审查范围，并记录该决定。

10. 如果基础不存在、无法解析合并基础或差异为空，停止并通知用户。不要继续到门控 2。

11. 在报告证据部分记录每个命令、其目标以及相关输出。

当用户提供日期而不是引用时，显式解析该日期之前的最后一个提交：

git rev-list -1 --before=<date> HEAD

只有在用户确认后，才使用生成的提交作为基础。

门控 2：查找规范

按以下顺序查找需求来源：

1. 提交、分支名称或 PR 描述中的问题引用（#123、Closes #45、Fixes #78）。
2. 用户提供的规范路径。
3. docs/、specs/、.scratch/ 或 tasks/ 中与分支名称或功能相关的文件。
4. 询问用户规范在哪里。

阅读来源并提取：

• 问题和期望结果；
• 验收标准；
• 显式的范围之内和范围之外的项目；
• 约束、边界情况和非功能性需求；
• 差异未触及但必须保留的需求。

将每个需求映射到实现它的文件、行为和测试。

如果用户说没有规范，则准确记录：

无可用规范；规范审查已跳过。

设置 Spec review: skipped，不要审查规范维度或发明需求。

门控 3：加载仓库标准

读取（如果存在）：

• CONTRIBUTING.md；
• CODING_STANDARDS.md；
• ARCHITECTURE.md；
• SECURITY.md；
• docs/adr/ 中的 ADR；
• lint、格式化器、测试和 CI 配置；
• 仓库中最近批准的示例。

规则：

• 记录的仓库标准优先于通用启发式规则。
• 忽略 lint、格式化器、类型检查器或 CI 已经检测并阻止的问题。
• 区分客观违反和改进建议。
• 引用支撑每个标准发现的规则。
• 如果没有记录标准，使用通用启发式规则，并在发现引用中标记为这样。
• 如果标准不明确，记录一个开放性问题，而不是发明一个规则。

门控 4：按类别审查

审查每个更改的文件和每个有意义的代码块。不要只审查添加的行；考虑周围的代码和变更行为的消费者。

规范维度

• 需求满足：将每个验收标准映射到实现及其测试。
• 差距或不正确实现：缺失的需求、部分实现、错误行为、与规范矛盾或未测试的需求。
• 额外范围：在规范之外添加的行为、未请求的重构、更改的公共契约或范围蔓延。
• 对于每个差距，引用确切的需求以及实现失败的文件和行。

标准维度

• 正确性：错误、边界情况、错误处理、并发、null/undefined、类型和意外行为。
• 安全性：注入、身份验证和授权、输入验证、数据泄露、机密、SSRF、XSS、CSRF、不安全的文件处理和权限边界。
• 测试：新或更改路径的覆盖、负面情况、回归、断言质量和脆弱性。
• API 和兼容性：破坏性变更、公共契约、版本控制、迁移和消费者兼容性。
• 性能：N+1 查询、不必要的循环、分配、缓存行为、索引和可避免的同步工作。
• 可维护性：名称、重复、耦合、职责、过早抽象以及与领域的一致性。
• 可观察性：当变更影响生产操作时的日志、指标、跟踪、警报和有用的错误消息。

有关详细检查清单，请使用 references/review-checklist.md。

门控 5：编写报告

使用 references/report-template.md 创建或更新 CODE-REVIEW.md。默认位置是当前工作区根目录。当用户提供不同路径时接受。

要求：

• 保留工件标记和每个必需的部分标记。
• 记录基础、HEAD、合并基础、提交数量、更改的文件、标准来源和规范来源。
• 保持规范和标准部分分离。永远不要将规范发现移至标准，反之亦然。
• 使用稳定的发现 ID：CR-001、CR-002 等。不记录更改时不要重新编号已批准的发现。
• 每个发现使用一个严重性：blocking、recommended 或 note。遵循 references/severity-baseline.md。
• 为每个发现提供维度、类别、位置、问题、证据、建议、引用和验证步骤。
• 使计数标记与发现完全匹配。
• 使摘要计数与计数标记匹配。
• 在可追溯性部分将每个发现映射到证据和建议的验证。
• 说明规范审查是已执行还是已跳过。当跳过时，包含门控 2 中的确切句子。
• 当某个类别没有发现时，写 No findings。不要留空节。
• 不要包含机密、个人数据或客户数据。将其编辑为 [REDACTED]。
• 不要包含批准结论、LGTM 或 Ship it。

门控 6：验证

解析相对于此 SKILL.md 的验证器路径并运行：

python3 skills/code-review/scripts/validate_review.py CODE-REVIEW.md

选项：

--strict                     将警告视为失败。
--json                       发出机器可读的报告。
--min-findings N             要求至少 N 个发现。默认为 0。
--require-spec               当规范审查被跳过时失败。
--require-standards-sources  当没有列出标准来源时失败。

修复每个错误并重新运行验证器。不要交付验证失败的报告。

如果 Python 不可用，请执行 references/validation-checklist.md 中的手动检查清单。

门控 7：交接

报告：

• CODE-REVIEW.md 写入的位置；
• 审查的基础、合并基础、提交数量和更改的文件；
• 按严重性和维度的发现计数；
• 规范审查状态和最高风险的规范差距；
• 最高风险的标准发现及其影响；
• 验证结果；
• 限制条件、排除的文件和未运行的检查；
• 没有更改应用程序代码、依赖项或配置。

提供提出修复或补救计划的提议，但除非用户明确要求，不要修改代码、提交、推送或打开拉取请求。

双维度规则

维度回答不同的问题，必须保持分离：

维度	问题	典型证据
规范	变更是否实现了请求的需求？	问题、PRD、规范、验收标准
标准	变更是否遵循仓库约定和工程标准？	CONTRIBUTING、ADRs、lint/测试/CI 配置、代码审查

仅当根本原因不同且修复方法不同时，发现才可能同时存在于两个维度。否则，在拥有根本原因的维度下记录一次，并在引用字段中交叉引用另一个维度。

示例：

• 一个变更遵循所有约定但省略了一个验收标准：一个规范 blocking 发现，没有标准发现。
• 一个变更实现了需求但引入了授权绕过：一个标准 blocking 发现和一条规范说明该需求已实现但不安全。
• 一个变更使用记录但不良的模式实现了需求：一个标准 recommended 发现和一条规范“需求满足”条目。

工件合同

CODE-REVIEW.md 以以下内容开头：

<!-- code-review:artifact type=review version=1 -->

必需部分使用标记：

<!-- code-review:section id=summary -->
<!-- code-review:section id=context -->
<!-- code-review:section id=spec -->
<!-- code-review:section id=standards -->
<!-- code-review:section id=validation -->
<!-- code-review:section id=evidence -->
<!-- code-review:section id=assumptions -->
<!-- code-review:section id=traceability -->

规范部分还使用状态标记：

<!-- code-review:spec status=performed -->
<!-- code-review:spec status=skipped -->

计数标记必须与发现匹配：

<!-- code-review:counts blocking=1 recommended=2 note=0 -->

每个发现紧接在其标题之前使用一个标记：

<!-- code-review:finding id=CR-001 axis=standards severity=blocking category=security status=open -->
### CR-001：简短发现标题

每个发现主体包含：

• Axis：Spec 或 Standards
• Severity：Blocking、Recommended 或 Note
• Category：spec-gap、scope、correctness、security、tests、api、performance、maintainability 或 observability
• Location：path/to/file.ext:42、path/to/file.ext 或用于没有代码位置的规范发现的 n/a
• Problem：缺陷、风险或差距
• Evidence：差异片段、文件和行、规范要求或可重现的观察