database-architect は、Claude Code にスキーマ設計とマイグレーションを任せるためのサブエージェントだ。 OSS のテンプレート集 claude-code-templates に入っていて、2026年11月12日に、682行の旧版から203行に書き直された。新版は「試していない SQL を渡さない」を決まりにし、マルチテナントの分離を RLS(行レベルセキュリティ)でどう組むかを細かく指示している。本記事は、旧版の RLS の例と新版の決まりを PostgreSQL 16 で流し、両方のエージェントに同じ設計を頼んで比べた結果をまとめる。
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 で流してから返す
-
01
今あるものを読む
マイグレーションの置き場と命名、ORM、テナントの境目
-
02
設計を左右する事実を固める
表の大きさ、接続のロール、プーラー、Postgres の版
-
03
決まりに沿って設計
制約は DB 側、テナントは複合 FK と RLS で分ける
-
04
使い捨ての Postgres で試す
権限の弱いロールに切り替え、2テナントで分離を確かめる
Prove it
-
05
報告
決めたこと、試した結果、置いた仮定、反映の順序
本文は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 本文)
書き直しは 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月版): 別テナントのプロジェクトを参照できる
新版の決まり: 複合外部キーが参照を拒否
| 試したこと(テナント 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 ドキュメント)





