# Cursor Agent Next.js: praktischer Leitfaden für Entwickler

URL: https://agentvera.dev/de/blog/cursor-agent-fuer-nextjs/ · Veröffentlicht: 2026-11-01

Cursor Agent Next.js: So richtest du AGENTS.md ein, gibst Prompts für App Router und Route Handlers und prüfst jede Änderung mit Lint, Tests und Build.

**Kurz gesagt:**

- Cursor Agent arbeitet am besten mit einem klaren AGENTS.md, das Next.js-Konventionen, Befehle und Grenzen festlegt.
- In kleinen Schritten planen, Diffs prüfen und nach jeder Änderung Lint, Tests und Build laufen lassen.
- Server-/Client-Grenzen, Caching und Route Handlers sind die häufigsten Fehlerquellen; dort eng prüfen.

Mit `cursor-agent` im Next.js-Projektordner startest du einen terminalbasierten Coding-Agenten, der Dateien liest, ändert und Tests ausführen kann. Dieser Leitfaden zeigt, wie du ihn über `AGENTS.md` oder `.cursor/rules` auf App Router, Server Components, Route Handlers und deine Test-Pipeline ausrichtest und wo du bei Next.js besonders genau hinschaust. Mehr zur Einrichtung des Agenten findest du unter [Cursor Agent](/de/agents/cursor-agent/).

## Warum Cursor Agent zu Next.js-Arbeit passt

Next.js-Projekte bestehen aus vielen kleinen Konventionen: Dateinamen wie `page.tsx`, `layout.tsx`, `loading.tsx`, `route.ts`, Server- und Client-Grenzen, Caching-Regeln und Build-spezifische Fehler. Der Cursor Agent kann genau dann produktiv sein, wenn er diese Konventionen aus einer lokalen Regeldatei kennt und Befehle selbst ausführen darf. Er liest mehrere Dateien gleichzeitig, erkennt Importketten und kann Refactorings über `app/` und `src/` hinweg konsistent umsetzen. Gleichzeitig ist er kein Architekt: Die Entscheidung, was Server Component oder Route Handler wird, solltest du über Regeln und Prompts vorgeben.

## Projekt für den Agenten einrichten

Lege im Projektroot eine `AGENTS.md` an oder nutze `.cursor/rules`. Halte die Datei kurz und konkret, damit der Agent bei jeder Session dieselben Befehle und Grenzen sieht. Ein realistisches Beispiel:

```markdown
# AGENTS.md

## Befehle
- Installieren: npm ci
- Entwickeln: npm run dev
- Lint: npm run lint
- Unit/Integration: npm test -- --runInBand
- E2E: npx playwright test
- Build: npm run build

## Struktur
- App Router unter `src/app`, Pages Router nicht verwenden.
- API-Routen unter `src/app/api`.

## Next.js-Regeln
- Server Components sind Standard; `'use client'` nur bei State, Events oder Browser-APIs.
- Datenzugriffe nie im Client; Route Handlers oder Server Actions verwenden.
- Client-seitige env vars nur mit `NEXT_PUBLIC_`-Präfix.
- Fetch-Caching explizit machen: `cache: 'no-store'` oder `next: { revalidate: ... }`.
- Nach jeder Änderung: `npm run lint && npm test -- --runInBand`.
```

Die Befehle müssen zu deinem Projekt passen; ersetze `npm` durch `pnpm` oder `yarn`, falls nötig. Wichtig ist vor allem die klare Aussage, welcher Router gilt und wo Server- und Client-Code erlaubt sind. Wenn du den allgemeinen CLI-Ablauf noch nicht kennst, hilft die [Cursor CLI verwenden: Schritt-für-Schritt-Anleitung](/de/blog/how-to-use-cursor-cli/).

## Arbeitsablauf: klein planen, Diffs prüfen, Tests fahren

