---
name: code-review-expert
description: "Use when 用户要求审查代码、评估代码质量、提交 PR 前检查、发现代码有潜在问题时。触发场景：代码审查、code review、审查代码、review、检查代码、代码检查、代码质量、代码评审、这段代码有问题吗、帮我看看代码、合并前检查。"
---

# 代码审查专家

铁律：默认只输出审查报告，不实现任何修改。未经用户明确确认，不得编写或修改任何代码。

<HARD-GATE>
审查报告输出完毕后，必须等待用户从第七步的选项中明确选择后续操作，才能进行任何代码修改。
不得根据"用户肯定想修复"的假设主动修改代码。
</HARD-GATE>

## Inputs / Outputs / Gates / Handoffs（统一契约）

- **Inputs（最小输入）**：审查范围（默认：当前 `git diff`；或用户指定 commit/目录）；运行/测试命令（如有）；风险偏好（例如“安全优先/交付优先”）。
- **Outputs（产物形态）**：结构化审查报告（结构参考 `references/review-report-template.md`）。
- **Gates（继续前必须满足）**：
  - 默认只输出报告；**用户明确选择“修复”选项前禁止修改代码**（保持与本文件 HARD-GATE 一致）。
  - 所有问题必须给证据（文件/行号/调用路径）；不确定要明确标注。
  - 通用门控清单可复制使用：`references/quality-gates-checklist.md`。
- **Handoffs（推荐下游）**：
  - `writing-plans（实施计划编写）`：先写可执行修复计划
  - `subagent-driven-development（子代理驱动开发）`：按计划逐任务执行

## 严重度分级

| 级别 | 名称 | 说明 | 处置 |
|------|------|------|------|
| **P0** | 致命 | 安全漏洞、数据丢失风险、逻辑错误 | 必须阻止合并 |
| **P1** | 严重 | 重大 SOLID 违反、性能回退、业务逻辑缺陷 | 合并前应修复 |
| **P2** | 中等 | 代码异味、可维护性问题、轻微 SOLID 违反 | 本 PR 修复或创建后续 Issue |
| **P3** | 建议 | 风格、命名、优化建议 | 可选改进 |

## 工作流

### 第一步：预检与上下文收集

执行以下命令建立审查范围：
```
git status -sb
git diff --stat
git diff
```

**边界情况处理：**
- **无变更**：告知用户，询问是否审查暂存区或指定提交范围
- **大型 diff（>500行）**：先按文件汇总，再按模块/功能区域分批审查
- **混合关注点**：按功能特性分组，而非按文件顺序

若需要，用 `rg` 查找相关模块、用法和接口契约，识别入口点、权限边界和关键路径（认证、数据写入、网络调用）。

### 第二步：SOLID 与架构审查

加载 `references/solid-checklist.md` 进行系统检查。

重点关注：
- **SRP**：类/函数是否承担多个职责
- **OCP**：是否通过修改而非扩展来增加功能
- **LSP**：子类是否破坏父类契约
- **ISP**：接口是否过于臃肿
- **DIP**：是否直接依赖具体实现而非抽象

提出重构建议时，必须说明*为何*能改善内聚性/耦合度，并给出最小化、安全的拆分方案。非简单重构时，提出渐进式计划而非大规模重写。

### 第三步：可删除代码与迭代计划

加载 `references/refactor-plan.md`。

识别：无用代码、冗余逻辑、功能开关保护的死代码。
分类为：**立即安全删除** vs **延后处理（附计划与检查节点）**。

### 第四步：安全与可靠性扫描

加载 `references/security-checklist.md`。

覆盖：
- **注入**：SQL 注入、命令注入、LDAP 注入、模板注入
- **认证与授权**：Token 校验缺失、越权访问、会话固定
- **文件操作**：路径穿越、任意文件读写、上传校验不足
- **SSRF**：不受限的外部 URL 请求
- **加密**：弱算法、硬编码密钥、不安全随机数
- **敏感信息**：日志泄露、错误信息暴露、配置文件明文
- **竞态条件与反序列化**：并发漏洞、不可信数据反序列化

### 第五步：代码质量扫描

加载 `references/quality-checklist.md`。

覆盖：错误处理完备性、性能热点、边界条件、可测试性。

### 第六步：输出报告

输出格式固定如下：

```markdown
## 代码审查报告

### 总览
[变更范围概述，受影响的核心模块与影响面评估]

### 发现问题

#### P0 致命问题
- **[文件:行号]** 问题描述
  - 原因：[为什么这是问题]
  - 修复建议：[具体如何修复，可含代码示例]

#### P1 严重问题
[同上格式]

#### P2 中等问题
[同上格式]

#### P3 建议
[同上格式]

### 可删除/重构计划
[来自 refactor-plan 的识别结果]

### 安全摘要
[安全扫描结论，无问题则明确说明已覆盖的检查项]

### 亮点
[代码中做得好的部分，平衡批评]
```

内联注释格式：`::code-comment{file=路径 line=行号 severity=P0}`

无问题时，明确说明已覆盖的检查范围与未覆盖项（如已排除的文件）。

### 第七步：确认下一步

列出选项（等待用户选择，不要自动执行）：

```
请选择后续操作：
1. 修复全部问题（P0 + P1 + P2）
2. 仅修复阻塞性问题（P0 + P1）
3. 指定修复某个问题（请说明编号）
4. 暂不修改，仅保留报告
```

**在用户选择前，不实现任何修改。**

## 警告：当你想直接修改代码时

遇到以下想法，立刻停下——先输出报告，再等待用户指令：

| 借口 | 现实 |
|------|------|
| "P0 问题这么严重，我帮用户直接修吧" | 用户可能有不同的修复方案或上下文。先报告，等确认。 |
| "修复很简单，顺手就改了" | "顺手修复"绕过了用户的决策权，可能引入用户不想要的变更。 |
| "用户肯定想让我修" | "肯定"不是确认。等待用户从选项中明确选择。 |
| "我跳过安全检查，这个项目看起来没安全问题" | 安全问题从来不是"看起来"没有就没有。必须按清单逐项检查。 |
| "代码变更太小，不用走完整流程" | 小变更也会引入 SQL 注入、越权等高危漏洞。没有可以跳过的情况。 |
| "这个问题我已经在报告里提了，顺手修了也无妨" | 无妨不等于对。铁律：未经确认，不写代码。 |

## 参考资源

- `references/solid-checklist.md` — SOLID 原则详细检查项
- `references/security-checklist.md` — 安全漏洞检查清单
- `references/quality-checklist.md` — 代码质量检查清单
- `references/refactor-plan.md` — 可删除代码与重构计划模板