schema-evolution-planner

模式演进规划器

规划安全、分阶段的数据库模式变更，涵盖应用代码、回填和切换。

范围： 面向在线系统的扩展-收缩和兼容性规划。不适用于从零开始的模式设计（database-architect）或 DBA 运维。

规范术语

术语	定义
expand	与现有代码兼容的增量模式变更
backfill	根据旧数据填充新结构的数据迁移
dual-write	暂时同时写入旧表示和新表示
dual-read	暂时同时读取旧表示和新表示
cutover	流量或逻辑切换到新路径的时点
contract	兼容窗口结束后移除弃用模式
compatibility window	旧代码和新代码都必须正常工作的时期
invariant	迁移期间必须始终成立的条件
shadow column	迁移期间在旧字段旁新增的字段
rollback point	可在不丢失数据的情况下恢复到的最后一个安全状态

分派

$ARGUMENTS	模式
plan <change>	制定完整的迁移顺序
review <migration or rollout>	审核现有的演进计划
backfill <change>	设计数据回填策略
cutover <change>	规划读或写的切换
deprecate <change>	规划收缩和移除阶段
关于零停机模式变更的自然语言描述	自动检测最匹配的模式
空	显示包含示例的模式菜单

模式菜单

#	模式	示例
1	规划	plan rename users.username to handle
2	审核	review migration plan for orders status enum change
3	回填	backfill new account_id on invoices
4	切换	cutover reads to new customer_profile table
5	弃用	deprecate legacy address columns

适用场景

• 重命名在线系统中的列或表
• 在不停机的情况下拆分或合并表
• 为现有表添加必填字段
• 逐步引入新标识符或外键
• 协调涉及多次应用部署的模式变更

分类逻辑

选择模式前，将以下逻辑用作分类关卡：

1. 如果任务涉及全新的模式设计、数据建模或从头设计表，则转交给 database-architect。
2. 如果任务涉及查询调优、索引调优、清理、复制或数据库管理，请勿使用此技能。
3. 如果任务涉及超出模式变更顺序范围的发布编排、制品晋级或发布拓扑，则转交给 release-pipeline-architect。
4. 如果任务是没有兼容窗口的应用功能变更，请改用应用或框架技能。
5. 如果提示对重命名还是重新设计存在疑问，请从 plan 模式开始，并明确判断该变更是增量演进还是更广泛的重新设计。

指令

模式：规划

1. 确定当前的读取路径、写入路径、下游使用方以及部署顺序限制。
2. 对变更进行分类：重命名、类型变更、拆分、合并、约束强化或删除。
3. 阅读 references/change-type-decision-matrix.md，为该变更类型选择最安全的扩展-收缩模式。
4. 如果变更涉及多次部署、读取方、写入方或下游使用方，请阅读 references/sample-rollout-sequences.md。
5. 编写扩展-收缩步骤，并明确列出检查点：扩展、部署兼容代码、回填、验证不变量、切换，然后收缩。
6. 明确兼容窗口，以及在此期间旧代码和新代码必须兼容的情况。
7. 指明进入下一阶段前必须衡量的不变量。
8. 使用 references/output-templates.md 中的相关模板呈现计划。

模式：审查

1. 阅读迁移计划、迁移文件和任何上线说明。
2. 阅读 references/migration-failure-modes.md 和 references/change-type-decision-matrix.md。
3. 检查是否存在隐藏的破坏性步骤、缺失的兼容窗口或缺失的回滚点。
4. 标出对数据质量、回填运行时长和消费者就绪情况的假设。
5. 按严重程度对发现的问题排序。
6. 使用 references/output-templates.md 中的审查模板呈现发现。

模式：回填

1. 定义数据的唯一可信来源和目标人群逻辑。
2. 确保回填具备幂等性，并可分块执行。
3. 阅读 references/migration-failure-modes.md，了解重复写入、数据漂移和对账方面的风险。
4. 说明批处理策略、重试行为、进度跟踪和对账检查。
5. 判断回填运行期间是否需要双写。
6. 使用 references/output-templates.md 中的回填模板呈现计划。

模式：切换

1. 如果写入切换和读取切换无需同时进行，则将二者分开。
2. 在切换流量或逻辑之前，定义确切的成功检查项。
3. 阅读 references/sample-rollout-sequences.md 和 references/migration-failure-modes.md，了解中止和回滚模式。
4. 在新路径证明稳定之前，保留回滚点。
5. 使用 references/output-templates.md 呈现切换检查清单。

模式：弃用

1. 确认没有任何线上代码、作业或消费者仍依赖旧结构。
2. 先移除写入，再移除读取，最后移除已弃用的架构。
3. 记录兼容窗口已结束的证据。
4. 使用 references/output-templates.md 中的弃用模板呈现证据和移除顺序。

输出要求

• 每个计划都必须包含扩展、兼容、验证、切换和收缩阶段。
• 说明各阶段之间需要检查的不变量。
• 指明回滚点和推进所需的证据。

关键规则

1. 兼容窗口结束前，绝不移除或更改线上字段的用途。
2. 每次回填都必须具备幂等性，并且可重新启动。
3. 切换必须预先定义成功和中止标准。
4. 破坏性变更只能放在收缩阶段。
5. 如果问题实际属于全新架构设计，则交由 database-architect 处理。

扩展策略

复杂度	策略
小	对简单重命名、添加可空字段或引入影子列，使用单一的增量兼容路径。
中	明确分阶段执行：扩展、部署兼容逻辑、分块回填、验证、切换，然后收缩。
大	将变更视为上线计划，分开进行读取和写入切换，并设置证据门槛，分阶段迁移消费者。

渐进式披露

• 根据当前模式的指示阅读参考文件，而不是一次性全部加载。
• 在需要变更分类和处理歧义时，按需加载 references/change-type-decision-matrix.md。
• 在需要审查、回填和切换时，按需加载 references/migration-failure-modes.md。
• 在需要规划多阶段执行时，按需加载 references/sample-rollout-sequences.md。
• 在呈现最终回复时，按需加载 references/output-templates.md。

参考文件索引

文件	用途	何时阅读
references/change-type-decision-matrix.md	将架构变更类型映射到安全的演进模式、兼容窗口和风险信号	任何 plan 或 review 请求
references/migration-failure-modes.md	汇总常见的发布、回填和切换失败模式及其缓解措施	review、backfill 或 cutover 工作
references/sample-rollout-sequences.md	常见迁移形态的扩展-收缩流程参考	多阶段 plan 或 cutover 工作
references/output-templates.md	计划、评审、回填、切换和弃用的标准回复模板	以任何模式呈现最终输出

范围边界

适用范围： 零停机重命名、拆分、合并、回填、分阶段切换、兼容性排序。

不适用范围： 全新架构建模、查询调优或数据库管理。