kill-legacy

清除旧版代码

唯一目标： 清除旧版代码和回退代码，让代码库只有一条当前路径，而不是新旧路径永远并存。

不要扩大范围，去做一般性代码异味清理、重命名或无关重构。如果代码不属于旧版代码／回退代码（或不是完成清除所必需的），就不要动它。

核心规则

• 优先删除旧路径，而不是套一层包装、加标记或“以后再清理”。
• 以当前实现为准。没有证据表明死掉的双路径仍有必要时，不要“以防万一”保留它们。
• 保留公开行为和外部契约，除非用户授权进行破坏性更改。如果旧路径本身就是公开契约，先迁移调用方，或在删除前取得明确许可。
• 删除前，先证明某条路径未被使用或可被替换（检查引用、功能标记、环境变量默认值、运行时配置、文档和测试）。
• 移除让旧版代码得以存续的脚手架：标记、环境变量、适配器、双读／双写、临时分支，以及仅为旧路径而存在的测试。
• 不要用新的静默回退替代已移除的回退。若输入不符合当前模型，应在边界处明确报错。
• 保留无关的用户更改。让每次修改都便于审查。

确定范围

• 定向处理： 仅处理指定的文件、目录、模块、功能、标记或迁移遗留项。只有完成清除所必需时，才修改其他文件。
• 整个代码库： 先搜索第一方代码中的旧版／回退热点。除非问题明确涉及，否则排除生成文件、第三方代码、构建输出、缓存、锁文件，以及磁盘上已应用的迁移历史。用于清理的、会删除旧列／旧表的新迁移代码可以保留。

如果某条路径是否仍有必要尚不明确，且删除可能破坏生产环境或公共 API，就问一个有针对性的问题。否则，说明假设并根据证据继续。

哪些情况属于旧版／回退代码

如果代码用于在新旧并存的情况下支持旧版本，就将其视为清除目标：

• 已弃用的 API、双重实现、兼容性垫片、“为旧客户端准备的”适配器
• 默认值永久为“新”的功能标记／环境变量开关，以及已失效的旧分支
• 双读／双写、过渡缓存、临时重定向、受支持的运行时已不再需要的 polyfill
• 注释掉的旧实现、#ifdef 式死分支、TODO: remove after migration
• 掩盖迁移缺失的回退值／分支（|| oldField、?? legacyDefault、为保留旧数据结构而使用的 any 类型断言）
• 只用于测试或说明旧路径的测试、测试夹具、文档和类型

模式目录：legacy-patterns.md。

工作流程

1. 查找候选项

在 legacy-patterns.md 中搜索相关信号。对每个候选项记录：

• 位置
• 它保留的旧行为
• 当前的规范路径
• 证明它仍有必要或可安全删除的证据
• 删除风险（公共 API、数据格式、客户端、生产环境中仍启用的标记）

2. 决定保留还是清除

决策	适用情况
立即清除	没有剩余调用方／配置；标记始终默认使用新路径；所有受支持的客户端都已使用新路径；用户已授权破坏性更改
随迁移一起清除	调用方／数据仍使用旧路径，但用户希望清理——先迁移，再在同一工作中删除旧路径
保留（仅报告）	受支持的客户端仍需要该路径、回滚仍在进行，或因法律／合规要求必须保留——列出负责人和退出条件

不要留下“软性”的旧版代码（注释代码、未使用的标记、空的垫片文件）。要么删除，要么说明必须保留的原因，并给出明确的退出条件。

3. 完全移除

对于每项移除操作：

1. 将所有剩余使用方切换到规范路径（或删除仅为兼容旧版而存在的使用方）。
2. 删除旧版实现、类型、导出、标志、环境变量配置和适配器。
3. 删除或改写测试，使其仅断言当前行为。
4. 更新描述旧路径的文档和注释。
5. 移除仅用于公开旧名称的重新导出和汇总文件。
6. 除非用户要求为外部客户端临时进行强制中断，否则不要保留会抛出“deprecated”的存根函数；内部代码应优先在编译时移除。

详情：removal-checklist.md。

4. 验证

对受影响的部分运行范围最小且相关的类型检查、Lint、测试和构建。再次搜索已移除的名称/标志，确保没有遗漏。

如果无法运行验证，请说明跳过了哪些内容。

完成报告

• 检查范围
• 已移除：路径/标志/垫片 → 规范替代项
• 保留项（及退出条件）：仍有必要的内容
• 搜索过的遗漏项
• 已运行的验证及结果