Safe Prisma Migration スキル

目的

.agent/rules/core.md の原則「bunx prisma db push は絶対禁止、bunx prisma migrate dev 必須」を徹底し、スキーマ変更を安全に適用するスキル。

⚠️ このスキルは破壊的操作を含むため invocation: explicit に設定されています。 ユーザーの明示的な指示（「マイグレーション実行」等）がない限り、自動実行されません。

実行手順（この順番を厳守すること）

Step 1｜スキーマ変更内容を読み込む

Read: prisma/schema.prisma

以下の変更タイプを特定する：

Step 2｜仕様書との整合性を確認する

Read: specs/multi-vendor-ecommerce/03-data-model.md

確認ポイント：

• 新規モデルが仕様書の ER 図に含まれているか
• フィールド変更が仕様書のエンティティ定義に記載されているか
• 乖離がある場合は警告をユーザーに提示する

Step 3｜既存マイグレーション履歴を確認する

bash
1ls -la prisma/migrations/

確認ポイント：

• 最新のマイグレーション名とタイムスタンプ
• 履歴の連続性
• migration_lock.toml の存在

Step 4｜バックアップ確認（必須・ブロッキング）

ユーザーに以下を表示し、明示的な「yes」が得られるまで次に進まない：

⚠️ データベースのバックアップは取得済みですか？

マイグレーションは破壊的操作を含む可能性があります。
以下を確認してください：

1. データベースのバックアップが取得されている
2. 本番環境ではない、またはメンテナンスウィンドウ内である
3. マイグレーション内容を理解している

続行しますか？ (yes/no)

Step 5｜接続先環境を確認する

認証情報を露出しないよう、ホスト名と DB 名のみを抽出して確認する：

bash
1if [ -n "$DATABASE_URL" ]; then
2  DB_INFO=$(echo "$DATABASE_URL" | sed -E 's/.*@([^\/]+)\/([^?]+).*/host=\1 db=\2/')
3  echo "データベース接続先: $DB_INFO"
4
5  IS_PROD=false
6  if [ "$NODE_ENV" = "production" ]; then IS_PROD=true; fi
7  if [ "$MIGRATION_TARGET" = "production" ] || [ "$MIGRATION_TARGET" = "prod" ]; then IS_PROD=true; fi
8  if echo "$DATABASE_URL" | grep -qiE '(production|prod|prd)'; then IS_PROD=true; fi
9
10  if [ "$IS_PROD" = true ]; then
11    echo "⚠️ 警告: 本番環境を指している可能性があります。本当に続行しますか？ (yes/no)"
12  fi
13else
14  echo "DATABASE_URL が設定されていません"
15fi

本番環境と判定された場合は追加の明示的確認を求める。

Step 6｜マイグレーションを実行する

マイグレーション名の命名規則

実行コマンド（db push は絶対使用禁止）

bash
1bunx prisma migrate dev --name <add_descriptive_name>

実行後、出力ログで以下を確認する：

• マイグレーションファイルが生成されたか
• エラーが発生していないか
• DB への適用が成功したか

Step 7｜生成された migration.sql を確認する

bash
1ls -la prisma/migrations/
2# → 最新ディレクトリの migration.sql を Read する

以下の破壊的操作が含まれる場合はユーザーに警告を表示する：

sql
1DROP TABLE ...
2DROP COLUMN ...
3DELETE FROM ...
4ALTER TABLE ... DROP COLUMN ...
5ALTER TABLE ... DROP CONSTRAINT ...
6TRUNCATE TABLE ...

破壊的操作が検出された場合の警告テンプレート：

⚠️ 破壊的操作が検出されました:

以下の SQL 文が含まれています:
- [検出されたSQL文]

この操作は元に戻せません。続行する前に以下を検討してください:
1. migration.sql を手動で確認・編集する
2. ステージング環境に先行適用する（bunx prisma migrate deploy）
3. ロールバックが必要な場合は、ディレクトリを削除せず補正マイグレーションを作成する

Step 8｜Prisma クライアントを再生成する

bash
1bunx prisma generate

Step 9｜関連コードの更新箇所を提案する

変更されたモデル名で影響範囲を特定する：

bash
1grep -rE "db\.[A-Za-z_][A-Za-z0-9_]*" src/queries/

Read: src/lib/types.ts
Read: src/lib/schemas.ts

更新が必要なファイルをリストアップして報告する。

Step 10｜仕様書更新案を提示する

specs/multi-vendor-ecommerce/03-data-model.md の更新が必要なセクションと内容を提示する。

Step 11｜実行結果レポートを出力する

markdown
1## Safe Migration 実行結果
2
3### マイグレーション詳細
4- **マイグレーション名**: `YYYYMMDDHHMMSS_[name]`
5- **実行日時**: YYYY-MM-DD HH:MM:SS
6- **ステータス**: ✅ 成功 / ⚠️ 警告あり / ❌ 失敗
7
8### 実行内容
91. スキーマ変更: [内容]
102. マイグレーションファイル生成: `prisma/migrations/[name]/`
113. DB への適用: 成功
124. Prisma クライアント再生成: 成功
13
14### 破壊的操作
15- ✅ なし / ⚠️ あり（[SQL文]）
16
17### 影響を受けるファイル（要更新）
181. `src/queries/XXX.ts` — [更新内容]
192. `src/lib/schemas.ts` — [更新内容]
203. `specs/multi-vendor-ecommerce/03-data-model.md` — [更新セクション]
21
22### 次のアクション
23- [ ] 影響するサーバーアクションを更新
24- [ ] Zod スキーマを更新
25- [ ] 仕様書を更新
26- [ ] テストを追加・更新
27- [ ] コミットして変更を確定

重要ルール

❌ 絶対禁止

• bunx prisma db push の使用（マイグレーション履歴が残らないため）
• migration_lock.toml の削除
• バックアップ確認なしのマイグレーション実行
• 適用済みマイグレーションの migration.sql 手動編集

✅ 必須

• bunx prisma migrate dev --name [説明的な名前] を使用する
• バックアップ確認でユーザーの明示的な「yes」を得る
• 破壊的操作（DROP / DELETE / TRUNCATE）は必ず警告する
• 仕様書 03-data-model.md との整合性を確認する
• マイグレーション名は add_ / modify_ / remove_ プレフィックスを使用する

💡 推奨

• 本番適用前に bunx prisma migrate deploy でステージング環境テストを行う
• prisma/migrations/ と migration_lock.toml を必ず Git にコミットする
• 破壊的変更がある場合はロールバック計画を事前に確認する

参考: 主要ファイルパス

# Prisma 関連
prisma/schema.prisma                    データモデル定義
prisma/migrations/                      マイグレーション履歴
prisma/migrations/migration_lock.toml  マイグレーションロックファイル

# 仕様書
specs/multi-vendor-ecommerce/03-data-model.md  データモデル仕様

# 実装
src/queries/*.ts      サーバーアクション
src/lib/types.ts      型定義
src/lib/schemas.ts    Zod スキーマ
src/lib/db.ts         Prisma シングルトン

# ルール
.agent/rules/core.md  migrate dev 必須ルール
CLAUDE.md             プロジェクト設定