migration-engineering

迁移工程

规划并执行跨系统边界的安全迁移。迁移是指将数据、架构、接口、基础设施或服务从当前状态转移到目标状态，同时在过渡期间保持正确性、可用性和可恢复性的任何变更。

此技能负责跨系统迁移方法——兼容性设计、分阶段实施、对账、切换、恢复和弃用。它不负责任何单项技术或子系统的实现细节；这些内容由专业技能负责。

适用场景

在任务涉及以下情况时加载此技能：

触发条件	示例
架构变更必须确保不破坏现有读取方或写入方	“为高流量表添加非空列，同时实现零停机”
在存储或数据表示之间迁移数据	“将用户资料从 Postgres 迁移到使用独立数据库的专用服务”
带弃用期的 API 版本迁移	“用六个月时间将使用方从 v1 REST 迁移到 v2 GraphQL”
基础设施或服务迁移	“跨区域将工作负载从自托管 VM 迁移到托管平台”
需要双轨运行和对账的跨系统变更	“替换旧版计费引擎，同时确保新旧引擎保持同步”
规划迁移的切换、回滚或不可逆步骤	“为数据仓库架构迁移制定恢复策略”

不适用场景

• 单项技术的快速修复——如果变更局限于一个系统，没有兼容窗口、双轨运行或跨系统协调，请直接使用相关专业技能（例如，简单的 DDL 变更使用 data-engineering，单个端点的弃用使用 api-design-and-evolution）。
• 特定工具的操作指南——此技能提供方法，而非特定供应商的说明。它不会规定使用某一种迁移技术、数据库引擎、API 网关或基础设施平台。
• 不跨越系统边界的迁移——原地重构、不跨越数据或接口边界的代码重写，或单一服务的配置变更，均不属于迁移工程的范围。
• 保证可以回滚——此技能不声称总能回滚。有些迁移包含不可逆步骤；此方法要求明确识别这些步骤，并规划验收、沟通和应急措施，而不是暗示存在并不存在的安全保障。

对于服务拆分，当边界已提出，且需要评估迁移模式、共存形式或模块化单体替代方案时，请加载 references/service-extraction-patterns.md。在填写通用迁移计划之前，使用 templates/service-extraction-assessment.md 记录证据。此技能负责安排已获批准的拆分工作；它不负责决定是否应拆分单体，也不负责确定目标架构。

核心工作流

1. 对迁移进行分类并界定范围

确定适用的迁移类型（现实中的迁移通常会组合多种类型，例如服务拆分同时包含数据迁移和 API 迁移）。记录当前状态、目标状态、跨越的边界、迁移类型及其兼容性要求，以及受影响的系统、团队和使用方。加载 references/migration-types.md，了解架构、数据、API、基础设施／服务和服务拆分迁移的分类。

2. 设计扩展／收缩顺序

扩展／收缩模式是安全迁移的基础原语：

1. 扩展 — 添加新的接口、架构或系统，同时旧系统继续提供服务；两者并存，现有使用方不受影响。
2. 兼容窗口 — 明确规定一段时间，在此期间新旧系统均可用，并设定明确的结束条件（日期、指标阈值，或诸如所有已注册使用方均已确认的事件）。
3. 双轨运行或并行操作 — 对于数据和服务迁移，两个系统并行运行（双写、双读并进行比较），以提供做出切换决策所需的证据。
4. 收缩 — 兼容窗口结束且验证确认正确性和完整性后，移除旧接口。

并非所有迁移都包含全部四个阶段：增量架构变更可能只需扩展阶段；复杂的服务拆分则要经历全部四个阶段。

3. 规划回填和核对

对于数据迁移，选择回填策略 — 全量、增量或流式（CDC／事件日志）。核对需从四个维度验证源端与目标端是否匹配 — 完整性、准确性、及时性和一致性；核对应在兼容窗口期间持续运行，并且必须在切换前通过；核对失败是停止条件。

4. 设计切换

明确具体流程（尽可能自动化，并设定前置／后置条件）、切换窗口和可接受的停机时间、可以暂停或回退切换的中断点（如果切换没有中断点，应明确标记为风险），以及用于确认进度并触发中止的可观测性机制。

