Eine Next.js-App mit Claude Code bauen

Problem: Next.js 16 von Grund auf einzurichten kostet echt Zeit. Der App Router bringt mit jeder Major-Version Breaking Changes, async params bringen dich schon am ersten Tag aus dem Tritt, und Claudes Trainingsdaten veralten schneller, als das Framework releast. Am Ende korrigierst du Claude mehr, als es dir hilft.

Quick Win: Starte Claude Code aus einem frischen create-next-app-Projekt und lass AGENTS.md das Briefing übernehmen. Claude liest die mitgelieferten Next.js-16-Docs, bevor es auch nur eine Datei anfasst:

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

Bevor du anfängst

Drei Dinge müssen stehen.

Node.js 20.9.0 oder neuer. Next.js 16 hat den Support für Node 18 fallengelassen. Prüf deine Version:

node --version

Claude Code global installiert:

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

Ein Claude-Pro- oder Team-Abo. Claude Code nutzt deinen Anthropic-Account. Der Free-Tier funktioniert nicht.

TypeScript 5.1+. Next.js 16 braucht es. Wenn du create-next-app@latest mit --typescript ausführst, wird die richtige Version gleich mitinstalliert.

Git und ein GitHub-Repo machen das Vercel-Deployment zu einem einzigen Schritt. Nicht zwingend nötig, aber der Deploy-Abschnitt setzt beides voraus.

Das Projekt anlegen

create-next-app@latest scaffoldet ein Next.js-16-Projekt mit Turbopack, TypeScript und Tailwind CSS v4, alles verdrahtet. Turbopack ist jetzt der Standard-Bundler und löst Webpack ab. Fast Refresh läuft bis zu 10-mal schneller als beim alten Setup, und Cold Builds sind 2- bis 5-mal schneller.

Führ das Scaffold aus:

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

Zwei Dateien im Projekt-Root sind für Claude Code wichtig: AGENTS.md und CLAUDE.md. Das canary-Release generiert beide automatisch. Im Stable-Release musst du sie eventuell selbst anlegen.

Falls sie fehlen, leg AGENTS.md im Projekt-Root an, mit einer Zeile, die die mitgelieferten Docs lädt:

node_modules/next/dist/docs/

Dann leg CLAUDE.md an, das sie importiert. Der nächste Abschnitt zeigt, was darüber hinaus reingehört.

Warum AGENTS.md wichtig ist: Es verweist Claude auf die mitgelieferte Dokumentation unter node_modules/next/dist/docs/. Claude liest diese Docs beim Session-Start, statt sich auf Trainingsdaten zu verlassen. In Next.js-Benchmarks erreichen Agents mit mitgelieferten Docs 100 % bei den Next.js-Evals. Agents ohne sie übersehen die Breaking-API-Changes, die in Next.js 16 eingeführt wurden.

CLAUDE.md nutzt die @AGENTS.md-Import-Syntax, um diese Regeln einzuziehen, ohne sie zu kopieren:

@AGENTS.md

Claude liest beide Dateien, bevor es Code schreibt.

CLAUDE.md anpassen

Das automatisch generierte CLAUDE.md deckt die Next.js-Konventionen ab. Pack den Stack deines Projekts obendrauf:

@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)

Den Hinweis zu proxy.ts solltest du explizit aufnehmen. Claude greift standardmäßig immer noch nach middleware.ts. Eine Zeile in CLAUDE.md verhindert diesen Fehler jedes Mal.

Halt CLAUDE.md konkret. Vage Anweisungen („schreib sauberen Code") ändern Claudes Verhalten nicht. Konkrete Dateipfade, Kommandos und Namenskonventionen schon.

Den App Router mit Claude Code verstehen

Der App Router teilt Komponenten in zwei Kategorien. Server Components laufen auf dem Server und können Daten direkt holen. Client Components laufen im Browser und kümmern sich um Interaktivität.

Claude liest die App-Router-Regeln aus AGENTS.md und trifft die Grenze richtig, ohne dass du es vorgibst. Der Standard ist Server Component. Du fügst "use client" nur oben in eine Datei ein, wenn du useState, useEffect, Browser-APIs oder Event-Handler brauchst.

Next.js 16 kommt mit React 19.2. Das umfasst View Transitions, useEffectEvent und die <Activity />-Komponente. Die sind so neu, dass Claudes Trainingsdaten sie womöglich nicht gut abdecken. Für alles, was React-19-APIs nutzt, füg explizite Beispiele zu CLAUDE.md hinzu oder beschreib, was du willst, über das Verhalten statt über API-Namen.

Bitte Claude, eine Dashboard-Seite zu bauen, und es platziert den Daten-Fetch in der Server Component und reicht die Ergebnisse als Props an alle interaktiven Teile weiter:

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

Claude generiert die Server Component an der Spitze des Baums, erstellt eine Client Component für den Refresh-Button und verdrahtet sie miteinander. Du gibst nicht vor, welche Komponente was ist. Claude liest die Regeln aus AGENTS.md und findet es heraus.

Ein Feature von Anfang bis Ende bauen

Hier ein konkreter Durchlauf: eine User-Profilseite mit serverseitigen Daten und einem clientseitigen Bearbeitungsformular.

Starte im Plan mode, bevor irgendein Code geschrieben wird:

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

Claude skizziert die Dateien, die es braucht: eine Page-Komponente, eine Server Action für den Formular-Submit, einen Datenbankabfrage-Helper und eine Client Component für das Formular. Du prüfst den Plan. Dann baut es.

Die Page-Datei nutzt async params, wie es Next.js 16 verlangt:

// 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>
  );
}

