# 企业 AI 代码 Review 能力治理方案
## 一、为什么要做 AI Review 治理
### 1.1 现实困境
传统 PR review 有三个结构性缺陷：
1. **稀缺性**：资深 reviewer 是瓶颈。PR 数量随团队规模线性增长，但审查能力不同步扩张，排队是必然。
2. **重复性**：大量 review 时间消耗在机械扫描——空指针、日志脱敏、测试缺失、依赖升级风险。这类工作价值密度低，却占用高价值人力。
3. **不一致性**：不同 reviewer 关注点差异导致审查质量波动，相同问题在不同 PR 里命运不同。

AI 提高了代码产出速度，却没有同步提升 review 吞吐——这个剪刀差会越来越大。
### 1.2 AI Review 的真实价值
AI review 的价值不是"更快看完代码"，而是：
- **审查前移**：在人工 reviewer 进入前，过滤掉 60~70% 的基础问题
- **注意力聚焦**：让人工 reviewer 把时间花在业务逻辑、架构判断和系统边界上
- **覆盖兜底**：跨文件影响、依赖链分析等人工容易漏掉的维度

---

## 二、Review 的七大维度

无论哪个阶段、哪种工具，review 的内容维度是相对固定的：

| 维度                          | 核心检查点            | 典型问题                     |
| --------------------------- | ---------------- | ------------------------ |
| **Security 安全**             | 注入、鉴权、加密、数据泄露    | SQL 注入、密钥硬编码、JWT 漏洞、越权访问 |
| **Bug 逻辑错误**                | 边界条件、并发、状态机、异常路径 | 空指针、Off-by-one、竞态条件、资源泄漏 |
| **Performance 性能**          | 数据库查询、数据结构、异步    | N+1 查询、不必要重复计算、阻塞调用      |
| **Maintainability 可维护性**    | DRY、复杂度、耦合       | 重复代码、圈复杂度过高、SOLID 违反     |
| **Test Coverage 测试覆盖**      | 边界测试、异常路径、Mock   | 缺失边界用例、未覆盖异常分支           |
| **Code Style 代码风格**         | 命名、格式、团队规范       | 命名不规范、格式不一致              |
| **Cross-file Impact 跨文件影响** | 依赖链、接口契约、上下游     | 接口改动未同步、隐式依赖断裂           |

**重要边界**：AI review 不覆盖以下内容，这两点必须保留人工判断：

- **业务逻辑正确性**：AI 不理解域模型，无法判断折扣计算对特定定价规则是否正确
- **架构决策**：AI 无法评估 PR 的整体设计方向是否符合系统目标

---

## 三、Review 指令体系

AI review 的质量上限取决于 review 指令的质量。指令体系分三个层级：
### 3.1 全局级
影响所有 AI 操作（不只是 review）：`sophie`AI检视提示词
### 3.2 仓库级
只影响当前仓库的 review 行为：
- `AGENTS.md`：和design、develop共享的规则
- `REVIEW.md`：team-specific review 规则，结构建议如下：
```markdown
## Always check
- 新 API 必须有集成测试
- 数据库查询必须有分页保护

## Style
- 用 match 替代链式 isinstance
- 错误信息必须包含 request_id

## Skip
- src/gen/ 下的自动生成文件
- vendor/ 目录
```
### 3.3 路径级
针对特定目录或文件类型的差异化 review 规则：
```yaml
# .coderabbit.yaml 示例
reviews:
  path_instructions:
    - path: "src/api/**"
      instructions: "严格检查认证和授权逻辑，所有入参必须校验"
    - path: "src/payment/**"
      instructions: "金融敏感模块，重点检查并发安全和幂等性"
    - path: "docs/**"
      instructions: "只检查格式和文档完整性"
    - path: "src/gen/**"
      instructions: "自动生成文件，skip review"
```

**实践建议**：为每个仓库指定 review instruction owner，每周花 1~2 小时维护规则和指令，这是 AI review 持续有效的关键。

---

## 四、Review 的五个阶段

AI review 不是一个点，而是覆盖开发全链路的能力体系。按介入阶段从早到晚分为五层：

### 4.1 开发过程分层 Review（最上游）

以 Superpowers 框架为代表的思路——**review 不应发生在实现完成之后，而应嵌入到设计与规划阶段，作为风险控制的前置机制**。

**四个核心原则**：

| 原则 | 含义 |
|---|---|
| **Review 前移** | 设计阶段发现问题的修复成本，远低于代码阶段。Spec 漏一个约束，到实现才发现，返工成本放大 10 倍 |
| **分层 Review** | 不同阶段暴露不同类型风险，不能用一次 review 覆盖所有 |
| **证据驱动** | `feels correct → proven correct`，review 必须基于可验证证据（测试通过、git history、smoke check） |
| **Gate 化** | Review 必须具备阻断能力，模糊建议会被忽略，必须是明确的 pass / fail gate |

