核心 GUIDE
Dependency / Migration Verification
Dependency Upgrade 与 Data/Schema Migration 必须跨 Compatibility、Rollout、Rollback Boundary 验证，因为 Local Correct 的代码在 Production Version 或 Persisted State 不同的情况下仍可能失败。
核心心智模型
把 Migration 看成 Compatibility Envelope 的变化。要证明 Old/New State 如何共存、Data 如何移动、Partial Rollout 时发生什么，以及 Reverse Change 时系统如何恢复。
为什么重要
AI Coding Agent 很容易把 Upgrade 理解成“改 Version 直到 Test Pass”。真实系统却有 Lockfile、Generated Client、Database State、Cache、多 Deployment Version 与 External Consumer。验证必须覆盖 Transition，而不只是最终 Destination。
01
验证 Transition Matrix，而不仅是 Final Build
记录 Before/After Version 或 Schema，识别 Persisted/External Contract，并在需要时测试 Forward Compatibility、Mixed-version Operation 与 Rollback。使用 Representative Data 跑 Migration，检查 Generated Diff 与 Lockfile，对 Irreversible Transformation 显式标记；高风险 Change 还需要 Canary 或 Post-migration Assertion。
02
示例：Schema Migration 测试通过，却破坏 Rolling Deploy
Service 重命名 Database Column，并同步修改所有 Code Reference。Fresh Database 上 Unit Test 全过，但第一台 New Instance 上线时 Old Instance 仍在服务，旧版本立即因为字段不存在而失败。Compatibility-aware Migration 会先新增 Column、Dual-read、Backfill，Fleet 收敛后再删除旧字段。
常见失败模式
- 只验证 Clean Install，不验证真实 Upgrade Path。
- Rolling Deployment 中同时改变 Schema 与 Application Assumption。
- 没有测试 Migrated Data 的行为就宣称 Rollback Safe。
工程启发
- 发布前写清支持哪些 Version/State Combination。
- 使用 Representative Persisted Data 与 Mixed-version Boundary 测试。
- 把 Reversible Rollout Step 与 Irreversible Cleanup 分开。
关键结论
- 01Migration Correctness 关注的是状态之间的 Transition。
- 02Final Build 通过并不证明 Rolling Compatibility。
- 03Rollback 与 Data Semantic 应在最初 Design 中考虑。
阅读记录
这里只记录你真实做过的动作，不代表掌握、熟练或认证。
用于这些学习路径
这个 Concept 会在多个 canonical 学习路径中复用。
来自 Knowledge Graph 的相关知识点
这些关系直接来自 canonical graph，不维护第二套 Guide 分类体系。