通用代码评审 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 文件：

   python .trae/skills/code-review/scripts/read_docx.py 
   

3. 直接读取 .md 文本文件
4. 在看代码之前，先理解业务意图

第三步：深度源码审查

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

第四步：生成评审报告

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

1. 📊 业务与安全概览

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

2. 🔴 核心业务与架构隐患

仅记录业务逻辑错误、与设计严重偏离、严重安全漏洞、并发/事务/性能隐患

3. 🟡 逻辑优化与代码降维

指出"能跑但写得啰嗦"的地方，给出更简洁的实现建议

4. 🟢 架构师的肯定

发现巧妙的抽象、优雅的设计模式应用，给予肯定

5. 📝 业务遗漏疑问

发现边缘场景遗漏，向开发者提问

评审维度（Expert Checklist）

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

1. 业务实现与设计的一致性

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

2. 逻辑的正确性与简洁性

   • 核心动作：审查代码"是否把简单问题复杂化"
   • 关注点：过度设计、冗余调用、认知负载

3. 核心架构与并发安全

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

脚本说明

read_docx.py

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

python .trae/skills/code-review/scripts/read_docx.py 

输出：

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

报告落盘

评审完成后：

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