database-documentation

database-documentation

データベースを、ドキュメントが推測ではなく、証明可能な形でスキーマそのものとなるほど、完全かつ正確に文書化します。半端に正しいスキーマドキュメントは、ないよりも悪いものです。人々がそれを信頼し、壊れたコードを書いてしまうからです。

唯一の原則：根拠に基づき、かつ検証済みであること

出力するすべての記述は、次の条件を満たす必要があります。

• 根拠に基づいている — 具体的な情報源までたどれること。稼働中のデータベース（システムカタログのイントロスペクション）を優先します。ORM モデル、マイグレーション、生成された型、シードデータはデータベースについての 主張 であり、データベースそのものではありません。実際に動作しているものはカタログです。
• 検証済みである — 稼働中のデータベースを再度イントロスペクションし、生成したドキュメントとの差分がなくなるまで、または残りの差分すべてに明示的な理由が付くまで、差分を確認すること。「ドキュメントが完成した」と書いてはいけません。代わりに差分をなくし、それを示してください。

最先端のモデルに任せると、ORM を読んで、自信たっぷりの文章を書き、不完全で一部が幻覚によるスキーマを出荷してしまいます（CHECK 制約の列挙値の見落とし、誤った ON DELETE、レガシーテーブルの省略、存在しないカラムの捏造など）。このスキルは、まさにそれを防ぐためにあります。次の 2 つの仕組みで実現します。（1）実際の DB を正解として扱い、（2）判断を単一のエージェントに委ねず、独立した対抗者が各作業で見落とされた点を探します。

対象範囲（v1）：リレーショナル／SQL のみ

PostgreSQL、MySQL、SQL Server、SQLite が対象です。ドキュメントストア（MongoDB）またはグラフデータベースを検出した場合は、そのストアが対象外であることを伝えて作業を止めてください。そのストアのリレーショナルドキュメントを出力してはいけません（誤ったドキュメントを黙って作ることが最悪の結果です）。推測せず、対象外として記録してください。

ワークフロー

以下のフェーズを順に実行してください。それぞれに終了時の成果物があります。中間抽出物や作業用 CSM などの一時ファイルはすべて、単一の .database-documentation/ スクラッチディレクトリまたはプラットフォームのスクラッチパッドに保管してください。永続的な成果物はドキュメントと schema.json のみです。

Phase 0 — 検出（読み取り専用）

1. フィンガープリントを取得します。エンジンとバージョン、ORM を調べます。schema.prisma、*.entity.ts とデータソース、drizzle.config.*、knexfile.* と migrations/、Django の models.py、Rails の schema.rb、生の SQL DDL を探します。データソース／プロバイダー、docker-compose.yml のイメージタグ、.env* 内の接続 URL から、エンジンとバージョンを特定します。
2. 稼働中 DB への接続経路を特定します。次の順に試し、最初に成功した時点で終了します。接続済みの DB MCP サーバー → DB コンテナ内での docker compose exec / docker exec（認証情報は compose の環境変数から読み取ります） → ホストとポートを .env から取得して接続する ローカル DB CLI（psql／mysql／sqlcmd／sqlite3）。続行する前に、簡単なクエリを 1 つ（SELECT 1、テーブル一覧の取得など）実行して、接続を証明してください。DB が停止中でも compose ファイルで定義されている場合は、起動を提案してください。認証情報を出力してはいけません。.env／compose から読み取ったパスワード／DSN はシークレットとして扱い、実行するコマンド内だけに保持してください。表示またはドキュメントに記載する際は、password=*** のように伏せ字にしてください。
3. その他すべての情報源を一覧化します。マイグレーションディレクトリ（とその件数）、生成クライアント／*.d.ts、シードデータ／フィクスチャを調べ、アプリケーション内で生 SQL／クエリビルダーの呼び出しを grep します。既存の docs/db/ があるか確認してください。存在する場合は更新作業となるため、差分の有無を調べて、プロジェクトの既存スタイルに合わせるために読み込みます。
4. 到達したティアを報告します（Degradation ladder を参照）。これにより、読者が確度を把握できます。

終了時の成果物：簡潔な検出メモ。エンジン、ORM、到達性ティア、検証済みの正確な稼働中 DB コマンド、各情報源のパスを記載します。

フェーズ 1 — すべての情報源を抽出する（可能な場合は並行して実施）

各情報源を個別に、Canonical Schema Model の形式に抽出します （references/csm-contract.md を参照）。サブエージェントを利用できるプラットフォームでは、情報源ごとに抽出担当を割り当てて並行実行し、 互いの出力を見せないでください。独立した一致は確かな証拠ですが、共有コンテキストは集団思考につながります。

オブジェクトクラスのチェックリスト — すべてのクラスを抽出してください。1 つでも省略することが、最もよくある失敗です。 このリストをコピーし、 各項目が実数とともに schema.json に含まれていることを確認してください。