Das params-Objekt ist in Next.js 16 ein Promise. await params ist Pflicht. Claude macht das korrekt, wenn AGENTS.md vorhanden ist. Ohne es schreibt Claude das alte synchrone Muster, und der Build scheitert mit einem Typfehler.

Die Server Action fürs Formular lebt in einer eigenen Datei:

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

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

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

Next.js-16-Stolperfallen, die Claude meistert

Ein paar Breaking Changes von Next.js 14/15 bringen Claude ohne AGENTS.md aus dem Tritt. Mit ihm funktionieren sie korrekt.

Cache Components und die "use cache"-Direktive. Next.js 16 ersetzt experimental.dynamicIO durch die "use cache"-Direktive. Setz sie oben in jede Komponente oder Funktion, die du cachen willst:

// 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>;
}

Für neue Dateien generiert Claude die Direktive korrekt. Für Code, der aus Next.js 15 migriert wird, sag es Claude explizit: „migriere diese Datei von experimental.dynamicIO auf die use-cache-Direktive."

Turbopack als Standard. npm run dev nutzt Turbopack. Webpack-Config in next.config.ts ist meist irrelevant, außer du hast Custom Loader. Claude weiß das aus AGENTS.md und generiert keine Webpack-spezifische Config.

Die Next.js DevTools MCP

Next.js 16 liefert einen Model-Context-Protocol-Server für KI-gestütztes Debugging mit. Er gibt Claude Routing-Kontext, vereinte Browser- und Server-Logs und automatischen Zugriff auf Error-Stack-Traces innerhalb der Session.

Verbinde ihn in deinen Claude-Code-Einstellungen, indem du auf den mitgelieferten MCP-Server zeigst:

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

Mit aktiver DevTools MCP kann Claude ein Caching-Problem diagnostizieren, ohne dass du Logs reinkopierst. Frag Claude, warum eine Route veraltete Daten ausliefert, und es liest die Server-Logs direkt, verfolgt den Cache-Key und sagt dir, welchen revalidateTag()-Aufruf du hinzufügen musst.

Ohne das diagnostiziert Claude allein aus dem Code. Damit diagnostiziert Claude aus Live-Runtime-Daten. Dieser Unterschied zählt am meisten, wenn ein Bug nur in Produktion auftaucht.

Die DevTools MCP gibt Claude außerdem Zugriff auf den Routing-Baum zur Laufzeit. Wenn du Claude bittest, eine neue Route hinzuzufügen, und sie mit einem bestehenden dynamischen Segment kollidiert, bringt die MCP das sofort zutage, statt dass du es zur Laufzeit findest. Für komplexe App-Router-Setups mit verschachtelten Layouts, Parallel Routes und Intercepting Routes ist dieser Kontext in jeder Session sein Geld wert.

Quality Gates, bevor du auslieferst

Zwei Kommandos laufen vor jedem Commit.

Type-Check mit null Fehlern:

npx tsc --noEmit

Sauberer Production-Build mit Turbopack:

npm run build

Bitte Claude, nach jeder größeren Änderung beide laufen zu lassen:

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

Claude liest die Fehlerausgabe, behebt die Probleme und führt den Check erneut aus. Genau hier kommen async-params-Fehler, fehlende "use cache"-Direktiven und falsch konfigurierte Server Actions ans Licht, bevor sie in Produktion landen.

Null Typfehler und ein sauberer Build sind die Mindesthürde fürs Ausliefern. Keine Empfehlung. Der Check läuft jedes Mal.

Auf Vercel deployen

Vercel erkennt Next.js 16 automatisch. Zwei Optionen fürs Deploy.

Git-Integration: Push auf deinen Main-Branch, und Vercel baut es. Setz die Environment-Variablen im Vercel-Dashboard unter Settings > Environment Variables, bevor du das erste Mal deployst. Vercel liest die Build-Ausgabe und leitet daraus ab, welche Routen statisch, dynamisch oder gecacht sind.

CLI-Deploy: Setz zuerst deine Environment-Variablen, dann push:

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

Die Build-Logs in Next.js 16 zeigen die Render-Strategie jeder Route neben ihrer Output-Größe. Statische Routen sind grün, dynamische Routen gelb. Das sagt dir genau, was zur Build-Zeit vorgerendert wird und was bei jedem Request läuft.

Wenn eine Route, die du als statisch erwartet hast, als dynamisch erscheint, hilft die DevTools MCP bei der Diagnose, warum. Oft ist es ein ungecachter Daten-Fetch, der die Route zwingt, zur Request-Zeit zu laufen.

Wie eine orchestrierte Pipeline aussieht

Eine einzelne Claude-Code-Session erledigt Features gut. Eine koordinierte Pipeline erledigt Produkte.

Build This Now lässt 32 spezialisierte Agents über Planung, Bau, Bewertung und Tests laufen, bevor ein Feature ausgeliefert wird. Drei Planungs-Agents arbeiten parallel, bevor irgendein Code geschrieben wird. Nach dem Bau prüfen adversarielle Evaluatoren die Ausgabe, und die Builder beheben, was sie markieren. Zwei Test-Agents laufen parallel, einer mit einem echten Browser. Jedes Feature verlässt die Pipeline mit null Typfehlern, null Lint-Fehlern und einem sauberen Turbopack-Build.

Der npx tsc --noEmit-Check am Ende dieses Guides ist genau dieses letzte Gate. In einer orchestrierten Pipeline läuft er nach jeder Agent-Übergabe automatisch.

Richte AGENTS.md ein, schreib ein konkretes CLAUDE.md, nutz den Plan mode vor komplexen Features und lass die Quality Gates vor jedem Commit laufen. Diese vier Gewohnheiten decken das meiste davon ab, was einen Claude-Code-Workflow mit Next.js 16 zuverlässig macht. Das Framework ändert sich. Der Prozess nicht.