要用 AI 规划代码迁移，先冻结经过核验的现状和目标库存，映射依赖与兼容边界，再让 AI 整理带入口门、出口门、观察项、回滚触发器和负责人的候选迁移波次。目标架构、不可逆决定和每阶段验收必须由人负责。模型只能起草迁移蓝图，不能执行改写或声称迁移完成。

这比通用 AI 项目计划更具体：迁移会改变运行契约，旧状态和新状态可能同时存在。AI 使用总指南介绍安全上下文和审批；这里用 AI 整理顺序与证据，不把架构权交给模型。

关键要点：

选择迁移模式前先写清目标和不做的事。

冻结现状和目标库存，并映射依赖。

把兼容性假设变成明确的测试和门禁。

切换前写好回滚触发器和动作。

AI 只起草蓝图，不执行迁移；关键决定由人批准。

迁移要达成什么结果、哪些不在范围内？

“迁移代码库”没说明改什么、为何改。先写明驱动因素：运行时不再受支持、库替换、服务拆分、语言转换、框架升级、部署平台变化、契约整合或安全要求。定义可衡量的结果，但不要过早选定实现方式。

写一页章程：

字段	问题
结果	哪项能力或风险会改变？
非目标	哪些内容必须保持不动？
范围	涉及哪些仓库、服务、客户端、任务和数据？
约束	兼容窗口、预算、冻结期、法规
成功	哪些可观察条件能证明结果达成？
权限	谁选择架构、谁批准切换？

NIST 的安全软件开发框架（SSDF）把安全实践定位为基于风险、按组织情境调整的活动。［1］据此按影响和证据为迁移风险排序，而非让模型给出通用步骤。

不要把私有仓库、凭据、生产数据转储、客户信息、内部网络细节或未公开漏洞上传到未经批准的工具。使用最少的脱敏清单、公开接口、合成数据结构和受控环境。

冻结现状和目标清单

按系统实际运行方式盘点现状，而非照搬旧架构图。包括可执行入口、库、构建和部署任务、配置、数据存储、队列、定时任务、外部提供方、客户端、可观测性、访问控制和负责人，并附上来源位置和版本。

另建目标清单，区分已批准设计和候选方案。AI 建议过的项目不会因此成为“目标状态”。使用 现状已确认、目标已批准、候选、未知 和 范围外 等状态。

项目 ID	现状	目标	证据	负责人	状态
R-01	运行时 A 版本 x	运行时 B 版本 y	构建文件、发布清单	平台团队	目标已批准
Q-03	队列消费者 v1	未知	部署配置	服务团队	未知

对比两份清单，找出新增、移除、保留的契约和归属不明的项目。不要让生成的摘要抹掉无人负责的定时任务或很少使用的客户端。

哪些依赖会扩大影响范围？

依赖不只是软件包导入。要映射同步调用、事件、队列、共享数据结构、数据库读写、文件格式、缓存、功能开关、身份与授权、部署顺序、运维手册和人工流程，并记录方向和证据。

只有每条边都引用文件、配置项、契约测试或获批运维记录时，才让 AI 生成候选依赖边。发现未知的运行时依赖属于单独的验证计划；导入关系图无法证明所有网络和数据依赖。

按迁移风险为消费者排序：

契约敏感度和发布独立性；
数据归属和是否有状态；
流量或业务重要性；
能否并行测试；
能否独立回滚；
负责人是否可用，以及外部协调难度。

输出应揭示看似局部的库升级，实际在哪些地方与序列化、数据库或客户端行为耦合。

建立迁移兼容矩阵

迁移往往败在边界，而非重写的内部逻辑。针对 API 版本、事件、数据结构、文件、缓存、CLI 参数和持久化状态，列出“旧生产者/新消费者”和“新生产者/旧消费者”等组合。

边界	旧 → 旧	旧 → 新	新 → 旧	新 → 新	证据/测试
事件数据结构	基线	候选	候选	目标	契约测试 ID
存储记录	基线	读取检查	回滚读取	目标	测试数据 ID

绝不要仅凭类型相似就标为兼容。要定义测试数据、测试、环境、预期结果和负责人。并覆盖语义变化，例如默认值、排序、超时、重试、错误映射、权限检查和语言地区处理。

