code-review

---
name: code-review
description: 代码审查标准——审查流程、P0-P3分级、检查项。质量保障SKILL，可独立使用。
---

# Code Review 规范

本 skill 定义 Code Review 的标准流程、评审维度和问题分级规则。适用于开发阶段的代码审查。可独立使用。

## 循环角色

版本背景：本循环语义于 0.65.0 引入；本标题是稳定规范，不随版本号变更。

**角色映射：** 在目标 Loop 模型中，本审查对应开发切片 Inner loop 的 `loop-exit-gate`。0.66.1 的当前运行能力仍是 experimental scaffolding；该映射不表示持久化 Loop runtime 已激活。

当前可执行行为仅为 Coordinator M7.4 的 `NEEDS_CHANGE -> 返工 -> 复审`，以及 Check 30 对复审链终态、轮次连续性和熔断结果的校验。

<!-- loop-runtime-target:{"claim_id":"LRC-CODE-PLANNED-001","target_version":"0.68.0","status":"planned_not_active"} -->
持久化 back-edge、flow-unit `loop_count`、Inner fuse、PARO transition 与自动升级属于 0.68.0 规划，当前不生效。

Reviewer 只审查并输出结论，不修改产品代码。Reviewer 必须输出 `APPROVED`、`APPROVED_WITH_NOTES`、`NEEDS_CHANGE` 或 `BLOCKED`；`APPROVED_WITH_NOTES` 是保留备注的通过终态，只能用于没有未解决 BLOCKING finding 的审查，不得包含未解决的 BLOCKING finding。`APPROVED_WITH_NOTES` 的审查输出与 REVIEW 证据 MUST 包含独立结构字段 `unresolved_blockers=0`；字段缺失、非零、非法或重复矛盾时不得通过，自然语言中偶然出现的 `blocking` 不构成该事实。`NEEDS_CHANGE`（及兼容输入 `NEEDS_CHANGES`）不是终态，Coordinator 必须在返工后发起下一轮复审。终态证据由 Check 30 的复审链消费：`APPROVED` 与 `APPROVED_WITH_NOTES` 可以通过并结束复审链；`BLOCKED` 结束链路但不是通过，必须 escalation；`NEEDS_CHANGE(S)`、未知或格式错误结论必须 fail-closed。超过复审 fuse 的 `NEEDS_CHANGE` 必须升级为 `BLOCKED`。

依据 ADR §3.5（loop-engineering-architecture-0.65.0）。完整映射见 [共享循环角色映射](../software-project-governance/references/loop-role-mapping.md)。

## 触发条件

- 代码已提交 Review 请求（Pull Request / Merge Request）
- 一个功能模块或一批关联变更开发完成
- 用户要求对当前代码进行 Review

## 输入

| 输入项 | 说明 | 是否必须 |
|--------|------|---------|
| 待审查代码 | PR/MR 或代码变更集 | 必须 |
| 设计文档 | 对应模块的详细设计 | 推荐 |
| 编码规范 | 项目的编码规范文档 | 推荐（缺失时使用通用规范） |

## 评审维度

### 维度 1：正确性

| # | 检查项 | 说明 |
|---|--------|------|
| 1 | 逻辑正确 | 代码逻辑是否实现了设计意图 |
| 2 | 边界条件 | 空输入、极大值、极小值、null/undefined 等是否处理 |
| 3 | 并发安全 | 共享状态的并发访问是否安全 |
| 4 | 资源管理 | 文件句柄、连接、内存等是否正确释放 |

### 维度 2：安全性

| # | 检查项 | 说明 |
|---|--------|------|
| 1 | 输入校验 | 外部输入是否做了验证和清洗 |
| 2 | 注入防护 | SQL 注入、XSS、命令注入等是否防护 |
| 3 | 敏感数据 | 密钥、token、密码是否硬编码（禁止） |
| 4 | 权限检查 | 接口是否有适当的权限控制 |

### 维度 3：可维护性

| # | 检查项 | 说明 |
|---|--------|------|
| 1 | 命名可读 | 变量、函数、类名是否表达意图 |
| 2 | 函数长度 | 单个函数是否超过 50 行（建议拆分） |
| 3 | 重复代码 | 是否有可提取的重复逻辑 |
| 4 | 注释质量 | 复杂逻辑是否有注释，注释是否与代码一致 |

### 维度 4：性能

| # | 检查项 | 说明 |
|---|--------|------|
| 1 | 避免不必要的循环 | O(n²) 以上算法是否必要 |
| 2 | 数据结构选择 | 是否使用了合适的数据结构 |
| 3 | 懒加载 | 大对象是否延迟初始化 |
| 4 | 批量操作 | 循环中的 I/O 是否可合并 |

### 维度 5：测试覆盖

| # | 检查项 | 说明 |
|---|--------|------|
| 1 | 核心路径有测试 | 关键业务逻辑是否有对应测试 |
| 2 | 边界测试 | 边界条件是否覆盖 |
| 3 | 错误路径测试 | 异常和错误情况是否覆盖 |
| 4 | 覆盖率达标 | 按 profile 要求（standard ≥70%, strict ≥90%） |

