code-review-mcp / rules

---
description: 代码审查规范（中文版）
globs: 
alwaysApply: false
---

# 代码审查规范

> 根据用户输入语言自动选择规范版本。中文输入使用本文件，英文输入使用 code-review-en.mdc。

## 核心原则

**理解优先**
- 先理解 PR/MR 整体目的，再分析 diff
- 深度分析（架构/逻辑/性能/安全）优先于风格检查
- 只提"确认的问题"，不提"可能的问题"
- 结合上下文分析，不孤立判断

---

## 审查流程

### 步骤 1：确定 PR 类型

```
主仓库 PR -> 从描述中提取子模块 PR
子模块 PR -> 直接审查
```

### 步骤 2：获取完整变更

```python
changes = get_pr_changes(provider, repo, pr_id)
for change in changes["changes"]:
    full_diff = change["diff"]
    analyze(full_diff)
```

**必须**：遍历所有文件的完整 diff
**禁止**：`diff[:100]` 或 `changes[:10]`

### 步骤 3：理解 PR 上下文（优先执行）

在查看任何 diff 之前，回答：

1. **目的**（从标题+描述）：新功能/Bug修复/重构？
2. **范围**（从变更列表）：新增/删除/修改了哪些文件？
3. **架构**：类关系、数据流、设计模式？
4. **预期实现**：应该实现什么？

### 步骤 4：深度代码分析

#### 4.1 理解 diff 意图
- 这段 diff 在整个 PR 中的作用？
- 是否符合 PR 目的？

#### 4.2 架构审查
- 职责是否单一？
- 是否有重复代码？
- 抽象层次是否清晰？
- 设计在整体架构中是否合理？

#### 4.3 逻辑审查（结合上下文）
- **边界条件**：调用方是否已确保非空？
- **异常场景**：业务流程中是否真的会发生？
- **状态转换**：在完整状态机中是否完整？

**避免误报**：调用方已校验 -> 不提

#### 4.4 性能审查（真实场景）
- 数据量多大？是否真的会成为瓶颈？
- 循环次数？是否真的影响性能？
- 耗时多久？是否真的会卡顿？

**避免误报**：数据量 <= 5 -> 不提 / 耗时 < 1ms -> 不提

#### 4.5 安全与崩溃风险
- 确认真实的 NPE/越界/资源泄漏风险
- 考虑完整调用链和业务流程

**避免误报**：上文已校验 -> 不提

### 步骤 5：去重

```python
# 1. 去重：同一文件相同问题合并
seen = {(file, issue_type): comment}
merge_line_numbers(seen[key], comment)

# 2. 按优先级分组
p0, p1, p2 = group_by_priority(seen.values())

# 3. 动态调整
if len(p0) > 10:
    p1 = p1[:len(p1)//2]
    p2 = p2[:len(p2)//3]

final_comments = p0 + p1 + p2
```

**去重规则**：
- 同一文件相同问题 -> 合并并列出所有行号
- 不同文件相同问题 -> 每个文件 1 条
- 方法过长 -> 每个文件最多 2 条

### 步骤 6：展示评论供确认

**提交前必须展示所有评论供用户确认**

格式：
```
## 审查结果预览

### 行内评论 (N 条)

1. [P0/P1/P2] 文件名:行号
   评论预览...

2. [P0/P1/P2] 文件名:行号
   评论预览...

### 总结评论

[总结预览]

---

等待确认后提交。
```

### 步骤 7：确认后提交

**重要**：使用 `line + 1` 避免遮挡代码行

```python
for comment in inline_comments:
    comment['line'] = comment['line'] + 1

batch_add_comments(
    provider=provider,
    repo=repo,
    pr_id=pr_id,
    inline_comments=inline_comments,
    pr_comment=summary_comment
)
```

---

## 评论格式

### 行内评论

**数量策略**：
- P0：不限
- P1：P0 > 10 时减少 50%
- P2：P0 > 10 时减少 70%

**格式**：`[图标] [问题]\n\n[原因（1行）]\n[建议（1-2行）]`

**图标**：P0 / P1 / P2

### 总结评论

格式（8-10 行）：
```
## 代码审查总结

**变更**：[简要描述，1行]
**结论**：[通过/需修改，1行]

### 问题 (N 个)
1. [类型] 文件:行号 - [描述]
```

---

## 优先级定义

**P0 - 不限数量**：
- 崩溃风险（确认）
- 内存泄漏（确认无释放路径）
- 严重性能问题（确认会卡死/超时）
- 安全漏洞
- 功能缺失

**P1 - P0 > 10 时减少 50%**：
- 架构问题（确认不合理）
- 性能优化（确认有瓶颈）
- 逻辑缺陷（确认有遗漏）
- 代码质量（确认影响可维护性）

**P2 - P0 > 10 时减少 70%**：
- 代码复用机会
- 命名改进
- 细微优化

---

## 检查清单

| 类型 | 检查项 | 不提条件 | 优先级 |
|------|--------|----------|--------|
| NPE | 调用方已校验？ | 是 -> 不提 | 确认 -> P0 |
| 越界 | 上文已检查长度？ | 是 -> 不提 | 确认 -> P0 |
| 资源泄漏 | finally 已关闭？ | 是 -> 不提 | 确认 -> P0 |
| 性能 | 数据量？ | <= 5 -> 不提 | 确认卡死 -> P0 |
| 线程 | 耗时？ | < 1ms -> 不提 | 确认卡顿 -> P0 |

**原则**：只提确认的问题

---

## 去重规则

| 类型 | 去重方式 |
|------|----------|
| NPE | 同文件合并 |
| 性能 | 每个循环单独 |
| 架构 | 合并所有位置 |
| 风格问题 | 必须合并 |
| 方法过长 | 每文件最多 2 条 |

**优先级**：风格必须合并 > NPE/方法过长建议合并 > 架构/性能可单独

---

## MCP 工具

| 工具 | 用途 |
|------|------|
| `get_pr_info` | 获取 PR/MR 信息（含描述） |
| `get_pr_changes` | 获取代码变更（完整 diff） |
| `extract_related_prs` | 从主仓库提取子模块 PR |
| `batch_add_comments` | 批量提交所有评论 |
| `add_inline_comment` | 添加单条行内评论 |
| `add_pr_comment` | 添加总结评论 |

---

## 必须做

1. 先理解整体 PR
2. 结合上下文分析
3. 只提确认的问题
4. 深度分析优先于风格检查
5. 评论去重
6. P0 不限，P0 > 10 时减少 P1/P2
7. **展示所有评论供用户确认**
8. **等待用户确认后再提交**
9. **提交时行号 +1（避免遮挡代码）**

## 禁止做

1. 不理解就审查
2. 忽略上下文
3. 误报（提"可能有问题"）
4. 纸上谈兵（忽略真实场景）
5. 规则驱动思维（机械匹配）
6. 风格优先于实质
7. 重复评论
8. 冗长总结（> 10 行）
9. 提注释相关问题
10. **未经用户确认直接提交评论**

---

**版本**: v1.0