Claude Media
Claude Codeにpg-aiguideを入れる — Postgresスキーマ設計を任せる3つの入れ方
Claude CodeMCPClaude連携チュートリアル

Claude Codeにpg-aiguideを入れる — Postgresスキーマ設計を任せる3つの入れ方

pg-aiguideはPostgreSQLの公式マニュアル検索とベストプラクティス集をClaude Codeに足す仕組みです。プラグイン・MCP・スキルの入れ方と、スキーマ設計での使いどころを解説します。

読了目安 約15分

pg-aiguideはClaude Codeに何を足すのか

pg-aiguide(Tiger Data製、Apache 2.0)は、PostgreSQLの公式マニュアルを検索するMCPツールと、Postgresの設計指針をまとめたスキルをClaude Codeに足す仕組みです。狙いはスキーマ設計やSQLの品質で、READMEは古い書き方・制約やインデックスの抜け・新しい機能を知らない出力を、AIコーディングツールがPostgresで出しやすい失敗として挙げています。

構成要素は2つです。

  • ドキュメント検索(MCPツール): search_docsが意味検索とキーワード検索(BM25)でマニュアルを引きます。対象はPostgreSQL本体(バージョン指定あり)、TimescaleDBなどTiger Dataのドキュメント、PostGISです
  • スキル: Postgresの設計指針を、データ型・インデックス・制約・命名・性能などの観点でまとめたものです。MCP側にはview_skillというツールがあり、スキルの本文を引き出せます

入れ方は3通りあり、結果として得られるものが少しずつ違います。この記事では、どれを選ぶかの基準、Claude Codeでの導入コマンド、入った後の確認、スキーマ設計を頼むときの運用までを順に扱います。

3つの入れ方のどれを選ぶか

READMEが挙げる形態は、Agent Skills・MCPサーバー・Claude Codeプラグインです。Claude Codeで使うなら、まず次の表で選びます。

入れ方入るもの向く場面
プラグイン(pg@aiguide)入るものスキル + MCP接続向く場面迷ったらこれ。1回の導入で両方が揃う
MCPサーバーのみ入るものsearch_docsとview_skill向く場面マニュアル検索だけ欲しい。他のAIツールとも共有したい
Agent Skills(npx skills)入るものスキルのみ向く場面ネットワーク接続なしでも効かせたい。MCPの追加が組織の設定で止められている

プラグインは、リポジトリのスキル群と、TigerDataが公開しているMCPエンドポイントの両方を使います。リポジトリ内のマーケットプレイス定義では、プラグイン名はpg、マーケットプレイス名はaiguide、バージョンは0.6.1です。MCP接続のURLはhttps://mcp.tigerdata.com/docs?disable_mcp_skills=1になっていて、スキルはMCP経由ではなくスキルとして読み込む構成だと読めます。

Claudeのコネクタ一覧にも「pg-aiguide」が載っています。Anthropic verifiedの表示があり、カテゴリはDeveloper tools、ログインは不要、追加は2026年3月です。コネクタのURLはhttps://mcp.tigerdata.com/docsで、ツールはsearch_docsとview_skillの2つが挙がっています。つまり、プラグインなしのMCP単体と同じ接続先です。

プラグインで入れる

Claude Codeではマーケットプレイスを追加してからプラグインを入れます。シェルから実行する形です。

claude plugin marketplace add timescale/pg-aiguide
claude plugin install pg@aiguide

marketplace addはGitHubのowner/repo形式を受け付けます。セッション内で操作したいときは/plugin marketplace add timescale/pg-aiguideでも同じ追加ができ、その後/plugin install pg@aiguideでインストールの詳細画面が開きます。インストール範囲(スコープ)はこの画面で選びます。

チームで使うなら、プロジェクトスコープにすると.claude/settings.jsonに有効化の記述が入ります。ただし、その記述がコミットされても、同僚のマシンにプラグイン本体が自動で入るわけではありません。各自がclaude plugin install pg@aiguide --scope projectを1回実行する必要があります。

プラグインの導入で「packages are not installed」と出たときの切り分けは、Claude Codeプラグインの対処にあります。

MCPサーバーだけを入れる

マニュアル検索だけが目的なら、リモートHTTPのMCPサーバーとして登録します。

claude mcp add --transport http pg-aiguide https://mcp.tigerdata.com/docs

READMEのJSON設定は次の形です。.mcp.jsonに書くなら、そのまま貼れます。

{
  "mcpServers": {
    "pg-aiguide": {
      "url": "https://mcp.tigerdata.com/docs"
    }
  }
}

