Claude Code で Next.js アプリを作る

問題：Next.js 16 をゼロからセットアップするのは、それなりに時間がかかります。App Router はメジャーバージョンごとに破壊的変更があり、async params に初日からつまずき、Claude の学習データはフレームワークのリリースより速く古くなります。Claude に助けられるより、Claude を直してばかりになってしまうのです。

手っ取り早い解決策：まっさらな create-next-app プロジェクトから Claude Code を起動し、ブリーフィングは AGENTS.md に任せましょう。Claude は最初の 1 ファイルに触れる前に、同梱の Next.js 16 ドキュメントを読みます：

npx create-next-app@latest my-app --typescript --tailwind --app --turbopack
cd my-app
claude

始める前に

3 つそろえておく必要があります。

Node.js 20.9.0 以降。 Next.js 16 は Node 18 のサポートを打ち切りました。バージョンを確認しましょう：

node --version

Claude Code をグローバルにインストール：

npm install -g @anthropic-ai/claude-code

Claude Pro または Team のサブスクリプション。 Claude Code は Anthropic アカウントを使います。無料ティアでは動きません。

TypeScript 5.1 以降。 Next.js 16 がこれを必要とします。create-next-app@latest を --typescript つきで実行すれば、適切なバージョンが入ります。

Git と GitHub リポジトリがあれば、Vercel へのデプロイが 1 ステップになります。必須ではありませんが、デプロイの章では両方ある前提で進めます。

プロジェクトを作る

create-next-app@latest は、Turbopack・TypeScript・Tailwind CSS v4 を組み込んだ Next.js 16 プロジェクトの雛形を作ります。Turbopack は今やデフォルトのバンドラで、Webpack を置き換えました。Fast Refresh は以前のセットアップより最大 10 倍速く、コールドビルドは 2〜5 倍速くなります。

雛形を作りましょう：

npx create-next-app@latest my-app --typescript --tailwind --app --turbopack
cd my-app

プロジェクトのルートにある 2 つのファイルが Claude Code にとって重要です。AGENTS.md と CLAUDE.md です。canary リリースは両方を自動生成します。stable リリースでは、手で作る必要があるかもしれません。

もし無ければ、同梱ドキュメントを読み込ませる 1 行を書いた AGENTS.md をプロジェクトルートに作ります：

node_modules/next/dist/docs/

次に、それをインポートする CLAUDE.md を作ります。それ以外に何を加えるかは次の章で扱います。

AGENTS.md が重要な理由： これは Claude を node_modules/next/dist/docs/ の同梱ドキュメントへ案内します。Claude は学習データに頼る代わりに、セッション開始時にこれらのドキュメントを読みます。Next.js のベンチマークでは、同梱ドキュメントを持つエージェントは Next.js の eval で 100% に達しました。持たないエージェントは、Next.js 16 で入った破壊的な API 変更を見落とします。

CLAUDE.md は @AGENTS.md のインポート構文を使い、ルールをコピーせずに取り込みます：

@AGENTS.md

Claude はコードを書く前に両方のファイルを読みます。

CLAUDE.md をカスタマイズする

自動生成された CLAUDE.md は Next.js の慣習をカバーしています。その上に、自分のプロジェクトのスタックを加えましょう：

@AGENTS.md

## Stack

- Next.js 16 with App Router (TypeScript)
- Tailwind CSS v4 with shadcn/ui components
- PostgreSQL via Supabase (use server-side client for Server Components)
- oRPC with Zod for type-safe API routes

## File Conventions

- Server Components by default. Add "use client" only when you need browser APIs or interactivity.
- Route handlers go in app/api/[route]/route.ts
- Database queries run in lib/db.ts, never inline in components

## Commands

- Dev server: npm run dev
- Type check: npx tsc --noEmit
- Build: npm run build

## Proxy

- Middleware logic lives in proxy.ts, not middleware.ts (Next.js 16)

proxy.ts のメモは、明示的に加えておく価値があります。Claude はいまだにデフォルトで middleware.ts に手を伸ばします。CLAUDE.md に 1 行入れておけば、毎回このミスを防げます。

CLAUDE.md は具体的に保ちましょう。曖昧な指示（「きれいなコードを書け」）では Claude の振る舞いは変わりません。具体的なファイルパス、コマンド、命名規則は変えてくれます。

