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.
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:
# 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.
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
/dashboardim App Router, inklusiveloading.tsxunderror.tsx. - Setze den Warenkorb-Button in
app/cart/cart-button.tsxals Client Component um. NutzeuseState, halte den Rest der Seite als Server Component. - Schreibe
app/api/orders/route.tsmitPOST, validiere den Body mit zod und gib bei ungültigen Daten 422 zurück. - Refaktoriere die Produktliste so, dass sie per
fetchmitnext: { 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).
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.