• テーブル · [ ] カラム（型＋NULL 許容＋デフォルト＋コメント） · [ ] 主キー · [ ] 外部キー（＋ON DELETE/UPDATE）
• 一意制約 · [ ] CHECK 制約 · [ ] インデックス（＋部分インデックス／式インデックス） · [ ] 列挙型（＋値）
• シーケンス · [ ] トリガー · [ ] ビュー（＋定義） · [ ] ルーチン（関数／プロシージャ）

シーケンス、トリガー、ルーチンはカラムではないため、見落とされがちです。明示的に抽出してください。 ビュー／トリガー／ルーチンの本体は全文をそのまま取得してください。省略、要約、... による省略はしないでください。 定義が途中で切れているドキュメントは不完全（誤り）です。 schema.json.enums は DB ネイティブの列挙型のみを指します。 CHECK (col IN (...)) を持つ文字列カラムは、そのテーブルの check_constraints に含めます（enums には含めません）。アプリケーションレベルのみの値セットは、カラムの説明に 「app-enforced」と記します。ネイティブではない列挙型を enums に記載すると、実際のスキーマに反する捏造になります。

• ライブ環境のイントロスペクション（信頼できる情報源）。 カタログ全体を読み取ります。正確な Postgres クエリについては references/introspection-postgres.md を参照してください （MySQL／MSSQL／SQLite の同等クエリもあります）。テーブル、カラム （長さ／精度を含む型、NULL 許容、デフォルト、ID、生成列、照合順序、コメント）、主キー、外部キー（ON DELETE／ON UPDATE を含む）、一意制約と CHECK 制約、インデックス（部分インデックスの述語と式カラムを含む）、列挙型、ドメイン、シーケンス、ビュー／マテリアライズドビュー、トリガー、ルーチンを網羅しています。ベンチマーク／オラクルのスクリプトをシェルから実行してはいけません。イントロスペクションを自分で作成し、実行してください。
• ORM モデル → CSM（意図と説明。ORM ごとの注意事項は references/ を参照）。
• マイグレーション → タイムスタンプ順に統合して、最終状態を再構築します（200 個のファイルを目視で確認しないでください）。
• 生成された型／シード／アプリケーションのクエリ → 照合に使用します。アプリケーションのクエリをスキャンすると、ORM には存在しない、使用中のテーブル／カラム（レガシーテーブル）を検出できます。

終了条件：情報源ごとに部分的な CSM を 1 つ作成します。

フェーズ 2 — 1 つの CSM に統合する（優先順位とドリフト）

マスター CSM に統合し、物理 DB 名をキーとしてテーブルを識別します。優先順位は次のとおりです。

1. ライブ DB が存在する場合は、常にライブ DB が優先です。 これと異なる情報源があれば、ドリフトの検出結果として記録します（issues/ に記録）。 ドキュメントを黙って編集してはいけません。ドキュメントにはライブデータベースを記載します。
2. ライブ DB がない場合 → マイグレーション ⊕ ORM の合意（構造はマイグレーションを優先し、意図は ORM を優先）。矛盾があればフラグを立てます。

各オブジェクトの confidence に、verified（ライブ環境で確認済み）／consensus／single-source／conflict のいずれかを設定します。 ライブ DB がある場合は、2 つの方法（例：information_schema と pg_catalog）で相互照合します。他の情報源を覆す前に、オラクル自身が一致している必要があります。

終了条件：マスター CSM と discrepancies リストを作成します。

フェーズ 3 — ドキュメントと schema.json の生成

すべての出力を専用のドキュメントディレクトリ 1 か所にまとめてください。リポジトリ内のあちこちにファイルを散在させてはいけません。既定では docs/db/ を使用します。フェーズ 0 で既存の DB ドキュメント用ディレクトリ（例：docs/db/、docs/database/、 docs/schema/、またはリポジトリですでに使用されているディレクトリ）が見つかった場合は、プロジェクトの既存スタイルに合わせてそちらに出力します。存在しない場合は ディレクトリを作成します。CSM（それ自体の純粋関数）を references/output-template.md のテンプレートに合わせて、スキーマ の規模に応じてそのディレクトリ内に生成します。

• テーブルが約 15 個以下 → docs/db/DATABASE.md 1 つ（統計ヘッダー、mermaid ERD 1 つ、テーブルごとのセクション、Issues セクション）。
• それ以上 → docs/db/ 配下に、README.md（目次 + 統計）+ ONBOARDING.md + ドメインごとの diagrams/<domain>.md（すべてのカラムと型を含む mermaid erDiagram + リレーションシップの線、その後にテーブルごとのセクション）+ diagrams/full-erd.md（レンダリング可能な状態を保てるよう、テーブルレベルのみ）+ tables/entity-reference.md + issues/README.md。

同じディレクトリ（docs/db/schema.json）に schema.json を出力します。

テーブルごとのセクションには、根拠に基づく説明を 1～2 文、Column | Type | Nullable | Default | Description の表、その後に Indexes: と Foreign Keys:（ON DELETE を含む）を記載します。ドメインは ORM モジュール／フォルダー → 名前のプレフィックス → FK のクラスタリングの順に分類し、Legacy/Misc をその他の受け皿にします。schema.json は references/csm-contract.md にある形式に従います。

