---
name: code-review
description: 执行深度代码评审，读取设计文档，分析当前分支与Master的差异，输出结构化评审报告。当用户请求"代码Review"、"CR"、评审代码、分析分支差异、查看变更时触发。此skill会主动加载 `./review/` 目录下的需求文档（含 .docx、.md），结合 Git 分支比对，进行符合《阿里巴巴Java开发手册》的深度业务逻辑、架构安全、并发性能评审。
---

# 通用代码评审 Skill

## 核心能力

1. **Git 分支比对**：分析当前分支与 master 的文件变更
2. **设计文档读取**：支持读取 `.docx`、`.md` 格式的需求/概要设计文档
3. **深度代码评审**：按业务逻辑、架构安全、代码质量维度输出结构化报告

## 工作目录

- **项目根目录**：当前项目根目录
- **文档目录**：`./review/` — 存放需求文档、概要设计
- **报告输出**：`./review/review_[分支名].md`

## 执行流程

### 第一步：环境感知

1. 执行 `git fetch origin master --depth=1` 拉取远程 master 最新状态
2. 获取当前分支：`git branch --show-current`
3. 获取变更文件列表：`git --no-pager diff --name-status origin/master...HEAD`

> **提示**：变更文件超过 20 个时，主动预警，建议优先评审核心业务线

### 第二步：加载业务上下文

1. 扫描 `./review/` 目录，发现相关设计文档（`.docx`、`.md`、`.pdf`）
2. 使用 `docx-reader` 读取 `.docx` 文件：
   ```bash
   python .trae/skills/code-review/scripts/read_docx.py <docx_file>
   ```
3. 直接读取 `.md` 文本文件
4. 在看代码之前，先理解业务意图

### 第三步：深度源码审查

1. **不要只看 Diff**：对于复杂逻辑修改，必须读取变更方法的完整上下文
2. **业务交叉验证**：
   - 代码逻辑与设计文档的流程图/状态机是否一致？
   - 异常分支处理是否完整？
   - 是否有更简单的实现方式？

### 第四步：生成评审报告

使用标准 Markdown 格式输出，包含以下模块：

#### 1. 📊 业务与安全概览
- **分支名称**：[分支名]
- **业务意图**：简述本次变更的业务目标
- **依据文档**：[文档名称] 或"未发现业务上下文，仅基于代码推演"
- **安全风险评估**：🔴 高 / 🟡 中 / 🟢 低
- **架构师整体评价**

#### 2. 🔴 核心业务与架构隐患
*仅记录业务逻辑错误、与设计严重偏离、严重安全漏洞、并发/事务/性能隐患*

#### 3. 🟡 逻辑优化与代码降维
*指出"能跑但写得啰嗦"的地方，给出更简洁的实现建议*

#### 4. 🟢 架构师的肯定
*发现巧妙的抽象、优雅的设计模式应用，给予肯定*

#### 5. 📝 业务遗漏疑问
*发现边缘场景遗漏，向开发者提问*

---

## 评审维度（Expert Checklist）

**三大核心维度（不纠缠于格式、命名等细枝末节）：**

1. **业务实现与设计的一致性**
   - 核心动作：强制校验代码实现是否与设计文档一致
   - 关注点：状态机流转、异常补偿机制、核心约束条件

2. **逻辑的正确性与简洁性**
   - 核心动作：审查代码"是否把简单问题复杂化"
   - 关注点：过度设计、冗余调用、认知负载

3. **核心架构与并发安全**
   - 核心动作：识别可能导致 P0/P1 故障的架构隐患
   - 关注点：状态竞争、死锁、事务一致性、缓存击穿、大事务

---

## 脚本说明

### read_docx.py

读取 `.docx` 文件，提取文本和图片：

```bash
python .trae/skills/code-review/scripts/read_docx.py <docx_file>
```

输出：
- 文档中的所有文本（段落和表格）
- 提取的图片保存到 `.trae/temp/docx_images/[文档名]/`

---

## 报告落盘

评审完成后：
1. 将报告保存到 `./review/review_[分支名].md`
2. **分支名中的斜杠 `/` 必须替换为下划线 `_`**，避免路径错误
3. 若目录不存在需主动创建