database-schema-design

データベーススキーマ設計

汎用的な SQL や ORM のコード片を出力するのではなく、ストレージモデルの選定と進化が主な作業である場合に、このスキルを使用します。

database-schema-design は、バックエンドのストレージ設計の要として、以下を支援します。

• リレーショナル優先、ドキュメント中心、ハイブリッドの各モデルから選択する
• ドメインエンティティを、テーブル、コレクション、所有権の境界、ライフサイクルルールに落とし込む
• 制約、インデックス、テナントのスコープ、履歴／監査の構造、削除／保持の動作を正当化する
• マイグレーション、バックフィル、クリーンアップに現実味を持たせ、段階的なスキーマの進化を計画する
• 実装、検証、レポート、オブザーバビリティの作業に分岐する前に、後続チームへ簡潔なストレージ設計パケットを引き渡す

規模が大きい作業やリスクの高い作業に取り組む前に、以下のサポートドキュメントを読んでください。

• references/storage-decision-matrix.md
• references/schema-review-checklist.md
• references/intake-packets-and-route-outs.md

このスキルを使用する場合

• 製品機能、社内ツール、管理者ワークフロー、顧客データ領域、またはライブ運用／ゲームのバックエンドシステム向けに、新しいスキーマを設計する場合。
• 制約が弱い、命名に揺れがある、カーディナリティのモデル化が不十分、またはインデックスが信頼できない既存のストレージモデルをリファクタリングする場合。
• 独立したカラムやインデックス付きドキュメントフィールドにするフィールドと、柔軟なメタデータペイロードにするフィールドを決める場合。
• マルチテナント、監査ログ、権限、ステータス履歴、データ保持、または論理削除の境界を計画する場合。
• マイグレーションが安全で現実的な段階に分けられ、バックフィル、互換性の維持期間、クリーンアップについて誠実に説明されているか確認する場合。
• 実装前、またはリスクの高いバックエンド変更の検討中に、範囲を限定したストレージパケットを作成する場合。

このスキルを使用しない場合

• 主な作業が REST／GraphQL の契約の形、エンドポイントの動作、Webhook のセマンティクス、またはバージョン管理である場合 → api-design。
• 主な作業が ID／セッション／プロバイダーの設定、または認証が管理するユーザー／組織の境界である場合 → authentication-setup。
• 主な作業がマイグレーションの検証、リポジトリの網羅性、または契約／回帰テストである場合 → backend-testing。
• 主な作業が公開ドキュメント、クイックスタート、または開発者向けのスキーマ／API の説明である場合 → api-documentation。
• 主な作業が、シークレットの取り扱い、CSRF、Cookie、不正利用対策など、データ整合性を超えた広範な強化である場合 → security-best-practices。
• 主な作業が、すでにモデル化されたデータに基づくダッシュボード／レポートの表示、またはテレメトリー／アラートの対応範囲である場合 → looker-studio-bigquery または monitoring-observability。
• 依頼に実際のドメイン、アクセスパターン、またはライフサイクルのコンテキストがまだない場合。この場合は、スキーマが確定したふりをせず、不足している質問を返してください。

手順

ステップ 1：主要なストレージ設計パケットを 1 つ分類する

主要なレーンを 1 つ選び、最小限ながら有用な成果物を 1 つ作成します。

schema_packet:
  workload_shape: oltp | analytics-adjacent | event-log | content-heavy | mixed | unknown
  data_lane: relational-first | document-heavy | hybrid | unknown
  change_type: greenfield | incremental | migration | cleanup | scale-fix
  ownership_focus: product-core | internal-ops | marketing-customer-data | game-live-ops | mixed
  durability_needs: basic | transactional | audit-heavy | compliance-sensitive | unknown
  hottest_risk: integrity | queryability | migration-safety | lifecycle-drift | unclear
  output_packet: design-memo | schema-review | migration-rollout | erd-plus-decisions | unknown

まず、以下を整理します。

1. 実際のビジネスエンティティまたは集約は何ですか？
2. 最も価値の高い読み取り、書き込み、フィルター、結合、レポートは何ですか？
3. 新規設計、稼働中システムの変更、スキーマの整理のどれですか？
4. どのルールが真のビジネス不変条件で、どのルールが一時的な実装上の都合ですか？
5. どのようなプラットフォーム上の制約がすでに存在しますか（データベースエンジン、ORM、ホステッドサービス、コンプライアンス、規模）？

