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，默认停止正式审查并提示用户补充。 - 只有在用户明确接受“基于现状代码的轻量审查”时，才允许在没有实现方案的情况下继续。

1. 读取 other 中与本次实现直接相关的材料，优先包括设计文档、验收标准、历史审查记录和当前代码范围。
2. 若 other 中包含历史审查记录，拆分为：

- 已修复问题 - 未关闭遗留问题 - 易复发问题模式

1. 若 other 中包含当前代码范围：

- 若用户提供提交范围，先看 diff，再看关键文件全文 - 若用户提供目录或模块，先识别入口、核心服务、数据访问层、测试和配置

1. 若 other 为空或与本次实现无直接相关材料：

- 明确记录证据不足范围 - 仅允许继续做基于现有代码范围的受限审查，不得伪装成“完整审查”

1. 若代码范围无法从分支、提交范围、目录或用户输入中推断：

- 先输出待确认范围 - 暂不启动 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. 证据要求：

- 文档或代码定位 - 影响说明 - 修复建议

1. 输出限制：

- 只报真实问题 - 避免泛泛建议 - 优先高风险问题

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

Step 5. Merge And Normalize Findings

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

1. 去重：同一问题被多个角色发现时，保留证据最完整的一条，其余作为交叉佐证。
2. 统一严重级别：

- Critical: 功能错误、数据破坏、安全漏洞、阻断上线 - High: 明显偏离设计、关键场景缺失、重大测试缺口、显著稳定性风险 - Medium: 可维护性差、边界处理不全、次关键性能问题、工程规范问题 - Low: 非阻塞优化项、可读性与一致性改进

1. 按类别归组：设计一致性、架构与可维护性、代码质量、健壮性与边界处理、性能与资源使用、测试质量、工程规范、安全性。
2. 对照历史审查记录，标记：

- 重复出现的问题 - 已解决的问题 - 新引入的问题

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

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

Step 6. Write The Review Document

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

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

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

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

输出结构必须固定为：

## 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 问题时给出含糊的放行结论