Review Code

Review Code

依据 spec 和明确的代码变更范围执行实现后静态审查。把 diff 当作入口，不要把 diff 当作全部上下文。

审查契约

• 只输出审查意见，不修改代码、spec 或其他文件。
• 只做静态审查。不要运行测试、lint、type-check、构建、安装、迁移、生成或其他验证命令。
• 可以使用只读 Git 和文件检查命令确定范围并收集证据。
• 把输入 spec 作为本次实现的需求基线，不重新审查产生 spec 的原始需求对话。
• 结论是建议，不自动阻止提交、合并或后续流程。
• 只报告可能改变功能正确性、spec 完成度、系统行为、维护成本或交付风险的实质问题。忽略纯风格偏好。

准备审查输入

主 agent 在委派前确定唯一 spec、仓库和代码范围，并向 reviewer 显式传入：

• spec_path：spec 的绝对路径；
• repository_root：仓库的绝对路径；
• implementation_commits：当前会话中 implement 或 git-workflow 明确记录、属于本次实现的有序 commit 列表；
• local_changes：当前会话明确属于本次实现的 staged、unstaged 和 untracked 文件及其状态；
• explicit_range：没有可靠会话记录时由用户提供的 base_ref、head_ref 或文件范围；
• evidence_limits：范围归属、spec、代码或上下文中的已知证据缺口。

按以下规则确定范围：

1. 优先使用当前会话明确记录的 implementation_commits。
2. 同时纳入当前会话明确属于本次实现的 local_changes；与 commits 重叠时去重，但保留 commit 后的本地变化。
3. 没有可靠记录时，要求用户提供 base_ref / head_ref 或文件列表。不要根据最近提交、当前分支名称或修改时间猜测。
4. 存在多个 spec、跨仓库 commit、文件归属不明或任务外修改混入时，先让用户消除歧义。

调度 reviewer

默认把审查委派给一个专用 subagent；主 agent 负责准备输入和返回最终报告，不在 subagent 之外并行执行第二份审查。

1. 按运行环境委派：
   • Codex：调用 spawn_agent。
     • 代码审查使用 fork_context: false，让 reviewer 只依赖 prompt 中显式传入的 spec_path、仓库、范围和证据边界。
     • Codex 下固定传 model: "gpt-6-astra" 和 reasoning_effort: "high"，即使当前会话模型不同也不能省略 model 或让 reviewer 继承父模型。
     • agents/openai.yaml 只提供 UI 元数据；reviewer 模型由 spawn_agent.model 指定。
   • 非 Codex：使用当前环境原生的 subagent 机制，不传入 Codex 专用模型名或参数。
2. reviewer prompt 必须要求：读取 spec_path，只审查明确的代码范围，遵循本 skill 的静态审查契约，只返回 reviewer 结果（Findings、证据缺口和总体建议），不输出主 agent 的最终报告表格、执行方式、验证边界或降级说明，不修改文件，也不进入 scope、修复或实施。
3. 当前环境没有 subagent 能力、委派失败或无法启动 reviewer 时，由当前 agent 降级执行完整审查。降级报告必须在“审查概览”中明确写出 执行方式：当前 agent 降级审查（原因：<原因>）；不要静默降级。

主 agent 与 reviewer 的输出边界

• reviewer 成功启动且主 agent 收到 reviewer 的最终结果时，主 agent 必须将执行方式记为 专用 subagent；不能因为 reviewer 没有自行填写执行方式，或因为当前 agent 没有再次调用 spawn_agent，就改写成降级审查。
• 只有没有发起委派、委派调用失败、reviewer 无法启动，或没有收到 reviewer 的最终结果时，主 agent 才能执行降级审查；降级原因必须对应实际发生的阶段，不要笼统写成“没有可用的 spawn_agent”。
• 主 agent 负责把 reviewer 结果汇总成最终报告、统计 P0/P1/P2、补齐输入、验证边界和证据边界；不要把 reviewer 的输出协议当成最终报告协议，也不要在 reviewer 之外并行执行第二份完整审查。

收集证据

1. 进入仓库后先读取适用的 AGENTS.md、CLAUDE.md 或等价指令。
2. 读取完整 spec，提取目标、需求边界、技术决策和验收，不用实现反向改写 spec 的含义。
3. 对 commits 检查其 diff；对 staged、unstaged 和 untracked 修改分别读取实际差异或完整新文件。
4. 把 diff 作为定位入口，按需读取变更符号的调用方、被调用方、类型、状态所有者、配置、迁移、测试和相邻实现。
5. 区分本次改动引入或暴露的问题与无关的历史问题。除非历史问题使本次 spec 无法成立，否则不要扩展审查范围。
6. 无法通过静态证据确认时标记为证据缺口或风险推断，不要声称已经复现或由测试证实。

按顺序审查

1. Spec 完成度

• 将每项需求、约束、技术决策和验收追溯到具体实现与测试代码。
• 找出缺失功能、部分实现、未经说明的偏离、越界实现和与 spec 冲突的行为。
• 检查最终用户可观察结果是否成立，而不只检查文件或符号是否存在。

