Gemini CLI in Next.js-Projekten: Praktischer Leitfaden

Der Coding-Agent Gemini CLI startet im Next.js-Projektordner mit gemini. Er liest die Projektdateien, befolgt die Regeln aus GEMINI.md und führt selbst Befehle wie npm run lint, npm test oder npm run build aus. Damit eignet er sich für Next.js-Arbeit, die viele Dateien und Konventionen berührt – von Route Handlers bis zu Server Components. Dieser Leitfaden zeigt, wie du ihn im Alltag mit App Router, Server Components, Testing und Fallstricken einsetzt.

Warum Gemini CLI für Next.js-Arbeit passt

Next.js-Projekte bestehen aus vielen kleinen Dateien mit starken Konventionen: app/ oder pages/, layout.tsx, page.tsx, Route Handlers, Server Actions, Server- und Client Components. Ein Terminal-Agent hat den ganzen Projektbaum im Kontext und kann Änderungen über mehrere Dateien hinweg konsistent ausführen. Er kennt TypeScript- und React-Muster, liest die next.config-Datei und kann die Next.js-Befehle direkt im Projekt ausführen. Dadurch sieht er Lint-Fehler, Build-Ausgaben und Testresultate selbst und korrigiert sich, ohne dass du jede Meldung manuell kopierst. Für wiederkehrende Aufgaben wie das Anlegen eines neuen Route Handlers samt Validierung, das Umwandeln einer Komponente in eine Client Component oder das Beheben von Hydration-Fehlern spart das spürbar Zeit. Gerade bei der Arbeit mit App Router und Server Components, wo Änderungen oft mehrere Dateien betreffen – eine Server Component für Daten, eine Client Component für Interaktion, ein Route Handler für die API –, ist die integrierte Sicht des Agenten wertvoll. Wichtig ist, dass du ihm die Projektregeln in GEMINI.md gibst; sonst arbeitet er mit generischen Annahmen und übersieht Next.js-Spezifika.

Projekt für den Agenten einrichten

Die zentrale Steuerdatei ist GEMINI.md im Projektstamm. Sie sollte kurz und verbindlich sein: Befehle, Ordnerkonventionen und Next.js-spezifische Regeln. Je präziser diese Datei ist, desto weniger muss der Agent raten. Eine gute Vorlage sieht so aus:

# GEMINI.md für Next.js

## Befehle
- Installieren: npm install
- Dev-Server: npm run dev
- Build: npm run build
- Lint: npm run lint
- Tests: npm run test (Vitest)
- E2E: npm run test:e2e (Playwright)

## Ordnerkonventionen
- App Router: app/ mit page.tsx, layout.tsx, loading.tsx, error.tsx
- Komponenten: components/ (nur wiederverwendbare UI)
- Server-Aktionen: app/actions.ts oder actions/
- Route Handlers: app/api/**/route.ts

## Regeln
- Server Components sind Default; `'use client'` nur wenn nötig.
- Keine Datenbankzugriffe in Client Components.
- Nutze next/link statt <a>.
- Halte API-Antworten schlank; verwende Route Handlers für JSON.
- Prüfe immer die Hydration: keine dynamischen Werte in Server- und Client-Rendering.

Ergänze bei Bedarf Abschnitte für Authentication, Datenbankzugriffe oder Deployment. Trage die tatsächlich genutzten Befehle ein – etwa npm run test für Vitest oder npx playwright test für Playwright. Enthält dein Projekt einen src/-Ordner oder ein Monorepo, beschreibe den Pfad eindeutig. Auch Regeln wie „Keine any-Typen“ oder „Server Actions nur in app/actions.ts“ helfen. Vermeide es, in GEMINI.md allgemeine Programmierregeln wie „Schreibe sauberen Code“ zu wiederholen; das bläht die Datei auf und verwässert die wichtigen Punkte. Die ausführliche Schritt-für-Schritt-Anleitung zeigt, wie du GEMINI.md weiter schärfst und den Agenten schrittweise einrichtest.

Ein tragfähiger Arbeitsablauf

Bewährt hat sich ein Loop aus Planen, kleinem Schritt, Tests und Diff-Review. Lass den Agenten zuerst den Plan formulieren, dann eine überschaubare Änderung umsetzen, danach npm run lint, npm test und npm run build ausführen und zeige dir am Ende den Diff mit git diff. Erst wenn Build und Tests grün sind, committest du. Dieser Ablauf ähnelt dem Pair Programming mit KI, nur dass der Agent die Ausführung übernimmt. Halte die Schritte bewusst klein: Eine neue Route plus Tests ist okay; ein komplettes Redesign nicht. So bleiben Fehler lokalisierbar und der Diff überschaubar.

Beispielprompts für typische Next.js-Aufgaben:

• „Erstelle einen Route Handler unter app/api/feedback/route.ts, der POST-Anfragen validiert und in eine SQLite-Tabelle speichert.“
• „Wandle components/UserProfile.tsx in eine Client Component um; nutze useEffect für das Laden und zeige einen Skeleton.“
• „Behebe alle ESLint-Fehler in app/dashboard/page.tsx, ohne die Server-Client-Grenze zu verletzen.“
• „Schreibe einen Vitest-Test für lib/api.ts, der den Auth-Token Header prüft.“
• „Ergänze eine Lade- und Fehler-UI für die Route /products mit loading.tsx und error.tsx.“

Diese Prompts sind bewusst auf eine Datei oder einen Aspekt begrenzt.

Typische Aufgaben und Fallstricke

Gemini CLI ist stark bei klar abgegrenzten, musterhaften Aufgaben. Besonders gut gelingt das Erstellen von Route Handlers mit Validierung, das Einrichten von Server Actions für Formulare, das Umwandeln von Komponenten in Client Components mit passenden Props und das Schreiben von Tests für Utilities und APIs. Auch Datenabrufe in Server Components direkt in der Datenbank oder über fetch mit Caching sind dank klarer Muster gut machbar.

Vorsicht ist bei drei Stellen geboten. Erstens die Server-/Client-Grenze: Der Agent setzt manchmal 'use client' zu großzügig und macht aus einer Server Component unnötig eine Client Component, oder er übersieht, dass eine importierte Komponente client-seitig sein muss. Zweitens Hydration-Fehler: Dynamische Werte wie Date.now() oder zufällige IDs ohne suppressHydrationWarning führen zu inkonsistentem Rendering. Drittens Build-Fehler durch nicht abgedeckte Importe oder falsche next.config-Einstellungen. Der Agent bemerkt sie oft erst, wenn npm run build ausgeführt wird – deshalb gehört der Build immer in den Loop. Auch das Refactoring von Seiten, die stark auf getServerSideProps im Pages Router basieren, kann schiefgehen, wenn der Agent nicht erkennt, dass der Wechsel zu App Router ein anderes Datenabrufmodell erfordert.

Testen und Verifizieren mit Gemini CLI in Next.js

Die wichtigste Verifikation ist der Produktions-Build. npm run build prüft Server-/Client-Imports, Typen und statische Optimierung. Der Dev-Server allein reicht nicht, weil er viele Fehler erst zur Laufzeit zeigt. Lass den Agenten nach jeder Änderung mindestens npm run lint und npm test ausführen. Unit-Tests mit Vitest oder Jest sollten vor allem Logik in lib/, utils/ und Server Actions abdecken. Für Integrationstests eignen sich Route Handler mit Supertest oder MSW. Führe Playwright-Tests für kritische Nutzerpfade aus, besonders nach Änderungen an Auth, Navigation oder Formularen. Der Agent kann die Tests selbst starten und auf Fehler reagieren – aber prüfe das Diff immer selbst, bevor du committest. Achte darauf, dass er keine Tests löscht oder nur oberflächlich anpasst, um sie grün zu bekommen. Ein rotes Build trotz grüner Tests ist ein Warnsignal.

Mehrere Agenten auf einem Next.js-Projekt mit AgentVera

AgentVera ist eine Desktop-App, die echte CLI-Agenten wie Gemini CLI, Claude Code und andere in eigenen Terminal-Panels parallel ausführt. Für Next.js-Arbeit ist besonders wertvoll, dass jeder Agent in einem eigenen Git-Worktree arbeiten kann – so überschreiben sich parallele Änderungen an App Router-Dateien nicht. Die automatische Codeüberprüfung durch ein zweites Modell nach jeder Agenten-Runde hilft, subtile Server-/Client-Fehler früh zu erkennen. Checkpoints erlauben es, einen fehlgeschlagenen Schritt per Klick zurückzunehmen und die Sitzung erneut abzuspielen – praktisch, wenn der Agent versehentlich Hydration-Fehler einbaut. Token-Budgets pro Agent und Tag begrenzen die Kosten, ohne die Konversation zu verlieren. So lassen sich mehrere Features gleichzeitig vorantreiben, ohne ständig manuell Branches zu wechseln. Weitere Muster dazu beschreibt der Beitrag zur KI-Agenten-Orchestrierung beim Coden.

Fazit

Gemini CLI ist ein nützlicher Pair-Programmierer für Next.js, wenn du ihn mit klaren Regeln aus GEMINI.md fütterst und in kleinen Schritten mit Build- und Test-Gate vorankommen lässt. Die typischen Fallstricke an Server-/Client-Grenze und Hydration sind beherrschbar, solange du den Diff prüfst und den Produktions-Build als oberste Instanz behandelst. Mit einem disziplinierten Loop und gelegentlich mehreren parallelen Worktrees wird der Agent zu einer echten Arbeitshilfe statt zu einem Risiko.