#### 设计阶段：Spec Review

**动机**：spec 质量没有独立门禁，设计缺陷太晚暴露。一旦 spec 有 TODO、含糊表述、范围漂移，问题会一路放大到 plan 和实现。

**执行方式**：让 AI agent 用全新视角对 spec 文档做一次 Self-Review checklist：

```
□ Placeholder scan    是否存在 TODO / TBD / 不完整段落？
□ Internal Consistency 各章节之间是否存在矛盾？架构是否与功能描述相符？
□ Scope check         是否足以制定单一实施计划，还是需要先拆解？
□ Ambiguity check     任何需求是否可能有两种解释？如有，选定一种并明确说明
```

> 注意：官方实践表明 subagent review loop 会增加大量耗时但质量提升不明显，推荐 inline Self-Review checklist 而非单独派发 reviewer subagent。

#### 设计阶段：Plan Review

**动机**：很多 plan 看起来逻辑通顺，但一执行就遇到"步骤模糊"、"责任边界不清"。如果 plan 本身不可靠，越自动化，错得越快。

**Checklist**：

```
□ Spec coverage       Spec 里的每个需求，是否有对应的实现任务？
□ Placeholder scan    是否存在 "TODO: refine this"、"add validation later" 类占位？
□ Type consistency    前后任务之间的接口是否一致？
                      （如 Task 3 叫 clearLayers()，Task 7 叫 clearFullLayers() → 是 bug）
```

#### 实现阶段：两阶段评审

每个 task 完成后，不直接认定 DONE，而是经历两道质量门：

```
Task 完成
  ↓
第一阶段：Spec Compliance Review（做的是要求的东西吗？）
  ├── 由 fresh subagent 独立审查，不继承 implementer 的上下文
  ├── 逐条比对"需求 vs 实现"，不信任 implementer 的自述
  ├── 检查有没有漏项、误解、或额外加戏
  └── PASS → 进入下一阶段 / FAIL → 返回 implementer 修复
  ↓
第二阶段：Code Quality Review（把事做对了吗？）
  ├── 只有 spec compliance 通过后才触发
  ├── 检查代码质量、架构、测试、生产可用性
  └── PASS → task DONE / FAIL → 返回修复 + 重新 review
```

**子代理隔离原则**：

- reviewer subagent 不继承主会话历史，由 controller 精确提供任务全文和必要上下文
- 目的是避免"上下文污染"——reviewer 应该评判 work product，而不是被 implementer 的思路带偏
- 收到 review 意见后，先验证建议对当前 codebase 是否成立，再决定修改、提问还是 push back——**review 建议是 suggestions，不是命令**

---

### 4.2 本地 Agent Review（最早介入）

在 commit / push 之前，借助本地 AI agent 在开发者工作流中完成第一轮自检。

**典型实现**：Claude Code 的两个内置 slash command：

**`/review`**：通用代码审查

```
执行流程：
1. gh pr list → 查看待审 PR
2. gh pr view <number> → 获取 PR 详情
3. gh pr diff <number> → 获取 diff
4. 输出：概述 + 代码质量 + 改进建议 + 风险点
审查维度：正确性 / 项目约定 / 性能影响 / 测试覆盖 / 安全
```

**`/security-review`**：专项安全审查

```
核心设计原则：
- 角色定位：资深安全工程师，只关注新增/变更代码的高置信漏洞
- 置信门槛：只报 ≥ 0.8 置信度的明确可利用问题
- 误报控制：17+ 类硬性排除规则（DoS、速率限制、测试文件等）
- 流程：子任务探索漏洞 → 并行子任务误报过滤 → 过滤置信度 < 8

重点检查类别：
- 输入校验（SQL 注入、命令注入、路径遍历）
- 鉴权与授权（认证绕过、权限提升、JWT 漏洞）
- 加密与密钥（硬编码凭证、弱加密算法）
- 注入与代码执行（反序列化、XSS）
- 数据暴露（PII 泄漏、调试信息暴露）
```

**价值**：在 push 前就消灭基础安全漏洞，成本最低。

---

### 4.3 Git Repo Review（PR 触发）

PR 创建或更新时，自动触发 AI review，以 inline comment 形式反馈到具体代码行。

**原理：Multi-Agent 并行分析**

以 Anthropic Claude Code Cloud Review 为例，其设计思路代表了当前最佳实践：

