- AIコーディングエージェントがPostgresを正しく扱えない問題を解決するため、データベースのルールを明示的に提供するAgent Skillsを公開
- Postgresには数十年にわたって蓄積された機能、エッジケース、性能特性があり、エージェントは動作するものの、フルテーブルスキャンを引き起こしたり、セキュリティポリシーを見落としたコードを生成することがある
- 全8カテゴリ、30のルールで構成され、クエリ性能、接続管理、セキュリティとRLS、スキーマ設計などを影響度ベースの優先順位で整理
- 人が読むドキュメントではなく、AIエージェントが直接参照するルールセットの形で提供
- MCPサーバーと組み合わせることで、実行能力と判断基準を同時に備えた実践的なデータベースエージェントを構成可能
問題意識: AIはコードを書くがシステムを理解していない
- AIコーディングエージェントは文法的には正しいコードを生成するが、Postgresの内部特性や運用リスクを考慮できない限界がある
- フルテーブルスキャンを引き起こすクエリ、書き込み性能を低下させるインデックス提案、Row Level Securityの欠落といった問題が繰り返し発生
- 本番環境で重要な性能、セキュリティ、安定性の要素をエージェントが見落とす事例が多数確認されている
Postgres Agent Skillsの概要
- AIエージェントがPostgresコードを書く際に参照するために作られたルールベースの知識リポジトリ
- 全30のルール、影響度ベースで並べられた8つのカテゴリで構成
- 各ルールにはタイトル、優先度、重要性の説明、正しい/誤ったコード例が含まれる
8つのルールカテゴリ構成
- 各ルールは一貫した形式に従い、タイトル、影響度、説明、タグを含む
- Query Performance (Critical): フルテーブルスキャン防止、効率的なクエリ作成ルール
- Connection Management (Critical): コネクションプーリング、クライアント寿命管理、リソース制限
- Security and RLS (Critical): Row Level Securityポリシー、アクセス制御パターン
- Schema Design (High): テーブル構造、データ型、正規化の判断
- Concurrency and Locking (Medium-High): トランザクション分離、デッドロック防止、ロック管理
- Data Access Patterns (Medium): ページネーション、バルク処理、アクセスパターン設計
- Monitoring and Diagnostics (Low-Medium): クエリ分析、性能追跡、デバッグ
- Advanced Features (Low): CTE、ウィンドウ関数、拡張機能などPostgres固有機能
Row Level Securityルールの例
- 誤った方法: アプリケーションレベルのフィルタリングだけに依存すると、バグやバイパスにより全データが露出する危険がある
select * from orders where user_id = $current_user_id; の形で書くと、バイパス時にすべての注文を返してしまう
- 正しい方法: データベースレベルでRLSを強制適用
alter table orders enable row level security; でRLSを有効化create policy でユーザーが自分のデータだけを見られるようにポリシーを作成alter table orders force row level security; でテーブル所有者にもRLSを強制
- 認証済みロール向けポリシー例:
create policy orders_user_policy on orders for all to authenticated using (user_id = auth.uid());
Agent Skillsフォーマットとエコシステム
- Agent Skillsは、エージェントにドメイン専門性を提供するオープン標準形式のAIエージェント専用ドキュメントフォーマットで、必要に応じてエージェントが直接読んで適用する
- Claude Code、Cursor、GitHub Copilot、VS Code、Gemini CLIなどと互換
- エージェントが必要なときに発見して使えるガイドラインと例が入ったフォルダ形式
- 学習データから正しいパターンを学習していることを期待するのではなく、明示的なルールを提供
- Anthropicが定義したオープン標準で、業界全体で採用が進んでいる
- Vercelは10年分のReactおよびNext.js最適化知識を40のルールにパッケージ化したreact-best-practicesを公開
- CloudflareはWorkers、Pages、D1、R2など40以上のサービスに関するSkillsを公開
Supabaseがこのルールを作った理由
- Supabaseは数十万のプロジェクトでPostgresを運用し、同じミスが繰り返されるのを目撃してきた
- Foreignキーへのインデックス不足
- 誤ってRLSを回避してしまうクエリ
- 本番環境でテーブルをロックするマイグレーション
- 不適切に管理されたクライアントによる接続プール枯渇
- ORMの背後に隠れたフルテーブルスキャン
- サポートチーム、データベースアドバイザー、ドキュメントにすでに存在する知識をエージェントフレンドリーな形に再構成してパッケージ化
MCPサーバーとの関係
- Supabase MCPサーバーは、AIエージェントがSupabaseプロジェクトに直接接続し、テーブル作成、クエリ実行、スキーマ管理、設定構成を自然言語で行えるようにする
- MCPサーバーはエージェントにデータベース作業の能力を与え、ベストプラクティスはそれを正しく行うよう教育する
- 比喩: MCPサーバーはハンドル、ベストプラクティスは運転教習
- MCPアクセス権だけを持つエージェントは、要求されたすべてのクエリを実行できる
- MCPアクセス権とルールの両方を持つエージェントは、テーブルをロックするインデックス作成の前に警告し、安全でないコードをデプロイする前にRLSポリシーを提案し、性能問題を避けるようにクエリを構造化できる
- MCPサーバーは接続と実行を担当し、このベストプラクティスは判断を担当する
- Agent Skillsは実行前にリスク要因を警告し、より良い選択へ導く
- 実行能力と判断基準を分離することで、安全で信頼できる自動化環境を構成
インストール方法
- リポジトリの場所: github.com/supabase/agent-skills
- Vercelのskills npmパッケージを使って対話的にインストール可能
npx skills add supabase/agent-skills
- Claude Code使用時はプラグインとしてインストール可能
/plugin marketplace add supabase/agent-skills/plugin install postgres-best-practices@supabase-agent-skills
まだコメントはありません。