フェーズ 4 — パリティの証明（検証済みの部分）

これは任意ではなく、雰囲気で済ませるものでもありません。「完全に見える」という主張に価値はありません。特に能力の低いモデルは、実現できていないパリティを達成したと主張することがあります。その主張を鵜呑みにせず、数値を確認してください。

1. 件数ゲート（早期検出）。 すべてのオブジェクトクラスについて、ライブ DB 内の件数を数え、schema.json の件数と比較します。件数クエリでは、抽出と CSM が定義するものとまったく同じ母集団を選択する必要があります。そうしないと、正しいドキュメントがゲートに失敗し、幻覚で「修正」することになります。実際のすべてのデータベースで問題になるルールは 2 つあります。インデックスは PK／一意制約を裏付けるものを除外し、ルーチン／オブジェクトは拡張機能に所有されるものを除外します（pg_depend.deptype='e'）。references/introspection-postgres.md の母集団に合わせた件数クエリ（「Count-gate queries」）を使用してください。単純な count(*) は使用せず、情報が失われるビューも決して使用しないでください（例：information_schema.check_constraints には NOT NULL 行が混入しており、reltuples は -1 の場合があります）。 class | live | documented | match? の表を出力します。不一致があれば調査してください。実際の漏れである可能性も、件数クエリが誤った母集団を選択している可能性もあります。件数の一致は必要条件ですが、十分条件ではありません（件数が同じでも、型の入れ替わりや誤った ON DELETE が隠れていることがあります）。
2. ID 差分（実際の証明）。 もう一度新たにイントロスペクションし、件数だけでなく、すべてのクラスについて識別子と属性を差分比較します。対象は、テーブル、カラム（名前／型／NULL 許容／デフォルト値）、PK、FK（+on_delete）、一意制約、チェック制約、インデックス（+部分／式インデックス）、列挙型（+値）、ビュー、トリガー、ルーチン、シーケンスです。
3. すべての差異について、ドキュメントを修正するか、理由を説明します（例：「ライブ DB にのみ存在するオブジェクトを Drift に記載」）。
4. 件数表が一致し、ID 差分が空になるか、すべての差異に理由が付くまで繰り返します。
5. README.md または issues/ にパリティレポートを記載します。クラスごとの件数表と、明示的な「文書化されていないもの 0 件、創作されたもの 0 件」を含めます。「検証済み」と記載できるのは、ID 差分（手順 2）が空の場合のみです。件数が一致しただけでは不十分です。ライブ DB がない場合は、コンセンサス CSM に対して差分を実行し、すべての出力ファイルに「コンセンサスとのパリティ（ライブ DB との照合は未検証）」と記載します。

フェーズ 5 — 敵対的レビュー（3 人以上、決して 1 人では行わない）

判定を行うエージェント自体が、ドキュメントを作成したエージェントと同じ盲点を持つ最先端モデルであるため、レビューが 1 回だけでは形だけの承認になってしまいます。3 人以上の、コンテキストを隔離した敵対的レビュアーを招集し、それぞれ別のセッションで、必ず欠点を見つけるよう指示し、異なる観点を割り当てます。

• 漏れの調査担当 — 実際のテーブルをサンプリングします。すべてのテーブルが、全カラムを含めて記載されていますか？ 旧式のテーブル、すべての enum／CHECK、すべてのインデックスと FK がドキュメント化されていますか？
• 幻覚の調査担当 — ドキュメントに記載されたすべてのオブジェクト／型／デフォルト値／ON DELETE／説明は、実在するソースにたどり着けますか？ 作り出された記述があれば指摘します。
• 正確性の調査担当 — 型、NULL 許容性、FK のカーディナリティは、実際の DB と正確に一致していますか？

各担当の結果を統合し、次の生成パスに反映します。判断が必要な箇所は、すべてパネルで決定します。

劣化段階（自分の段階を明示する）

段階	利用可能なもの	信頼度
T1	実際の DB ＋ 並列サブエージェント ＋ 敵対的レビュアー	検証済み、証明可能
T2	実際の DB、単一エージェント	検証済み、逐次処理
T3	実際の DB なし、サブエージェント	合意済み、未検証
T4	実際の DB なし、単一エージェント	合意済み、未検証
T5	静的な情報源が 1 つだけ	低 — 目立つ「未検証 — 実際の DB なし」バナーを表示

サブエージェント、MCP、docker は最適化のためのものであり、必須ではありません。同じフェーズを、それらを使わずにインラインで実行できます。 読み取れなかったデータを決して捏造しないでください。欠落している情報にはフラグを立て、推測で補わないでください。

参考資料

• references/csm-contract.md — schema.json の形式（検証可能な出力契約）。
• references/introspection-postgres.md — エンジンごとの正確なカタログクエリ。
• references/output-template.md — 再現する人間向けドキュメントの形式。
• references/hard-cases.md — enum（ネイティブ／CHECK／アプリ）、JSON カラム、ポリモーフィックなリレーション、ソフトデリート、複合キー、部分／式インデックス、ビュー、複数スキーマ、citext／照合順序、旧式のテーブル。