req-code-review
Req Code Review
发起一次面向落地质量的系统性代码审查。审查必须基于需求与设计证据，而不是只看代码表面；必须使用 SubAgent 并行执行，再由主代理归并结论、去重并落盘。
When To Request Review
优先在这些时机发起：
- 完成一个较大的实现任务后
- 合并到主分支前
- 完成重构或跨模块改动后
- 修复复杂问题后，想确认没有引入回归
- 需要判断当前实现是否满足方案和验收要求时
如果只是做很小的局部改动，也不要直接跳过审查；至少做一次轻量范围审查。
Core Rules
- 先定义“审查语义输入”，再映射到具体文件、分支、提交范围或目录。不要在 skill 中硬编码项目专属文件名。
- 先读取实现方案，再看其他材料和代码。
- 审查角色按项目情况动态定义，不要机械套固定职位名称。角色要覆盖设计一致性、正确性、可维护性、测试与上线风险。
- 必须使用 SubAgent 发起审查。中大型任务默认并行 3 到 5 个 SubAgent；小型任务至少 2 个。
- 只输出有证据的问题。每条问题都要给出影响、严重级别、定位和可执行建议。
- 最终结果必须保存为 Markdown 文件。
Quick Request
发起时先快速补齐这三类输入：
implementation_plan: 本次实现依据output_dir: 审查文档输出目录other: 其他材料，包括设计文档、验收标准、历史审查记录、代码目录、分支、提交范围
如果用户没有明确给代码范围，优先从当前分支或最近一次完整改动范围中推断。 如果用户没有指定输出目录，按以下顺序确定：
- 复用仓库中已经存在的审查输出目录
- 若存在通用文档目录，则在其中创建
reviews/子目录 - 若仍无法确定，则退化为
./docs/reviews/
Step 1. Build Review Context
先把用户输入整理成以下三类，再去解析实际文件：
implementation_plan: 实现方案output_dir: 输出目录other: 其他所有材料，包括补充设计文档、验收标准、历史审查记录、代码范围、分支、提交范围、模块目录等
如果用户给的是具体文件路径，直接归类到上述三类；如果用户给的是目录或通配模式，先解析出候选文件，再筛选与本次实现直接相关的材料。
若未指定 output_dir，按以下顺序推断：
- 若仓库中已存在审查输出目录，直接复用
- 若仓库中存在文档目录，如
docs/，则使用其下的reviews/子目录 - 若仍无法确定，则退化为
./docs/reviews/
归类优先顺序如下：
- 用户显式给出的实现方案
- 用户显式给出的输出目录
- 其余输入全部归入
other
Step 2. Read Evidence Before Reviewing
按下面顺序建立证据链：
- 读取实现方案，提炼功能点、关键约束、边界条件和明确禁止项。
- 如果缺少
implementation_plan，默认停止正式审查并提示用户补充。 - 只有在用户明确接受“基于现状代码的轻量审查”时，才允许在没有实现方案的情况下继续。
- 如果缺少
- 读取
other中与本次实现直接相关的材料，优先包括设计文档、验收标准、历史审查记录和当前代码范围。 - 若
other中包含历史审查记录，拆分为：- 已修复问题
- 未关闭遗留问题
- 易复发问题模式
- 若
other中包含当前代码范围：- 若用户提供提交范围，先看 diff，再看关键文件全文
- 若用户提供目录或模块，先识别入口、核心服务、数据访问层、测试和配置
- 若
other为空或与本次实现无直接相关材料：- 明确记录证据不足范围
- 仅允许继续做基于现有代码范围的受限审查，不得伪装成“完整审查”
- 若代码范围无法从分支、提交范围、目录或用户输入中推断：
- 先输出待确认范围
- 暂不启动 SubAgent，直到范围被补齐或用户明确接受受限审查
输出一个简短的“审查基线摘要”，供后续 SubAgent 共用。摘要至少包含：
- 本次实现目标
- 必须满足的关键设计约束
- 高风险区域
- 代码范围
- 历史问题关注点
Step 3. Define Review Roles Dynamically
不要预设固定角色名。根据项目类型、改动范围和风险点，从 role-playbook.md 选择并定制 3 到 5 个审查角色。
角色定义原则：
- 每个角色负责一个互补视角，避免重复审查同一维度
- 每个角色都必须知道本次实现目标、审查范围和输出格式
- 每个角色都要有明确的“重点检查项”和“不必展开的范围”
最少覆盖这些维度：
- 设计一致性
- 架构与可维护性
- 正确性、健壮性与安全性
- 性能、测试与工程规范
若历史审查记录较多，增加一个“历史问题回归”角色；若涉及数据库、权限、外部接口或迁移，优先增加对应专项角色。
Step 4. Launch SubAgents
使用 SubAgent 并行发起审查。每个 SubAgent 只拿到：
- 它负责的审查角色定义
- 审查基线摘要
- 必要的原始文档与代码范围
- 输出格式要求
不要把你的结论提前告诉 SubAgent。让它独立判断。
给每个 SubAgent 的任务必须包含：
- 角色目标
- 必查清单
- 严重级别定义：
Critical | High | Medium | Low - 证据要求：
- 文档或代码定位
- 影响说明
- 修复建议
- 输出限制：
- 只报真实问题
- 避免泛泛建议
- 优先高风险问题
提示词骨架见 subagent-review-template.md。先实例化模板，再发起 SubAgent。
Step 5. Merge And Normalize Findings
主代理负责合并所有 SubAgent 结果：
- 去重：同一问题被多个角色发现时，保留证据最完整的一条，其余作为交叉佐证。
- 统一严重级别：
Critical: 功能错误、数据破坏、安全漏洞、阻断上线High: 明显偏离设计、关键场景缺失、重大测试缺口、显著稳定性风险Medium: 可维护性差、边界处理不全、次关键性能问题、工程规范问题Low: 非阻塞优化项、可读性与一致性改进
- 按类别归组：设计一致性、架构与可维护性、代码质量、健壮性与边界处理、性能与资源使用、测试质量、工程规范、安全性。
- 对照历史审查记录，标记：
- 重复出现的问题
- 已解决的问题
- 新引入的问题
如果多个 SubAgent 对同一问题结论冲突：
- 以证据更完整、定位更准确的一方为主
- 若仍无法判断，在最终文档里显式记录为待确认问题，不要强行合并成确定结论
Step 6. Write The Review Document
把最终结果保存到 output_dir 下。若用户未指定，按前述规则推断目录；若仍无更合适的位置，则保存到：
./docs/reviews/YYYY-MM-DD-<topic>-code-review.md
保存前还要处理以下分支：
- 若
output_dir不存在，先创建目录再写入 - 若目录创建或文件写入失败，直接在会话中输出完整审查报告，并明确说明未能落盘的原因与原计划路径
- 落盘前在结论中写明本次实际使用的审查范围与输出路径，避免用户误判覆盖范围
输出结构必须固定为：
## 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
保存前自查：
- 是否覆盖关键审查维度
- 是否存在无证据问题
- 是否遗漏历史问题对比
- 是否给出明确上线建议
- Checklist 是否能直接指导整改
如果审查范围过大，先说明覆盖范围与未覆盖范围，再输出报告，避免制造“已全量审查”的假象。
Red Flags
不要这样做：
- 因为“改动不大”就跳过审查
- 只读代码，不对照实现方案
- 让 SubAgent 看到主代理已经形成的结论
- 输出泛泛建议而不给证据
- 在有
Critical或未解决High问题时给出含糊的放行结论