Mit Codex kannst du in einem Next.js-Projekt direkt im Terminal arbeiten: codex im Projektordner starten, und der Agent liest die Projektdateien sowie die AGENTS.md. Er eignet sich für Komponenten, Route Handler, Tests und Refactorings, wenn du ihm klare Konventionen gibst. Dieser Leitfaden zeigt einen praxistauglichen Ablauf, typische Prompts und die Punkte, an denen du den Diff genauer prüfen solltest.
Warum Codex zu Next.js-Arbeit passt
Codex arbeitet mit echten Dateien und Shell-Kommandos, nicht nur mit Chat-Antworten. Das passt gut zu Next.js, weil das Framework klare Dateikonventionen hat: App Router unter app, Route Handler unter app/**/route.ts, Server Components als Standard. Der Agent kann so aus einer Aufgabenbeschreibung den richtigen Dateipfad ableiten und direkt Änderungen vorschlagen. Die Grundlagen zum CLI-Agenten findest du auf Codex.
Zwei Dinge entscheiden über die Qualität: die AGENTS.md mit projektspezifischen Regeln und ein Arbeitsablauf, der nach jedem Schritt testet. Ohne diese Leitplanken generiert Codex oft plausible, aber für Next.js falsche Lösungen, etwa window in einer Server Component oder einen fehlenden revalidatePath nach einer Datenmutation.
Projekt für den Agenten einrichten
Lege im Projektstamm eine AGENTS.md an. Codex liest sie beim Start automatisch. Die Datei sollte kurz und verbindlich sein: Befehle, Ordnerkonventionen und Regeln, die für Next.js spezifisch sind. Ein Beispiel:
# AGENTS.md
## Befehle
- Installieren: `npm ci`
- Lint: `npm run lint`
- Unit-Tests: `npm test` (Vitest)
- Build: `npm run build`
- E2E-Tests: `npm run e2e` (Playwright)
## Ordnerkonventionen
- App Router unter `src/app`, Server Components sind Standard.
- Client Components nur wenn nötig, mit `"use client"` als erster Zeile.
- Route Handler unter `src/app/api/**/route.ts`.
- Datenzugriff zentral in `src/lib/data.ts`, keine Fetch-Calls direkt in Komponenten.
## Regeln
- Keine Server-only-Imports (z. B. `fs`, `process.env`) in Client Components.
- Bei Datenmutationen immer `revalidatePath` oder `revalidateTag` prüfen.
- Vor Abschluss immer Lint, Tests und Build ausführen.
- Keine neuen Abhängigkeiten ohne Rückfrage.Eine solche Datei beantwortet die häufigsten Rückfragen, bevor sie entstehen. Ergänze bei Bedarf Hinweise zu deinem Test-Setup, zu Server Actions oder zu Auth-Grenzen.
Ein Arbeitsablauf für Codex und Next.js
Arbeite in kleinen, testbaren Schritten. Starte mit einer Planungsaufforderung, dann implementiere, teste und review den Diff. Eine Schritt-für-Schritt-Einführung zum CLI findest du unter Codex CLI nutzen: Schritt-für-Schritt-Anleitung.
Typische Prompts für den Einstieg:
- „Erstelle eine Server Component
src/app/dashboard/page.tsx, die Produkte aussrc/lib/products.tslädt und als Tabelle ausgibt. Fügeloading.tsxunderror.tsxhinzu.“ - „Implementiere den Route Handler
POST /api/checkoutmit Zod-Validierung. Schreibe dazu Vitest-Tests für gültige, ungültige und leere Requests.“ - „Wandle
src/components/ProductList.tsxin eine Client Component mit Suchfeld um. Achte darauf, dass die Server-Daten als Props übergeben werden unduse clientganz oben steht.“ - „Lass
npm run lint,npm testundnpm run buildlaufen und behebe alle Fehler in der Reihenfolge ihres Auftretens.“ - „Ergänze einen Playwright-Test für den Checkout-Flow und fixe den fehlgeschlagenen Test
checkout.spec.ts.“
Nach jeder Antwort: git diff ansehen, Tests ausführen und erst dann den nächsten Schritt starten. So bleiben Fehler lokal und nachvollziehbar. Wenn du mit dem App Router arbeitest, begrenze den Prompt auf eine bestimmte Datei, damit der Agent nicht ungefragt mehrere Segmente umbaut.
Typische Next.js-Aufgaben und typische Fallstricke
Codex ist stark bei schematischen Arbeiten: neue Routen, Formulare, API-Endpunkte, Tests, Refactorings über mehrere Dateien. Die folgende Tabelle zeigt, welche Aufgaben gut funktionieren und wo du besonders hinschauen solltest.
| Aufgabe | Guter Prompt (Kurzform) | Worauf du achten solltest |
|---|---|---|
| Server Component | „Erstelle src/app/transactions/page.tsx mit Daten aus src/lib/transactions.ts“ | Keine Browser-APIs oder Hooks; Daten-Fetching nur serverseitig |
| Route Handler | „POST /api/transactions mit Zod-Validierung und korrekten Statuscodes“ | Nicht mit Server Actions verwechseln; Cache- und Revalidate-Header prüfen |
| Client Component | „Baue TransactionFilter mit useState, Props und onChange“ | "use client" nicht vergessen; keine Server-only-Imports |
| Server Action | „Ersetze den API-Call im Formular durch eine Server Action in src/app/actions.ts“ | Nur für Mutationen; Authentifizierung, Fehlerbehandlung und revalidatePath beachten |
Die größten Fallstricke liegen an der Client/Server-Grenze. Codex neigt dazu, eine Komponente vorschnell mit use client zu markieren oder umgekehrt Server-only-Code in eine Client-Komponente zu ziehen. Prüfe deshalb bei jedem Diff, welche Datei auf welcher Seite läuft. Achte auch auf Caching: Next.js cached Route Handler und Seiten standardmäßig. Fehlt export const dynamic = 'force-dynamic' oder ein revalidatePath, bleiben Änderungen unsichtbar. Bei Server Actions muss klar sein, wer sie aufrufen darf; Codex implementiert oft keine Auth-Prüfung. Auch Umgebungsvariablen sind eine häufige Fehlerquelle: Nur Variablen mit NEXT_PUBLIC_-Präfix sind im Client sichtbar. Codex verwendet gelegentlich private Variablen in Client Components und findet den Fehler erst beim Build. Eine zweite Modellprüfung, wie sie KI-Code-Review: Prüfe, was deine Agenten schreiben beschreibt, hilft, solche Fehler systematisch zu finden.
Testen und Verifizieren mit Codex in Next.js
Definiere für Codex eine feste Verifikationskette: npm run lint, npm test und npm run build. Gerade npm run build ist in Next.js wichtig, weil er TypeScript prüft und alle Seiten vorrendert; viele Fehler erscheinen erst hier. Für kritische Flows lass Playwright-Tests laufen, bevor du eine Änderung als fertig betrachtest. Codex kann Testausgaben lesen und gezielt nachbessern. Verlange nach jeder Aufgabe eine kurze Zusammenfassung der geänderten Dateien und der ausgeführten Befehle. Review den Diff selbst mit git diff und achte auf unerwartete Dateien, neue Abhängigkeiten oder auskommentierte Testfälle.
Mehrere Agenten mit AgentVera in einem Next.js-Projekt
Bei größeren Next.js-Projekten kannst du mehrere CLI-Agenten mit AgentVera parallel arbeiten lassen. Jeder Agent läuft in einem eigenen Terminal-Panel und kann in einem eigenen Git-Worktree arbeiten, sodass sich Änderungen an App Router, Route Handlern und Tests nicht gegenseitig überschreiben. Wenn ein Agent fertig ist, prüft ein zweites Modell automatisch den Code und meldet Fundstellen mit Datei und Zeile – das fängt Client/Server-Fehler früh. Checkpoints pro Turn lassen sich per Klick zurücksetzen, was bei einem kaputten Build schnell hilft. Mehr zum Ablauf findest du unter KI-Agent-Workflow: Teams, Parallelteile und Flows.
Fazit
Codex wird in einem Next.js-Projekt dann produktiv, wenn die AGENTS.md klare Konventionen setzt, die Aufgaben klein bleiben und die Verifikationskette konsequent läuft. Nutze die Dateikonventionen des App Router als Leitplanken, lass den Agenten Lint, Tests und Build ausführen und prüfe Client/Server-Grenzen sowie Caching selbst. Mit AgentVera kannst du diese Arbeitsweise auf mehrere parallele Agenten ausweiten, ohne die Kontrolle über den Diff zu verlieren.