クイックスタート

Kozou を最も早く理解する方法は、それが「間違った答え」を正す様子を見ることです。

このウォークスルーでは、小さな seeded デモを動かします: オンラインストアのデータベースで、AI エージェントが書く「当たり前の」売上クエリは 4.8 倍ずれ、同じエージェントが Kozou のコンテキストを得ると正しく答えます。まずギャップを見て、それを埋めるものを見て、MCP 経由でエージェントを接続し、それからようやく自分のプロジェクトを scaffold します。

所要時間は約 10 分。Docker、git、そして(最後のステップで)Node.js 20 以降が必要です。

何が見えるか

デモのスキーマには、支払い済みに見える注文が 6 件あります。エージェントに総売上を尋ねると、生の DDL だけを頼りに、自信を持って間違った数字を返します:

| エージェントが次から書くクエリ… | 結果 | なぜ | | --- | --- | --- | | 当たり前のカラム — paid 注文の sum(amount_total) | 575.00 ❌ | amount_total は非推奨の古いキャッシュ | | products.list_price から再計算 | 580.00 ❌ | 過去の注文を今日のカタログ価格で評価 | | 明細行を捕捉時の unit_price で合計 | 560.00 ❌ | 慎重な答え — それでも間違い | | Kozou のコンテキスト — vw_recognized_revenue の sum(net_revenue) | 120.00 ✅ | このビューが全認識ルールを内包する |

どの間違った答えも、カラムの選び方では直らない一つの誤りを共有しています: 400 ドルの社内テスト注文と、2 件の論理削除済みの行が売上に数えられています。それらは DDL のどこにもありません — COMMENT ON テキストに存在し、 Kozou がそれをエージェントに渡します。

1. デモを動かす

リポジトリをクローンし、デモスタックを起動します:

git clone --depth 1 https://github.com/kozou-dev/kozou.git
cd kozou/examples/quickstart
cp .env.example .env
docker compose up

docker compose up は、デモの schema.sql で初期化された PostgreSQL と、バンドルされた Admin UI および MCP サーバーをデータベースに向けて提供する kozou dev を起動します。ログが落ち着くと、次が手に入ります:

Admin UI — http://localhost:3333
MCP エンドポイント (HTTP) — http://localhost:3334/mcp

Admin UI を開いて orders に入ってみてください: 行、非推奨の amount_total カラム、status と is_test のフラグ、3 つのレポーティングビューが、すべてスキーマから生成され、UI コードを書くことなく表示されます。

2. なぜ当たり前のクエリが間違うのか — そして何が直すのか

デモのデータベースに対して psql シェルを開き、数字を自分で再現します:

docker compose exec postgres psql -U kozou -d kozou

-- 正しい: ビューが全認識ルールを内包する
SELECT sum(net_revenue) FROM vw_recognized_revenue;            -- 120.00

-- 間違い: paid 注文に対する「当たり前の」カラム
SELECT sum(amount_total) FROM orders WHERE status = 'paid';    -- 575.00

\d orders のどこにも、amount_total が放棄されていること、テスト注文が混ざっていること、2 件の行が論理削除されていることは書かれていません。その知識は COMMENT ON テキストに存在します — そしてエージェントが MCP 経由で行う同じ describe_table("public.orders") 呼び出しが、それを構造化されたエージェント向けフィールドとして返します(抜粋):

{
  "name": "amount_total",
  "aiDescription": "レポートにこれを使わないこと — アプリが維持をやめた古いキャッシュで、テスト注文を含む。売上は vw_recognized_revenue から計算すること。"
},
{
  "name": "is_test",
  "aiDescription": "売上・注文数・ダッシュボードからは is_test = true を常に除外すること — これらは実顧客の注文ではない。"
}

…さらにテーブル自体に、ポリシーと信頼できるビューへのポインタが付きます:

{
  "qualifiedName": "public.orders",
  "aiDescription": "注文が認識売上になるのは status = 'paid' かつ is_test = false かつ deleted_at IS NULL のときだけ … vw_recognized_revenue ビューは既にこれら全ルールを適用済み — 売上の問いはまずそこから。"
}

このコンテキストがあれば、エージェントはビジネスルールを再導出するのをやめ、それを内包するビューを使います。同じモデル、同じ問い — もっともらしい間違いの代わりに正しい答えが返ります。(Kozou は、特定のロールが何に触れてよいかもエージェントに伝えられます — デモの README を参照。)

3. MCP 経由で AI エージェントを接続する

自分のエージェントを稼働中のデモに向けて、売上の問いを自分で尋ねてみましょう。スタックは既に MCP エンドポイントを HTTP の http://localhost:3334/mcp で提供しています。エージェントは stdio 経由で Kozou 自身を起動することもできます。クライアント別の完全な設定(Claude Code・Claude Desktop・Cursor) — 接続を確認する方法やトラブルシューティングを含む — は MCP 経由で AI エージェントを接続するにあります。稼働中のデモに対する Claude Code の短縮版:

claude mcp add --transport http kozou http://localhost:3334/mcp
claude mcp list   # 期待値: kozou … ✓ Connected

試してみる。 kozou のツールが現れたら、エージェントに尋ねます:

kozou のツールを使って、当社の総認識売上はいくらですか? どの行とカラムを除外したか、その理由も説明してください。

Kozou を備えたエージェントは describe_table / get_concept_context を呼び、 vw_recognized_revenue を見つけ、120.00 と答えます — 除外したテスト注文と論理削除済みの行を名指しで挙げながら。同じ問いをツールなしで尋ねれば、上記のもっともらしい間違った数字のどれかが返ります。その対比こそが要点です。

4. 自分のプロジェクトを scaffold する

ペイオフを見届けたら、自分のプロジェクトを始めましょう。create-kozou はバンドルされたテンプレートから新しいプロジェクト — デモではなくあなた自身のスキーマ — を書き出します:

npx -p kozou create-kozou my-project
cd my-project

create-kozou は単体の npm パッケージではなく kozou パッケージのセカンダリ bin として配布されているため、クリーンなマシンで npx がそれを見つけるには -p kozou が必要です。

これによりプロジェクトディレクトリが書き出されます:

my-project/
├── docker-compose.yml      # PostgreSQL + a `kozou` service (REST served in-process)
├── kozou.config.yaml       # database URL, adapter, and UI-hints path
├── ui-hints.yaml           # optional per-column label / widget overrides
├── .env.example            # template for the env vars the stack reads
└── migrations/             # your schema; 0001_init.sql ships a worked example

スターターの migrations/0001_init.sql は空ではありません — COMMENT 規約の動く例(@ai / @widget / @policy / @example を使った orders テーブルと source-of-truth ビュー)が、コメントアウトされた状態で同梱されています。これを自分の CREATE TABLE / CREATE VIEW / COMMENT ON … で置き換え、デモと同じように cp .env.example .env && docker compose up で自分のスタックを起動してください。

COMMENT で注釈を付ける

Kozou は通常の PostgreSQL の COMMENT テキストを読み込みます。いくつかの接頭辞タグは構造化されたヒントとして抽出されます — @ai、@widget、 @policy、@example です。上のデモを駆動している単一のコメントはこうです:

COMMENT ON COLUMN orders.amount_total IS
  'Denormalized order total in cents.

   @ai: レポートにこれを使わないこと — アプリが維持をやめた古いキャッシュ。
        売上は vw_recognized_revenue から計算すること。';

ひとつのコメントから 2 つのことが起こります:

@ai: … は MCP コンテキストに届きます。describe_table や get_concept_context といったツールを通じて surface されるため、クエリを書くエージェントはあなたのガイダンスを目にします。@ai 行は人間が読める本文にも残るので、コメントは依然として自然に読めます。
@widget: enum-select(カラムコメント上)は Admin UI の入力を変えます — プレーンなテキストフィールドがドロップダウンになります。これがなくても、 Kozou は status IN ('draft','published','archived') のような値リストの CHECK 制約を持つカラムに対して enum-select を推論します。このタグはそれを明示的に上書きするものです。

規約の全体については、 COMMENT 規約を参照してください。

トラブルシューティング

ポートが既に使用中 — 別のプロセスが 3333 または 3334(あるいは PostgreSQL の 5432)にバインドされています。それを停止するか、 kozou.config.yaml の server.ui / server.mcp.http(および docker-compose.yml の対応するマッピング)でポートを再マッピングしてください。
データベースに到達できない — データベースコンテナが healthy であること (docker compose ps)を確認してください。初回起動が遅い場合、PostgreSQL が接続を受け付ける準備が整う前に他のサービスが起動することがあります(リトライします)。
エージェントが kozou ツールを一覧しない — MCP 接続ガイドの「ツールが表示されないとき」を順に確認してください。最速の確認は、サーバーを手で起動してエラーを読むことです。
Admin UI のフォーム POST が拒否される — Admin UI はプレーンな HTTP で提供されるため、SvelteKit は ORIGIN を必要とします。scaffold は ORIGIN=${KOZOU_ORIGIN:-http://localhost:3333} を設定します。Admin UI のポートを再マッピングした場合は同期を保ってください。

次に

MCP 経由で AI エージェントを接続する — Claude Code・ Claude Desktop・Cursor のクライアント別設定、両トランスポート、トラブルシューティング。
COMMENT 規約 — すべてのタグ(@ai、 @widget、@policy、@example)と、それぞれがどう解析されるか。
出力されるサーフェス — Admin UI、REST レイヤー、MCP がそれぞれ何を公開するか、そしてなぜか。
インストール — グローバルインストール、ランタイムイメージ、そしてワークスペースパッケージをライブラリとして使う方法。

REST レイヤーは v1.0 以降のデフォルトのバックエンド @kozou/api がインプロセスに提供します。PostgREST はオプトアウトで、kozou dev --adapter postgrest で有効化できます。