migration-planning

name	migration-planning
description	规划安全的 schema、数据、API、契约和配置迁移，覆盖发布阶段、向后兼容、验证、回滚、数据回填和部署顺序；当 Codex 被要求设计或评审迁移、破坏性 API 变更、数据库变更、数据回填、特性开关发布或兼容性敏感版本时使用。

迁移规划

快速开始

• 当仓库路径或变更路径可用时，运行 scripts/migration_signal_scan.py <path>。
• 在完成计划前，先阅读 references/migration-checklist.md。
• 遵循 ../_shared/references/skill-operating-rules.md 中共享的安全、验证和范围规则。
• 对数据库和公共契约优先采用 expand-contract 迁移模式。
• 未经明确许可，不要执行迁移、修改数据、部署、提交或推送。

规划流程

1. 识别迁移对象：schema、数据、API、事件契约、配置、依赖或运行时行为。
2. 定义兼容性要求：旧代码配合新数据、新代码配合旧数据、旧客户端配合新 API，以及回滚路径。
3. 把发布拆成多个阶段：

• Prepare：加法式变更、双读或双写、特性开关。
• Backfill：幂等、可恢复、可观测的数据变更。
• Switch：把流量或行为切换到新路径。
• Contract：只有在安全性被证明之后，才移除旧字段、旧代码、旧开关或兼容垫片。

4. 为每个阶段产出带验证和回滚方案的迁移计划。
5. 明确标记不可逆步骤，并在执行前要求批准。

输出规则

• 包含部署顺序和回滚顺序。
• 包含数据验证查询或检查项。
• 包含监控和告警信号。
• 包含影响面和预期耗时。
• 说明移除兼容性代码之前必须满足哪些条件。