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>	contract と削除の段階を計画します
ゼロダウンタイムのスキーマ変更に関する自然言語の入力	最も近いモードを自動検出します
空	例を含むモードメニューを表示します

モードメニュー

#	モード	例
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 モードから始め、変更が追加型の進化か、より広範な再設計かを明示的に決定します。

手順

モード：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 に依頼してください。

スケーリング戦略

複雑度	戦略
小	単純な名前変更、NULL 許容フィールドの追加、シャドウカラムの導入には、単一の追加的な互換性経路を使います。
中	明示的な段階実行を行います。拡張、互換性ロジックのデプロイ、チャンク単位のバックフィル、検証、切り替え、そして契約の順に進めます。
大	変更をロールアウト計画として扱い、読み取りと書き込みの切り替えを分け、証拠に基づくゲートを設け、コンシューマーを段階的に移行します。

段階的な情報開示

• すべてを一度に読み込まず、現在のモードで指定されているリファレンスファイルを読みます。
• 変更の分類と曖昧さへの対応には、必要に応じて 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	計画、レビュー、バックフィル、切り替え、非推奨化のための標準的な応答テンプレートです	いずれのモードでも最終出力を提示する際

対象範囲

対象: ダウンタイムなしの名前変更、分割、統合、バックフィル、段階的な切り替え、互換性を考慮した実施順序。

対象外: 新規スキーマの設計、クエリのチューニング、データベース管理。