5. 定义恢复路径

每个迁移步骤必须且只能归入四种恢复分类之一 — 切勿混为一谈：回滚（撤销变更）、向前修复（在新状态下修复）、恢复（从备份／快照恢复）和不可逆（任何层面都无法逆转）。执行不可逆步骤前，必须获得明确确认；要区分“我们选择不构建逆转路径”和“物理上不可能逆转”。两者都需要获得认可、进行沟通并制定应急方案。对具体步骤进行分类时，加载 references/recovery-classification.md。

6. 规划弃用和清理

验证切换完成后：为旧系统定义弃用窗口，在此期间以只读／降级模式运行；跟踪仍依赖旧接口的使用方；移除旧架构／代码路径／标志／配置／凭据／基础设施；并在每个阶段进行沟通（窗口开启、切换计划确定、切换完成、窗口即将关闭、移除）。

7. 验证并结束

宣布完成前，收集正确性证据（核对报告、使用方验证、错误率对比、SLO 合规情况），确认可观测性显示预期的稳定状态，验证恢复流程已测试且不可逆步骤已获确认，并获取各阶段负责人的签字确认。

加载指南

按需加载参考资料和模板——不要一次性加载所有内容。

文件	加载时机
references/discovery-brief.md	需要了解迁移概念如何映射到同级技能，以及此技能的边界在哪里
references/migration-types.md	在选择模式前，对迁移进行分类（架构、数据、API、基础设施／服务、服务拆分）
references/compatibility-patterns.md	为特定迁移类型设计向前／向后兼容性
references/recovery-classification.md	为具体迁移步骤划分恢复路径（回滚、前滚、还原、不可逆）
references/planning-fields.md	起草或审查结构化规划字段（对账、证据、可观测性、客户影响、责任归属），这些内容必须在计划中涵盖
references/service-extraction-patterns.md	评估拆分边界并选择绞杀者路由、抽象分支、防腐层、CDC 和并行运行模式；包含保留模块化单体的判断标准
templates/migration-plan.md	生成包含所有结构化字段的完整迁移计划
templates/compatibility-matrix.md	为涉及多个使用方的迁移构建兼容性矩阵
templates/reconciliation-plan.md	为数据迁移设计对账策略
templates/cutover-and-recovery-record.md	记录切换流程、恢复路径和不可逆步骤确认
templates/service-extraction-assessment.md	记录边界证据、耦合、责任归属、共存、排序、运维风险、可逆性，以及拆分服务还是保留模块化单体的决策

专家路由

迁移工程整合领域专家的工作，但绝不重复其方法论。实现细节应交由负责相应子系统的技能处理。

迁移事项	路由至
拆分依据和目标边界决策	software-architecture；此技能负责安排经授权的迁移
API 契约设计、版本策略、弃用机制	api-design-and-evolution
数据库架构演进、ETL/ELT 管道设计、回填操作	data-engineering
迁移期间的基础设施配置、服务网络、密钥管理	platform-engineering
发布排序、渐进式交付、金丝雀发布、制品晋级	release-engineering
迁移期间的 SLO 定义、错误预算、运维就绪度、事件响应	site-reliability-engineering
工作拆分、依赖关系映射、关键路径、责任分配	implementation-planning
威胁建模、迁移范围的安全审查、认证边界变更	secure-software-engineering
测试策略、回归覆盖率、迁移期间的验证关卡	qa-methodology
验证结论、证据标准、边界测试	verification-methodology

路由到同波次和后续技能

迁移证据——对账报告、切换记录、恢复路径分类和弃用跟踪——可用于评估生产就绪情况。生产就绪技能会使用迁移计划作为服务已准备好投入生产运行的证据。

production-excellence 技能包将 migration-engineering 与 production-readiness、resilience-and-recovery、capacity-and-cost-engineering、incident-learning 和 privacy-engineering 组合在一起。Migration-engineering 为 production-excellence 生命周期提供安全变更这一维度。

路由到产品生命周期技能

如果迁移由功能退役或产品停用触发，请与 product-lifecycle-learning 协作，获取退役决策记录、弃用时间表和客户处置计划。