JSONのまま登録したいときはclaude mcp add-jsonが使えます。手順はclaude mcp add-jsonの解説にまとめています。スコープや認証など登録まわりの全体像はClaude Code MCP設定ガイドが受け持ちます。

注意点が1つあります。この方法で入るのは2つのMCPツールだけで、スキルがClaude Codeのスキルとして読み込まれるわけではありません。view_skillを呼ぶかどうかはClaudeの判断に委ねられるため、指針を毎回効かせたいなら、プラグインかスキル導入を併用します。

スキルだけを入れる

READMEはnpx skillsによる導入も案内しています。

npx skills add timescale/pg-aiguide --skill postgres
npx skills add timescale/pg-aiguide --skill schema-exploration

postgresは設計・インデックス・マイグレーションなどの入口になるスキルで、必要に応じて下位の参照ファイルを読みに行く構成です。schema-explorationは、既存のPostgreSQLデータベースを調べるためのスキルです。スキル名を付けずにnpx skills add timescale/pg-aiguideと実行すると、対話形式で個別に選べます。

READMEによれば、この方法はClaude Code以外にもCursor、Codex、Gemini CLIなど40以上のエージェントで使えます。インストール後は、Claude Codeが読むスキルの置き場所(個人用は~/.claude/skills/、プロジェクト用は.claude/skills/)にファイルが入ったか、lsで確かめておくと安心です。

入ったかどうかを確かめる

導入方法にかかわらず、次の3点を見ます。

  1. セッション内で/mcpを開き、pg-aiguideが接続済みで、ツールが2つ並んでいるか
  2. プラグインで入れたなら、/pluginの一覧にpgがあるか
  3. スキルは/skillsの一覧に出ているか

プラグインで入れた場合、MCPツールの呼び出し名には、プラグイン名とサーバー名が両方入ります。Claude Codeの規則はmcp__plugin_<プラグイン名>_<サーバー名>__<ツール名>です。ここでは次のようになります。

mcp__plugin_pg_pg-aiguide__search_docs
mcp__plugin_pg_pg-aiguide__view_skill

MCP単体で登録した場合はmcp__pg-aiguide__search_docsの形です。この違いは、次に扱う権限設定で効いてきます。

権限を絞っておく

search_docsはドキュメントを引くだけのツールです。読み取り専用で使う前提なら、許可ルールに入れておくと毎回の確認が減ります。プラグイン経由の名前は長いので、サーバー単位のワイルドカードにするのが現実的です。

{
  "permissions": {
    "allow": ["mcp__plugin_pg_pg-aiguide__*"]
  }
}

MCP単体で登録したなら、mcp__pg-aiguide__*と書きます。権限ルールの<server>部分は、登録名の.や空白が_に置き換わる点にも注意が要ります。pg-aiguideのハイフンはそのまま残ります。

もう1点、送信先の話です。search_docsの検索語は、TigerDataが運用するエンドポイントに届きます。テーブル名やカラム名から社内の事業内容が推測できる場合は、プロンプトに含めるスキーマ情報の粒度を決めてから入れてください。コネクタのページにも、信頼できる開発元のコネクタだけを使うようにとの注意書きがあります。

スキーマ設計を頼むときの運用

導入しただけでは、Claudeがpg-aiguideを使う保証はありません。使わせるための運用を3段で組みます。

CLAUDE.mdに書く規約

プロジェクトのCLAUDE.mdに、Postgresの作業の入口を決めておきます。たとえば次のような断片です。

## Postgres
- テーブル設計・インデックス・マイグレーションを書く前に、pg-aiguideのpostgresスキルを読む
- 使うPostgreSQLのバージョンは17。バージョン依存の構文はsearch_docsで確かめてから書く
- DDLは db/migrations/ に置き、本番へは適用しない

バージョンの明記が効く理由は、search_docsのPostgreSQL検索がバージョン指定に対応しているからです。READMEの説明どおりなら、使っているバージョンが書いてあるほど、引く先のマニュアルも合わせられます。

設計を頼むプロンプト

READMEの最初のプロンプト例は、ユーザー名と一意のメールアドレスを持つテーブルを作らせる、短いものです。業務の設計なら、前提を具体的に渡すほうが指針に沿った出力になります。

受注管理のPostgreSQLスキーマを設計してください。
顧客・注文・注文明細・商品の4テーブルです。
金額は税込・税抜の両方を持ち、注文は後からキャンセルできます。
pg-aiguideのスキルとsearch_docsを使い、
使った指針をDDLのコメントに残してください。

最後の1行が要点です。指針をコメントに残させると、あとでレビューするときに「どの規則に従った結果か」を追えます。

出力を検証するループ

