schema-evolution-planner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Schema Evolution Planner

Schema演化规划器

Plan safe, staged database schema changes across application code, backfills, and cutovers.

Scope: Expand-contract and compatibility planning for live systems. NOT for greenfield schema design (database-architect) or DBA operations.

规划跨应用代码、数据回填和切换阶段的安全、分阶段数据库架构变更。

适用范围： 运行中系统的扩展-收缩与兼容性规划。不适用于全新架构设计（需使用database-architect）或数据库管理员（DBA）操作。

Canonical Vocabulary

标准术语表

Term	Definition
expand	Additive schema change compatible with existing code
backfill	Data migration that populates new structures from old data
dual-write	Temporarily writing old and new representations
dual-read	Temporarily reading from both old and new representations
cutover	The point where traffic or logic switches to the new path
contract	Removal of deprecated schema after compatibility window closes
compatibility window	Period where old and new code must both work
invariant	Condition that must remain true during migration
shadow column	New field added beside the old field during migration
rollback point	Last safe state that can be restored without data loss

术语	定义
expand	与现有代码兼容的增量式架构变更
backfill	从旧数据填充新结构的数据迁移操作
dual-write	临时同时写入旧版和新版数据表示
dual-read	临时同时读取旧版和新版数据表示
cutover	流量或逻辑切换到新路径的节点
contract	兼容窗口关闭后移除已弃用的架构
compatibility window	旧版和新版代码必须同时正常运行的时间段
invariant	迁移过程中必须始终保持成立的条件
shadow column	迁移期间在旧字段旁新增的字段
rollback point	可在无数据丢失情况下恢复到的最后安全状态

Dispatch

命令调度

$ARGUMENTS	Mode
`plan <change>`	Build the full migration sequence
`review <migration or rollout>`	Audit an existing evolution plan
`backfill <change>`	Design the data backfill strategy
`cutover <change>`	Plan read or write switchover
`deprecate <change>`	Plan the contract and removal stage
Natural language about zero-downtime schema changes	Auto-detect the closest mode
Empty	Show the mode menu with examples

参数	模式
`plan <change>`	构建完整的迁移序列
`review <migration or rollout>`	审核现有的演化规划
`backfill <change>`	设计数据回填策略
`cutover <change>`	规划读取或写入切换
`deprecate <change>`	规划收缩与移除阶段
关于零停机架构变更的自然语言描述	自动检测最匹配的模式
空输入	显示模式菜单及示例

Mode Menu

模式菜单


plan rename users.username to handle
review migration plan for orders status enum change
backfill new account_id on invoices
cutover reads to new customer_profile table
deprecate legacy address columns

#	Mode	Example
1	Plan	`plan rename users.username to handle`
2	Review	`review migration plan for orders status enum change`
3	Backfill	`backfill new account_id on invoices`
4	Cutover	`cutover reads to new customer_profile table`
5	Deprecate	`deprecate legacy address columns`


plan rename users.username to handle
review migration plan for orders status enum change
backfill new account_id on invoices
cutover reads to new customer_profile table
deprecate legacy address columns

