# Codex mit Next.js nutzen: ein praktischer Guide

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

So nutzt du den Coding-Agenten Codex effektiv in Next.js-Projekten: AGENTS.md, typische Aufgaben, Tests, Fallstricke und parallele Agenten mit AgentVera.

**Kurz gesagt:**

- Codex arbeitet in Next.js am besten mit klaren Konventionen in AGENTS.md, kleinen Schritten und konsequenter Verifikation.
- Typische Aufgaben sind Server Components, Route Handler, Client Components und Server Actions; der Diff-Review bleibt Pflicht.
- Mit AgentVera lassen sich mehrere Agenten in getrennten Git-Worktrees parallel an einem Next.js-Projekt einsetzen.

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](/de/agents/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:

```markdown
# 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](/de/blog/how-to-use-codex-cli/).

Typische Prompts für den Einstieg:
- „Erstelle eine Server Component `src/app/dashboard/page.tsx`, die Produkte aus `src/lib/products.ts` lädt und als Tabelle ausgibt. Füge `loading.tsx` und `error.tsx` hinzu.“
- „Implementiere den Route Handler `POST /api/checkout` mit Zod-Validierung. Schreibe dazu Vitest-Tests für gültige, ungültige und leere Requests.“
- „Wandle `src/components/ProductList.tsx` in eine Client Component mit Suchfeld um. Achte darauf, dass die Server-Daten als Props übergeben werden und `use client` ganz oben steht.“
- „Lass `npm run lint`, `npm test` und `npm run build` laufen 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](/de/blog/ai-code-review/) 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](/de/blog/ai-agent-workflow-pipeline/).

## 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.

## Häufige Fragen

**Wie starte ich Codex in einem Next.js-Projekt?** Wechsle in den Projektordner und führe codex aus. Der Agent liest dort die AGENTS.md automatisch. Danach kannst du Aufgaben in natürlicher Sprache stellen.

**Kann Codex App Router und Server Components bearbeiten?** Ja, Codex versteht die Dateikonventionen des App Router, Server- und Client Components sowie Route Handler. Wichtig ist, die Grenzen zwischen Server und Client in AGENTS.md festzuhalten.

**Welche Tests sollte ich Codex in Next.js ausführen lassen?** Mindestens Unit-Tests mit Vitest oder Jest und End-to-End-Tests mit Playwright. Codex sollte immer npm run lint, npm test und bei Bedarf npm run build ausführen.

**Wo muss ich bei Codex in Next.js besonders aufpassen?** Bei Client/Server-Grenzen, Cache-Verhalten, Server Actions und Build-Fehlern. Prüfe den Diff genau und lass keine ungetesteten Datenmutationen durchgehen.

---

**Ü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/