code-review

对代码变更进行多维度审查：需求覆盖检查（PRD ↔ 代码）、技术方案合规（tech-design ↔ 代码）、 代码质量（coding-knowledge ↔ 代码）、安全与性能。输出按严重程度分级的审查报告。 当用户提到"代码审查"、"code review"、"CR"、"检查代码"、"审查代码"、"review 代码"、 "看看代码有没有问题"、"代码质量检查"、"代码是否符合需求"时使用此 skill。 即使用户只是说"code-gen 生成的代码靠谱吗"或"帮我看看这些改动"，也应该用这个 skill。

Purpose

代码写完了（无论是 code-gen 生成的还是开发手写的），提交 CR 之前需要确认：这些代码真的实现了 PRD 中的每个需求吗？接口参数和技术方案一致吗？代码风格符合项目规范吗？有没有安全漏洞或性能问题？

传统 Code Review 依赖 reviewer 个人经验——资深开发能看出"这个接口缺了分页参数"、"这个查询没走索引"，但新人可能只能检查代码格式。更棘手的是，reviewer 通常不会逐字对照 PRD 和技术方案，所以"需求遗漏"和"接口不一致"这两类问题经常到测试阶段才暴露。

这个 skill 自动化四个维度的审查：需求覆盖、技术方案合规、代码质量、安全性能。它不是替代人工 CR，而是在人工 CR 之前先跑一遍自动化检查，把容易遗漏的"对照性检查"提前解决。

核心依赖是 coding-knowledge：代码质量检查的标准不是通用的"最佳实践"，而是这个项目的实际编码模式。coding-knowledge 中的 symbols.md 告诉你项目里好代码长什么样，architecture.md 告诉你什么代码不该出现在什么地方，code-quality.md 告诉你团队的编码约定。审查标准从项目实际中来，不是从教科书中来。

输入

  • 代码变更：以下方式之一：
    • Git diff（默认：当前分支与主分支的 diff）
    • 指定文件列表
    • code-gen-report.md 中的文件清单
  • requirements/{模块名}/tech-design.md（技术方案合规性检查）
  • requirements/{模块名}/prd-draft.md（需求完整性覆盖检查）
  • coding-knowledge/（核心参考——代码规范、架构约束、现有代码模式作为审查基准）

工作流程

Step 1: 确定审查范围，构建审查基准

1.1 确定代码变更范围

  • 如果用户指定了文件列表 → 直接使用
  • 如果存在 code-gen-report.md → 从中提取文件清单
  • 否则 → 使用 git diff 获取变更文件列表
  • 向用户确认：审查范围是否正确

1.2 读取审查基准文档

  • 读取 tech-design.md，提取接口清单（API-XX）、DDL、任务拆解（T-XX）、代码定位信息
  • 读取 prd-draft.md，提取功能清单（F-XX）、验收标准、错误处理要求

1.3 深度读取 coding-knowledge（构建项目级审查标准）

这是 code-review 与通用 lint 工具最大的差异。不是用通用规则检查代码，而是用项目自己的编码模式作为审查标准。

第一层：编码规范（全局标准）

读取 coding-knowledge/infra/：

  • code-quality.md → 团队的命名规范、注释要求、异常处理模式、日志规范、分层约束
  • 其他基础设施规范 → 中间件使用方式（MQ 消息格式、缓存操作模式）

第二层：仓库级标准（按涉及仓库读取）

对变更涉及的每个仓库，读取 coding-knowledge/repos/{repo}/：

文件审查时用来做什么
architecture.md检查新代码是否放在正确的层/包中；检查是否违反"不负责"标注
symbols.md定位 2-3 个同类型的现有实现作为"好代码参考"——新代码应该与之风格一致
database-schema.md检查新增索引是否合理；检查字段命名是否与现有表一致
call-chains.md检查跨服务调用方式是否与项目现有模式一致（Feign？RestTemplate？）

第三层：风格对照（关键步骤）

从 symbols.md 中定位 2-3 个同类型的现有实现文件（如现有的 Controller、Service），用 Read 工具读取完整源码。这些文件就是审查的"参考答案"——新代码应该在以下方面与之一致：

  • 注解组合（@RestController + @RequestMapping 还是 @Controller + @ResponseBody）
  • 返回值包装（Result<T> 还是 ResponseEntity）
  • 依赖注入方式（构造器注入还是 @Autowired）
  • 异常处理模式（throw BusinessException 还是返回 error code）
  • 分页实现（PageHelper 还是 IPage）
  • 参数校验方式（@Valid + JSR 303 还是手动校验）