Ein zuverlässiger Loop sieht so aus: Erst den Agenten bitten, die betroffenen Dateien und Abhängigkeiten zu nennen, dann genau eine logische Änderung umsetzen, danach `git diff` lesen und die relevanten Tests ausführen. So verhinderst du, dass der Agent aus einem kleinen Prompt eine halbe App umbaut.

Beispiel-Prompts für typische Next.js-Aufgaben:

- Zeige zuerst die betroffenen Dateien. Ändere dann nur die Route `/dashboard` im App Router, inklusive `loading.tsx` und `error.tsx`.
- Setze den Warenkorb-Button in `app/cart/cart-button.tsx` als Client Component um. Nutze `useState`, halte den Rest der Seite als Server Component.
- Schreibe `app/api/orders/route.ts` mit `POST`, validiere den Body mit zod und gib bei ungültigen Daten 422 zurück.
- Refaktoriere die Produktliste so, dass sie per `fetch` mit `next: { revalidate: 60 }` aus einem Route Handler lädt. Kein Client-Fetch.
- Ergänze einen Vitest-Test für die Preisberechnung und einen Playwright-Smoke-Test für den Login. Führe beide aus und melde die Ergebnisse.

## Typische Next.js-Aufgaben und Stolperfallen

Die folgende Tabelle zeigt, was der Agent gut umsetzt und wo du den Diff besonders genau lesen solltest:

| Aufgabe | Guter Prompt | Worauf du prüfen solltest |
|---|---|---|
| Server Component | Erstelle `app/products/page.tsx` als Server Component, die Produkte direkt aus der Datenbank lädt. | Kein `useState`/`useEffect`; keine Secrets im Client-Bundle; Ladezustand über `loading.tsx`. |
| Client Component | Wandle nur `app/cart/cart-button.tsx` in eine Client Component um. | Import-Grenzen; keine Server-only Module; Props bleiben serialisierbar. |
| Route Handler | Schreibe `app/api/checkout/route.ts` mit POST, zod-Validierung und 422 bei Fehlern. | HTTP-Status, Fehlerbehandlung, Caching-Header, keine Browser-APIs. |
| Data Fetching & Cache | Ändere die Startseite auf `fetch` mit `next: { revalidate: 60 }`. | Revalidate-Konflikte mit dynamischen APIs, Timeouts, Segment Cache. |
| Middleware | Ergänze `middleware.ts` für Auth-Prüfung auf `/account/*`. | Edge-Laufzeit, keine Node-APIs, Matcher-Konfiguration. |
| Pages Router | Fasse die alte `pages/alt.js` nicht an; migriere sie nicht. | Keine Vermischung von `getServerSideProps` und Server Components. |

Achte besonders auf diese Punkte: Ein `'use client'` an der falschen Stelle macht schnell ganze Teilbäume clientseitig. `fetch` ohne explizite Cache-Option kann in aktuellen Next.js-Versionen unerwartet cachen oder dauerhaft dynamisch rendern. Route Handlers brauchen klare Statuscodes und dürfen keine Secrets an den Client weitergeben. Middleware läuft auf der Edge Runtime; Node-APIs wie `fs` oder `bcrypt` funktionieren dort nicht. Metadata-Exporte und Image-Konfiguration können Build-Fehler auslösen, die erst `next build` sichtbar macht.

## Testen und Verifizieren mit dem Agenten

Lass den Agenten nach jedem Schritt die Prüfkette selbst ausführen, statt nur Code zu schreiben. Die wichtigsten Befehle für ein Next.js-Projekt sind `npm run lint`, `npx tsc --noEmit`, `npm test -- --runInBand` und `npm run build`. Der Build ist in Next.js besonders wertvoll, weil er Server-/Client-Grenzen und Typfehler früh sichtbar macht. Bei UI-Flows ergänzt Playwright echte Smoke-Tests, etwa für Login, Warenkorb oder Checkout. Ein guter Prompt dafür: Erstelle einen Playwright-Test, der `/checkout` öffnet, ein Produkt hinzufügt und den Kauf abschließt. Führe ihn headless aus und behebe nur Fehler, die mit deiner Änderung zusammenhängen. Für Route Handlers kannst du Vitest oder Jest mit gemocktem `fetch` nutzen und den Handler direkt importieren; bei komplexeren Flows startest du den Dev-Server und testest per Playwright gegen echte HTTP-Antworten.