若无法向后兼容，就明确写出协调切换和停机风险，不要藏在笼统的“更新消费者”任务里。

哪种迁移模式适合你的约束？

AWS 把 Strangler Fig 模式描述为：在新旧路径共存期间逐步替换旧系统的功能，迁移完成后再让旧系统退役。［2］当路由和有边界的能力允许逐步转移时，它能降低风险；但对强耦合状态或原子一致性要求并不自动适用。

根据证据评估候选模式：

原地升级，辅以兼容适配层；
通过抽象层分支；
增量路由或 Strangler 方式；
影子流量或只读比较；
双读、双写或事件复制；
在维护窗口内离线转换；
当部分共存不安全时，进行协调式一次性切换。

让 AI 比较各模式的前置条件、可逆步骤、状态分叉风险、运维成本和退出条件。由人类架构负责人选择模式并记录理由。例如，双写能提高过渡灵活性，但会引入顺序、部分失败、对账和回滚的复杂性。

数据与状态该如何单独规划？

代码可重新部署，状态却未必可逆。盘点数据结构变更、回填、标识符、时间戳、编码、索引、约束、保留期、事件偏移量、缓存键、会话和衍生数据。明确每个阶段的真源是什么。

每项转换都要记录：

输入和输出的数据结构版本；
确定性的转换规则；
验证样本或对账查询；
无效记录或迟到记录的处理方式；
检查点和重新启动行为；
向前兼容和回滚读取行为；
备份、保留和恢复的证据；
负责人和批准。

在合适环境中测试恢复前，不要声称备份可用。不要把真实生产数据放进模型上下文；除非获批私有流程明确允许，只使用数据结构或合成样本。

用 AI 规划代码迁移时拆分带门禁的波次

Microsoft 的迁移规划指南强调依赖发现、迁移排序、工作负载分组、回滚规划和迁移波次，而不是把所有工作负载一视同仁。［3］每个波次应小到可观察、可撤回，并尊重依赖关系。

每个波次需要：

字段	用途
范围	精确的组件、消费者和数据
入口门禁	开始前需要的证据
变更	已批准的技术动作，而非生成的代码
观察	指标、日志、跟踪、契约测试、对账
保持期	扩大范围前所需的时间或样本
出口门禁	继续推进的条件
回滚触发条件	停止该波次的可衡量条件
负责人	有权作决定的人

适当时，先建设能减少不确定性的基础设施和测试能力：契约测试、遥测、路由控制、数据对账或兼容适配层。未说明证据和剩余影响范围时，不要称某个波次“低风险”。

设计并行运行和比较

系统允许时，影子执行或双跑可在转移权威前比较输出。明确哪一侧是权威、如何抑制副作用、如何对请求采样，以及如何规范化非确定性字段。绝不要把生产写入发送到未经批准的影子路径。

建立比较类别：

标识符或规范化序列化结果要求完全相等；
数值或时间类输出使用容差区间；
在契约允许时，采用集合比较或忽略顺序的比较；
由领域负责人批准的语义等价；
无法自动化的情况进行人工复核。

记录不匹配的类别和负责人。很高的总体匹配率可能掩盖严重的授权或资金处理不匹配，因此要按严重程度设门禁，而非只看一个醒目百分比。

把可观测性写进计划

在迁移前选定信号：可用性、延迟、错误类别、资源使用、队列延迟、数据对账、授权拒绝、客户端版本和业务不变量。建立已知基线，并把迁移专用遥测与常规监控分开。

每个信号都需要查询或仪表板引用、预期范围、采集间隔、保留期、负责人和动作阈值。AI 可以整理目录格式或提出缺失类别，但不能虚构基线数值或断言某个仪表板存在。

还要纳入反向证据：某波次后旧路径不应再有流量，就去测量；旧格式记录不应再被创建，就去查询。退出条件既要证明目标能正常工作，也要证明退役路径不再具有权威。

切换前的迁移回滚方案要写清什么？

回滚是经过测试的转换，不是一句“必要时还原”。定义触发条件、决策权限、最长决策时间、路由动作、部署动作、状态处理、客户端沟通和验证方式。把代码回滚和数据回滚分开：旧的二进制程序可能无法理解新版本写入的记录。

