migration-safety-review-framework-agnostic

id	migration-safety
name	Migration Safety Review (framework-agnostic)
description	スキーマ/データ移行の安全性を framework 非依存で審査する。破壊的スキーマ変更・ロック誘発・backfill・ロールバック可逆性・expand-contract の段階適用を、prisma / typeorm / Rails / Django / Alembic / 生 SQL などに横断適用する。
version	0.1.0
category	upstream
phase	["upstream","midstream"]
applyTo	["**/migrations/**/*","**/migrate/**/*","prisma/schema.prisma","db/**/*.sql"]
tags	["migration","database","schema","safety","rollback","upstream"]
severity	major
inputContext	["diff"]
outputKind	["findings","questions"]
modelHint	balanced
dependencies	["code_search"]

Pattern declaration

Primary pattern: Reviewer Secondary patterns: Inversion Why: 移行の破壊的・ロック誘発・不可逆操作をチェックリスト型で検査するが、移行を含まない差分では実行を止めるゲートが必要。

Goal / 目的

• ORM やフレームワークに依存せず、スキーマ/データ移行に共通する運用事故（データ損失・本番ロック・ロールバック不能・反復不能）を検出する。
• 特定フレームワーク固有の深い規約（例: Laravel change() の修飾子消失）は専用 skill に委ね、本 skill は横断的な安全性に集中する。

Non-goals / 扱わないこと

• データモデル設計の妥当性（正規化・関連設計）は data-model-db-design のスコープ。
• フレームワーク固有の細則（Laravel 固有は laravel-migration-safety）。
• アプリ側のクエリ効率（N+1 等）。

Pre-execution Gate / 実行前ゲート

このスキルは以下の条件がすべて満たされない限り NO_REVIEW を返す。

• 差分にスキーマ/データ移行（migrations ディレクトリ・schema.prisma・*.sql・ALTER/CREATE/DROP を含む変更）が含まれている
• diff コンテキストが利用可能である

ゲート不成立時の出力: NO_REVIEW: migration-safety — 移行の変更なし

False-positive guards / 抑制条件

• 新規テーブル作成内の index/制約追加は既存行へのロックが無いため指摘しない。
• 不可逆な down/rollback は、データ変換系移行で完全な逆操作が原理的に不可能なケースが正当（コメントで明示があれば許容）。
• 破壊的操作が「別 PR で deprecate 済み／expand-contract の contract フェーズ」と明示されている場合は指摘しない。
• 小規模テーブルが diff／文脈から確実な場合はロック懸念を断定しない（questions で確認）。

Rule / ルール

横断的に以下を確認する（該当するもののみ）:

1. 破壊的スキーマ変更: カラム/テーブル/制約の DROP、型の縮小変換（例: text→varchar(n)）、リネームは、データ損失と後方互換を確認する。
2. ロック誘発: 大規模テーブルへの index 追加・ALTER TABLE・NOT NULL 追加は本番でロック/長時間化し得る。PostgreSQL なら CREATE INDEX CONCURRENTLY、MySQL なら online DDL / pt-osc 等の非ロック手段を検討する。
3. NOT NULL + default 無し: 既存行があるテーブルへ default 無しの NOT NULL カラム追加は失敗/全行書込みになる。default 付与または backfill 後に制約化（expand-contract）を推奨。
4. backfill 安全性: 大量 UPDATE/INSERT はバッチ分割・タイムアウト・レプリケーション遅延を考慮する。1 トランザクションでの巨大更新を避ける。
5. ロールバック可逆性: down/rollback が up の逆操作として整合し、データを失わず戻せるか。不可逆なら明示する。
6. 段階適用（expand-contract）: 破壊的変更はコードのデプロイと移行の順序（expand→migrate→contract）で無停止化できないか。

Evidence / 根拠の取り方

• 指摘は で差分に紐づけ、検出した操作（DROP / ALTER / NOT NULL / 大量 backfill 等）を引用する。