database-architect は、Claude Code にスキーマ設計とマイグレーションを任せるためのサブエージェントだ。 OSS のテンプレート集 claude-code-templates に入っていて、2026年11月12日に、682行の旧版から203行に書き直された。新版は「試していない SQL を渡さない」を決まりにし、マルチテナントの分離を RLS(行レベルセキュリティ)でどう組むかを細かく指示している。本記事は、旧版の RLS の例と新版の決まりを PostgreSQL 16 で流し、両方のエージェントに同じ設計を頼んで比べた結果をまとめる。

aitmpl.com の database-architect のページ。203行・12.9KBの定義ファイル、11月12日の書き直しのコミット、npx でのインストールのコマンド、12,527 のダウンロード数、model は inherit、使えるツールは Read・Write・Edit・Bash・Glob・Grep と表示されている

30秒でわかる database-architect

  • ・何をする:スキーマ設計、マイグレーションの作成とレビュー、テナントの分離を受け持つ Claude Code のサブエージェント
  • ・決まり:書いた SQL は使い捨ての PostgreSQL で流し、RLS は権限の弱いロールで2テナントを試してから報告する
  • ・11月12日の書き直し:旧版の例は持ち主やビューから全テナントが見えた。新版はそれを防ぐ決まりを書いた
  • ・入れる:npx claude-code-templates@latest --agent database/database-architect。前に入れた人は入れ直すと新版になる

テンプレート集全体の使い方は claude-code-templates完全解説|エージェント100種をワンコマンドで導入するOSS で、Claude Code そのものの設定から運用までは Claude Code|2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引き で扱っている。

database-architect の役割と定義ファイルの中身

claude-code-templates は、Claude Code のエージェント、スキル、コマンドなどを集めたテンプレート集だ。GitHub のスターは約3.36万、ライセンスは MIT(11月15日時点)。aitmpl.com はその閲覧サイトで、エージェントは423個ある。database-architect の表示ダウンロード数は 12,527 だった。

定義ファイルは先頭の設定(名前、説明、使えるツール、モデル)と、エージェントへの指示の本文でできている。新版は使えるツールを Read・Write・Edit・Bash・Glob・Grep に限り、モデルは呼び出し元と同じものを使う(model: inherit)。サブエージェントの仕組みと frontmatter の項目は Claude Code サブエージェントとは?作り方・frontmatter全項目・呼び出し方まとめ【2026年版】 にまとめている。

HOW IT WORKSdatabase-architect の進め方

設計して終わりではなく、使い捨ての DB で流してから返す

  1. 01

    今あるものを読む

    マイグレーションの置き場と命名、ORM、テナントの境目

  2. 02

    設計を左右する事実を固める

    表の大きさ、接続のロール、プーラー、Postgres の版

  3. 03

    決まりに沿って設計

    制約は DB 側、テナントは複合 FK と RLS で分ける

  4. 04

    使い捨ての Postgres で試す

    権限の弱いロールに切り替え、2テナントで分離を確かめる

    Prove it

  5. 05

    報告

    決めたこと、試した結果、置いた仮定、反映の順序

出典: claude-code-templates の database-architect.md(2026-11-12 書き直し版)

本文は8つの節に分かれる。進め方、モデリングの決まり、マルチテナント、稼働中の DB の変更、DB の選び方、「Prove it」(試し方)、レビューの順序、ほかのエージェントへの引き継ぎだ。特徴は、決まりごとに理由が書いてある点にある。たとえば「本番に出したマイグレーションは書き換えず、新しく足す」「大きな表への変更は lock_timeout を付け、待たされたら失敗させる」のように、何をなぜ避けるかが具体的だ。

11月12日の書き直しで何が変わったか

THE REWRITEPR #1536 の書き直し

682行を203行に。呼ばれない説明文も直した

682→203行

定義ファイルの長さ

PG16 で動かない例を削った

0/12回

旧版が自然に呼ばれた回数

PR 本文の評価

4/4

時間制約つき移行で旧コードと両立

比較対象は 0/2(PR 本文)

出典: davila7/claude-code-templates PR #1536(2026-11-13 マージ)。行数は編集部が git で数えた値

書き直しは PR #1536(11月13日マージ)で行われた。PR の本文によると、理由は2つある。 ・旧版の SQL の例が PostgreSQL 16 で動かなかった(部分 UNIQUE の構文の誤り、定義していない enum 型など)。監視や設定の例も、PostgreSQL 12・13 で消えた項目を使っていた
・説明文がサブエージェントへの委譲を起こさなかった。PR は「自然な依頼12回で0回」と書いている

新版は説明文を「MUST BE USED for any database schema work」で始め、急ぎの小さな変更でも呼ばれるようにした。PR は claude -p で計40回の評価を行い、時間の制約がある移行で旧コードとの両立を 4/4 で保てたとしている。一方で、設計やレビューの課題では、もともと点が高く差が出なかったとも書いている。この数字は PR の評価で、編集部は再現していない。

旧版の RLS の例を PostgreSQL 16 で流した

旧版には、マルチテナントの RLS の例が載っていた。新版はこの例に足りなかった点を、決まりとして書き足している。編集部は旧版の例のポリシーと権限に、試験用の表、ビュー、外部キーを足して PostgreSQL 16.15 で流した。新版の決まりで作った表にも同じ試験をした。