READMEは、e-commerceのスキーマをMCPの有効時と無効時で2回書かせて比較した例を紹介しています。結果は、制約が4倍、インデックスが55%増え、PG17推奨の書き方やGENERATED ALWAYS AS IDENTITY、NULLS NOT DISTINCTが入ったという要約です。READMEの著者による一例であり、自分のプロジェクトで同じ差が出るとは限りません。

そこで同じ比較を手元で再現し、数字を自分で取ります。

  1. スキルとMCPを無効にしたセッションで、同じ要件のDDLをbefore.sqlに書かせる
  2. 有効にしたセッションでafter.sqlに書かせる
  3. 空のローカルDBに両方を流し、\d+でテーブル定義を比べる
createdb schema_check
psql -d schema_check -f after.sql
psql -d schema_check -c '\d+ orders'

DDLが通るかどうかは、人間のレビューより先にデータベースが答えます。Claudeに「流して、エラーを直して」と繰り返させる反復は、スキーマ設計では特に効きます。本番や共有DBには向けず、使い捨てのローカルDBに限ってください。

スキルが求める設計の中身

postgresスキルから辿れるdesign-postgres-tablesは、データ型と制約の選び方を細かく決めています。Claudeに任せる前に、何が規則として入っているかを知っておくと、出力のレビューが楽になります。

場面避ける書き方スキルが示す書き方
主キー避ける書き方serialスキルが示す書き方BIGINT GENERATED ALWAYS AS IDENTITY
時刻避ける書き方timestamp(タイムゾーンなし)スキルが示す書き方TIMESTAMPTZ
金額避ける書き方money型、浮動小数点スキルが示す書き方NUMERIC(p,s)
文字列避ける書き方varchar(n)、char(n)スキルが示す書き方TEXT。長さ制限はCHECK (LENGTH(col) <= n)
外部キー避ける書き方インデックスなしで放置スキルが示す書き方参照する側の列に手動でインデックスを足す
一意制約とNULL避ける書き方UNIQUEのみ(NULLは複数入る)スキルが示す書き方PostgreSQL 15以降はNULLS NOT DISTINCTを検討
JSON避ける書き方jsonスキルが示す書き方JSONB。GINインデックスで引く

PostgreSQLは外部キーの列にインデックスを自動では作りません。この点は手書きDDLでも抜けやすく、スキルが「手動で」と太字で強調している項目です。逆に、スキルが規則として固めすぎている面もあります。たとえば「varchar(n)を使わない」は一つの流儀であり、既存システムの慣習がvarcharなら、そちらに合わせる判断も成り立ちます。その場合はCLAUDE.mdに既存の方針を書き、スキルとの優先順位を明示します。

スキル側のユーザー・注文の例は、主キーにIDENTITY、created_atにTIMESTAMPTZ、orders.user_idにインデックス、statusにCHECK制約という作りです。この例は公開されているスキルの記述であり、Claudeが生成する出力そのものではありません。

限界と使い分け

pg-aiguideが知っているのは、PostgreSQLの一般的な作法とマニュアルです。自分のデータベースの中身は知りません。既存のスキーマを前提にした変更では、schema-explorationスキルのような「まず読み取り専用で調べる」工程が先に要ります。このスキルは、pg_catalogへの読み取りクエリで対象を探し、データから導く統計や行の確認は承認を得てから進めるよう書かれています。

拡張機能の対応範囲も限られます。READMEによると、対応済みはTimescaleDB(ドキュメントとスキル)とPostGIS(ドキュメント)で、pgvectorは「近日対応」の扱いです。ただしリポジトリのスキル一覧にはpgvector向けの参照も含まれるため、検索ツールの対象とスキルの対象は分けて考えます。

ORMを使うプロジェクトでは、スキーマの正がORM側のモデルになることがあります。そのときはDDLを直接書かせるより、ORMのスキーマ定義を設計させる運用が自然です。Prismaでの進め方はClaude CodeでPrismaスキーマを設計するが扱っています。Postgres自体を操作するMCPサーバーを探しているなら、PostgreSQL MCPサーバーの使い方が別系統の選択肢です。pg-aiguideは「知識を足す」もの、あちらは「データベースに接続して実行する」ものという違いがあります。

まとめ

迷ったらプラグイン(pg@aiguide)で入れ、/mcpでツールが2つ見えることを確かめます。効果は、同じ要件を有効・無効で書かせてpsqlで比べると、READMEの数字に頼らず自分で測れます。既存DBを触る作業は、設計の前にschema-explorationで調べる段取りをCLAUDE.mdに書いておくと、Claudeの動きが安定します。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →