大規模システムの複雑なDBスキーマをAIに「正しく」理解させるための実践的アプローチ

はじめに：なぜAIは複雑なスキーマを処理しきれないのか

現代の大規模システム開発において、生成AI（LLM）の活用は不可欠になりつつあります。しかし、コード生成やリファクタリングの相談においては優秀なAIも、**「既存の大規模データベースのスキーマを正しく考慮した機能追加」**というタスクになった途端、うまく機能しないことがあります。 具体的な失敗例は以下のようなものです。

• カラム名の推測ミス: 例えば実在しない user_name というカラムを使ってSQLを書く（正しくは name や full_name だった、など）。

• 存在しないリレーションの捏造: 結合キーが存在しないテーブル同士を無理やり JOIN しようとする。

• ビジネスロジックの無視: deleted_at に日付が入っているレコードは除外すべきなのに、全件取得してしまう。

これらの原因として多いのが、「情報過多」もしくは「暗黙知の欠如」といった要因です。 テーブル数が数百〜数千に及ぶ大規模システムでは、AIに渡す必要があるDBに関する情報を過不足なく抽出するのが難しいです。 例えば、すべてのDDL（Create文）などをプロンプトに含めることは、コンテキストウィンドウ（トークン数）の無駄遣いであるだけでなく、AIにとっての「ノイズ」となり、推論精度を著しく低下させます。 逆に、現場の人間のエンジニアが暗黙のうちに共有している知識がAIに渡すプロンプトから欠落していることもあります（テーブルの運用方法が変わったのに、テーブルに付与されたコメントが追従できていない、など）。 こういった問題を踏まえつつ、本レポートではAIがシステム構造を正確に把握しでDB操作を行うための「情報の渡し方」と、それを支援する「最新ツールの活用法」を解説します。

1. 基礎編：AIフレンドリーなメタデータの整備

AIは、SQLコード（Syntax）よりも、そこに込められた「自然言語の意味（Semantics）」を重視して解釈します。まずは、既存のDB定義自体をAIが読みやすい状態に整備することが第一歩です。

1.1 詳細なコメント付与 (COMMENT ON) の徹底

多くの現場では物理名（usr_sts など）だけで運用され、その意味はドキュメントやWikiに散らばっています。これではAIは理解できません。 PostgreSQLやMySQLなどが持つコメント機能を活用し、DDL自体にドキュメントを含めることが効果的です。

具体例

• 物理名だけでなく意味を汲み取りやすい論理名を記載: COMMENT ON COLUMN users.status IS '会員ステータス';

• マジックナンバーの排除: 0=仮登録, 1=本登録, 9=退会済み といった区分値の意味をコメントに明記します。これにより、AIは WHERE status = 1 という条件を自律的に導き出せるようになります。

1.2 外部キー制約の明示

レガシーシステムや一部のパフォーマンス重視の設計では、DBレベルでの外部キー（Foreign Key）制約を貼らず、アプリケーションコード側で整合性を担保しているケースがあります。 しかし、AIにとって外部キー定義はシステム全体の構造を把握するための重要な手がかりです。 もし本番DBに制約を追加できない場合でも、AIに読み込ませるための「参照用スキーマ定義」には外部キー制約を追記するか、Mermaid記法などでリレーションを明示的に与える必要があります。 類似のケースとしては、DBのデータの型をDB側で制約せずに、アプリケーション側で制約しているケースもあります。 確かに、実務上こういった方法が役立つ場面はしばしばありますが、AIにDBスキーマを理解させる上では問題を引き起こす可能性があります。 なので、特に事情がなければDBレベルでの外部キー制約をはることを検討してみましょう。

2. 戦略編：コンテキストウィンドウを圧迫しない情報提供

AIが処理できるコンテキストウィンドウは飛躍的に長くなっています。 例えばGeminiシリーズなどでは100万単位のトークンを処理できます。 とはいえ、可能な限り必要な情報のみをコンテキストとしてAIに渡したほうが精度が向上するのは今も昔も変わりません。 数千テーブルの定義を一度に渡すのは非効率です。必要な情報を、必要な分だけ、AIが理解しやすい形式で渡す戦略が求められます。

2.1 モジュール化（サブセット化）

システム全体を「ドメイン境界（Bounded Context）」で分割します。 例えば、「注文機能」の実装を行う際、「人事管理」や「在庫詳細」のテーブル定義はノイズでしかありません。 実際の運用の場面では、schema/order.sql, schema/user.sql のようにスキーマのSQLをファイル単位で分割しておくことを心がけるとよいでしょう。 こうしておけば、タスクに関連するファイルのみをAIのコンテキストにロードさせやすくなります。

2.2 構造化フォーマットの活用

「生のDDL（SQL）」は意外と冗長です。AIに構造を伝えるだけであれば、よりトークン効率の良いフォーマットへの変換が有効です。

• Mermaid.js (ER図): テーブル間の関係性を視覚的かつテキストベースで表現できるため、複雑な結合関係を理解させるのに適しています。

• TypeScript型定義 / Prisma Schema: SQLよりも簡潔で、型情報やリレーションが明記されているため、LLM（特に学習データにコードが多いモデル）にとって非常に理解しやすい形式です。

2.3 RAG（検索拡張生成）の適用

さらに規模が大きい場合、全スキーマ定義をVector Store（ベクトルデータベース）などに格納し、RAGを活用します。 ユーザーが「先月の売上を集計したい」と質問すると、AIはまずVector Storeから「売上」「注文」「商品」に関連しそうなテーブル定義だけを検索・取得し、その情報を元に回答を生成します。