与不读 coding-knowledge 的差距：

  • 有 coding-knowledge → 审查标准是"这个项目的 Controller 都用构造器注入，你用了 @Autowired，不一致"
  • 没有 coding-knowledge → 只能检查"这个 Controller 有没有 bug"，无法检查风格一致性

1.4 读取变更代码

逐文件读取变更内容，理解每个文件的改动。

Step 2: 需求覆盖检查（PRD ↔ 代码）

逐条检查 PRD 功能清单中的每个功能点：

  1. 功能覆盖：每个 F-XX 是否有对应的代码实现

    • 从 tech-design 的"PRD 功能与接口映射"表找到 F-XX 对应的 API-XX
    • 检查 API-XX 对应的 Controller/Service 是否在变更文件中

  2. 验收标准覆盖：PRD 中每个功能的验收标准是否可从代码行为中验证

    • 重点检查：输入校验逻辑是否覆盖 PRD 中的每个验收条件
    • 边界条件处理是否与 PRD 一致

  3. 错误处理覆盖：

    • PRD 中标注的异常场景是否有对应的错误处理代码
    • PRD 中给出的错误提示文案是否在代码中体现

Step 3: 技术方案合规检查（tech-design ↔ 代码）

逐接口检查代码是否与技术方案一致：

  1. 接口一致性：

    • 接口路径（HTTP Method + URL）是否与 API-XX 一致
    • 请求参数名、类型、必填性是否与 tech-design 一致
    • 响应结构是否与 tech-design 一致
    • 错误码是否使用 tech-design 定义的业务错误码

  2. DDL 一致性：

    • Entity 类的字段是否与 tech-design 的 DDL 一致
    • 是否有 DDL 中定义但 Entity 中遗漏的字段
    • 索引是否按 tech-design 要求创建

  3. 改动范围合规：

    • 代码变更是否超出 tech-design 定义的仓库/文件范围
    • 如果有超出范围的改动，标注原因

  4. 时序图合规：

    • 跨服务调用关系是否与 tech-design 的时序图一致
    • 是否有 tech-design 未提及的额外服务调用

Step 4: 代码质量检查（coding-knowledge ↔ 代码）

这是 coding-knowledge 深度发挥作用的环节——用项目自己的标准审查代码。

4.1 风格一致性（对照 Step 1.3 的参考文件）

将变更代码与 Step 1.3 读取的"同类型参考文件"逐项对比：

检查项参考来源检查方式
注解组合参考 Controller/Service新代码的注解是否与参考文件一致
返回值包装参考 Controller是否使用了相同的返回值包装类
依赖注入方式参考 Service构造器注入 vs @Autowired 是否一致
异常处理模式参考 Service + code-quality.mdthrow 方式和异常类是否一致
命名风格code-quality.md + 参考文件方法名、变量名的命名习惯是否一致
分页实现参考 Controller/Service分页方式是否与项目现有实现一致

不一致的项标为 🟡 建议，除非不一致会导致运行错误（如返回值包装类不同导致前端解析失败）则标 🔴。

4.2 分层架构合规（对照 architecture.md）

  • 代码分层是否与 architecture.md 中定义的分层一致
  • Controller 是否只做参数校验和转发，不包含业务逻辑
  • Service 是否不直接操作 HTTP 请求/响应对象
  • 是否引入了 architecture.md 中标注的"本服务不负责"的逻辑

4.3 跨服务调用模式（对照 call-chains.md）

  • 调用方式是否与项目现有模式一致（如项目用 Feign，新代码不应该用 RestTemplate）
  • 超时和重试配置是否参照现有调用的配置
  • 错误处理是否与现有跨服务调用的模式一致

4.4 通用代码质量（无论是否有 coding-knowledge 都检查）

  • 是否有明显的代码重复
  • 是否有硬编码的配置值
  • 异常处理是否恰当（不吞异常、不用 catch(Exception)）
  • 日志是否充分（关键操作有 info 日志、异常有 error 日志）

Step 5: 安全与性能检查

5.1 安全（OWASP Top 10）

  • SQL 注入：是否使用参数化查询，是否有字符串拼接 SQL
  • XSS：前端是否对用户输入进行转义
  • 越权访问：是否有恰当的权限校验
  • 敏感数据：是否有明文存储密码、日志打印敏感信息
  • CSRF：表单提交是否有 token 校验

