Claude Code × Next.js フルスタック開発完全ガイド｜CLAUDE.mdテンプレート・use cache・Server Actions・Prisma 7対応【2026年最新】

# Next.js 16 フルスタック開発ルール

@AGENTS.md

## プロジェクト構成
- Next.js 16 App Router専用（Pages Router/getServerSideProps/getStaticPropsは使用禁止）
- TypeScript strict: true（anyは禁止、unknownかgenericsを使う）
- Tailwind CSS v4（tailwind.config.tsは不要、globals.cssの@themeで設定）
- shadcn/ui v4（CLIでインストール、直接編集禁止）
- Prisma 7（importパスは@/generated/prisma/client、@prisma/clientは不可）
- Zod（バリデーション統一）

## ディレクトリ構造
src/
  app/           # App Router（page.tsx, layout.tsx, loading.tsx, error.tsx必須）
  components/    # UIコンポーネント
  actions/       # Server Actions（"use server"専用ファイル）
  lib/           # DB接続（db.ts）・ユーティリティ
  types/         # 型定義

## コンポーネントルール（重要）
- デフォルトはServer Components
- "use client"はonClick/useState/useEffectなどインタラクションが必要な箇所のみ
- データ取得のためだけにClient Componentにしない
- Server Componentsでasync/awaitを使いDBを直接取得する
- loading.tsxとerror.tsxをすべての非同期ルートに追加する

## データ取得・変更のルール
- データ取得: Server ComponentsでPrisma/Drizzleを直接await
- ミューテーション: Server Actions（"use server" + Zodバリデーション + revalidatePath）
- 内部データアクセスにAPIルートを使わない（webhookや外部公開APIのみRoute Handlers使用）
- useEffectでの初期データ取得は禁止

## キャッシング（Next.js 16の"use cache"）
- 静的コンテンツ: "use cache"ディレクティブ + cacheLife()
- キャッシュ無効化: cacheTag() + revalidateTag()（Server Actions内）
- "use cache"内でcookies()/headers()を直接呼ばない（外で読んで引数として渡す）

## Next.js 16の変更点（必ず従うこと）
- params/searchParams/cookies()/headers()/draftMode()はすべてPromise型→awaitが必要
- middleware.tsはproxy.tsにリネーム推奨（新しいプロジェクト）
- Turbopackがデフォルトバンドラー（webpackは--webpackフラグで切替）
- next lintコマンド廃止（ESLintを直接使う）

## Prisma 7の変更点
- importパス: @/generated/prisma/client（@prisma/clientは廃止）
- @prisma/adapter-pgが必須: npm install @prisma/adapter-pg pg
- P2002エラーのmeta.targetの取得方法が変更（コードコメントで補足）

## 禁止事項
- Pages Router/getServerSideProps/getStaticPropsの使用
- any型の使用
- useEffectでのデータフェッチ
- 内部データアクセスにAPIルートを使う
- shadcn/uiコンポーネントの直接編集
- キャッシュ設定なしの裸のfetch()

# NG: 意図が不明確
「ユーザー一覧コンポーネントを作って」

# OK: Server Componentsを意図として明示
「ユーザー一覧のServer Componentを作ってください。
- DBから直接データを取得（useEffectは不使用）
- loading.tsxとerror.tsxも作成
- ページネーションはsearchParamsで管理
- 検索フィールドのみ別途Client Componentとして分離」

// app/users/page.tsx（Server Component）
import { Suspense } from "react";
import { db } from "@/lib/db";
import { UserList } from "@/components/user-list";
import { UserSearch } from "@/components/user-search"; // Client Component

type Props = {
  searchParams: Promise<{ page?: string; q?: string }>;
};

export default async function UsersPage({ searchParams }: Props) {
  // Next.js 16: searchParamsはPromise型→awaitが必要
  const { page = "1", q = "" } = await searchParams;

  const users = await db.user.findMany({
    where: q ? { name: { contains: q } } : undefined,
    take: 20,
    skip: (Number(page) - 1) * 20,
    select: { id: true, name: true, email: true, createdAt: true },
  });

  return (
    <div>
      {/* 検索は状態管理が必要なのでClient Component */}
      <UserSearch defaultValue={q} />
      <Suspense fallback={&lt;div&gt;読み込み中...&lt;/div&gt;}&gt;
        <UserList users={users} />
      </Suspense>
    </div>
  );
}

src/actions/post.tsにブログ投稿のServer Actionsを実装してください。

仕様:
- createPost: タイトル・コンテンツを受け取りDBに保存
- updatePost: IDと更新内容を受け取り更新
- deletePost: IDを受け取りソフトデリート

実装規約:
- "use server"ディレクティブ必須
- Zodで入力バリデーション
- 戻り値: { success: boolean, error?: string, data?: T } の統一フォーマット
- revalidatePath("/posts")でキャッシュ再検証
- エラーメッセージは日本語で
- 未認証の場合はunauthorizedError()を返す

"use server";

import { z } from "zod";
import { revalidatePath } from "next/cache";
import { db } from "@/lib/db";

const createPostSchema = z.object({
  title: z.string().min(1, "タイトルを入力してください").max(200),
  content: z.string().min(1, "本文を入力してください"),
});

type ActionResult<T = void> = {
  success: boolean;
  error?: string;
  data?: T;
};

