Knowledge

Cursor, Claude Code, GitHub Copilot — jeder KI-Coding-Agent, den dein Team einsetzt, wurde mit Daten aus einer Zeit trainiert, in der Next.js den Pages Router, getServerSideProps und useEffect für alles bedeutete. 2026 ist das der falsche Default. App-Router-Projekte mit React Server Components, Server Actions und dem neuen Caching-Modell sind ein anderes Programmiermodell, und Agenten erzeugen kaputten oder unsicheren Code, wenn du ihnen das nicht explizit beibringst.

Dieser Artikel ist die Regeldatei, die wir in jedes Next.js-Projekt einbauen, das wir bei Softescu leiten. Kopiere sie in .cursorrules, claude.md oder AGENTS.md, passe die projektspezifischen Teile an — und dein Agent hört auf, Pages-Router-Muster aus 2022 zu halluzinieren. Wenn du das größere Bild zum Bau von KI-Features in Next.js-Apps suchst, deckt unser Next.js-KI-Entwicklungsguide die Produktionsmuster ab.

Das Format — agents.md, claude.md, .cursorrules

Drei Dateinamen, dieselbe Idee: eine Markdown-Datei im Projekt-Root, die der Agent bei jedem Prompt liest und als System-Kontext nutzt.

• AGENTS.md — der vorgeschlagene offene Standard. Gelesen von OpenAI Codex, Aider und einer wachsenden Liste von Agenten.
• .cursorrules — die Projekt-Regeldatei der Cursor-IDE. 2025 durch .cursor/rules/*.mdc abgelöst, beide funktionieren weiterhin.
• claude.md oder CLAUDE.md — wird von Claude Code beim Sitzungsstart automatisch geladen, sowohl global (in ~/.claude/) als auch projektspezifisch (im Arbeitsverzeichnis).

Alle drei sind reines Markdown. Die folgenden Regeln funktionieren in jeder davon.

Regel 1 — Server Components sind der Default

Jede Komponente in app/ ist eine Server Component, sofern sie sich nicht explizit mit 'use client' abmeldet. Markiere eine Datei nur dann mit 'use client', wenn die Komponente eine der folgenden Stellen nutzt:

• React-State (useState, useReducer)
• React-Effekte (useEffect, useLayoutEffect)
• Browser-spezifische APIs (window, localStorage, IntersectionObserver)
• In JSX angehängte Event-Handler (onClick, onChange, onSubmit)
• Drittanbieter-Bibliotheken, die auf einem davon beruhen

Anti-Pattern: 'use client' auf app/layout.tsx oder auf einer Seite mit überwiegend statischem Inhalt. Das zwingt den ganzen Teilbaum in das Client-Bundle und löscht den größten Performance-Vorteil des Frameworks.

Regel 2 — Server Actions, nicht API Routes, für Mutationen

Für Formularübermittlungen und jede durch eine Nutzeraktion ausgelöste Mutation innerhalb der App nimm eine Server Action. Greife nur dann zu einer API Route (app/api/foo/route.ts), wenn der Endpunkt von außerhalb der App aufrufbar sein muss — durch Mobile-Clients, Webhooks, Drittanbieter-Services oder geplante Jobs.

// app/contact/page.tsx
async function submit(formData: FormData) {
  'use server'
  await db.contactSubmissions.create({
    email: formData.get('email'),
    message: formData.get('message'),
  })
  revalidatePath('/contact')
}

export default function ContactPage() {
  return <form action={submit}>…</form>
}

Anti-Pattern: ein Agent erzeugt /api/contact/route.ts plus ein clientseitiges fetch('/api/contact', { method: 'POST' }) für ein Formular, das nur diese App absendet. Zwei Dateien, ein zusätzlicher Netzwerk-Hop, kein Progressive Enhancement, kein eingebauter CSRF-Schutz.

Regel 3 — Daten in Server Components laden, niemals in useEffect

Wenn eine Seite Daten aus der Datenbank oder von einer externen API braucht, lade sie in der Server Component und reiche sie als Props weiter. Erzeuge keine Client Component mit useEffect(() => { fetch(…) }, []).

// app/posts/page.tsx — Server Component
import { db } from '@/server/db'

export default async function PostsPage() {
  const posts = await db.posts.findMany()
  return <PostList posts={posts} />
}

Anti-Pattern: jedes useEffect, das initiale Daten lädt. Das ist ein 2021er Muster. Die einzige legitime Verwendung von useEffect in Next.js 2026 ist die Integration mit imperativen Browser-APIs — Canvas, Video, Geolocation, WebSocket.

Regel 4 — Edge Runtime ist Opt-in

Das Standard-Runtime ist Node.js. Setze export const runtime = 'edge' nur, wenn:

• Die Route latenzkritisch und global verteilt ist (Auth-Checks, Geo-Routing, A/B-Tests).
• Der Code ausschließlich Edge-kompatible APIs nutzt (Web Crypto, fetch, Headers; kein Node fs, kein crypto.createHash, kein Buffer).
• Das Bundle klein ist (Edge hat auf den meisten Hosts ein Limit von ~1 MB komprimiert).

Anti-Pattern: ein Agent fügt runtime = 'edge' zu einer Route hinzu, die Prisma, den Node-Client von Drizzle oder eine Bibliothek importiert, die crypto/fs nachzieht. Der Build scheitert in Produktion, geht aber in der Entwicklung durch — genau der Fehlermodus, den du nicht willst.

Regel 5 — Dateistruktur

app/                    # nur Routen — Seiten, Layouts, Route Handler
components/             # präsentationelle React-Komponenten, kein Data-Fetching
lib/                    # framework-unabhängige Utilities, Typen, Validatoren
server/                 # server-only Code: DB-Client, Auth, KI-Provider
public/                 # statische Assets

server/ existiert, damit der Agent ein klares Ziel für Code hat, der niemals das Client-Bundle erreichen darf. Markiere Datenbank-Verbindungsdateien mit import 'server-only' am Dateianfang — der Build scheitert hörbar, sobald eine Client-Komponente sie importiert.

Anti-Pattern: Agenten, die pages/-, services/-, utils/- oder hooks/-Verzeichnisse anlegen, weil ihre Trainingsdaten diese Konventionen nutzen. Lass das Parallel-Universum nicht zu.

Regel 6 — URL-State schlägt Client-State

Wenn ein Stück State sinnvoll per URL teilbar wäre — Filter, Pagination, Sortierreihenfolge, der offene Tab auf einer Einstellungsseite — speichere es per searchParams (Server Components) oder useSearchParams (Client Components) in der URL. Es überlebt Reloads, lässt sich teilen und wird von Suchmaschinen indiziert.

Greife nur dann zu Zustand, Jotai oder Redux, wenn es sich um echten Client-only-State handelt, der nicht in die URL passt: ein offenes Modal, ein laufender Drag-Vorgang, ein ungespeicherter Formular-Entwurf.

Anti-Pattern: „aktuelle Seite = 3" in Zustand zu speichern, obwohl ?page=3 dasselbe kostenlos leistet — mit teilbaren Links und funktionierendem Zurück-Button.

Regel 7 — Streaming mit Suspense für langsame Daten

Wenn eine Server Component auf etwas Langsames wartet — einen LLM-Aufruf, eine Vektorsuche, eine Drittanbieter-API — verpacke es in <Suspense> und übergib die wartende Kind-Komponente als Grenze. Der Rest der Seite rendert sofort; der langsame Teil streamt nach, sobald er bereit ist.

export default function Page() {
  return (
    <>
      <Header />
      <Suspense fallback={<Skeleton />}>
        <SlowRecommendations />
      </Suspense>
    </>
  )
}

Anti-Pattern: eine einzige async Page-Komponente, die alles sequenziell awartet, bevor das erste Byte rausgeht. Langsame Time-to-first-Byte ohne Grund.

Regel 8 — Cache explizit, nicht zufällig

Next.js 15 hat Caching zum Opt-in gemacht. Der Agent soll jeden fetch und jede Route mit einer expliziten Caching-Absicht annotieren:

• fetch(url, { cache: 'force-cache' }) — statisch, dauerhaft gecacht
• fetch(url, { next: { revalidate: 60 } }) — ISR, alle 60 s aktualisieren
• fetch(url, { cache: 'no-store' }) — immer frisch
• Setze 'use cache' auf teure Server Components, die memoisiert werden sollen
• Setze export const dynamic = 'force-dynamic' auf Routen, die niemals gecacht werden dürfen (auth-gated, personalisiert)

Anti-Pattern: sich stillschweigend auf den Default verlassen. Verschiedene Next.js-Versionen, Hoster und Umgebungen wählen verschiedene Defaults. Explizite Annotationen machen die Absicht des Agenten überprüfbar.

Die vollständige Kontextdatei zum Kopieren

Füge den Block unten in AGENTS.md, .cursorrules oder claude.md ein (oder in alle drei — sie sind identisch). Passe die Stack-Zeilen am Ende an dein Projekt an und committe sie zusammen mit dem Code. Der Block ist auf Englisch, weil ihn der KI-Agent liest:

# Next.js Rules for AI Agents

This is a Next.js 15+ App Router project. Follow these rules when generating
or editing code.

## Server Components by default
- Every component in `app/` is a Server Component.
- Mark a file `'use client'` only if it uses: useState, useEffect, browser
  APIs, JSX event handlers, or libraries that need any of those.
- Never put `'use client'` on a layout or a mostly-static page.

## Server Actions for mutations
- Forms and in-app mutations use Server Actions (`'use server'`).
- API Routes (`app/api/*/route.ts`) are only for external callers: mobile
  clients, webhooks, scheduled jobs.

## Data fetching
- Fetch in Server Components, pass data down as props.
- Do not use `useEffect` to load initial data.
- `useEffect` is only for imperative browser APIs (canvas, video, etc).

## Edge Runtime
- Default is Node.js. Do not set `runtime = 'edge'` unless explicitly asked.
- If switching to edge: only Web APIs, no Node `fs`/`crypto`/`Buffer`, bundle
  under ~1 MB.

## File structure
- `app/`        — routes only (pages, layouts, route handlers)
- `components/` — presentational React, no data fetching
- `lib/`        — framework-agnostic utilities, types, validators
- `server/`     — server-only code; add `import 'server-only'` at the top
- `public/`     — static assets
- Do not create `pages/`, `services/`, `utils/`, or `hooks/` directories.

## State
- URL state (`searchParams`, `useSearchParams`) beats client state.
- Use Zustand/Jotai/Redux only for state that cannot reasonably live in
  the URL (open modals, drag state, unsaved drafts).

## Streaming
- Wrap slow Server Components in `<Suspense fallback={…}>`.
- Do not await everything in one async page component.

## Caching
- Annotate every fetch: `cache: 'force-cache' | 'no-store'` or `next.revalidate`.
- Use `'use cache'` on expensive Server Components.
- Use `export const dynamic = 'force-dynamic'` on auth-gated / personalised
  routes.

## Project stack (edit per project)
- TypeScript strict mode
- Tailwind CSS + shadcn/ui
- Drizzle ORM + Postgres
- Auth.js (NextAuth) for authentication
- Vercel AI SDK for LLM calls (server-side only)
- Zod for runtime validation

Wie wir das bei Softescu einsetzen

Wir pflegen eine Basisversion dieser Datei in unseren Next.js-Kundenprojekten und versionieren sie zusammen mit dem Code. Zwei Konventionen, die wir immer obenauf legen:

1. Ein Verzeichnis server/ai/ für LLM-Provider-Clients, Prompts und Rate Limits — nur aus Server Actions referenziert, nie aus Client-Komponenten.
2. Eine Notiz in der Regeldatei, welche Logging- oder Analytics-Tags der Agent beim Erzeugen neuer Seiten setzen soll — wir betreiben OpenPanel in unseren Projekten, und der Agent setzt die richtigen Data-Attribute zuverlässig, wenn die Regeldatei sie erwähnt.

Die Regeldatei ist keine einmalige Einrichtung. Wir behandeln sie wie eine CI-Konfiguration: erzeugt ein Agent Code, der nicht zu einer Projekt-Konvention passt, korrigieren wir entweder das Agenten-Verhalten über eine neue Regel oder akzeptieren, dass die Konvention sich geändert hat, und aktualisieren die Codebasis. So oder so ist die Datei die Single Source of Truth.

Wenn dein Team ein Next.js-Projekt startet und Hilfe bei einem KI-Agenten-freundlichen Setup sucht — Regeldateien, Struktur, RAG-Muster für KI-Funktionen in der App selbst — meld dich gern.