OLD EXAMPLE vs NEW RULESPostgreSQL 16 で流した結果

旧版の RLS の例は、持ち主やビューから全テナントが見えた

旧版の例(2026年5月版)

新版の決まり

旧版の例(2026年5月版): 表の持ち主は全テナントの行が見える

新版の決まり: FORCE を付け、持ち主でも自テナントだけ

旧版の例(2026年5月版): テナント未設定でエラーになる

新版の決まり: NULLIF で 0 行を返す

旧版の例(2026年5月版): ビュー経由で全テナントが見える

新版の決まり: security_invoker のビューは自テナントだけ

旧版の例(2026年5月版): 別テナントのプロジェクトを参照できる

新版の決まり: 複合外部キーが参照を拒否

出典: 編集部が PostgreSQL 16.15 で流した結果(2026-11-15)。superuser はどちらでも RLS を無視
試したこと(テナント A を設定) 旧版の例 新版の決まり
superuser で数える 2行(全テナント) 2行(全テナント)
表の持ち主のロールで数える 2行(全テナント) 1行(FORCE あり)
テナントを一度も設定していない接続 エラー(設定項目がない) 0行
前のトランザクションでだけ設定した接続 エラー('' を uuid にできない) 0行
持ち主が作ったビュー経由で数える 2行(全テナント) 1行(security_invoker)
テナント B のプロジェクトを指すタスクを入れる 入る 外部キー違反で拒否
テナント B の行を入れる (試験なし) RLS の違反で拒否

superuser は FORCE を付けても RLS を無視する。新版が「使い捨ての DB は superuser で接続するので、そのまま試すと何も確かめずに通る」と書くのはこのためだ。持ち主に全行が見える点は、アプリが表の持ち主で接続しているとそのまま漏れにつながる。PgBouncer のようなトランザクション単位のプーラーでは、前の利用者が設定した値が '' として残る。旧版の式ではこれがエラーになり、新版の NULLIF では0行になる。

database-architect の入れ方と、新旧の見分け方

プロジェクトのフォルダで次を実行すると、.claude/agents/database-architect.md が置かれる。

npx claude-code-templates@latest --agent database/database-architect

CLI(v1.33.1、11月10日公開)で試すと、11月12日に書き直された203行の新版が入った。CLI はエージェントの中身を npm のパッケージに持たず、入れた時点の GitHub の main から取ってくる。つまり、11月12日より前に入れたファイルは旧版のままだ。次のコマンドで見分けられる。

grep -c '^## Prove it' .claude/agents/database-architect.md

新版なら 1、旧版なら 0 が出る。新旧のファイルで試して確かめた。旧版なら、同じ npx のコマンドで入れ直す。中身が後から変わるので、チームで使うなら .claude/agents/ をリポジトリにコミットして、版を固定しておくと差分を追える。プロジェクトとユーザーの設定の置き場の違いは Claude Code 設定ガイド|settings.jsonのスコープ優先順位とpermissions設計 で扱っている。

呼び出すときは、Claude Code に「database-architect サブエージェントを使って」と名指しで頼むのが確実だ。新版は説明文で自動の委譲も狙っているが、編集部の試験は名指しで行った。アプリが接続するロールが RLS を無視しないかは、そのロールで接続して確かめる。

select current_user, rolsuper, rolbypassrls from pg_roles where rolname = current_user;

rolsuper と rolbypassrls がどちらも f なら、そのロールには RLS が効く。t なら、ポリシーを書いても素通りする。

旧版と新版に同じ設計を頼んだ結果

両方のエージェントに、同じ依頼をした。組織、メンバー、プロジェクト、タスクを持つマルチテナントのタスク管理のスキーマで、アプリは PgBouncer のトランザクションモードで app_user として接続する。モデルは両方とも同じものを指定し、使い捨ての PostgreSQL 16 を渡した。

項目 旧版(682行) 新版(203行)
RLS と FORCE 全表で有効 全表で有効
テナント未設定のとき 0行(NULLIF) 0行(NULLIF)
別テナントの参照を防ぐ複合外部キー あり あり
マイグレーションのロック待ちの上限 なし lock_timeout 5秒
表の持ち主 postgres(superuser) 専用の app_owner
費用(API 換算) 約 0.31 ドル 約 0.27 ドル

新版が作ったスキーマは、編集部が別に組んだ試験でも分離が効いた。テナント A の設定では A の行だけが見え、テナント B の行を入れる要求と、B のプロジェクトを指すタスクは拒否された。メンバーを消すと、タスクの担当者の列だけが空になり、テナントの列は残った。

旧版も分離の効くスキーマを作った。今回のモデルは、旧版の例の誤りを自分で避けたことになる。差が出たのは、ロック待ちの上限や持ち主のロールの分け方といった、本番で効く運用の部分だった。PR の評価と同じ傾向だが、編集部の試験は1回ずつで、結論を言い切れる数ではない。なお新版のエージェントは試験で入れた行を DB に残したまま終えていた。渡す DB は、本当に捨ててよいものにする。

参照ソース

・database-architect.md(davila7/claude-code-templates)
・Rewrite the database-architect agent with tested PostgreSQL rules(PR #1536)
・Database Architect(aitmpl.com)
・Row Security Policies(PostgreSQL 16 ドキュメント)