## 问题分级

| 级别 | 含义 | 处理方式 | 示例 |
|------|------|---------|------|
| **P0 阻塞** | 必须修改才能合并 | 阻塞合并，修改后重新 Review | 安全漏洞、数据丢失风险、逻辑错误 |
| **P1 关键** | 强烈建议修改 | 原则上本轮修改，可申请遗留到下一轮 | 性能隐患、边界条件未处理、明显代码坏味道 |
| **P2 建议** | 建议修改 | 可作为遗留项，不阻塞合并 | 命名改进、注释补充、代码简化 |
| **P3 讨论** | 纯讨论/疑问 | 不要求修改，用于知识分享 | "为什么选这个方案？"+ 作者回复 |

## 执行步骤

### 第一步：自检（代码作者）

提交 Review 前，代码作者完成自检：

| # | 自检项 | 通过标准 |
|---|--------|---------|
| 1 | 本地测试通过 | 单元测试 + 集成测试全部通过 |
| 2 | 静态检查通过 | lint / type check 无错误 |
| 3 | 自查安全性 | 无硬编码密钥、无注入风险 |
| 4 | PR 描述完整 | 包含变更原因、变更内容、测试方法 |

### 第二步：Review（审查者）

| # | 活动 | 说明 |
|---|------|------|
| 1 | 通读 PR 描述 | 理解变更的背景和目的 |
| 2 | 按维度检查 | 依次检查 5 个评审维度 |
| 3 | 标注问题级别 | 每条意见标注 P0~P3 |
| 4 | 给出总结评价 | 总体评价 + 是否建议合并 |

**事实依据红线**：
- 每条阻塞/通过结论 MUST 指向可复查事实：文件路径、代码行、命令输出、测试结果、日志或用户明确输入。
- 无法从事实验证的内容 MUST 标为“未验证/待验证/BLOCKED”，不得写成已通过。
- 禁止用假设、猜测、推测、估计、编造或幻觉作为审查结论依据。

**Review 原则**（参考 Google Code Review）：
- 审查者不只是看代码对不对，更要看设计是否合理
- Review 意见应具体、可执行，不用"这里不太好"等模糊描述
- 发现更好方案时，提建议而非直接要求改

### 第三步：问题处理（代码作者）

| # | 活动 | 说明 |
|---|------|------|
| 1 | 逐条回复 Review 意见 | 每条标注：采纳 / 拒绝（附理由） / 遗留（附计划） |
| 2 | 处理 P0 和 P1 问题 | P0 必须修改，P1 原则上修改 |
| 3 | 更新代码 | 修改后推送到同一 PR |
| 4 | 请求二次 Review | 修改完成后通知审查者复查 |

### 第四步：关闭

| 条件 | 动作 |
|------|------|
| P0 = 0 且 P1 = 0 | 合并 |
| P0 = 0 且 P1 > 0（有遗留计划） | 有条件合并，遗留项记录到跟踪表 |
| P0 > 0 | 不得合并，修改后重新 Review |

## 输出

| 产出物 | 格式 |
|--------|------|
| Review 意见清单 | 每条有级别、位置、描述、建议 |
| 处理结果 | 每条意见的采纳/拒绝/遗留状态 |
| Review 结论 | APPROVED / APPROVED_WITH_NOTES / NEEDS_CHANGE / BLOCKED |
| 遗留项列表（如有） | 每条有关闭截止日期 |

## 质量标准

- [ ] Review 意见覆盖了 5 个评审维度
- [ ] 每条意见有明确的级别标注（P0~P3）
- [ ] 所有 P0 问题已关闭（P0 计数 = 0）
- [ ] 所有 P1 问题已处理或记录为遗留项
- [ ] Review 结论有明确理由

## 独立使用说明

本 skill 可脱离完整生命周期独立使用。

### 如果项目已初始化 governance（`.governance/` 存在）
1. 先执行目标锚定检查（读 plan-tracker → 确认成功标准 → 偏离检查）
2. 不需要先通过任何 Gate
3. 可用于任何代码变更的 Review（不限于正式开发阶段）
4. 如果后续接入完整工作流，本 skill 的产出自动成为 G6（开发完成）中"Code Review 记录"的证据

### 如果项目未初始化 governance（`.governance/` 不存在）
1. 跳过所有治理前置检查
2. 直接执行本 skill 的核心流程（P0 阻塞检查 + P1 关键检查 + P2 建议检查）
3. 执行完毕后提醒用户："当前项目未初始化 governance。如需自动证据记录、Gate 检查、风险跟踪，运行 `/governance-init`。"

## 子工作流映射

| 本 skill 步骤 | 对应子工作流活动 | 映射说明 |
|--------------|-----------------|---------|
| 自检 | 开发实现→Code Review→自检清单 | 自检是提交 Review 的前置条件 |
| Review | 开发实现→Code Review→提交 Review | 审查者按 5 个维度检查 |
| 问题处理 | 开发实现→Code Review→处理 Review 意见 | 逐条回复和处理 |
| 关闭 | 开发实现→集成验证 | P0=0 时可合并进入集成分支 |