# 代码审查清单（CODE_REVIEW_CHECKLIST）

> 用途：自审或请审前逐项过。按严重度分级，先 Critical/Important 再 Minor。
> 对标 obra/superpowers requesting/receiving-code-review，本表为科研/后端代码加强。
> 回应规范：技术化、动作导向；禁止"你说得太对了"式表演性赞同；改完用 "Fixed. [改了什么]"。

## 请审前（提交方）

- [ ] 工作已入 git，确定评审范围 base SHA 与 head SHA
- [ ] 备好计划/规格，只给审查者精心构造的上下文（不给会话历史）
- [ ] 本地全部测试通过、ruff check/format 干净

## 一、Critical（立即修，阻断合并）

- [ ] **安全**：无硬编码密钥/token（走环境变量/配置）；SQL 用参数化查询；外部输入有校验；不回显敏感值
- [ ] **网络暴露服务有鉴权**：新接口/服务若无认证，必须显式标注安全影响，不静默上线
- [ ] **功能正确**：实现精确匹配规格，不多不少；边界与异常路径有处理
- [ ] **无数据破坏**：删除/批量更新/迁移类操作可逆或有备份
- [ ] **每个新行为有"被看着失败过"的测试**；bug 修复有复现该 bug 的回归测试

## 二、Important（进下个任务前修）

- [ ] **输入校验在源头做**，而非在多个下游症状处补（见 systematic-debugging Phase 1.5）
- [ ] **错误处理**：异常被恰当捕获/上抛，不吞异常、不裸 `except:`
- [ ] **可复现**：随机种子已固定；依赖版本锁定（lock 文件）；数据划分确定
- [ ] **数值/科研代码**：shape/dtype 一致；浮点比较用 `approx`/`assert_allclose` 而非 `==`；无静默 NaN 传播；无数据泄漏（标准化/特征工程在划分之后）
- [ ] **测试质量**：测真实代码非 mock 行为；测名描述单一行为（无 "and"）；覆盖边界
- [ ] **YAGNI**：grep 实际用法，无人用的参数/抽象/分支删掉

## 三、Minor（记录待后）

- [ ] 命名达意；注释解释"为什么"而非"是什么"，与周围同密度
- [ ] 单一职责、小函数、清晰数据流；无明显重复
- [ ] README/运行说明随改动更新
- [ ] 格式符合 ruff format

## 四、架构信号（用"删除测试"诊断）

- [ ] 设想删掉该模块：复杂度消失 = 穿透层（浅，可吸收合并）；复杂度在 N 个调用方重现 = 深模块（值得留）
- [ ] 浅模块（接口几乎和实现一样复杂）→ 考虑合并或在缝处加深
- [ ] "接口即测试面"：测契约不测内部细节
- [ ] 连修 3 次仍失败 / 每次修复牵出新耦合 → 这是结构问题不是 bug，停手讨论设计

## 五、评估外部审查意见的五查 + 回应

收到意见先全收不反应 → 用自己话复述需求（不清就问）→ 对照真实代码核实 → 五查评估 → 技术性回应 → 逐条实施每条测。

五查：① 对本库技术正确吗？② 会破坏现有功能吗？③ 当前实现为何这么写？④ 跨所有支持平台/版本可行吗？⑤ 审查者有完整上下文吗？

实施顺序：Blocking（安全/功能坏）→ 简单修复（拼写/import）→ 复杂修复（重构/逻辑）。动手前把不清楚的全部澄清。审查者错时用代码/测试佐证地技术反推；反推错了如实更正"You were right — 我查了 X 确实 Y"，不长篇道歉。
