【Supabase公式】AIエージェントのためのPostgresベストプラクティス：自動コーディング時代のDB設計

お疲れ様です！IT業界で働くアライグマです！

「AIにコードを書かせたら、JOINの結合条件がめちゃくちゃで動かない…」
「Cursorにスキーマを読み込ませたはずなのに、意図しないテーブルを参照される…」

AIコーディングエージェントを活用する際、このような経験はありませんか？
結論から言います。AIエージェントにDB操作を任せるなら、まず人間が「正解」となる厳密なデータベース設計を行い、それをコメントとして明示する必要があります。

あいまいな設計は、AIのハルシネーション（幻覚）を引き起こす最大の原因です。この記事では、Supabase公式が提唱する「AIエージェントのためのPostgresベストプラクティス」をベースに、Claude CodeやCursorが迷わず正確なSQLを生成できるDB設計の極意を解説します。

なぜAIエージェントに「Postgresベストプラクティス」が必要なのか

AIエージェントは優秀なプログラマですが、熟練のDBA（データベース管理者）ではありません。
彼らはテーブル名やカラム名といった「記号」の類似性から推論を行いますが、そこにある「ビジネスロジック」や「データの整合性ルール」までは、コード上で明示されない限り理解できません。

実際のプロジェクトでも、この認識ギャップが原因でAIが暴走するケースを何度も見てきました。現場でAIを使いこなすには、まずこの「暗黙知」をなくすことが重要です。

「暗黙の了解」はAIには通じない

人間同士なら「user_idと言えばusersテーブルの主キーを参照しているはず」と察せますが、AIにとってそれは単なる文字列です。外部キー制約（Foreign Key）が物理的に貼られていなければ、AIは平気で存在しないIDを挿入しようとしたり、誤ったテーブルと結合したりします。

参考：仕様駆動開発入門：AIエージェントで設計8割・開発2割を実現するシステム開発手法の実践ガイドでも、AIに対する「指示の明確化」の重要性を解説しています。

IT女子 アラ美

なんとなく動くスキーマで作っていたけど、それがAIの精度を下げていたんですね。

ITアライグマ

そうです。AIにとって「制約」や「コメント」は、コードを書くための唯一の手がかり（コンテキスト）なのです。

Supabase公式が提唱する「エージェントフレンドリー」なDB設計

では、具体的にどのような設計がAIにとって「フレンドリー」なのでしょうか。Supabaseの公式ブログで解説されているポイントを要約すると、以下の3点に集約されます。

すべてのふさわしい場所に主キーと外部キーを貼る

主キー（Primary Key）は各行を一意に識別するために必須であり、外部キー（Foreign Key）はテーブル間の関係性を定義します。これを省略すると、AIはテーブル同士の結合方法（JOIN ON …）を正しく推論できません。

カラムとテーブルに詳細なコメント（description）を付ける

Postgresの COMMENT ON 機能を使って、各カラムが何を意味するのか、どのようなデータが入るべきかを自然言語で記述します。AIはこのコメントを読み取り、変数の命名やUIのラベル生成に活用します。

一貫した命名規則を採用する

snake_case で統一し、リレーションシップには 単数形_id （例: customers テーブルへの参照は customer_id）を用いることで、AIのパターン認識精度が向上します。

上のグラフは、スキーマ定義の厳密さがAIのコード生成精度に与える影響を表したものです。制約とコメントを付与するだけで、精度は劇的に向上します。

参考：Cursor + ローカルLLM完全ガイド：仕事で使える最強のAI開発環境構築も、AI開発環境の構築において参考になります。

IT女子 アラ美

コメントを書くのは面倒ですが、それでAIのミスが減るなら費用対効果は高そうですね。

ITアライグマ

その通りです！一度しっかり定義してしまえば、あとはAIが自律的に正しいクエリを量産してくれますからね。

【ケーススタディ】AI任せのスキーマ設計で崩壊したチャットアプリの末路