ステップ 2：信頼できる最小限の根拠を集める

漠然とした印象だけでストレージを設計しないでください。実際の判断を裏付ける最小限のパケットを集めます。

• 製品／ドメインの目的
• 既存のスキーマ、モデル、または代表的なレコード
• 既知の読み取り／書き込み、フィルター、結合、検索／レポートのニーズ、データ保持ルール
• テナント／所有権、監査／履歴、削除に関する期待
• ロールアウト上の制約：トラフィック、マイグレーションの時間枠、ロックのリスク、互換性の懸念、下流の利用者
• 設計を見せかけの完成状態にしてしまう未解決の質問

根拠が不十分な場合は、その旨を明示し、実装可能な状態であるふりをせず、パケットをレビュー／メモのレベルにとどめてください。

ステップ 3：データレーンを意図的に選ぶ

references/storage-decision-matrix.md を使用します。

• リレーショナル優先：整合性、トランザクション、共有不変条件、結合、レポートが最も重要な場合。
• ドキュメント中心：通常、1 つの集約単位をまとめて読み書きし、その構造に十分なばらつきがあって厳格なリレーショナルモデリングでは見せかけの精密さになってしまう場合。
• ハイブリッド：トランザクションの中核は安定している一方、一部のメタデータやコンテンツのペイロードには正当な柔軟性が必要な場合。

理由を 1～2 文で述べます。「既存のスタックで使われているから」は有用な背景情報ですが、それだけでは十分な根拠になりません。

ステップ 4：所有権、ライフサイクル、クエリ上重要なフィールドをモデル化する

中核となる各エンティティ／コレクション／集約について、以下を定義します。

• 目的と所有権の境界
• 識別子の方針
• 必須属性と任意属性
• ライフサイクルの状態とタイムスタンプ
• 関係または参照の方向
• 該当する場合はテナント／組織の所有権
• 削除、アーカイブ、保持、履歴のルール
• クエリ可能、一意、またはレポート可能な状態を維持する必要があるフィールド
• 検索／レポート／運用に支障をきたさず、柔軟なメタデータとして保持できるフィールド

次の落とし穴に注意してください。

• ビジネス概念ではなく、UI オブジェクトをそのまま再現する
• 多対多の関係や履歴を JSON ブロブや場当たり的な配列に隠す
• 変更可能な状態、監査履歴、派生データ／キャッシュデータを 1 つのテーブル／ドキュメントにまとめる
• 認証／プロフィール／セッションの所有権を、無関係なプロダクトエンティティと混同する
• 分析、テレメトリー、キャンペーン属性がすでにフィルタリング、レポート、ライブ運用上の判断に使われているのに、それらを不透明なペイロードに格納する

ステップ 5：整合性とアクセスルールを同時に設計する

スキーマの品質は、守ることのできる不変条件によって決まります。

以下を明記します。

• キーと所有権のルール
• 一意性／NULL 許容性／デフォルト値／状態の制約
• 頻繁に行われる読み取り、書き込み、フィルタリング、結合、集約検索
• インデックスと、それぞれの目的
• 意図的な非正規化や柔軟なフィールド、および柔軟性を保つ理由

主なクエリのパターンを挙げられない場合、インデックスに関する指針はおそらく実態に即していません。

ステップ 6：段階的な導入と適切な振り分けを計画する

段階的な変更や稼働中のシステムへの変更では、以下を定義します。

• 追加的変更か破壊的変更か
• 必要に応じて、拡張と縮小、バックフィル、二重読み取り／書き込み、シャドー読み取りを行うフェーズ
• インデックス／制約を安全に適用できるタイミング
• ロールバックまたは停止の条件
• 古いカラム／テーブル／ドキュメントフィールドを削除する条件

次に、references/intake-packets-and-route-outs.md を使用して、関連作業を明確に振り分けます。

• モデルに依存するインターフェースやコントラクトの変更は api-design
• ID／セッション／プロバイダーの所有権は authentication-setup
• マイグレーションの検証とリグレッションテストの網羅は backend-testing
• 主な作業が、整備済みデータを使った関係者向けダッシュボード／レポートの場合は looker-studio-bigquery
• 主な作業が、テレメトリーの鮮度、アラートの網羅性、または実行時の可視性の場合は monitoring-observability
• 懸念がデータ整合性を超えて、アプリ／Web のより広範なセキュリティ強化に及ぶ場合は security-best-practices