```
PR 触发
  ↓
并行 Agent 分析（各司其职）
  ├── Correctness Reviewer：逻辑正确性、边界条件、并发、状态机
  ├── Security Reviewer：权限、注入、密钥、依赖风险
  └── Maintainability Reviewer：抽象质量、重复代码、耦合度
  ↓
Review Synthesizer：聚合 + 排序 + 去重 + 阈值过滤
  ↓
Inline Comment（按 severity 分级输出）
```

**Severity 分级**：

| 标记 | 含义 |
|---|---|
| 🔴 Important | 应在合并前修复的 bug |
| 🟡 Nit | 次要问题，不阻塞 |
| 🟣 Pre-existing | 非本次 PR 引入的已有问题 |

> 单模型一次性输出容易产生噪声；多 agent 并行 + synthesizer 过滤是降低误报的关键设计。

**触发策略**（三种模式）：

| 模式 | 适用场景 | 成本 |
|---|---|---|
| PR 创建后触发一次 | 推荐默认配置 | 低 |
| 每次 push 都触发 | 高风险核心服务 | 高 |
| 手动触发（`@claude review`） | 按需 | 可控 |

---

### 4.4 SaaS 平台 Review（专业化工具）

当团队需要更系统的 review 能力时，专业化 SaaS 平台（如 CodeRabbit）提供了更完整的工程化方案。

**技术架构核心：Context Engineering**

> "我们做的是 context engineering，而不是 prompt engineering。" —— CodeRabbit Director of AI

在调用任何推理模型之前，先通过确定性流水线构建完整上下文：

| 上下文来源 | 说明 |
|---|---|
| AST 代码图谱 | 构建函数/类/变量调用关系图，理解改动在整个 codebase 中的传播路径 |
| Import 依赖图 | 识别改动影响的相关文件范围 |
| 40+ Linters/SAST | 静态分析结果作为 LLM 推理的参考信号（非直接输出） |
| 知识库 Learnings | 从历史 PR 反馈中沉淀的团队习惯和规范 |
| MCP 外部文档 | Jira、Notion、Confluence 等业务上下文 |

**执行流水线**：

```
Step 01  Webhook 触发 & 鉴权
Step 02  沙箱环境初始化（独立容器，克隆仓库 + 安装依赖）
Step 03  上下文工程（并行）
         ① AST 图谱  ② 依赖图  ③ 40+ linters  ④ Learnings  ⑤ MCP 文档
Step 04  轻量模型摘要（压缩上下文 → 生成 PR Summary）
Step 05  多轮深度推理（o3/o4-mini/Claude，多 pass 分维度深审）
Step 06  噪声过滤 & 去重（LLM 判断 linter 警告是否真实问题）
Step 07  Comment 输出（inline + 一键修复建议）
```

**多模型分工策略**（精细成本控制）：

| 模型 | 用途 |
|---|---|
| o4-mini / o3 | 多行 Bug 检测、跨文件重构、架构层问题（推理密集型） |
| GPT-4.1 | PR 摘要、文档生成（长上下文型） |
| Claude Opus/Sonnet | 深度推理、生成 review comment |
| Nemotron-30B | 上下文收集与摘要阶段（降成本） |

---

### 4.5 多阶段联动全景

```
开发启动
  ↓ Spec Review（设计门禁）
  ↓ Plan Review（规划门禁）
  ↓
编码实现
  ↓ Spec Compliance Review（需求符合性）
  ↓ Code Quality Review（实现质量）
  ↓
push / commit
  ↓ 本地 /review、/security-review（开发者自检）
  ↓
PR 创建
  ↓ Cloud Review / SaaS Review（自动 inline comment）
  ↓
人工 Review（业务逻辑 + 架构判断）
  ↓
merge
```

五个阶段依次拦截不同类型的风险，越靠前的阶段修复成本越低。

---

## 五、持续学习机制

AI review 和人工 reviewer 一样，需要不断学习团队习惯才能越来越准。

### 5.1 Learning 沉淀

PR 对话中的反馈自动沉淀为 Learnings：

- **接受建议** → 强化该类规则
- **忽略/拒绝建议** → 降低该类问题的权重
- **@bot 对话纠正** → 实时学习偏好

这些 Learnings 影响后续所有 review，使 AI 持续适应团队习惯。

### 5.2 治理建议

| 频率 | 操作 |
|---|---|
| 每次 PR | AI review 作为标准前置步骤，作者先处理高置信问题再请人工 review |
| 每周 30~60 min | 复盘 AI review 质量：误报率、采纳率、漏报案例 |
| 每周 1~2 h | review instruction owner 维护规则和 prompt |
| 每季度 | 对高风险仓库保留双人 review 策略评估 |

