# Req Code Review

> 发起基于实现方案和当前代码的系统性代码审查，并输出可执行的 Markdown 审查报告。Use when asked to request code review, review an implementation against plans/designs, audit code before release, review before merge, or generate a structured findings document. 适用于需要根据项目情况定义审查角色、用 SubAgent 并行审查，并将输入抽象为实现方案、输出目录和其他材料的场景。

- Skill: `vamdawn/req-code-review` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add vamdawn/req-code-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vamdawn/req-code-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: vamdawn (https://skillmd.com/u/vamdawn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vamdawn/req-code-review

---


# Req Code Review

发起一次面向落地质量的系统性代码审查。审查必须基于需求与设计证据，而不是只看代码表面；必须使用 SubAgent 并行执行，再由主代理归并结论、去重并落盘。

## When To Request Review

优先在这些时机发起：

- 完成一个较大的实现任务后
- 合并到主分支前
- 完成重构或跨模块改动后
- 修复复杂问题后，想确认没有引入回归
- 需要判断当前实现是否满足方案和验收要求时

如果只是做很小的局部改动，也不要直接跳过审查；至少做一次轻量范围审查。

## Core Rules

1. 先定义“审查语义输入”，再映射到具体文件、分支、提交范围或目录。不要在 skill 中硬编码项目专属文件名。
2. 先读取实现方案，再看其他材料和代码。
3. 审查角色按项目情况动态定义，不要机械套固定职位名称。角色要覆盖设计一致性、正确性、可维护性、测试与上线风险。
4. 必须使用 SubAgent 发起审查。中大型任务默认并行 3 到 5 个 SubAgent；小型任务至少 2 个。
5. 只输出有证据的问题。每条问题都要给出影响、严重级别、定位和可执行建议。
6. 最终结果必须保存为 Markdown 文件。

## Quick Request

发起时先快速补齐这三类输入：

- `implementation_plan`: 本次实现依据
- `output_dir`: 审查文档输出目录
- `other`: 其他材料，包括设计文档、验收标准、历史审查记录、代码目录、分支、提交范围

如果用户没有明确给代码范围，优先从当前分支或最近一次完整改动范围中推断。
如果用户没有指定输出目录，按以下顺序确定：

1. 复用仓库中已经存在的审查输出目录
2. 若存在通用文档目录，则在其中创建 `reviews/` 子目录
3. 若仍无法确定，则退化为 `./docs/reviews/`

## Step 1. Build Review Context

先把用户输入整理成以下三类，再去解析实际文件：

- `implementation_plan`: 实现方案
- `output_dir`: 输出目录
- `other`: 其他所有材料，包括补充设计文档、验收标准、历史审查记录、代码范围、分支、提交范围、模块目录等

如果用户给的是具体文件路径，直接归类到上述三类；如果用户给的是目录或通配模式，先解析出候选文件，再筛选与本次实现直接相关的材料。

若未指定 `output_dir`，按以下顺序推断：

1. 若仓库中已存在审查输出目录，直接复用
2. 若仓库中存在文档目录，如 `docs/`，则使用其下的 `reviews/` 子目录
3. 若仍无法确定，则退化为 `./docs/reviews/`

归类优先顺序如下：

1. 用户显式给出的实现方案
2. 用户显式给出的输出目录
3. 其余输入全部归入 `other`

## Step 2. Read Evidence Before Reviewing

按下面顺序建立证据链：

1. 读取实现方案，提炼功能点、关键约束、边界条件和明确禁止项。
   - 如果缺少 `implementation_plan`，默认停止正式审查并提示用户补充。
   - 只有在用户明确接受“基于现状代码的轻量审查”时，才允许在没有实现方案的情况下继续。
2. 读取 `other` 中与本次实现直接相关的材料，优先包括设计文档、验收标准、历史审查记录和当前代码范围。
3. 若 `other` 中包含历史审查记录，拆分为：
   - 已修复问题
   - 未关闭遗留问题
   - 易复发问题模式
4. 若 `other` 中包含当前代码范围：
   - 若用户提供提交范围，先看 diff，再看关键文件全文
   - 若用户提供目录或模块，先识别入口、核心服务、数据访问层、测试和配置
5. 若 `other` 为空或与本次实现无直接相关材料：
   - 明确记录证据不足范围
   - 仅允许继续做基于现有代码范围的受限审查，不得伪装成“完整审查”
6. 若代码范围无法从分支、提交范围、目录或用户输入中推断：
   - 先输出待确认范围
   - 暂不启动 SubAgent，直到范围被补齐或用户明确接受受限审查

输出一个简短的“审查基线摘要”，供后续 SubAgent 共用。摘要至少包含：

- 本次实现目标
- 必须满足的关键设计约束
- 高风险区域
- 代码范围
- 历史问题关注点

## Step 3. Define Review Roles Dynamically

不要预设固定角色名。根据项目类型、改动范围和风险点，从 [role-playbook.md](references/role-playbook.md) 选择并定制 3 到 5 个审查角色。

角色定义原则：

- 每个角色负责一个互补视角，避免重复审查同一维度
- 每个角色都必须知道本次实现目标、审查范围和输出格式
- 每个角色都要有明确的“重点检查项”和“不必展开的范围”

最少覆盖这些维度：

- 设计一致性
- 架构与可维护性
- 正确性、健壮性与安全性
- 性能、测试与工程规范

若历史审查记录较多，增加一个“历史问题回归”角色；若涉及数据库、权限、外部接口或迁移，优先增加对应专项角色。

## Step 4. Launch SubAgents

使用 SubAgent 并行发起审查。每个 SubAgent 只拿到：

- 它负责的审查角色定义
- 审查基线摘要
- 必要的原始文档与代码范围
- 输出格式要求

不要把你的结论提前告诉 SubAgent。让它独立判断。

给每个 SubAgent 的任务必须包含：

1. 角色目标
2. 必查清单
3. 严重级别定义：`Critical | High | Medium | Low`
4. 证据要求：
   - 文档或代码定位
   - 影响说明
   - 修复建议
5. 输出限制：
   - 只报真实问题
   - 避免泛泛建议
   - 优先高风险问题

提示词骨架见 [subagent-review-template.md](references/subagent-review-template.md)。先实例化模板，再发起 SubAgent。

## Step 5. Merge And Normalize Findings

主代理负责合并所有 SubAgent 结果：

1. 去重：同一问题被多个角色发现时，保留证据最完整的一条，其余作为交叉佐证。
2. 统一严重级别：
   - `Critical`: 功能错误、数据破坏、安全漏洞、阻断上线
   - `High`: 明显偏离设计、关键场景缺失、重大测试缺口、显著稳定性风险
   - `Medium`: 可维护性差、边界处理不全、次关键性能问题、工程规范问题
   - `Low`: 非阻塞优化项、可读性与一致性改进
3. 按类别归组：设计一致性、架构与可维护性、代码质量、健壮性与边界处理、性能与资源使用、测试质量、工程规范、安全性。
4. 对照历史审查记录，标记：
   - 重复出现的问题
   - 已解决的问题
   - 新引入的问题

如果多个 SubAgent 对同一问题结论冲突：

- 以证据更完整、定位更准确的一方为主
- 若仍无法判断，在最终文档里显式记录为待确认问题，不要强行合并成确定结论

## Step 6. Write The Review Document

把最终结果保存到 `output_dir` 下。若用户未指定，按前述规则推断目录；若仍无更合适的位置，则保存到：

`./docs/reviews/YYYY-MM-DD-<topic>-code-review.md`

保存前还要处理以下分支：

1. 若 `output_dir` 不存在，先创建目录再写入
2. 若目录创建或文件写入失败，直接在会话中输出完整审查报告，并明确说明未能落盘的原因与原计划路径
3. 落盘前在结论中写明本次实际使用的审查范围与输出路径，避免用户误判覆盖范围

输出结构必须固定为：

```markdown
## 1. 总体评价（Summary）
- 整体评价：优秀 / 良好 / 存在风险 / 不可接受
- 核心问题概览（3~5 条）

## 2. 详细问题列表（Findings）
### [类别]
- 问题描述
- 影响范围
- 严重级别
- 定位信息
- 建议修改方案

## 3. 与历史审查对比（Diff Review）
- 重复出现的问题
- 已解决的问题
- 新引入的问题

## 4. 风险评估（Risks）
- 主要上线风险点
- 是否建议阻止上线（Yes / No + 理由）

## 5. 整改 Checklist
- [ ] ...

## 6. 建议改进（Nice-to-have）
- ...
```

写结论时遵守以下规则：

- 总结必须由证据支撑，不能先下结论再找理由
- Checklist 必须可执行，直接对应 Findings
- 若未发现某类问题，宁可省略该类 Findings，也不要编造

## After Review

收到审查结论后按严重级别处理：

- `Critical`: 立即修复，默认阻止上线或合并
- `High`: 在上线或合并前修复，除非有明确豁免理由
- `Medium`: 进入本轮整改计划，至少在文档中记录处理决策
- `Low`: 作为优化项进入后续迭代

如果你认为某条审查意见不成立，需要给出技术依据、代码证据或测试结果，而不是直接忽略。

## Step 7. Final Sanity Check

保存前自查：

1. 是否覆盖关键审查维度
2. 是否存在无证据问题
3. 是否遗漏历史问题对比
4. 是否给出明确上线建议
5. Checklist 是否能直接指导整改

如果审查范围过大，先说明覆盖范围与未覆盖范围，再输出报告，避免制造“已全量审查”的假象。

## Red Flags

不要这样做：

- 因为“改动不大”就跳过审查
- 只读代码，不对照实现方案
- 让 SubAgent 看到主代理已经形成的结论
- 输出泛泛建议而不给证据
- 在有 `Critical` 或未解决 `High` 问题时给出含糊的放行结论