実際に、スキーマ設計の質がプロジェクトの成否を分けた事例を紹介します。

参考：nanocodeで学ぶAIコーディングエージェントの仕組みを読むと、エージェントが内部でどう動いているかの理解が深まります。

IT女子 アラ美

「急がば回れ」とはこのことですね。最初に楽をすると後ですごいコストがかかる…。

ITアライグマ

はい。AI時代の開発において、人間が担うべき最も重要な責務は「正確な仕様（スキーマ）の定義」にシフトしているんですよ。

実践！Cursor/Claude Codeに読ませるための.sqlファイル構成

AIエージェントにコンテキストとして渡すための、理想的なSQL定義ファイルの構成例を紹介します。これをプロジェクトのルートに schema.sql として置いておくと、AIが見事に理解してくれます。

-- テーブル定義：ユーザー
CREATE TABLE public.users (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  email text NOT NULL UNIQUE,
  created_at timestamptz DEFAULT now()
);

-- コメント定義（重要！）
COMMENT ON TABLE public.users IS 'アプリケーションのユーザー情報を管理するテーブル';
COMMENT ON COLUMN public.users.email IS 'ユーザーのログイン用メールアドレス。重複不可';

-- テーブル定義：メッセージ
CREATE TABLE public.messages (
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  user_id uuid NOT NULL REFERENCES public.users(id) ON DELETE CASCADE,
  content text NOT NULL CHECK (length(content) > 0),
  created_at timestamptz DEFAULT now()
);

-- 外部キー制約とコメントによって、AIは user_id が users テーブルと紐付いていることを理解する
COMMENT ON TABLE public.messages IS 'チャットルーム内のメッセージ履歴';

このように、REFERENCES で関係性を明示し、COMMENT ON で意図を注釈することが、AIとの協働におけるプロトコルとなります。

参考：Vercel公式React Best Practicesを読み解くでも、公式ドキュメント（一次情報）に沿った実装の重要性を説いています。

さらなる年収アップやキャリアアップを目指すなら、ハイクラス向けの求人に特化した以下のサービスがおすすめです。

比較項目	TechGo	レバテックダイレクト	ビズリーチ
年収レンジ	800万〜1,500万円ハイクラス特化	600万〜1,000万円IT専門スカウト	700万〜2,000万円全業界・管理職含む
技術スタック	◎モダン環境中心	◎Web系に強い	△企業によりバラバラ
リモート率	◎フルリモート前提多数	◯条件検索可能	△原則出社も多い
おすすめ度	S技術で稼ぐならここ	A受身で探すなら	Bマネジメント層向け
公式サイト	無料登録する	-	-

IT女子 アラ美

年収を上げたいんですが、ハイクラス求人ってハードルが高そうで迷います…

ITアライグマ

技術力を武器に年収を上げたいならTechGo一択！でも、自分の市場価値を幅広くチェックしたいならビズリーチも登録しておくと安心ですよ。

まとめ

SupabaseとAIエージェントを組み合わせて開発する際の、データベース設計のベストプラクティスについて解説しました。

• スキーマはAIへの手紙：制約とコメントは、AIに仕様を伝えるための最強のドキュメントです。
• 制約駆動開発：外部キーやRLSを最初にガチガチに固めることで、AIの暴走を防げます。
• 人間は設計者へ：コードを書くのはAI、その土台となるルールを決めるのが人間の役割です。

AIツールは日々進化していますが、その性能を100%引き出せるかどうかは、使い手である私たちの「基礎設計力」にかかっています。まずは次のプロジェクトで、COMMENT ON を書くところから始めてみませんか？

厳しめIT女子 アラ美による解説ショート動画はこちら

IT女子 アラ美

よーし！次の個人開発ではSchema駆動でやってみます！

ITアライグマ

素晴らしいです！しっかりした土台があれば、開発スピードは何倍にも加速しますよ。応援しています！

厳しめIT女子 アラ美による解説ショート動画はこちら