---

name: clerk-auth description: Clerk認証・マルチユーザー対応をcraftgardenプロダクトに導入する。「Clerk導入」「認証追加」「マルチユーザー対応」「NextAuth移行」「ログイン機能」などの作業に使う。

Clerk Auth — craftgarden 認証基盤スキル

Clerk を使った認証・マルチユーザー対応を craftgarden プロダクトに導入するスキル。 AI PM Service での実績をベースに、横展開を効率化する。

事前確認（必須）

1. LEARNINGS.md を読む — 過去のハマりポイントを確認
2. 対象プロダクトの現在の認証方式を確認（NextAuth? Basic Auth? なし?）
3. Clerk Dashboard に対象アプリが作成済みか確認

craftgarden 共通設定

Clerk Dashboard 基本設定

• Sign in options: Google のみ（他プロバイダは必要時に追加）
• Localization: コード側で jaJP を適用（Dashboard設定は不要）
• Theme: Quiet Garden カラー（colorPrimary: '#6B8F71'）
• Block email subaddresses: ON

共通環境変数

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...
CLERK_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up

実行フロー

Phase 0: パッケージ導入

# 旧認証パッケージ削除（存在する場合）
pnpm remove next-auth @auth/drizzle-adapter drizzle-orm

# Clerk パッケージ追加
pnpm add @clerk/nextjs @clerk/localizations svix

Phase 1: DB スキーマ変更

1.1 users テーブル追加 + 既存テーブルに user_id カラム追加

SQLスキーマは references/schema-users.sql を参照。

対象テーブル: tasks, projects, その他ユーザースコープが必要なテーブル

1.2 User CRUD 関数

// db.ts に追加
export async function upsertUser(data: { id: string; email: string; name?: string | null; image_url?: string | null }): Promise<User> {
  // INSERT ON CONFLICT UPDATE パターン
}
export async function getUser(id: string): Promise<User | null>
export async function deleteUser(id: string): Promise<boolean>
export async function assignOrphanedDataToUser(userId: string): Promise<void> {
  // user_id IS NULL のレコードを一括割当（初回ユーザー作成時）
}

Phase 2: 認証基盤（一括で実施）

2.1 auth.ts ヘルパー

テンプレート: references/template-auth-helper.ts

src/lib/auth.ts に requireUserId() と getUserId() を実装。

2.2 middleware.ts

テンプレート: references/template-middleware.ts

注意: matcher から静的アセット（favicon, icons, .png, .svg）を必ず除外すること。 未ログイン時に 404 エラーが出る原因になる。

2.3 layout.tsx に ClerkProvider

テンプレート: references/template-clerk-provider.tsx

注意: ClerkProvider はビルド時に publishableKey を要求する。 layout.tsx に export const dynamic = "force-dynamic" を追加すること。

2.4 Sign-In / Sign-Up ページ

テンプレート: references/template-sign-in-page.tsx

ファイルパス:

src/app/sign-in/[[...sign-in]]/page.tsx
src/app/sign-up/[[...sign-up]]/page.tsx

2.5 旧認証ファイル削除

• src/app/api/auth/[...nextauth]/route.ts
• src/app/login/page.tsx
• src/types/next-auth.d.ts

Phase 3: Webhook エンドポイント

// src/app/api/webhooks/clerk/route.ts
import { Webhook } from 'svix';
import { headers } from 'next/headers';

// user.created → upsertUser + assignOrphanedDataToUser（初回のみ）
// user.updated → upsertUser
// user.deleted → deleteUser
// ハンドラ先頭で initializeSchema() を呼ぶ（API route は layout を通らない）

Clerk Dashboard Webhook 設定:

1. Webhooks → Add Endpoint
2. URL: https://{domain}/api/webhooks/clerk
3. Events: user.created, user.updated, user.deleted
4. Signing Secret → CLERK_WEBHOOK_SECRET に設定

Phase 4: Server Actions にユーザーコンテキスト注入

テンプレート: references/template-server-actions.ts

要点:

• 全 Server Action の先頭で requireUserId() を呼ぶ
• キャッシュキーに userId を含める（マルチユーザーキャッシュ分離）
• 所有権チェックヘルパーで他ユーザーのデータへのアクセスを防止

Phase 5: DB クエリのマルチユーザー対応

全クエリ関数に userId?: string パラメータを追加し、WHERE user_id = ? で絞り込む。

JOIN クエリの注意: 複数テーブルに user_id がある場合、必ずテーブルプレフィックスを付ける。

// NG: ambiguous column name エラー
const userFilter = ' AND user_id = ?';

// OK: JOIN クエリ用
const userFilter = ' AND t.user_id = ?';       // JOIN あり
const userFilterNoAlias = ' AND user_id = ?';   // 単一テーブル

Phase 6: UI 変更

UserButton をサイドバー/ヘッダーに配置

テンプレート: references/template-ui-components.tsx

API Route の保護

import { auth } from '@clerk/nextjs/server';

const { userId } = await auth();
if (!userId) {
  return NextResponse.json({ error: '認証が必要です' }, { status: 401 });
}

Phase 7: 既存データの移行

初回デプロイ後、既存データを Clerk ユーザーに紐づける:

# 1. Clerk API でユーザー ID を取得
curl -H "Authorization: Bearer $CLERK_SECRET_KEY" \
  "https://api.clerk.com/v1/users?email_address=user@example.com"

# 2. DB で孤立データを割当
UPDATE tasks SET user_id = 'user_xxxxx' WHERE user_id IS NULL;
UPDATE projects SET user_id = 'user_xxxxx' WHERE user_id IS NULL;
INSERT INTO users (id, email, name) VALUES ('user_xxxxx', 'user@example.com', 'Name');

Phase 8: デプロイ

Vercel 環境変数

スクリプト: scripts/setup-vercel-env.sh

Clerk用の環境変数追加と旧認証変数の削除を一括で行う。

Clerk Dashboard — Google OAuth 本番設定

1. SSO connections → Google → Use custom credentials ON
2. Authorized Redirect URI をコピー
3. Google Cloud Console → OAuth client ID 作成
   • Authorized redirect URIs: Clerk の URI を貼付
4. Client I