用 Codex 把代码迁移拆成可回退的检查点

一次受控迁移的交付物应当包含迁移面清单、旧概念与新概念的映射、按依赖排序的检查点、每一步的验证记录，以及仍可执行的回退办法。验收时可以停在任意一个检查点运行系统，也能说清哪些请求已经走新路径，哪些仍由旧实现承担。整仓改完后才第一次验证，会把定位和回退都变得困难。

先画出旧系统的契约

准备旧栈与目标栈的版本、生产约束、可运行的测试和一组代表性输入。让 Codex 先盘点路由、数据模型、认证、配置、后台任务、构建工具、部署方式与外部接口。每一项都记录入口、拥有者、调用方和当前验证手段。某个行为虽显得奇怪，只要外部调用方依赖它，就先视为待保留契约。

随后建立映射表，写明旧概念在目标栈中的对应方式。没有直接对应项时，要标成设计决策，附上备选方案与影响。变化要单列。不要让 Codex 顺手替你决定用户可见变化。确实要改响应结构、错误码或配置名称时，把它从技术迁移中分离，单独取得产品与调用方确认。

基线应在动代码前运行。保存定向测试、类型检查、构建和关键请求的结果，连同现有失败一起记录。可见结果是一份旧行为基线，后续每个检查点都与同一组输入比较。

给每条契约分配一种核验方式。公开接口用请求与响应样例，文件转换用固定输入和产物摘要，后台任务用状态变化与副作用记录。没有自动测试的契约先补可重复观察，再开始搬运代码。否则迁移后只剩“目前没听到投诉”这一种判断。

按依赖关系拆里程碑。可以先建立目标栈骨架，再迁一条读取路径，随后处理写入、后台任务和清理。边界应当有清晰输入输出，能够独立测试，也能在失败时切回旧实现。兼容适配器、并行入口或按配置选择路径，都可以暂时隔离新旧差异。

让 Codex 为每个里程碑写执行计划。计划列出要改的文件、保持不变的契约、预期差异、检查命令、停止条件与回退动作。长任务中把已经完成的证据和剩余风险持续写回计划，后续恢复工作时就不会依赖聊天记忆。

先保留旧路。迁移第一条路径时保留旧入口。新实现通过以后，用契约测试向两条路径发送同一输入，比较结果、错误和关键副作用。时间、随机值与生成标识需要归一化后再比。可见结果是一份差异报告，任何未解释差异都会阻止进入下一步。

每个里程碑完成后，先运行最接近改动的测试，再运行类型检查、构建和必要的烟雾测试。失败就停。涉及外部接口时增加契约验证，涉及性能敏感路径时在同一环境与输入下比较。测试失败要留在当前检查点解决，不能继续堆下一层改动。

查看这一阶段的差异，确认没有提前删除回退路径，也没有混入无关清理。独立工作树能让迁移切片与其他功能开发隔离。若基础分支前进，应先在干净状态下重新结合最新代码，再重复当前里程碑的验证。

数据要能恢复。数据迁移和不可逆外部写入要更谨慎。先验证备份、幂等性、重放方式与失败后的人工处理。需要双写时，明确以哪条路径为准，怎样发现分歧，何时停止双写。缺少可恢复条件时，代码层面的回退按钮也无法恢复已经改变的数据。

删旧实现要慢。只有当调用点清单归零、目标路径稳定通过完整检查、部署环境已经验证，才删除旧实现与兼容层。搜索静态导入之外的配置键、字符串路由、脚本和运行手册，避免隐藏入口在清理后失效。删除动作应作为单独检查点，仍保留一段可理解的迁移记录。

代码审查适合查漏掉的调用方和危险差异。权限配置限制文件系统和网络边界，审批策略决定越界操作、网络访问、非可信命令和有副作用的工具调用何时需要确认。生产切换仍应由团队发布流程单独设闸。Codex 能推进计划和执行检查，业务契约的取舍、生产切换时间与不可逆操作仍由负责团队决定。

测试无法覆盖生产中的所有历史数据、流量顺序和外部系统行为。迁移计划应把这些未知写成条件，并安排观测或小范围验证。新旧栈长期并存会增加维护成本，因此每个兼容层都要有退出条件、负责人和删除证据。