用途:在保持可观察行为不变的前提下,让代码更易读、分层更清晰。若任何可观察行为发生变化,就不再是重构,而是重写(有意改行为)或迁移(API A→B),应停止并说明。
主要能力与要求:
- 先规划转换:基线、批次、回滚属于变更计划,本规范负责执行部分。
- 用等价性检查证明行为保持,而非绿色测试套件。优先使用属性测试、差分测试(旧路径留在 shim 后并对比至干净)或变更前固定的黄金输出;若只能用套件,需写明为何套件足以作为 oracle。
- 逐文件修改,禁止批量 codemod;sed 全量替换会掩盖不适配的调用点。
- 每个批次都运行检查,约 10 个文件为默认批次,风险处收紧。
- 优先删除而非修改,并证明每次删除安全:粘贴源码与测试中零调用者的搜索,以及字符串形式(动态派发、注册表、反射、生成代码、配置)的单独搜索。
- 每个 shim 在引入前必须有可验证的移除条件,如 git grep -c '<old-name>' src/ 返回 0。
- 不做“顺手”的语义改进;搬迁后确认旧位置已空。
- 粘贴真实输出;命令从 AGENTS.md 解析;未定义时询问;不得对自己的工作写评审结论。
使用方式:开始前打开 references/task-template.md 复制到任务文件,随做随填,其中包含等价性检查、批次检查点、shim 表、删除安全搜索与自审。任务包使用套件自带任务模板,基线、批次计划与回滚在变更计划中。
适用场景:需要结构化重构并保留行为的代码库维护工作。
限制:这些是评审包检查的约定,编辑时无强制机制;测试失败意味着行为改变,应先调查而非改测试;公开契约变更属于重写或迁移决策,需上报。其他细节暂未提供。