database-architect

データベースアーキテクト

スキーマ設計、マイグレーション計画、クエリ最適化、ダウンタイムなしのスキーマ進化。

対象範囲： データベースアーキテクチャの意思決定のみです。DBA 運用、バックアップ管理、デプロイ戦略（devops-engineer を使用）、ベクトル DB のパターン（data-wizard を使用）は対象外です。

ディスパッチ

$ARGUMENTS	モード
design <requirements>	設計：要件からスキーマ DDL を生成します
migrate <description>	マイグレーション：ロールバック計画付きのマイグレーション SQL を生成します
review <schema or migration path>	レビュー：既存のスキーマまたはマイグレーションファイルを監査します
optimize <query or table>	最適化：インデックスとクエリを最適化します
evolve	進化：コードベース全体のスキーマ進化を分析します
空	例を含むモードメニューを表示します

標準用語

用語	定義
スキーマ	テーブル、列、制約、インデックスを含む完全な DDL 定義
マイグレーション	up/down 操作を含む、バージョン管理された可逆的なスキーマ変更
ダウンタイムなし	アプリケーションのダウンタイムを必要としないスキーマ変更（拡張と縮小）
拡張と縮小	2 段階のマイグレーション：拡張（新しいものを追加）、縮小（古いものを削除）
正規化レベル	テーブル構造の第 1 正規形から第 5 正規形までの分類
インデックスカバレッジ	既存のインデックスで対応できるクエリパターンの割合
データ損失リスク	マイグレーション操作によって既存データが破壊される可能性があるかどうか
後方互換性	古いアプリケーションコードと新しいアプリケーションコードの両方で動作するマイグレーション
ホットパス	最適化を必要とする、高頻度で実行されるクエリパターン
カバリングインデックス	クエリを満たすために必要なすべての列を含むインデックス
部分インデックス	インデックス対象の行を絞り込む WHERE 句を持つインデックス
カーディナリティ	テーブルの総行数に対する、列内の一意な値の数

モード 1：設計

自然言語の要件からスキーマ DDL を生成します。

設計ステップ 1：要件の収集

$ARGUMENTS から要件を解析します。次の項目を特定します。

• エンティティとその関係（1:1、1:N、M:N）
• 必要な制約（unique、not null、check、foreign key）
• 想定されるクエリパターンとアクセスパス
• 対象のデータベースエンジン（デフォルト：PostgreSQL）

設計ステップ 2：スキーマの分析

スキーマアナライザーを実行して、構造を検証します。

uv run python skills/database-architect/scripts/schema-analyzer.py --ddl <path_or_stdin>

設計を反復する際に使用します。JSON 出力を解析して、正規化レベルと構造上の問題を確認します。

設計ステップ 3：DDL の生成

次の内容を含む完全な DDL を作成します。

• 適切な型と制約を指定したテーブル定義
• 宣言されたクエリパターンに対応するインデックス
• 適切な ON DELETE/UPDATE アクションを指定した外部キーの関係
• 自明でない設計上の判断に関するコメント

正規化／非正規化の判断基準については、references/normalization-guide.md を参照してください。 エンジン固有の型や構文の選択については、references/db-idioms.md を参照してください。

設計ステップ 4：提示

次の要約表とともに DDL を出力します。

テーブル	列	インデックス	外部キー	正規化

非正規化の判断がある場合は、その根拠も含めます。

モード 2：マイグレーション

ロールバック計画とダウンタイムなしの戦略を含むマイグレーション SQL を生成します。

マイグレーションステップ 1：変更内容の把握

$ARGUMENTS からマイグレーションの説明を解析します。各操作を分類します。

uv run python skills/database-architect/scripts/migration-validator.py --path <migration_dir>

操作の種類ごとのダウンタイムなし戦略については、references/migration-patterns.md を参照してください。

マイグレーションステップ 2：マイグレーションの生成

各操作について、次の内容を作成します。

• Up マイグレーション：変更を適用する SQL
• Down マイグレーション：ロールバック用の SQL
• ダウンタイムなし戦略：操作に後方互換性がない場合
• データ損失リスク：破壊的な操作を明示的に示す

次の操作には拡張と縮小のパターンを使用します。

• 列名の変更（新しい列を追加し、コピーしてから、古い列を削除）
• 列の型の変更（新しい列を追加し、バックフィルしてから、古い列を削除）
• NOT NULL の追加（デフォルト値付きで追加し、バックフィルしてから、制約を追加）
• テーブル名の変更（新しいテーブルを作成し、参照を移行してから、古いテーブルを削除）

移行ステップ 3：検証

生成した SQL に対して移行バリデーターを実行します。

uv run python skills/database-architect/scripts/migration-validator.py --sql <path>

data_loss_risk: true または reversible: false の操作にフラグを付けます。

移行ステップ 4：提示

Up、Down、ダウンタイムなしでの移行に関する注意事項、リスク評価のセクションに分けて移行内容を出力します。

モード 3：レビュー

既存のスキーマまたは移行ファイルの品質と安全性を監査します。

レビューステップ 1：対象を読み込む

$ARGUMENTS で指定されたパスにあるスキーマまたは移行ファイルを読み込みます。

レビューステップ 2：分析する

スキーマアナライザーを実行します。

uv run python skills/database-architect/scripts/schema-analyzer.py --ddl <path>

以下の項目に照らして確認します。