#	模式	示例
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`

When to Use

适用场景

Renaming columns or tables in a live system
Splitting or merging tables without downtime
Adding required fields to existing tables
Introducing new identifiers or foreign keys gradually
Coordinating schema changes with multiple application deploys

在运行中的系统重命名列或表
无停机拆分或合并表
向现有表添加必填字段
逐步引入新标识符或外键
协调架构变更与多轮应用部署

Classification Logic

分类逻辑

Use this as the classification gate before choosing a mode:

If the task is fresh schema design, data modeling, or table design from scratch, route to
```
database-architect
```
.
If the task is query tuning, index tuning, vacuuming, replication, or database administration, do not use this skill.
If the task is release orchestration, artifact promotion, or rollout topology beyond schema sequencing, route to
```
release-pipeline-architect
```
.
If the task is an application feature change with no compatibility window, use the application or framework skill instead.
If the prompt mixes rename-vs-redesign uncertainty, start in
```
plan
```
mode and explicitly decide whether the change is additive evolution or a broader redesign.

在选择模式前，使用以下分类规则：

如果任务是全新架构设计、数据建模或从零开始的表设计，转至
```
database-architect
```
。
如果任务是查询调优、索引调优、清理（vacuuming）、复制或数据库管理，请勿使用此工具。
如果任务是发布编排、制品升级或超出架构排序的部署拓扑设计，转至
```
release-pipeline-architect
```
。
如果任务是无兼容窗口的应用功能变更，请使用对应应用或框架工具。
如果提示中存在重命名与重新设计的不确定性，从
```
plan
```
模式开始，明确判断该变更是增量演化还是更广泛的重新设计。

Instructions

操作指南

Mode: Plan

Plan模式

Identify the current read paths, write paths, downstream consumers, and deployment order constraints.
Classify the change: rename, type change, split, merge, constraint hardening, or deletion.
Read
```
references/change-type-decision-matrix.md
```
to pick the safest expand-contract pattern for the change type.
Read
```
references/sample-rollout-sequences.md
```
if the change touches multiple deploys, readers, writers, or downstream consumers.
Write an expand-contract sequence with explicit checkpoints: expand, deploy compatibility code, backfill, validate invariants, cutover, then contract.
Define the compatibility window and what old and new code must tolerate during it.
Name the invariants that must be measured before moving to the next phase.
Present the plan using the relevant template from
```
references/output-templates.md
```
.

识别当前的读取路径、写入路径、下游消费者以及部署顺序约束。
对变更进行分类：重命名、类型变更、拆分、合并、约束强化或删除。
查阅
```
references/change-type-decision-matrix.md
```
，为该变更类型选择最安全的扩展-收缩模式。
如果变更涉及多轮部署、多个读取者、写入者或下游消费者，查阅
```
references/sample-rollout-sequences.md
```
。
编写包含明确检查点的扩展-收缩序列：expand（扩展）、部署兼容代码、backfill（回填）、验证invariant（不变量）、cutover（切换）、然后contract（收缩）。
定义兼容窗口，以及在此期间旧版和新版代码必须容忍的情况。
命名进入下一阶段前必须验证的不变量。
使用
```
references/output-templates.md
```
中的相关模板呈现规划。

Mode: Review

Review模式

Read the migration plan, migration files, and any rollout notes.

Read

references/migration-failure-modes.md

and

references/change-type-decision-matrix.md

Check for hidden destructive steps, missing compatibility windows, or missing rollback points.
Flag assumptions about data quality, backfill runtime, and consumer readiness.
Rank findings by severity.
Present findings using the review template in
```
references/output-templates.md
```
.

阅读迁移规划、迁移文件及任何部署说明。

查阅

references/migration-failure-modes.md

和

references/change-type-decision-matrix.md

。

检查是否存在隐藏的破坏性步骤、缺失的兼容窗口或缺失的回滚点。
标记关于数据质量、回填运行时间和消费者就绪状态的假设。
按严重程度对发现的问题排序。
使用
```
references/output-templates.md
```
中的审核模板呈现结果。

Mode: Backfill

Backfill模式

Define the source of truth and target population logic.
Make the backfill idempotent and chunkable.
Read
```
references/migration-failure-modes.md
```
for duplicate-write, drift, and reconciliation hazards.
Specify batching strategy, retry behavior, progress tracking, and reconciliation checks.
Decide whether dual-write is required while the backfill runs.
Present the plan using the backfill template in
```
references/output-templates.md
```
.

定义数据源和目标数据的筛选逻辑。
确保回填操作具备幂等性和可分块性。
查阅
```
references/migration-failure-modes.md
```
，了解重复写入、数据漂移和对账风险。
指定批处理策略、重试机制、进度跟踪和对账检查方式。
决定回填运行期间是否需要启用dual-write（双写）。
使用
```
references/output-templates.md
```
中的回填模板呈现规划。

Mode: Cutover

Cutover模式

Separate write cutover from read cutover when they do not need to happen together.
Define the exact success checks before switching traffic or logic.

Read

references/sample-rollout-sequences.md

and

references/migration-failure-modes.md

for abort and rollback patterns.

Keep a rollback point until the new path is proven stable.
Present the cutover checklist using
```
references/output-templates.md
```
.

当写入切换与读取切换无需同时进行时，将二者分开处理。
定义切换流量或逻辑前的明确成功校验标准。

查阅

references/sample-rollout-sequences.md

和

references/migration-failure-modes.md

，了解中止和回滚模式。

在新路径被证明稳定前，保留回滚点。
使用
```
references/output-templates.md
```
中的模板呈现切换检查清单。

Mode: Deprecate

Deprecate模式

Verify no live code, jobs, or consumers still depend on the old structure.
Remove writes first, then reads, then the deprecated schema.
Record the evidence that the compatibility window is closed.
Present evidence and removal ordering using the deprecate template in
```
references/output-templates.md
```
.

验证是否仍有运行中的代码、任务或消费者依赖旧结构。
先停止写入，再停止读取，最后移除已弃用的架构。
记录兼容窗口已关闭的证据。
使用
```
references/output-templates.md
```
中的弃用模板呈现证据和移除顺序。

Output Requirements

输出要求

Every plan must include expand, compatibility, validation, cutover, and contract stages.
State the invariants to check between stages.
Name the rollback point and the evidence needed to advance.

每个规划必须包含expand（扩展）、兼容、验证、cutover（切换）和contract（收缩）阶段。
说明阶段之间需要检查的不变量。
命名回滚点以及进入下一阶段所需的证据。

Critical Rules

核心规则

Never remove or repurpose a live field before the compatibility window closes.
Every backfill must be idempotent and restartable.
Cutovers must define success and abort criteria in advance.
Destructive changes belong only in the contract stage.
If the change is really a fresh schema design problem, route it to database-architect.

在兼容窗口关闭前，绝不能移除或重新使用运行中的字段。
每个回填操作必须具备幂等性和可重启性。
切换操作必须提前定义成功和中止标准。
破坏性变更只能在contract（收缩）阶段执行。
如果任务本质是全新架构设计问题，转至database-architect。

Scaling Strategy

扩展策略

Complexity	Strategy
Small	Use a single additive compatibility path for simple renames, nullable adds, or shadow-column introductions.
Medium	Use explicit staged execution: expand, deploy compatibility logic, backfill in chunks, validate, cut over, then contract.
Large	Treat the change as a rollout program with separate read and write cutovers, evidence gates, and phased consumer movement.

复杂度	策略
小型	针对简单重命名、可空字段添加或shadow column（影子列）引入，使用单一增量兼容路径。
中型	使用明确的分阶段执行流程：expand（扩展）、部署兼容逻辑、分块回填、验证、切换、然后contract（收缩）。
大型	将变更视为部署项目，分开处理读取和写入切换、设置证据 gates、分阶段迁移消费者。

Progressive Disclosure

渐进式查阅

Read reference files as indicated by the active mode instead of loading everything at once.
Load
```
references/change-type-decision-matrix.md
```
on demand for change classification and ambiguity handling.
Load
```
references/migration-failure-modes.md
```
on demand for reviews, backfills, and cutovers.
Load
```
references/sample-rollout-sequences.md
```
on demand for multi-phase execution planning.
Load
```
references/output-templates.md
```
on demand when presenting the final response.

根据当前模式按需读取参考文件，而非一次性加载所有文件。
按需加载
```
references/change-type-decision-matrix.md
```
以进行变更分类和歧义处理。
按需加载
```
references/migration-failure-modes.md
```
以进行审核、回填和切换工作。
按需加载
```
references/sample-rollout-sequences.md
```
以进行多阶段执行规划。
按需加载
```
references/output-templates.md
```
以呈现最终响应。

Reference File Index

参考文件索引

File	Purpose	When to Read
`references/change-type-decision-matrix.md`	Maps schema change types to safe evolution patterns, compatibility windows, and red flags	Any `plan` or `review` request
`references/migration-failure-modes.md`	Catalog of common rollout, backfill, and cutover failure modes with mitigations	`review` , `backfill` , or `cutover` work
`references/sample-rollout-sequences.md`	Reference expand-contract sequences for common migration shapes	Multi-phase `plan` or `cutover` work
`references/output-templates.md`	Standard response templates for plans, reviews, backfills, cutovers, and deprecations	Presenting final output in any mode

文件	用途	查阅时机
`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`	规划、审核、回填、切换和弃用的标准响应模板	任何模式下呈现最终输出时

Scope Boundaries

范围边界

IS for: zero-downtime renames, splits, merges, backfills, staged cutovers, compatibility sequencing.

NOT for: greenfield schema modeling, query tuning, or database administration.

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

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