---

## 六、人机协作的边界划分

### 6.1 职责分工

| 职责 | AI | 人工 |
|---|---|---|
| 第一轮全量扫描 | ✓ | |
| 基础安全/测试/文档问题 | ✓ | |
| 风险点预标注 | ✓ | |
| 低复杂度修复建议 | ✓ | |
| 评论聚合与 briefing | ✓ | |
| 业务逻辑正确性判断 | | ✓ |
| 架构合理性判断 | | ✓ |
| 系统边界和回滚策略 | | ✓ |
| 最终 merge 责任 | | ✓ |

### 6.2 PR 阶段的人机协作协议

PR 阶段内，AI 在三个时间点承担不同角色：

| 时间点 | AI 的职责 |
|---|---|
| **PR 打开时** | 生成摘要、跑基础 review、标出高风险区域。作者先处理高置信问题，再发起人工 review |
| **人工 reviewer 进入前** | 生成 briefing：改了什么 / 哪些地方最值得看 / 已发现但未修的问题 / 可能影响的上下游 |
| **review 收尾** | 汇总所有 comment，输出 closing checklist，确认是否仍有 unresolved risk |

> 目标不是"AI 做 90%，人看 10%"，而是"AI 做掉 70% 的基础扫描，人把主要精力放在最值钱的 30% 判断上"。

---

## 七、Benchmark：如何衡量 Review 质量

### 7.1 北极星指标

参考 CodeRabbit 内部评估体系，AI review 质量的核心指标：

| 指标 | 说明 |
|---|---|
| **用户接受率** | review comment 被开发者采纳的比例，最直接的价值信号 |
| **信噪比（SNR）** | 有效 comment / 总 comment，衡量噪声水平 |
| **可读性** | comment 是否表达清晰、定位准确 |
| **详细程度** | 问题描述、复现场景、修复建议是否完整 |
| **p95 延迟** | review 完成时间的长尾分布 |
| **成本** | 每次 review 的 token 消耗和费用 |

### 7.2 学术 Benchmark 体系

> 当前 code review benchmark 正在从"文本相似度评测"转向"真实问题发现能力评测"。

**评测方法演进**：

| 方法 | 代表 | 优点 | 局限 |
|---|---|---|---|
| BLEU / Exact Match | 早期 | 简单 | 只奖励"说法相似"，不衡量是否真正发现问题 |
| LLM-as-a-Judge | SWE-PRBench | 语义等价比较，可扩展 | 依赖 judge prompt 质量和可审计性 |
| Executable Oracle | c-CRAB | 最客观，不依赖措辞 | 软性问题（命名、文档）覆盖弱，构建成本高 |
| Post-review Fixes 对齐 | withmartian | 贴近生产，真实用户行为 | 修复≠评论有价值，两者非绝对因果 |
| 多维联合评测 | CodeFuse-CR-Bench | 覆盖更全面 | 权重主观，总分解释困难 |

### 7.3 企业内部如何建立 Benchmark

参考 withmartian 的方法论，企业可以建立自己的评测闭环：

```
1. 收集历史高质量 PR（人工标注 golden comments）
2. 持续跟踪 AI comment → 开发者后续修复的对齐率
3. 定期抽样做人工 precision/recall 评估
4. 建立 regression 测试集，防止规则迭代后质量下降
```

---

## 八、研讨议题

以下 5 个问题没有标准答案，但每一个都会直接影响落地效果。

**1. 置信门槛设多高？**
AI review agent 实测只能发现约 40% 的真实问题，既漏报也误报。门槛高了漏报多，门槛低了噪声淹没信号。你们团队对这两种错误的容忍度各是多少？

**2. AI 该不该有阻断权？**
目前主流做法是"AI 只建议，人工 merge"。随着采纳率提升，是否应该赋予高置信安全漏洞自动 block 能力？阻断权一旦开放，谁来对误报负责？

**3. 规则文件如何避免变成"墓地"？**
`REVIEW.md` 和 path_instructions 写了很多规则，但规则腐烂速度往往快于维护速度。哪些规则真正被触发？instruction owner 机制如何保证不流于形式？

**4. 资深 reviewer 省下来的时间去哪了？**
AI 做掉 70% 基础扫描后，资深工程师的时间会真的转向架构判断，还是被更多 PR 填满？junior 工程师从 review 过程中学习的机会是否也在同步压缩？

**5. 责任链如何重新定义？**
一个 bug 通过了 AI review 和人工 review 后上线——责任在谁？AI 介入让"我以为没问题"有了新的理由。这个问题早于事故前讨论，好过事故后追溯。