Claude Code で App Router を理解する

App Router はコンポーネントを 2 つのカテゴリに分けます。Server Components はサーバー上で動き、データを直接フェッチできます。Client Components はブラウザで動き、インタラクティブな部分を担います。

Claude は App Router のルールを AGENTS.md から読み、あなたが指定しなくても境界を正しく扱います。デフォルトは Server Component です。useState、useEffect、ブラウザ API、イベントハンドラが必要なときだけ、ファイルの先頭に "use client" を加えます。

Next.js 16 には React 19.2 が同梱されています。これには View Transitions、useEffectEvent、そして <Activity /> コンポーネントが含まれます。これらは新しすぎて、Claude の学習データではうまくカバーされていないかもしれません。React 19 の API を使う場合は、CLAUDE.md に明示的な例を加えるか、API 名ではなく振る舞いの言葉で何をしたいか説明してください。

Claude にダッシュボードページを作ってと頼むと、データのフェッチを Server Component に置き、結果をプロップスとしてインタラクティブな部分へ渡してくれます：

claude "build a /dashboard page that fetches user stats from the database and shows them in a summary card with a refresh button"

Claude はツリーの上部に Server Component を生成し、更新ボタン用に Client Component を作り、両者を繋ぎます。どちらがどのコンポーネントかをあなたが指定する必要はありません。Claude が AGENTS.md からルールを読んで判断します。

機能をエンドツーエンドで作る

具体的な手順を見てみましょう。サーバーサイドのデータとクライアントサイドの編集フォームを持つユーザープロフィールページです。

コードを書き始める前に、まず plan mode から入ります：

claude --plan "add a /profile page with server-fetched user data and an editable display name form"

Claude は必要なファイルを洗い出します。ページコンポーネント、フォーム送信用の Server Action、データベースクエリのヘルパー、フォーム用の Client Component です。あなたは計画をレビューします。それから Claude が作ります。

ページファイルは、Next.js 16 で必須となった async params を使います：

// app/profile/[id]/page.tsx
import { ProfileForm } from "@/components/profile-form";
import { getUser } from "@/lib/db";

interface PageProps {
  params: Promise<{ id: string }>;
}

export default async function ProfilePage({ params }: PageProps) {
  const { id } = await params;
  const user = await getUser(id);

  return (
    <main className="max-w-lg mx-auto py-12">
      <h1 className="text-2xl font-bold mb-6">Your Profile</h1>
      <ProfileForm user={user} />
    </main>
  );
}

params オブジェクトは Next.js 16 では Promise です。await params が必須です。AGENTS.md があれば Claude はこれを正しく扱います。無ければ、Claude は古い同期パターンを書いてしまい、ビルドが型エラーで失敗します。

フォーム用の Server Action は別ファイルに置きます：

// app/profile/actions.ts
"use server";

import { updateUser } from "@/lib/db";

export async function updateDisplayName(userId: string, name: string) {
  await updateUser(userId, { displayName: name });
}

Claude が対処してくれる Next.js 16 の落とし穴

Next.js 14/15 からのいくつかの破壊的変更は、AGENTS.md が無いと Claude がつまずきます。あれば、これらは正しく動きます。

Cache Components と "use cache" ディレクティブ。 Next.js 16 は experimental.dynamicIO を "use cache" ディレクティブに置き換えました。キャッシュしたいコンポーネントや関数の先頭に加えます：

// app/stats/page.tsx
"use cache";

import { getStats } from "@/lib/db";

export default async function StatsPage() {
  const stats = await getStats();
  return <pre>{JSON.stringify(stats, null, 2)}</pre>;
}

Claude は新しいファイルではディレクティブを正しく生成します。Next.js 15 から移植したコードについては、Claude に明示的にこう伝えてください：「このファイルを experimental.dynamicIO から use cache ディレクティブに移行して」。

デフォルトの Turbopack。 npm run dev は Turbopack を使います。next.config.ts の Webpack 設定は、カスタムローダーがない限りほとんど無関係です。Claude はこれを AGENTS.md から知っているので、Webpack 特有の設定を生成しません。

Next.js DevTools MCP