2. 功能正确性

• 检查正常路径、边界输入、失败路径、状态转换和恢复行为。
• 检查空值、错误传播、异步顺序、并发、重试、幂等、资源释放和生命周期问题。
• 追踪关键数据从入口到持久化或输出的流转，寻找数据丢失、重复、污染或语义变化。

3. 架构与系统适配

• 检查职责、状态所有权、接口和依赖方向是否符合现有系统边界。
• 检查是否绕过已有抽象、重复建设能力、引入不必要耦合或破坏调用约定。
• 检查协议、存储、配置、迁移和兼容性影响是否被实现完整承接。

4. 代码结构与质量

• 检查内聚性、复杂度、重复、抽象层级和可维护性，只报告具有实际成本的问题。
• 检查错误处理、类型与不变量、非法状态防护、日志和必要的可观测性。
• 不把个人命名、格式或风格偏好当作 Finding，除非它直接造成歧义或错误风险。

5. 交付风险

• 按任务相关性检查安全、权限、隐私、数据完整性、性能、可扩展性和可靠性。
• 静态检查测试是否覆盖变更行为和关键失败场景，但不要声称测试已经运行或通过。
• 检查相关文档、配置、迁移、协议和生成物是否与代码保持一致。

控制发现质量

仅报告有具体 spec 或代码证据、且会实质影响本次实现的事项。每项 Finding 按实际影响标记：

• P0 — 必须先解决：核心目标或关键验收不能成立；必需能力缺失；方案或实现被阻断；存在严重安全、数据损坏或兼容性破坏风险。
• P1 — 应当解决：存在明确缺陷或实质歧义；重要边界或失败路径错误；非核心需求遗漏；存在明显架构、可靠性、数据一致性或测试风险。
• P2 — 改进建议：尚未证明存在错误行为，但调整能实质改善结构、可维护性、清晰度、性能余量或未来风险。

不要按问题类型机械定级：严重 bug 可以是 P0；没有具体影响的代码风格意见不属于 P2。

静态审查结论按 Findings 映射：

• 存在 P0：必须修改；
• 没有 P0，但存在 P1 或 P2：建议修改；
• 没有实质 Finding：未发现实质问题。

输出报告

以下完整报告模板仅由主 agent 使用；reviewer subagent 不输出该模板，只返回 reviewer 结果。

按以下结构输出；没有内容的章节直接省略：

# Code review

## 审查概览

| 项目 | 内容 |
|---|---|
| 静态审查结论 | <未发现实质问题 / 建议修改 / 必须修改> |
| P0 / P1 / P2 | <数量 / 数量 / 数量> |
| Spec | `<绝对路径>` |
| Commits | <commit 列表或无> |
| Local changes | <文件列表或无> |
| 执行方式 | <专用 subagent / 当前 agent 降级审查及原因> |
| 验证边界 | 未运行验证命令；结论仅来自静态代码审查 |
| 证据边界 | <一句话说明关键缺口或“无”> |

## Findings 摘要

| ID | 优先级 | 类别 | 问题 | 证据位置 | 处理方向 |
|---|---|---|---|---|---|
| F1 | P0 | <类别> | <一句话问题> | `<file:line>` | <一句话修改方向> |

## Findings 详情

### F1 [P0|P1|P2] <简短标题>
- 类别：Spec 完成度 | 功能 Bug | 架构/系统适配 | 代码结构 | 代码质量 | 安全/数据 | 兼容/迁移 | 性能/可靠性 | 测试/文档/配置
- Spec 依据：<spec 章节、行号或验收项>
- 代码证据：<file:line 和相关行为>
- 影响：<为什么会改变功能、完成度、维护成本或交付风险>
- 修改意见：<具体修改方向，不直接修改代码>

## 证据缺口
- <无法确认的范围、代码上下文或运行时行为>

## 结论
- 静态审查结论：<未发现实质问题 | 建议修改 | 必须修改>
- 说明：<最高优先级问题和剩余风险；明确未运行验证命令>

使用以下格式规则：

• 在概览中统计 P0、P1、P2 数量。摘要和详情按 P0、P1、P2 排列，同级内按对 spec 和用户行为的影响排序。
• 为每项 Finding 分配稳定的 F1、F2 编号；摘要表与详情标题必须一一对应。
• 摘要表只写单段短文本。证据位置只放最关键的路径、行号或 commit；完整依据、证据、影响和修改意见放在详情中。
• 表格中的路径、行号和 commit 使用行内代码。单元格中的 | 必须写成 \|，不要在单元格中放多段文字或列表。
• 详情不要逐字重复摘要；引用具体证据，没有证据时不要制造 Finding。

没有实质问题时，在概览中写 P0 / P1 / P2 = 0 / 0 / 0 和“未发现实质问题”，省略“Findings 摘要”和“Findings 详情”，仍列出验证边界和证据缺口。输出报告后停止，不要自动修改代码、进入 scope 或生成实施计划。