Claude Code × Supabase フルスタック開発完全ガイド【2026年最新】｜MCP連携・RLS自動生成・Realtime・Edge Functions・pgvectorまで

claude --version          # Claude Code 2.x 系
supabase --version        # Supabase CLI v2 系
node -v                   # v22 LTS 推奨（Bun の場合は bun -v）
docker info               # supabase start が内部で使う
deno --version            # Edge Functions ローカル実行に必要

# Next.js アプリ雛形
npx create-next-app@latest my-app --ts --app --tailwind --eslint --src-dir --import-alias "@/*"
cd my-app

# Supabase クライアント
npm install @supabase/supabase-js @supabase/ssr

# Supabase CLI で backend を初期化
supabase init               # supabase/ ディレクトリ生成
supabase start              # ローカル Supabase（Postgres / Studio / Auth / Realtime）起動
supabase link --project-ref <YOUR_PROJECT_REF>   # 本番プロジェクトに紐づけ

NEXT_PUBLIC_SUPABASE_URL=https://xxxxxxxx.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_xxxxxxxxxxxxxxxx
# secret キーはサーバーのみ。絶対に NEXT_PUBLIC_ を付けない
SUPABASE_SECRET_KEY=sb_secret_xxxxxxxxxxxxxxxx

# 読み取り専用 + プロジェクト固定が安全デフォルト
claude mcp add --scope user supabase \
  --transport http \
  "https://mcp.supabase.com/mcp?project_ref=<PROJECT_REF>&read_only=true"

# 初回 /mcp コマンド実行時にブラウザが開き Supabase にログインする
# 完了後に /mcp の出力で supabase が connected と表示されれば OK

# Supabase プロジェクト運用ルール

## スタック
- Next.js 15 App Router + React 19
- Supabase（Auth / Postgres / Realtime / Storage / Edge Functions / pgvector）
- クライアント: @supabase/ssr v0.x（createBrowserClient / createServerClient を使い分け）

## API キー方針
- 公開鍵は必ず sb_publishable_ 系（旧 anon は新規追加禁止）
- サーバー鍵は sb_secret_ 系。NEXT_PUBLIC_ プリフィックス禁止
- Edge Functions 内では Deno.env.get("SUPABASE_SECRET_KEY") のみ使用

## 認証
- Server Components / Server Actions では必ず createServerClient + supabase.auth.getClaims() を使う
- サーバー側で getSession() は使わない（Cookie を検証せず改ざんを見抜けない）
- getUser() は API 往復するため安全だが遅い。基本は getClaims() に寄せる
- middleware.ts でリクエストごとに getClaims() を呼びトークンを更新する