Next.js 16 には、AI 支援のデバッグ用に Model Context Protocol サーバーが同梱されています。これは Claude にルーティングのコンテキスト、ブラウザとサーバーの統合ログ、そしてセッション内でのエラースタックトレースへの自動アクセスを与えます。

Claude Code の設定で、同梱の MCP サーバーを指定して接続します：

{
  "mcpServers": {
    "nextjs-devtools": {
      "command": "node",
      "args": ["node_modules/next/dist/mcp/index.js"]
    }
  }
}

DevTools MCP がアクティブなら、Claude はログをコピペしなくてもキャッシュの問題を診断できます。なぜルートが古いデータを返しているのか Claude に尋ねると、サーバーログを直接読み、キャッシュキーを辿り、どの revalidateTag() 呼び出しを加えるべきか教えてくれます。

これが無いと、Claude はコードだけから診断します。あれば、ライブのランタイムデータから診断します。この違いが最も効いてくるのは、バグが本番でしか出ないときです。

DevTools MCP は、実行時のルーティングツリーへのアクセスも Claude に与えます。新しいルートを追加してと頼んで、それが既存の動的セグメントと衝突する場合、MCP はそれを即座に表面化させます。実行時に自分で見つける必要がなくなるのです。ネストされたレイアウト、並列ルート、インターセプトルートを持つ複雑な App Router の構成では、そのコンテキストはどのセッションでも持っておく価値があります。

リリース前のクオリティゲート

コミットのたびに 2 つのコマンドを走らせます。

エラーゼロで型チェック：

npx tsc --noEmit

Turbopack でクリーンな本番ビルド：

npm run build

何か大きな変更をしたら、Claude に両方を実行させましょう：

claude "run tsc --noEmit and fix any type errors, then confirm the build passes"

Claude はエラー出力を読み、問題を直し、チェックを再実行します。async params のミス、抜けた "use cache" ディレクティブ、設定ミスの Server Actions が、本番に到達する前にここで表面化します。

型エラーゼロとクリーンなビルドが、リリースの最低ラインです。提案ではありません。このチェックは毎回走ります。

Vercel にデプロイする

Vercel は Next.js 16 を自動で検出します。デプロイの方法は 2 つです。

Git 連携： main ブランチにプッシュすれば Vercel がビルドします。初回デプロイの前に、Vercel ダッシュボードの Settings > Environment Variables で環境変数を設定してください。Vercel はビルド出力を読み、どのルートが静的・動的・キャッシュ済みかを推論します。

CLI デプロイ： まず環境変数を設定してからプッシュします：

npx vercel env add DATABASE_URL production
npx vercel env add NEXT_PUBLIC_SUPABASE_URL production
npx vercel --prod

Next.js 16 のビルドログは、各ルートのレンダリング戦略を出力サイズと並べて表示します。静的ルートは緑、動的ルートは黄色で表示されます。これでビルド時に何が事前レンダリングされ、各リクエストで何が走るかが正確にわかります。

静的になると思っていたルートが動的と表示された場合、DevTools MCP が理由の診断を助けてくれます。多くの場合、キャッシュされていないデータフェッチが、ルートをリクエスト時に走らせる原因です。

オーケストレーションされたパイプラインとはどんなものか

1 つの Claude Code セッションは機能をうまく扱います。協調されたパイプラインはプロダクトを扱います。

Build This Now は、機能をリリースする前に、プランニング・ビルド・評価・テストにわたって 32 体の専門エージェントを動かします。コードが書かれる前に 3 体のプランニングエージェントが並列で働きます。ビルドの後、敵対的な評価者が出力をレビューし、ビルダーが指摘された点を直します。2 体のテストエージェントが並列で走り、うち 1 体は実際のブラウザを使います。すべての機能は、型エラーゼロ、lint エラーゼロ、クリーンな Turbopack ビルドの状態でパイプラインを抜けます。

このガイドの最後にある npx tsc --noEmit のチェックが、その最後のゲートです。オーケストレーションされたパイプラインでは、エージェントの引き継ぎごとに自動で走ります。

AGENTS.md をセットアップし、具体的な CLAUDE.md を書き、複雑な機能の前には plan mode を使い、コミットのたびにクオリティゲートを走らせる。この 4 つの習慣が、Next.js 16 での Claude Code の workflow を信頼できるものにする要素のほとんどをカバーします。フレームワークは変わります。プロセスは変わりません。