Opencode für Next.js: so arbeitet der Coding-Agent

opencode ist ein Coding-Agent, den Sie im Projektordner mit opencode starten. Für Next.js lohnt sich das besonders, weil der Agent Dateien lesen, ändern und Projektbefehle wie pnpm lint oder pnpm test ausführen kann. Mehr zur Einrichtung von opencode finden Sie in der Projektdokumentation.

Warum opencode für Next.js-Arbeit geeignet ist

Next.js-Projekte folgen starken Konventionen: App Router, Server Components, Route Handlers, Layouts und Middleware. Genau diese wiederkehrenden Muster lassen sich in AGENTS.md beschreiben. opencode kann diese Datei lesen, relevante Dateien im Projekt finden und Änderungen vorschlagen oder direkt umsetzen. Im Gegensatz zu einem generischen Chat-Assistenten führt es Befehle wie next build, next lint oder den Test-Runner aus und nutzt die Fehlerausgabe als Feedback. Dadurch entsteht ein kurzer Zyklus: Code ändern, Test laufen lassen, Diff prüfen, nächsten Schritt planen. Das passt gut zu inkrementellen Aufgaben wie dem Hinzufügen einer API-Route, dem Umbau einer Komponente in eine Client Component oder dem Schreiben von Tests. Da Next.js viele Dateigrenzen und Konventionen hat, profitiert ein Agent davon, wenn er nicht nur Code generiert, sondern auch die Projektstruktur versteht. opencode kann gezielt nach vorhandenen Komponenten, Hooks und Hilfsfunktionen suchen und diese wiederverwenden.

Projekt für den Agenten einrichten: AGENTS.md

opencode liest beim Start die Datei AGENTS.md im Projektstamm. Für ein Next.js-Projekt sollte sie mindestens die Befehle, Ordnerkonventionen und Regeln zu Server/Client-Komponenten enthalten. Je präziser diese Datei ist, desto weniger muss der Agent raten. Ein kurzes Beispiel:

# AGENTS.md
## Befehle
- Installieren: pnpm install
- Dev-Server: pnpm dev
- Lint: pnpm lint
- Typecheck: pnpm typecheck
- Test: pnpm test -- --run
- E2E: pnpm test:e2e

## Konventionen
- App Router unter src/app, Route Handlers in src/app/api.
- Server Components sind Standard; `use client` nur wenn nötig.
- Client-Komponenten in src/components/client, Server-only-Helfer in src/server.
- Datenabruf nur in Server Components, Route Handlers oder Server Actions.
- Next-spezifische APIs wie cookies, headers und redirect nur in Server-Umgebung verwenden.

## Regeln
- Vor jeder Änderung den betroffenen Test ausführen.
- Keine großen Refactorings in einem Schritt.
- Bei Fehlern zuerst Typecheck und Lint ausführen.
- Änderungen an next.config oder middleware.ts separat reviewen.

Passen Sie die Befehle an Ihren Package Manager an. Bei Pages Router ersetzen Sie src/app durch pages und ergänzen Regeln zu getServerSideProps und getStaticProps. Wichtig ist, dass der Agent weiss, welche Bereiche er anfassen darf und welche Prüfungen er nach einer Änderung ausführen soll. Vermeiden Sie zu lange AGENTS.md; zehn bis zwanzig Zeilen reichen meist, damit der Agent die wichtigsten Entscheidungen trifft. Eine ausführliche Anleitung zum Einstieg finden Sie unter opencode verwenden: Schritt-für-Schritt-Anleitung.

Arbeitsablauf: planen, kleine Schritte, Tests, Diff prüfen

Ein produktiver Loop sieht so aus: Zuerst beschreiben Sie die Aufgabe mit Dateipfad und erwartetem Verhalten. Dann lässt opencode einen kleinen Schritt umsetzen, zum Beispiel eine Datei anlegen oder eine Funktion ändern. Danach führen Sie oder der Agent die relevanten Tests aus, mindestens aber Lint und Typecheck. Prüfen Sie anschließend den Diff mit git diff; bei Next.js sind feine Unterschiede zwischen Server- und Client-Code oft erst im Diff sichtbar. Erst wenn der Schritt grün ist, folgt der nächste.

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