5.2 性能（对照 database-schema.md）

  • 索引完整性：对新增的查询条件，检查 database-schema.md 和 tech-design DDL 中是否有对应索引
  • N+1 查询：循环中是否有逐条 DB 查询（应改为批量）
  • 批量操作：循环中是否有逐条 DB 写入（应改为批量）
  • 缓存：高频读取是否考虑缓存（参考 coding-knowledge 中现有的缓存使用模式）
  • 大对象：是否有不必要的大对象创建或深拷贝

Step 6: 生成审查报告

在 requirements/{模块名}/code-review/ 目录下生成报告。

报告结构

总览报告 review-summary.md：

---
title: "{模块名} — 代码审查报告"
review_date: "{日期}"
tech_design_version: "{版本}"
---

# {模块名} — 代码审查报告

## 审查概览

| 维度 | 🔴 阻塞 | 🟡 建议 | 🔵 提示 |
|------|---------|---------|---------|
| 需求覆盖 | {N} | {N} | {N} |
| 技术方案合规 | {N} | {N} | {N} |
| 代码质量 | {N} | {N} | {N} |
| 安全与性能 | {N} | {N} | {N} |
| **合计** | **{N}** | **{N}** | **{N}** |

## 审查基准

| 基准类型 | 来源 |
|----------|------|
| 需求覆盖 | prd-draft.md (F-01 ~ F-XX) |
| 技术方案合规 | tech-design.md (API-01 ~ API-XX) |
| 代码风格 | coding-knowledge: {参考的同类型现有实现文件路径} |
| 架构合规 | coding-knowledge: repos/{repo}/architecture.md |
| 编码规范 | coding-knowledge: infra/code-quality.md |

## 审查结论

{通过 / 有阻塞项需修复 / 建议修复后再提交}

## 需求覆盖检查

### PRD 功能覆盖率

| PRD 功能 | 对应接口 | 代码覆盖 | 状态 |
|----------|----------|---------|------|
| F-01 {功能名} | API-01, API-02 | ✅ 已覆盖 | — |
| F-02 {功能名} | API-03 | ❌ 未覆盖 | 🔴 |

### 问题列表

#### 🔴 [RC-01] {问题标题}
- **位置**：{文件路径:行号}
- **问题**：{描述}
- **影响**：{PRD 中的哪个功能/验收标准受影响}
- **建议**：{修复建议，含代码片段}

## 技术方案合规检查

### 接口一致性

| 接口编号 | 路径一致 | 参数一致 | 响应一致 | 状态 |
|----------|---------|---------|---------|------|
| API-01 | ✅ | ✅ | ✅ | — |
| API-02 | ✅ | ❌ | ✅ | 🔴 |

### 问题列表
...

## 代码质量检查

### 风格一致性

| 检查项 | 项目标准（来自参考文件） | 实际代码 | 状态 |
|--------|----------------------|---------|------|
| 依赖注入 | 构造器注入（参照 XxxService.java） | @Autowired | 🟡 |
| 返回值包装 | Result<T>（参照 XxxController.java） | Result<T> | ✅ |

### 问题列表
...

## 安全与性能检查
...

## 修复建议优先级

按修复优先级排列所有问题：
1. 🔴 [RC-01] ...
2. 🔴 [TD-03] ...
3. 🟡 [CQ-01] ...
4. 🔵 [SP-02] ...

按仓库的详细报告 {仓库名}.md（当变更涉及多个仓库时生成）：

# {仓库名} — 代码审查详情

## 变更文件清单

| 文件 | 操作 | 行数 | 问题数 |
|------|------|------|--------|
| src/.../XxxController.java | 新增 | +120 | 2 |
| src/.../XxxService.java | 修改 | +45/-3 | 1 |

## 逐文件审查
...

Step 7: 输出总结

生成完成后告知用户：

  1. 审查报告位置
  2. 各级别问题数量汇总
  3. 阻塞问题列表（需要修复才能合并）
  4. 审查结论（通过/不通过）

输出目录

requirements/{模块名}/
├── prd-draft.md              ← PRD 终稿（输入）
├── tech-design.md            ← 技术方案（输入）
├── code-gen-report.md        ← code-gen 产出（可选输入）
└── code-review/              ← 本 skill 产出
    ├── review-summary.md     ← 总览报告
    ├── {仓库名-1}.md         ← 仓库级详细报告
    └── {仓库名-2}.md