3. ツール編：MCP (Model Context Protocol) と最新ツールの活用

これまでは「人間がテキストをコピペしてAIに渡す」もしくは、「Cursorなどのコーディングエージェントがスキーマが記載されたファイルを読みに行く」ケースを想定して解説してきましたが、現在は**「AIが自らDBに接続し、必要な情報を調べに行く」**時代へとシフトしています。

3.1 MCP (Model Context Protocol) とは

Anthropic社などが提唱するMCPは、AIモデルと外部データ（DB、ファイルシステム、APIなど）を接続するための標準規格です。 これを利用すると、Claude DesktopやCursorなどのAIクライアントが、あたかもローカルツールのようにデータベースサーバーと対話できるようになります。

3.2 mcp-postgres-server による動的探索

MCPの実装例である mcp-postgres-server を導入し、読み取り専用（Read-Only）ユーザーでDBに接続させます。 これにより、AIは以下のような探索フローを自律的に行います。

1. AI: 「どんなテーブルがあるか知りたい」

2. Tool: SELECT table_name FROM information_schema.tables... を実行。

3. AI: 「orders テーブルの構造と、関連する order_items の構造が知りたい」

4. Tool: 指定されたテーブルのDDLを取得して提示。

人間が事前に資料を用意しなくても、AIが必要な時に必要な情報を「自分で見に行く」ことができるため、ハルシネーションのリスクが下がります。

3.3 ドキュメント生成ツールとの連携 (tbls / SchemaSpy)

静的な情報を渡す場合でも、ツール生成ドキュメントが役立ちます。

• tbls (CI-Friendly Tool for DB Documentation):

日本発のオープンソースツールである tbls は、DBスキーマから非常に整形されたMarkdownなどのドキュメントを自動生成します。 MarkdownはAIにとって最も読みやすい形式の一つです。Gitリポジトリで tbls で生成した README.md や schema.md を管理し、それをそのままAIに読ませるだけで、DDLを読むよりも高い精度で構造を理解します。

• SchemaSpy:

HTMLベースのレポートを出力しますが、リレーションの可視化に優れており、例えば画像認識可能なマルチモーダルAIに全体像（ER図）を見せることも可能です。

4. 応用編：マルチDB・マイクロサービス環境での対処

大規模開発の現場では、DBのアーキテクチャもより複雑化することがあります。 例えば本格的なエンプラシステムや、負荷が高いサービスを開発している現場では、データが複数のDBに分散していることが一般的です（例：メインはPostgreSQL、ログはDynamoDB、検索はElasticsearchなど）。

4.1 サービス間マッピングの定義（クロスマッピングドキュメント）

異なるDB間では、外部キー制約が存在しません。そのため、**「論理的な結合キー」**をAIに教える必要があります。

• プロンプト例: 「User ServiceのDBにある id カラムは、Order ServiceのDBにある customer_uuid カラムと同一の意味を持ちます」といったマッピングルールをまとめたドキュメント（Markdownなどの形式）を作成し、常に参照させます。

4.2 クエリプランの検証とアプリ層結合

AIは放っておくと、異なる物理サーバーにあるテーブル同士をSQLで JOIN しようとします。 「これらは別々のDBインスタンスである」という前提条件を与え、「SQLでの結合は不可能なので、アプリケーションコード（Python/TypeScriptなど）でIDリストを使ってデータをフェッチし、メモリ上で結合するロジックを書いてください」と指示するプロンプトエンジニアリングが必要です。

5. 実践フロー：AIによる理解度チェックとDry Run

AIに対して、いきなり「この機能の実装コードを書いて」と依頼するのは危険です。以下のステップを挟むことで、手戻りを防ぎます。

5.1 「逆説明」の要求 (Reverse Engineering Prompt)

スキーマ情報を渡した後、次のように問いかけます。

「渡されたDB構造に基づき、注文が完了するまでのデータの流れと、各テーブルの役割をあなたの言葉で説明してください」
AIの認識が間違っていれば、この段階で「`order_status` の更新ロジックが違います」と指摘し、認識のズレ（コンテキストの欠落）を補正します。

5.2 Read-Onlyな探索クエリ (Dry Run)

実装に入る前に、AIに実際のデータを「味見」させます。 MCPなどを通じて、SELECT * FROM target_table LIMIT 5 を実行させます。

• カラム定義は NOT NULL だが、実際には空文字が入っていないか？

• 日付のフォーマットは YYYY-MM-DD か、UNIXタイムスタンプか？

• JSON型カラムの中身はどのような構造か？

実際のデータ値を見ることで、AIの理解度は「机上の空論」から「実務レベル」へと昇華します。

おわりに

適切なコンテキスト管理、メタデータの整備、そしてMCPのような動的な接続プロトコルを組み合わせることで、AIは複雑怪奇なレガシーシステムのスキーマであっても、高速に理解し、正確なクエリを書くことができます。 これからの開発者は、SQLをゼロから書く能力以上に、「AIにDB構造を正しく説明する能力（メタデータ管理能力）」や、「AIが探索しやすい環境（MCPやドキュメントツール）を整えるアーキテクト能力」が問われることになる可能性があります。 AIを単なるコードジェネレーターではなく、システム構造を共に把握する「データベース管理者のパートナー」として迎え入れる為に日々試行錯誤していくことが重要です。