预提交自审清单 是做什么的?
在提交重大变更之前,逐一检查此清单。在 CI 捕捉到问题之前——或者更糟,在用户发现之前——先自己抓住它们。
何时使用
当以下任一情况成立时,运行此技能:
- 更改了超过 100 行代码
- 修改了超过 5 个文件
- 触及了核心基础设施(执行器、存储、主调度循环)
- 引入了新的抽象或公共 API
- 对边界情况或设计选择不确定
快速判断:
git diff --stat HEAD | tail -5 # 更改了多少行?
git diff --name-only HEAD | wc -l # 更改了多少文件?
何时跳过
- 微小变更(≤50 行,≤3 个文件)
- 纯文档或课程更新
- 仅测试的更改(测试本身已有审查)
- 简单的一行 Bug 修复,范围明显且有限
- 无逻辑更改的机械性重构
清单
1. 边界情况
- [ ] 空/空输入已处理?
- [ ] 边界条件已测试(差一错误、空列表、零值)?
- [ ] 并发访问或竞态条件已考虑?
- [ ] 可能涉及 Unicode/编码问题?
2. 错误路径
- [ ] 所有异常在适当的层级捕获(不要过于宽泛)?
- [ ] 错误信息具有信息性(什么失败、为什么失败、如何解决)?
- [ ] 故障模式优雅降级,而非静默失败?
- [ ] 没有裸 `except:` 或吞掉错误?
3. 测试覆盖
- [ ] 关键路径有测试?
- [ ] 上述边界情况有测试?
- [ ] 测试实际运行并通过?
- [ ] 没有留下 `pass` 或 `...` 的测试桩?
4. 文档
- [ ] 文档字符串/注释与当前行为一致?
- [ ] 如果公共接口变更,README 已更新?
- [ ] 提交消息说明了更改了什么以及为什么?
- [ ] 相关架构文档仍然准确?
5. 代码质量
- [ ] 命名清晰且与周围代码一致?
- [ ] 没有明显的代码异味(上帝函数、魔术数字、硬编码路径)?
- [ ] 遵循文件/包中的现有模式?
- [ ] 静态分析 / 类型检查通过?
一行冒烟测试
# 在提交前运行(根据你的栈调整):
make format && make typecheck && pytest -x -q && echo "✅ 可以提交"
如果任何步骤失败,修复后再提交。不要带着红色状态发布。
反模式
| 反模式 | 修正方法 |
|---|---|
| "CI 会抓住它的" | CI 是最后手段,不能替代你自己的判断。先自己抓住问题。 |
| "我稍后再加测试" | “稍后”永远不会来。现在就写测试,否则永久接受这个缺口。 |
| "我手动测试过,没问题" | 手动测试不可复现。编写自动化测试,以便未来的会话也能验证。 |
| "错误消息写的是 TODO" | TODO 错误消息会以 TODO 形式发布。现在就写真实消息。 |
| "我从代码中就能看出它处理了这个情况" | 如果没有测试,未来的重构会悄无声息地破坏它。 |
为什么这很重要
自主代理被训练为产生“足够好”的输出,以避免纠正。如果没有结构化的审查门控,自主代码提交就会绕过通常能捕获回退和边界情况的人类在环检查。此技能充当那个门控——五个针对性透镜按顺序运行,确保没有明显问题漏网。
回报是累积的:每次审查通过捕获一个真正的问题,就节省了一次 CI 往返、避免了一个用户 Bug、消除了一次回滚的合并请求。