export async function createPost(
  formData: FormData
): Promise<ActionResult<{ id: string }>> {
  const raw = {
    title: formData.get("title"),
    content: formData.get("content"),
  };

  const parsed = createPostSchema.safeParse(raw);
  if (!parsed.success) {
    return { success: false, error: parsed.error.errors[0].message };
  }

  try {
    const post = await db.post.create({
      data: {
        title: parsed.data.title,
        content: parsed.data.content,
        status: "DRAFT",
      },
      select: { id: true },
    });
    revalidatePath("/posts");
    return { success: true, data: { id: post.id } };
  } catch {
    return { success: false, error: "投稿の作成に失敗しました" };
  }
}

src/lib/queries.tsにブログ投稿の取得関数を実装してください。

キャッシング要件:
- 投稿一覧: 1時間キャッシュ。投稿が変更されたら無効化
- 投稿詳細: 1日キャッシュ。その投稿が更新されたら無効化
- Next.js 16の"use cache"ディレクティブを使う

"use cache";

import { cacheLife, cacheTag } from "next/cache";
import { db } from "./db";

// 投稿一覧: 1時間キャッシュ
export async function getPosts() {
  cacheLife("hours");       // 1時間キャッシュ
  cacheTag("posts");        // revalidateTag("posts")で無効化

  return db.post.findMany({
    where: { status: "PUBLISHED", deletedAt: null },
    orderBy: { publishedAt: "desc" },
    take: 20,
    select: { id: true, title: true, publishedAt: true },
  });
}

// 投稿詳細: 1日キャッシュ（投稿IDごとにタグを設定）
export async function getPostById(id: string) {
  cacheLife("days");        // 1日キャッシュ
  cacheTag("posts", `post-${id}`);  // 個別無効化も可能

  return db.post.findUnique({
    where: { id, status: "PUBLISHED" },
    include: { author: { select: { name: true } } },
  });
}

"use server";

import { revalidateTag } from "next/cache";
import { db } from "@/lib/db";

export async function updatePost(id: string, data: { title: string }) {
  await db.post.update({ where: { id }, data });

  // この投稿のキャッシュだけを無効化
  revalidateTag(`post-${id}`);
  // 一覧のキャッシュも無効化
  revalidateTag("posts");

  return { success: true };
}

# shadcn/ui Skillをインストール
npx shadcn@latest skills add

# Claude Codeで自動的にコンテキストが補完される
# → shadcn/uiの最新APIに基づいたコードが生成される

# 変更内容を事前確認（ファイル変更なし）
npx shadcn@latest add button --dry-run

# 差分を確認
npx shadcn@latest add button --diff

# プリセットで設定を一括投入
npx shadcn@latest init --preset a1Dg5eFl

shadcn/uiを使って投稿フォームを作成してください。

使用コンポーネント:
- Form（react-hook-form統合版）
- Input（タイトル）
- Textarea（本文）
- Select（カテゴリ選択）
- Button（送信・下書き保存）

仕様:
- Server Actionsと接続
- バリデーションエラーをフォームフィールドに表示
- 送信中はボタンをdisabled + loading spinner表示
- 成功時にtoastで通知

npm install prisma@latest @prisma/adapter-pg pg
npx prisma init --datasource-provider postgresql

import { PrismaPg } from "@prisma/adapter-pg";
// Prisma 7: importパスが変更（@prisma/client → @/generated/prisma/client）
import { PrismaClient } from "@/generated/prisma/client";
import { Pool } from "pg";

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const adapter = new PrismaPg(pool);

const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };

export const db =
  globalForPrisma.prisma ??
  new PrismaClient({ adapter });

if (process.env.NODE_ENV !== "production") {
  globalForPrisma.prisma = db;
}

# .mcp.jsonに設定を追加
{
  "mcpServers": {
    "nextjs-devtools": {
      "command": "npx",
      "args": ["@next/devtools-mcp"]
    }
  }
}

# Claude Codeのターミナルで
> 現在のビルドエラーの詳細を確認して原因を特定して

> /_next/data/...のこのページのハイドレーションエラーを調査して

> Turbopackのバンドル結果を確認して、バンドルサイズが大きいモジュールを特定して

# → Claude CodeがDevTools MCP経由でNext.jsのデバッグ情報に直接アクセスする

# Step 1: スキーマ設計
「schema.prismaを作成してください。
エンティティ: User, Post（下書き/公開）, Tag（多対多）
N+1対策のインデックス設計も含めてください」

# Step 2: Server Actions生成
「src/actions/post.tsにPostのCRUD Server Actionsを実装してください。
Zodバリデーション + { success, error?, data? } フォーマット統一」

# Step 3: ページとコンポーネント生成
「app/posts/page.tsxを作成してください。
- Server Componentで投稿一覧を取得
- use cacheで1時間キャッシュ
- shadcn/uiのCardコンポーネントで表示
- searchParamsによるページネーション」

# Step 4: フォームUI生成
「app/posts/new/page.tsxに投稿作成フォームを作成してください。
- shadcn/uiのForm（react-hook-form統合版）を使用
- Server Actionsと接続
- バリデーションエラー表示・成功時toast通知」

# Step 5: ビルド確認
「next buildを実行して、エラーや警告があれば修正してください」