Prüfe außerdem den Diff auf unbeabsichtigte Änderungen an `next.config.*`, `middleware.ts` oder `package.json`. Gerade bei Abhängigkeiten oder Build-Konfiguration ist ein manueller Blick nötig, weil der Agent die Auswirkungen auf Deployment und Caching nicht vollständig einschätzen kann.

## Mehrere Agenten parallel mit AgentVera

Wer in einem größeren Next.js-Projekt mehrere Coding-Agenten gleichzeitig arbeiten lassen will, kann AgentVera nutzen. Die Desktop-App führt echte CLI-Agenten in eigenen Terminal-Panels aus. Für Next.js sind vor allem drei Dinge wichtig: Parallele git-Worktrees verhindern, dass sich Änderungen an `app/`, `middleware.ts` oder Tests überschreiben. Die automatische Code-Review nach jeder Runde prüft Server-/Client-Grenzen und Route Handlers. Checkpoints erlauben, riskante App-Router-Refactorings per Klick zurückzunehmen. Token-Budgets stoppen lange Sessions, bevor sie Datei für Datei umbauen. Mehr dazu unter [Parallele KI-Coding-Agenten: die besten Tools (2026)](/de/blog/best-tools-parallel-ai-coding-agents/).

## Fazit

Cursor Agent ist in Next.js-Projekten dann zuverlässig, wenn du ihm in `AGENTS.md` klare Router- und Server-/Client-Regeln mitgibst, in kleinen Schritten arbeitest und jede Änderung mit Lint, Tests und Build verifizierst. Die meiste Aufmerksamkeit verdienen Server-/Client-Grenzen, Caching und Route Handlers. Mit diesem Loop wird der Agent vom schnellen Codegenerator zu einem berechenbaren Teammitglied.

## Häufige Fragen

**Wie starte ich den Cursor Agent in einem Next.js-Projekt?** Wechsle in den Projektordner und führe cursor-agent aus. Lege vorher eine AGENTS.md oder .cursor/rules mit Build-, Test- und Lint-Befehlen sowie Next.js-Konventionen an, damit der Agent im richtigen Kontext arbeitet.

**Welche Regeln gehören in die AGENTS.md für Next.js?** Dort sollten die verwendeten Befehle stehen, ob App Router oder Pages Router gilt, wo Server und Client Components erlaubt sind, wie Route Handlers aufgebaut werden und welche env vars im Client sichtbar sind. Kurze, verbindliche Regeln verhindern die meisten Fehler.

**Kann der Cursor Agent App Router und Pages Router gemeinsam bearbeiten?** Ja, aber du solltest klar festlegen, welcher Router für neue Dateien gilt und welche Alt-Seiten unangetastet bleiben. Sonst vermischt der Agent schnell getServerSideProps mit Server Components oder legt Dateien im falschen Verzeichnis an.

**Wie teste ich Änderungen des Cursor Agents in Next.js?** Lass den Agenten nach jedem Schritt npm run lint, npm test -- --runInBand und npm run build ausführen. Für UI-Flows eignen sich Playwright-Smoke-Tests, für Route Handlers direkte Tests mit gemocktem fetch.

---

**Über AgentVera.** AgentVera ist eine Desktop-App für macOS, Windows und Linux, entwickelt von Solviera Teknoloji. Sie führt 18 KI-Coding-Agenten (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) nebeneinander aus, pro Projekt, in echten Terminals mit den eigenen CLI-Installationen und Logins des Nutzers. Der kostenlose Plan hat unbegrenzt viele Agenten. Download: https://agentvera.dev/de/download/ · Preise: https://agentvera.dev/de/pricing/