## DB とマイグレーション
- SQL は supabase/migrations/*.sql に配置（直接 DB を触らない）
- 命名規則: YYYYMMDDHHMMSS_short_description.sql
- すべてのテーブルに RLS を有効化。ポリシーなしの ENABLE は禁止
- 例外: public.app_config のような完全公開テーブルのみコメントで明記

## RLS ルール
- auth.uid() は必ず呼び側でキャッシュする: (select auth.uid())
- using 句と with check 句を両方書く（INSERT/UPDATE/DELETE のすべてで）
- ポリシー追加時は必ず pg_policies のスナップショットを確認する

## Edge Functions
- 1 関数 1 責務。import は jsr: or npm: 指定を使う
- --no-verify-jwt は明示的に理由をコメント
- CORS は共通 util（supabase/functions/_shared/cors.ts）を使う

## Claude Code 実行ルール
- supabase db push を実行する前に git diff supabase/migrations を提示する
- Supabase MCP の execute_sql は SELECT 以外は実行しない
- Edge Functions のデプロイは必ず supabase functions deploy --use-api でローカル検証 → デプロイ

タスク: 投稿（posts）と コメント（comments）のテーブルを追加する

要件:
- posts: id uuid PK, user_id uuid FK auth.users, title text, body text, created_at timestamptz default now()
- comments: id uuid PK, post_id uuid FK posts on delete cascade, user_id uuid FK auth.users, body text, created_at timestamptz
- posts / comments とも RLS 有効化
- RLS ポリシー:
  * SELECT: 公開（誰でも読める）
  * INSERT: auth.uid() が user_id と一致する場合のみ
  * UPDATE/DELETE: 作成者本人のみ
- supabase migration new posts_comments_init で新規ファイルを作り、上記を SQL として書き込む
- ポリシーの auth.uid() は必ず (select auth.uid()) 形式でキャッシュする
- 完了後に SELECT で pg_policies を表示して確認

-- posts / comments のスキーマ定義
create table public.posts (
  id         uuid primary key default gen_random_uuid(),
  user_id    uuid not null references auth.users(id) on delete cascade,
  title      text not null,
  body       text not null default '',
  created_at timestamptz not null default now()
);

create table public.comments (
  id         uuid primary key default gen_random_uuid(),
  post_id    uuid not null references public.posts(id) on delete cascade,
  user_id    uuid not null references auth.users(id) on delete cascade,
  body       text not null,
  created_at timestamptz not null default now()
);

-- RLS
alter table public.posts    enable row level security;
alter table public.comments enable row level security;

-- SELECT（誰でも読める想定）
create policy "posts_select_all"
  on public.posts for select
  using (true);

create policy "comments_select_all"
  on public.comments for select
  using (true);

-- INSERT（自分の行のみ）
create policy "posts_insert_self"
  on public.posts for insert
  with check ((select auth.uid()) = user_id);

create policy "comments_insert_self"
  on public.comments for insert
  with check ((select auth.uid()) = user_id);

-- UPDATE/DELETE（所有者のみ）
create policy "posts_modify_owner"
  on public.posts for update using ((select auth.uid()) = user_id)
  with check ((select auth.uid()) = user_id);

create policy "posts_delete_owner"
  on public.posts for delete using ((select auth.uid()) = user_id);

create policy "comments_modify_owner"
  on public.comments for update using ((select auth.uid()) = user_id)
  with check ((select auth.uid()) = user_id);

create policy "comments_delete_owner"
  on public.comments for delete using ((select auth.uid()) = user_id);

# ローカル DB に適用（supabase start で起動済み前提）
supabase db push

# 本番に適用するなら必ずプルリク経由。ローカルで十分確認してから
supabase db push --linked

# DB スキーマから型を自動生成（TS 定義として src/types/database.ts に保存）
supabase gen types typescript --local > src/types/database.ts

import { describe, it, expect, beforeAll } from "vitest";
import { createClient } from "@supabase/supabase-js";

// 匿名クライアント（未ログイン）と 2 人のユーザークライアントを用意
const anon   = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_PUBLISHABLE_KEY!);
const alice  = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_PUBLISHABLE_KEY!);
const bob    = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_PUBLISHABLE_KEY!);

beforeAll(async () => {
  await alice.auth.signInWithPassword({ email: "alice@test.dev",  password: "pw" });
  await bob.auth.signInWithPassword({   email: "bob@test.dev",    password: "pw" });
});

describe("RLS: posts", () => {
  it("匿名ユーザーは SELECT できるが INSERT はできない", async () => {
    const read = await anon.from("posts").select("id").limit(1);
    expect(read.error).toBeNull();
    const write = await anon.from("posts").insert({ title: "x", body: "x" });
    expect(write.error).not.toBeNull();
  });

  it("Alice は自分の投稿は更新できるが Bob の投稿は更新できない", async () => {
    const { data: aPost } = await alice.from("posts").insert({ title: "A", body: "a" }).select().single();
    const own = await alice.from("posts").update({ title: "A2" }).eq("id", aPost!.id);
    expect(own.error).toBeNull();
    const foreign = await bob.from("posts").update({ title: "A-hacked" }).eq("id", aPost!.id);
    expect(foreign.error).not.toBeNull();   // 更新失敗 or 行数 0 が正
  });
});

import { createServerClient } from "@supabase/ssr";
import { cookies } from "next/headers";

export async function getSupabaseServer() {
  const cookieStore = await cookies();
  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
    {
      cookies: {
        getAll() { return cookieStore.getAll(); },
        setAll(cookiesToSet) {
          try {
            cookiesToSet.forEach(({ name, value, options }) =>
              cookieStore.set(name, value, options)
            );
          } catch {
            // Server Components から呼ばれた時は set 不可（無視して OK）
          }
        },
      },
    }
  );
}

import { createBrowserClient } from "@supabase/ssr";

export const getSupabaseBrowser = () =>
  createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!
  );

import { createServerClient } from "@supabase/ssr";
import { NextResponse, type NextRequest } from "next/server";

export async function middleware(request: NextRequest) {
  let response = NextResponse.next({ request });

  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
    {
      cookies: {
        getAll() { return request.cookies.getAll(); },
        setAll(cookiesToSet) {
          cookiesToSet.forEach(({ name, value }) => request.cookies.set(name, value));
          response = NextResponse.next({ request });
          cookiesToSet.forEach(({ name, value, options }) =>
            response.cookies.set(name, value, options)
          );
        },
      },
    }
  );

  // JWT 署名検証つきで claims を取る（推奨）
  const { data: { claims } } = await supabase.auth.getClaims();

  // /app 以下はログイン必須
  if (!claims && request.nextUrl.pathname.startsWith("/app")) {
    const url = request.nextUrl.clone();
    url.pathname = "/login";
    return NextResponse.redirect(url);
  }

  return response;
}

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};

-- 対象テーブルを supabase_realtime パブリケーションに追加
alter publication supabase_realtime add table public.comments;

-- DELETE で削除行の中身が必要ならレプリカアイデンティティを full に
alter table public.comments replica identity full;

"use client";
import { useEffect, useState } from "react";
import { getSupabaseBrowser } from "@/lib/supabase/client";

export function CommentStream({ postId }: { postId: string }) {
  const [comments, setComments] = useState<{ id: string; body: string }[]>([]);

  useEffect(() => {
    const supabase = getSupabaseBrowser();
    const channel = supabase
      .channel(`comments:${postId}`)
      .on(
        "postgres_changes",
        {
          event: "INSERT",
          schema: "public",
          table: "comments",
          filter: `post_id=eq.${postId}`,
        },
        (payload) => {
          setComments((prev) => [...prev, payload.new as any]);
        }
      )
      .subscribe();

    return () => {
      supabase.removeChannel(channel);
    };
  }, [postId]);

  return <ul>{comments.map((c) => <li key={c.id}>{c.body}</li>)}</ul>;
}

-- バケット作成（Studio UI でも可）
insert into storage.buckets (id, name, public)
values ('avatars', 'avatars', true),
       ('user-files', 'user-files', false);

-- 公開バケット: 誰でも読める / 認証ユーザーのみアップロード可
create policy "avatars_public_read"
  on storage.objects for select
  using (bucket_id = 'avatars');

create policy "avatars_auth_insert"
  on storage.objects for insert
  with check (
    bucket_id = 'avatars'
    and (select auth.uid()) is not null
  );

-- プライベートバケット: 自分のフォルダのみアクセス可
create policy "user_files_own_read"
  on storage.objects for select
  using (
    bucket_id = 'user-files'
    and (storage.foldername(name))[1] = (select auth.uid())::text
  );

create policy "user_files_own_write"
  on storage.objects for insert
  with check (
    bucket_id = 'user-files'
    and (storage.foldername(name))[1] = (select auth.uid())::text
  );

const supabase = getSupabaseBrowser();
const { data: { user } } = await supabase.auth.getUser();
if (!user) throw new Error("未ログイン");

const file = e.target.files![0];
const path = `${user.id}/${crypto.randomUUID()}-${file.name}`;

const { error } = await supabase.storage
  .from("user-files")
  .upload(path, file, {
    cacheControl: "3600",
    upsert: false,
    contentType: file.type,
  });

if (error) console.error(error);

supabase functions new summarize
# supabase/functions/summarize/index.ts が生成される

# ローカル実行（別ターミナルで supabase start 済み前提）
supabase functions serve summarize --env-file supabase/functions/.env.local

# 呼び出し確認
curl -i --location --request POST http://127.0.0.1:54321/functions/v1/summarize \
  --header "Authorization: Bearer <ANON_OR_PUBLISHABLE>" \
  --header "Content-Type: application/json" \
  --data '{"text":"長文..."}' 

export const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers":
    "authorization, x-client-info, apikey, content-type",
  "Access-Control-Allow-Methods": "POST, OPTIONS",
};

import { corsHeaders } from "../_shared/cors.ts";

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const { text } = await req.json();
  if (!text) {
    return new Response(JSON.stringify({ error: "text required" }), {
      status: 400,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const openaiKey = Deno.env.get("OPENAI_API_KEY");
  if (!openaiKey) {
    return new Response(JSON.stringify({ error: "server misconfigured" }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const res = await fetch("https://api.openai.com/v1/chat/completions", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${openaiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gpt-4o-mini",
      messages: [
        { role: "system", content: "入力を 3 行で日本語要約せよ。" },
        { role: "user", content: text },
      ],
    }),
  });

  const data = await res.json();
  const summary = data.choices?.[0]?.message?.content ?? "";

  return new Response(JSON.stringify({ summary }), {
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});

# 本番用 secret を登録
supabase secrets set OPENAI_API_KEY=sk-xxxxxxxxxxxx

# デプロイ（JWT 検証あり = 認証必須）
supabase functions deploy summarize

# 認証不要（Webhook 用途など）の場合のみ明示的に
supabase functions deploy public-webhook --no-verify-jwt

-- 拡張を有効化
create extension if not exists vector with schema extensions;

-- ドキュメントテーブル（1536 次元を想定）
create table public.documents (
  id         bigint generated always as identity primary key,
  content    text not null,
  embedding  extensions.vector(1536),
  metadata   jsonb not null default '{}'::jsonb
);

-- HNSW インデックス（INSERT と検索のバランスが良い）
create index documents_embedding_hnsw
  on public.documents using hnsw (embedding vector_cosine_ops);

-- RPC: 類似ドキュメント検索
create or replace function match_documents(
  query_embedding vector(1536),
  match_threshold float,
  match_count int
)
returns table (
  id bigint,
  content text,
  similarity float
)
language sql stable as $$
  select
    d.id,
    d.content,
    1 - (d.embedding <=> query_embedding) as similarity
  from public.documents d
  where 1 - (d.embedding <=> query_embedding) > match_threshold
  order by d.embedding <=> query_embedding
  limit match_count;
$$;

// supabase/functions/ask/index.ts
import { corsHeaders } from "../_shared/cors.ts";
import { createClient } from "jsr:@supabase/supabase-js@2";

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") return new Response("ok", { headers: corsHeaders });

  const { query } = await req.json();

  // 1) OpenAI で embedding を作る
  const embRes = await fetch("https://api.openai.com/v1/embeddings", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${Deno.env.get("OPENAI_API_KEY")}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ model: "text-embedding-3-small", input: query }),
  });
  const { data } = await embRes.json();
  const embedding = data[0].embedding;

  // 2) Supabase の RPC で類似検索（SERVICE キーで管理者権限）
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!    // 旧名。新 API では sb_secret_
  );
  const { data: hits, error } = await supabase.rpc("match_documents", {
    query_embedding: embedding,
    match_threshold: 0.75,
    match_count: 5,
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify({ hits }), {
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});

select
  schemaname, tablename, rowsecurity
from pg_tables
where schemaname = 'public'
  and rowsecurity = false;
-- 結果が 0 行であることが正常