ステップ 7：境界のチェックを行う

最終決定の前に references/schema-review-checklist.md を使用します。

以下を確認します。

1. データレーンを 1 つ選び、出力パケットを 1 つ選んでいる。
2. 所有権、ライフサイクル、クエリ上重要なフィールドが明確になっている。
3. 柔軟なメタデータが、先送りされたモデリング上の負債としてではなく、正当な理由に基づいている。
4. 稼働中のシステムに対するマイグレーションの安全性に信頼性がある。
5. API／認証／テスト／レポート／オブザーバビリティの作業が、暗黙のうちに取り込まれるのではなく、適切に振り分けられている。
6. パケットが次の具体的なアクションで締めくくられている。

出力形式

## Storage Design Packet: [System or Feature]

### Packet framing
- Workload shape:
- Chosen data lane:
- Change type:
- Ownership focus:
- Why this lane fits:

### Evidence used
- Current artifacts:
- Query/reporting needs:
- Lifecycle or retention constraints:
- Assumptions / gaps:

### Entity / collection map
| Entity | Purpose | Key fields | Relationships / ownership | Lifecycle notes |
|--------|---------|------------|----------------------------|-----------------|
| ... | ... | ... | ... | ... |

### Integrity and access rules
- Required constraints:
- Uniqueness / nullability notes:
- Indexes and why:
- Flexible metadata that stays flexible:

### Rollout / migration plan
- Sequence:
- Backfill / compatibility notes:
- Cleanup conditions:
- Stop / rollback signals:

### Route-outs
- API / contract:
- Auth / identity:
- Verification:
- Reporting / observability:

### Recommended next move
- draft migration plan | review with owners | hand off to API/auth/testing/reporting | defer until missing evidence is gathered

例

例1：SaaS のコアモデル

入力：「ユーザー、組織、メンバーシップ、サブスクリプション、請求書、監査ログを備えた B2B SaaS アプリのスキーマについて相談したいです。Postgres を使用しており、すぐに実装できるものが必要です。」

望ましい出力の方向性

• relational-first を選択します
• ユーザー、組織、メンバーシップ、サブスクリプション、不変の請求書レコードを明確に分けます
• 監査／履歴を、変更可能なエンティティの状態とは別に扱います
• セッション／プロバイダーの詳細は authentication-setup に引き継ぎます

例2：柔軟なメタデータの移行

入力：「当社のマーケットプレイスでは、商品メタデータを1つの JSON 列に保存していますが、検索、モデレーション、フィルターが安定したフィールドに依存するようになりました。安全な移行を計画してください。」

望ましい出力の方向性

• hybrid を選択します
• JSON から独立した列またはインデックス付きフィールドに昇格させる必要があるフィールドを特定します
• 段階的なロールアウト、バックフィル、クリーンアップの条件を提案します
• 検証は backend-testing に引き継ぎます

例3：ゲームのライブ運営における境界

入力：「レポートの要件が不透明なデータの塊に埋もれないように、ライブゲームのプレイヤーインベントリ、シーズンイベントの進行状況、テレメトリをモデル化する必要があります。」

望ましい出力の方向性

• プレイヤーが所有するトランザクション状態を、テレメトリ／レポートの関心事から分離します
• 1つのストレージパケットは、状態の整合性とライフサイクルに焦点を絞ります
• ダッシュボード／テレメトリの後続作業は looker-studio-bigquery または monitoring-observability に引き継ぎます

ベストプラクティス

1. テーブルの見た目ではなく、ビジネス上の不変条件とアクセスパターンから始めます。
2. 移行の安全性は、後回しにする運用上の作業ではなく、スキーマ設計の一部として扱います。
3. 柔軟なメタデータは適切な理由がある場合に有用ですが、クエリに不可欠なフィールドを隠すと危険になる点を踏まえて扱います。
4. 変更可能な状態、履歴／監査、派生／レポートデータを分離します。
5. これを汎用的な巨大バックエンドスキルにせず、関連する API／認証／テスト／レポート作業は他に引き継ぎます。
6. ベンダー固有の巨大なサンプル集よりも、長く使えるパケットを優先します。

参考資料

• PostgreSQL のデータ定義に関するドキュメント
• Prisma Data Guide — 接続の作成
• MongoDB のデータモデリングに関するドキュメント
• Firestore のデータ構造化ガイド