与其他 skill 的关系

coding-knowledge-init                         ← 第零步：项目地图
  生成 coding-knowledge/
        ↓ (审查基准)
project-import → knowledge-init → prd-draft → prd-review → proto-gen
                                                                ↓
                                              tech-design → code-gen → code-review
                                                                         ↑
                                                               coding-knowledge/
                                                               (项目级审查标准)
  • 核心依赖：coding-knowledge/ 提供项目级的审查标准——不是通用的"最佳实践"，而是这个项目的实际编码模式。symbols.md 提供"好代码的参考答案"，architecture.md 定义职责边界，code-quality.md 定义编码规范
  • 审查基准：tech-design.md 定义接口应该是什么样、prd-draft.md 定义功能应该覆盖哪些、coding-knowledge/ 定义代码应该怎么写
  • 与 prd-review 的关系：prd-review 检查 PRD 文档本身的完整性，code-review 检查代码是否正确实现了 PRD。两者的问题分级体系（🔴🟡🔵）保持一致
  • 与 code-gen 的关系：code-gen 生成代码时参考 coding-knowledge 确保风格一致，code-review 审查时用同一份 coding-knowledge 验证一致性。两者的审查/生成标准来源相同

审查原则

问题分级标准（与 prd-review 一致）：

  • 🔴 阻塞：不修复不能合并。包括：安全漏洞、需求功能遗漏、接口参数不一致（会导致前后端对不上）、DDL 不一致（会导致运行报错）
  • 🟡 建议：建议修复但不阻塞合并。包括：与项目风格不一致（不影响功能但影响可维护性）、缺少必要注释、性能隐患、错误处理不完善
  • 🔵 提示：优化建议。包括：可选的代码重构、更优雅的实现方式

审查标准从项目实际中来：每个审查意见都要有具体的参考依据——引用 PRD 的 F-XX 编号、tech-design 的 API-XX 编号、coding-knowledge 中的具体文件和规范条目、或同类型参考文件中的具体写法。不基于"我觉得应该..."提出问题。

风格对照而非风格发明：代码质量检查的标准是"与项目现有代码是否一致"，不是"是否符合某个教科书的最佳实践"。如果整个项目都用 @Autowired，那新代码用 @Autowired 就不应该被标为问题。

给出可操作的修复建议：每个问题不仅要说明"哪里有问题"，还要给出"怎么修"的具体建议。如果是代码级别的问题，给出修改后的代码片段。

审查不是挑刺：目标是帮助开发者发现遗漏和不一致，不是对代码风格吹毛求疵。如果代码能正确工作、符合需求、没有安全问题，风格上的小差异不应该标为 🔴。

存量修改的专项检查：当代码变更是修改现有功能时，额外检查以下高频问题：

  • 是否误动了不该动的代码：对照 tech-design 的改动范围，检查变更文件中是否有超出范围的修改（重命名变量、调整格式、"优化"逻辑）。超范围改动标 🔴
  • 是否重复实现了现有逻辑：tech-design 说"新增一个校验"，代码却把整个方法重写了。检查新增代码量是否远超需求预期
  • 是否破坏了现有调用方的兼容性：从 call-chains.md 找到被修改方法的所有调用方，确认参数/返回值变更不会影响上游

Common Pitfalls

只看代码不看 PRD：纯从代码质量角度审查，忽略了"代码是否实现了需求"这个最重要的问题。需求覆盖检查必须放在第一位。

不读 coding-knowledge 直接审查：用通用的"Java 最佳实践"检查代码，结果提出的建议与项目现有风格冲突。必须先读 coding-knowledge 建立项目级审查标准。

不找参考文件就检查风格：没有 Read 同类型的现有实现文件，无法判断新代码的风格是否一致。Step 1.3 的风格对照不能省略。

把所有问题都标为阻塞：命名不规范标 🔴、缺注释标 🔴，会让开发者对审查报告失去信任。严格按分级标准打标。

审查范围失控：被代码变更牵引到审查整个仓库的代码质量。只审查变更涉及的文件，周边代码的问题不在本次审查范围内。

重复 prd-review 的工作：code-review 不检查 PRD 本身是否完整（那是 prd-review 的职责），只检查代码是否正确实现了 PRD 中定义的功能。