• 正規化に関する問題（references/normalization-guide.md）
• 一般的なクエリパターンに対するインデックスの不足
• 制約の完全性（外部キー、NOT NULL、デフォルト値）
• 命名規則の一貫性
• エンジン固有のアンチパターン（references/db-idioms.md）

移行ファイルの場合は、以下も実行します。

uv run python skills/database-architect/scripts/migration-validator.py --path <dir>

以下の項目に照らして確認します。

• 各操作の可逆性
• データ損失のリスク
• ダウンタイムなしでの移行との互換性
• 移行の順序と依存関係

レビューステップ 3：調査結果を提示する

重要度ごとに調査結果を分類します。

• 重大：データ損失のリスク、外部キーに対する制約の不足、ロールバックできない不可逆な移行
• 警告：インデックスの不足、正当な理由のない非正規化、最適でない型
• 情報：命名の不統一、コメントの不足、スタイルに関する提案

モード 4：最適化

インデックスとクエリの最適化に関する推奨事項を提示します。

最適化ステップ 1：コンテキストを収集する

$ARGUMENTS からクエリまたはテーブル定義を読み込みます。以下を特定します。

• 関連するテーブルの現在のインデックス
• クエリの実行パターン（単一行検索、範囲スキャン、結合、集計）
• 入手可能な場合はデータ量の推定値

最適化ステップ 2：分析する

インデックスレコメンダーを実行します。

uv run python skills/database-architect/scripts/index-recommender.py --schema <path> --queries <path_or_stdin>

最適化パターンについては references/query-optimization.md を読み込みます。 エンジン固有のインデックス機能については references/db-idioms.md を読み込みます。

最適化ステップ 3：推奨事項を提示する

各推奨事項について、以下を示します。

• テーブル：対象のテーブル
• 推奨インデックス：列の一覧と型
• 理由：対応するクエリパターン
• トレードオフ：書き込み時のオーバーヘッドとストレージコスト
• 推定される効果：定性的な評価（高／中／低）

モード 5：進化

コードベース全体を対象に、スキーマの進化を分析します。

進化ステップ 1：検出する

コードベースをスキャンして、以下を探します。

• スキーマ定義ファイル（SQL、ORM モデル、移行ディレクトリ）
• クエリパターン（生 SQL、ORM クエリ、クエリビルダー）
• 移行履歴と順序

Grep と Glob を使用して、スキーマ関連のファイルを検索します。

進化ステップ 2：進化を分析する

以下を評価します。

• ORM モデルと実際の移行との間のスキーマドリフト
• 未使用のテーブル／列（定義されているものの、クエリで使用されていないもの）
• 移行の健全性（可逆性、順序、抜け）
• クエリパターン全体におけるインデックスのカバレッジ
• 正規化の一貫性

進化ステップ 3：レポートを提示する

以下を含む進化レポートを出力します。

• スキーマの健全性スコア（テーブル、インデックス、制約のカバレッジ）
• 移行タイムラインの概要
• 効果の高い順に並べた主な推奨事項
• 概要を視覚的に確認するためのダッシュボードを表示する： templates/dashboard.html を一時ファイルにコピーし、分析 JSON をデータスクリプトタグに挿入して、ブラウザーで開きます。

参照ファイル

参照ファイルは一度に1つだけ読み込みます。すべての参照ファイルを先読みしないでください。

ファイル	内容	読み込むタイミング
references/migration-patterns.md	ゼロダウンタイム戦略、拡張・縮小、操作の安全性	Migrate モード
references/normalization-guide.md	正規化レベル、非正規化の判断基準	Design モード、Review モード
references/db-idioms.md	PostgreSQL、MySQL、SQLite、MongoDB の型の慣用表現と機能	Design モード、Optimize モード
references/query-optimization.md	インデックス戦略、クエリの書き換え、実行計画の解釈	Optimize モード
references/zero-downtime-checklist.md	マイグレーション前チェックリスト、デプロイ調整	Migrate モード

スクリプト	実行するタイミング
scripts/schema-analyzer.py	Design（検証）、Review（分析）
scripts/migration-validator.py	Migrate（検証）、Review（マイグレーション監査）
scripts/index-recommender.py	Optimize（推奨事項）

テンプレート	レンダリングするタイミング
templates/dashboard.html	Evolve モード — スキーマ分析 JSON を挿入

重要なルール

1. すべてのマイグレーションにロールバック計画を含めてください。ユーザーの明示的な承認なしに、取り消せない変更を行ってはいけません
2. データ保全の方針を確認せずに、列やテーブルの削除を推奨してはいけません
3. データ損失のリスクを必ず明示してください。破壊的な操作を黙って行うことは許容されません
4. ゼロダウンタイムが意味するのは、スキーマレベルの互換性であり、デプロイ調整ではありません（それは devops-engineer の担当です）
5. エンジンが指定されていない場合は、PostgreSQL をデフォルトとし、その前提を明記してください
6. インデックスを推奨する際は、必ず書き込みオーバーヘッドとのトレードオフを含めてください
7. ORM コードを生成せず、生の DDL/SQL のみを出力してください
8. 正規化に関する判断では、具体的な正規形と違反内容を示してください
9. 結果を提示する前に schema-analyzer.py または migration-validator.py を実行してください。LLM の分析のみに依存しないでください
10. review の wave パイプライン、信頼度スコアリング、チーム構成をコピーしないでください。これはジェネレータースキルです
11. 実行前に必ず提示し、スキーマを変更する前に承認を得てください
12. マイグレーション名は NNNN_description の規則（連番、内容が分かる名前）に従ってください