Claude Code × Next.js：AI生成コードのApp Routerミスを防ぐ方法

// NG — 不要なネットワークラウンドトリップ
// app/users/page.tsx (Server Component)
export default async function UsersPage() {
  const res = await fetch("http://localhost:3000/api/users");
  const users = await res.json();
  return <UserList users={users} />;
}

// OK — Server Componentで直接データベースにアクセス
// app/users/page.tsx (Server Component)
import { db } from "@/lib/db";

export default async function UsersPage() {
  const users = await db.user.findMany();
  return <UserList users={users} />;
}

// NG — ページ全体がClient Componentになる
"use client";

export default function DashboardPage() {
  // ここにあるものすべてがブラウザに送られる
}

// OK — インタラクティブな末端だけをClient Componentにする
// app/dashboard/page.tsx (Server Component — ディレクティブなし)
import { InteractiveChart } from "./interactive-chart";

export default async function DashboardPage() {
  const data = await fetchDashboardData();
  return (
    <div>
      <h1>Dashboard</h1>
      <StaticSummary data={data} />
      <InteractiveChart data={data} />
    </div>
  );
}

// NG — Suspenseが間違ったコンポーネントをラップしている
export default function Page() {
  return <AsyncDataComponent />;
}

async function AsyncDataComponent() {
  const data = await fetchData();
  return (
    <Suspense fallback={<Loading />}>
      <DataView data={data} />
    </Suspense>
  );
}

// OK — Suspenseは非同期コンポーネントを外側からラップする
export default function Page() {
  return (
    <Suspense fallback={<Loading />}>
      <AsyncDataComponent />
    </Suspense>
  );
}

async function AsyncDataComponent() {
  const data = await fetchData();
  return <DataView data={data} />;
}

// NG — Client Componentではmetadataが無視される
"use client";

export const metadata = { title: "Dashboard" };

// OK — metadataはServer Component（page.tsxまたはlayout.tsx）に書く
// app/dashboard/page.tsx ("use client" なし)
export const metadata = { title: "Dashboard" };

// NG — ミューテーション後にUIが更新されない
"use server";

export async function createPost(formData: FormData) {
  await db.post.create({ data: { title: formData.get("title") as string } });
  // UIは古いデータを表示し続ける
}

// OK — 影響するパスを再検証する
"use server";

import { revalidatePath } from "next/cache";

export async function createPost(formData: FormData) {
  await db.post.create({ data: { title: formData.get("title") as string } });
  revalidatePath("/posts");
}

// NG — redirectは内部でthrowするので、try/catchに捕まる
"use server";

export async function loginAction(formData: FormData) {
  try {
    await authenticate(formData);
    redirect("/dashboard"); // NEXT_REDIRECTがthrowされ、下のcatchに捕まる
  } catch (error) {
    return { error: "Login failed" }; // リダイレクトが発生しない
  }
}

// OK — redirectをtry/catchの外に出す
"use server";

export async function loginAction(formData: FormData) {
  let success = false;
  try {
    await authenticate(formData);
    success = true;
  } catch (error) {
    return { error: "Login failed" };
  }
  if (success) redirect("/dashboard");
}

// NG — Next.js 16では同期アクセスが削除された
import { cookies } from "next/headers";

export default function Page() {
  const cookieStore = cookies(); // Next.js 16ではビルドエラー
}

// OK — 非同期アクセスが必須
import { cookies } from "next/headers";

export default async function Page() {
  const cookieStore = await cookies();
}

# Project: Next.js 16 App Router

## Tech Stack
- Next.js 16.1 + TypeScript strict + Tailwind CSS v4
- App Router only. No Pages Router patterns
- React Server Components by default

## Critical Rules
- NEVER add "use client" to page.tsx or layout.tsx unless the entire page must be interactive
- NEVER call Route Handlers from Server Components — access data directly
- ALWAYS use async/await for cookies(), headers(), params, searchParams
- ALWAYS place Suspense boundaries OUTSIDE the async component
- ALWAYS call revalidatePath() or revalidateTag() in Server Actions after mutations
- NEVER put redirect() inside try/catch blocks

## Data Fetching
- Server Components: direct database/API access (no fetch to own Route Handlers)
- Client Components: Server Actions for mutations, Route Handlers only for third-party webhooks
- Cache: use the "use cache" directive for explicit caching

## Reference
- Read AGENTS.md for bundled Next.js docs location
- When unsure about an API, check node_modules/next/dist/docs/ first

{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    }
  }
}

# バックグラウンドで開発サーバーを起動
npm run dev

# Claude Codeを起動
claude

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx tsc --noEmit --pretty 2>&1 | head -20"
          }
        ]
      }
    ]
  }
}