• „Erstelle die Route app/api/feedback/route.ts mit POST-Handler, validiere das JSON mit Zod und schreibe einen Vitest-Test für Erfolgsfall und Fehlerfall.“
• „Wandle die Komponente ProductCard in eine Client Component um, verschiebe den Datenabruf in die Server Component ProductList und reiche die Daten als Props weiter.“
• „Behebe den ESLint-Fehler in app/dashboard/page.tsx, ohne das Verhalten zu ändern.“
• „Schreibe einen Playwright-Test für den Checkout-Flow vom Warenkorb bis zur Bestellbestätigung.“
• „Analysiere die Server-/Client-Grenzen in src/app/checkout und schlage eine minimale Aufteilung vor, die ohne neue Abhängigkeiten auskommt.“

Geben Sie bei jedem Prompt den genauen Pfad an; das reduziert Fehlversuche und unnötige Datei-Suchen.

Typische Next.js-Aufgaben und Stolperfallen

opencode ist stark bei Aufgaben, die klaren Mustern folgen: neue Route Handlers, Server Actions, Datenabruf mit fetch und Revalidierung, Umwandlung von Server- zu Client-Komponenten, Testgenerierung und Beheben von TypeScript- sowie ESLint-Fehlern. Weniger gut eignet es sich für Architekturänderungen, die mehrere Bereiche gleichzeitig betreffen, etwa die Migration von Pages Router zu App Router. Dort ist eine enge Begleitung nötig.

Die häufigsten Stolperfallen sind die Server-/Client-Grenze und das Caching. Der Agent verwendet gelegentlich cookies, headers oder redirect in einer Komponente, die später als Client Component markiert wird. Das fällt erst beim Build auf. Prüfen Sie deshalb jede Änderung an Komponenten, die Daten laden oder mit dem Request arbeiten. Ebenso kritisch sind fetch-Aufrufe ohne cache-Option, fehlende revalidatePath-Aufrufe nach Mutationen und dynamische APIs in statisch gerenderten Seiten. Wenn der Agent next.config, middleware.ts oder layout.tsx ändert, sollte das immer separat im Diff geprüft werden, weil diese Dateien das Verhalten der ganzen Anwendung beeinflussen.

Testen und Verifizieren mit dem Agenten

Lassen Sie den Agenten Tests schreiben, aber verlassen Sie sich nicht blind darauf. Als Mindestprüfung nach jeder Änderung eignen sich pnpm lint, pnpm typecheck und der betroffene Unit-Test. Für Next.js ist ein anschließender pnpm build besonders wertvoll, weil er Server-/Client-Fehler, dynamische Render-Probleme und fehlende Suspense-Grenzen sichtbar macht. Bei API-Routen und Server Actions sollten Unit-Tests mit Vitest oder Jest die Handler isoliert testen; echte Netzwerkaufrufe gehören gemockt. Für kritische Flows wie Checkout oder Login lohnt sich ein Playwright-Test, der den gesamten Ablauf im Browser prüft. Wenn der Agent einen Test erzeugt, prüfen Sie, ob er auch Fehlerfälle abdeckt und nicht nur den Happy Path. Bei Pages Router ersetzen Sie den Build-Check durch next build ebenfalls, achten Sie aber auf getStaticProps und getServerSideProps, die oft zusätzliche Typen benötigen.

Mehrere Agenten mit AgentVera auf einem Next.js-Projekt

Für größere Next.js-Projekte kann AgentVera helfen, opencode parallel zu anderen Coding-Agenten laufen zu lassen. Die Desktop-App führt die echten CLI-Tools in getrennten Terminal-Panels aus. Für Next.js besonders nützlich sind parallele Git-Worktrees, damit mehrere Agenten gleichzeitig an verschiedenen Routen oder Komponenten arbeiten, ohne Dateien zu überschreiben. Die automatische Code-Review nach jedem Turn fängt typische Fehler wie falsche Server-/Client-Grenzen oder vergessene Revalidierung ab. Token-Budgets pro Agent und Turn verhindern, dass lange Build- und Testläufe das Budget sprengen. Checkpoints erlauben, einen fehlerhaften Schritt per Klick zurückzunehmen, falls eine Änderung den Build oder die Hydration bricht. Mehr zu solchen Setups unter parallele KI-Coding-Agenten.

Fazit

opencode ist für Next.js-Arbeit dann stark, wenn das Projekt klare Regeln in AGENTS.md hat und Sie den Agenten in kleinen, testbaren Schritten einsetzen. Die größte Aufmerksamkeit verdienen Server-/Client-Grenzen, Caching und Build-Ausgaben. Wer diese Punkte im Diff und mit pnpm build absichert, bekommt einen produktiven Assistenten für Routen, Server Actions und Tests – ohne die Kontrolle über die Architektur abzugeben.