使用回滚表：

触发条件	阈值	决策人	动作	状态处理	验证
契约不匹配	任一严重类别	API 负责人	路由回旧路径	停止新写入并对账	契约测试套件 + 计数器

依赖回滚机制前先测试它。如果某项变更不可逆，就如实说明，并定义预防措施、备份、补偿动作和更高级别的审批。不要让模型把“不可逆”淡化成“较难还原”。

迁移怎样才算真正完成？

Microsoft 的现代化指南建议按业务价值、技术依赖、成功标准和回滚规划划分逻辑阶段。［4］迁移完成应包括旧系统退役，而不只是目标系统上线。

退出条件可以包括：

冻结范围内的兼容性和契约测试套件全部通过；
对账结果达到各类别的阈值；
所需保持期结束且没有触发回滚；
所有受支持的客户端都已迁移，或已获得批准的例外；
新状态成为权威，且备份/恢复证据是最新的；
旧系统的流量、任务、凭据、功能开关和写入已全部移除；
文档、归属、告警和运维手册都与目标状态一致；
具名的决策负责人批准退役。

把证据包和未解决的例外归档。长期保留“临时”适配层的迁移不一定失败，但必须明确其负责人、成本和复查日期。

使用可复制的迁移蓝图

# 代码迁移蓝图
- 结果：
- 非目标：
- 冻结证据引用：
- 现状清单：
- 已批准的目标清单：
- 未知项：
- 架构决策负责人：

## 边界
- 消费者 / 生产者：
- 当前契约：
- 目标契约：
- 兼容性测试：
- 数据 / 状态影响：

## 波次
- 范围：
- 依赖：
- 入口门禁：
- 已批准的变更：
- 并行运行方式：
- 观察项与阈值：
- 保持期：
- 出口门禁：
- 回滚触发条件与动作：
- 负责人：

## 完成
- 对账：
- 旧系统退役：
- 文档 / 运维手册：
- 例外：
- 人工批准：

让 AI 查找空字段、无依据的假设、循环依赖、缺失的负责人和回滚缺口。不要在同一次批准中让它既生成又应用迁移。执行任何生成的变更之前，先按 AI 生成代码审阅清单和仓库的变更流程进行审阅。

常见问题

AI 能选择目标架构吗？

它可以比较已记录的选项和约束。架构须由负责工程师选择和批准，因为决定涉及提示词之外的背景、风险和归属。

增量迁移总是更安全吗？

不是。共存可能带来路由、兼容性和状态分叉风险。应按系统约束和经测试的回滚方案选择模式。

数据库迁移应如何处理？

把数据结构兼容、回填、无效记录、检查点、对账、备份、恢复和回滚读取与代码部署分开规划。

项目计划与迁移蓝图有什么区别？

项目计划广泛协调工作；迁移蓝图则为技术共存、兼容性、状态权威、带门禁的切换和退役建模。

什么时候适合一次性切换？

部分共存不可行或风险更高，且团队有获批窗口、完整演练、有力验证、恢复方案和明确权限时。

AI 能根据这份计划生成迁移代码吗？

那应是一项独立、范围明确并经代码审阅和测试的变更。批准蓝图不等于批准生成的实现。

波次进行中出现未知依赖怎么办？

在相应门禁停止，记录证据，重估影响范围和兼容性，修改波次前先取得批准。

迁移什么时候才算完成？

当目标行为和状态达到已批准门禁、客户端完成过渡、例外都有负责人、旧系统权威已移除且退役获批时。

来源

Sources checked 2026 年 8 月 29 日。

NIST, “Secure Software Development Framework” — https://csrc.nist.gov/projects/ssdf
AWS Prescriptive Guidance, “Strangler fig pattern” — https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/strangler-fig.html
Microsoft Cloud Adoption Framework, “Plan a cloud migration” — https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/migrate/plan-migration
Microsoft Cloud Adoption Framework, “Plan cloud modernization” — https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/modernize/plan-cloud-modernization

如何用 AI 规划代码迁移：波次门禁、兼容矩阵与回滚方案