GitHub Copilot CLI Next.js: So arbeitest du effizient

GitHub Copilot CLI lässt sich direkt im Next.js-Projektordner mit copilot starten und arbeitet dann als Coding-Agent an deinem Code. Dieser Guide zeigt, wie du das Projekt für den Agenten vorbereitest, typische Next.js-Aufgaben mit klaren Prompts steuerst und Änderungen sauber verifizierst. Eine Einführung zum Start mit copilot findest du in der Schritt-für-Schritt-Anleitung zu GitHub Copilot CLI.

Warum GitHub Copilot CLI für Next.js-Arbeit passt

Next.js-Projekte bestehen aus vielen zusammenhängenden Dateien: Layouts, Seiten, Route Handlers, Server Actions und Komponenten. Der Agent kann mehrere Dateien in einem Arbeitsschritt ändern, Befehle wie npm test oder npm run build ausführen und das Ergebnis anhand der Ausgabe iterieren. Anders als ein Chat im Browser liest er den tatsächlichen Arbeitsbaum, führt Tests aus und verarbeitet Diffs.

Für Next.js zahlt sich das besonders aus, weil viele Aufgaben klare Datei- und Importsregeln haben. Der Agent kann neue Routen unter src/app anlegen, Server Components als Standard verwenden und Client Components gezielt mit 'use client' markieren, wenn diese Regeln in den Projektanweisungen stehen. Auch das Umstellen von <img> auf next/image, das Erzeugen von Route Handlers mit korrekten HTTP-Methoden und das Schreiben von Tests sind wiederkehrende Aufgaben, die sich gut als kleine Agentenaufträge formulieren lassen. Die Agent-Funktionen selbst sind auf der Seite zu GitHub Copilot CLI beschrieben.

Projekt für den Agenten einrichten

Damit der Agent nicht raten muss, legst du eine Datei .github/copilot-instructions.md oder AGENTS.md im Projektstamm ab. GitHub Copilot CLI liest sie beim Start und nutzt sie als fachliche Projektanweisung. Für ein Next.js-Projekt gehört dort mindestens hinein: der Paketmanager und die Befehle für Install, Dev, Lint, Test und Build, die Ordnerkonventionen für src/app, src/components und src/lib, die Server-/Client-Component-Regeln und Hinweise zu Route Handlers und Umgebungsvariablen.

Ein realistisches Beispiel:

# Anweisungen für GitHub Copilot CLI

## Befehle
- Installieren: `npm ci`
- Entwicklung: `npm run dev`
- Lint: `npm run lint`
- Tests: `npm test -- --run`
- Build: `npm run build`

## Next.js-Konventionen
- App Router unter `src/app`; Pages Router nur, wenn dort bereits Dateien liegen.
- Komponenten sind Server Components, außer sie haben `'use client'`.
- Client-Komponenten nur in `src/components/client`; keine Server-only-Imports dort.
- Route Handler in `src/app/api/**/route.ts`; exportiere `GET`, `POST`, `PUT`, `DELETE` statt einer Default-Funktion.
- Datenbankzugriffe nur in Server Components, Route Handlers oder Server Actions.
- Nutze `next/image` statt `<img>` und `next/link` statt `<a>`.
- Keine Secrets in Variablen mit `NEXT_PUBLIC_`.

## Tests
- Unit- und Integrationstests mit Vitest in `src/**/*.test.{ts,tsx}`.
- E2E-Tests mit Playwright in `e2e/`; vorher `npm run build` und `npm run start`.

Diese Datei hält den Agenten davon ab, App-Router- und Pages-Router-Muster zu mischen oder eine Client-Komponente mit Server-only-Code zu bauen. Passe die Befehle an dein Projekt an: mit Jest ersetzt du npm test -- --run durch npm test -- --watchAll=false, mit pnpm durch pnpm test -- --run.

Arbeitsablauf: Plan, kleine Schritte, Tests, Diff

Ein stabiler Loop sieht so aus: Beschreibe zuerst das Ziel und die betroffenen Dateien. Lass den Agenten einen kleinen, in sich geschlossenen Schritt umsetzen. Danach führst du Tests und Lint aus oder lässt den Agenten das selbst tun. Lies den Diff mit git diff, bevor du den nächsten Schritt startest. So bleiben Fehler lokal und du kannst Server-/Client-Grenzen früh erkennen.

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

• „Erstelle eine Server Component src/app/dashboard/page.tsx, die Daten über eine Server Action aus src/lib/data.ts lädt und bei leerem Zustand einen Link zu /setup zeigt. Halte die Komponente server-only.“
• „Füge einen Route Handler src/app/api/export/route.ts hinzu, der als POST einen CSV-Export aus src/lib/export.ts zurückgibt. Exportiere nur POST und schreibe einen Vitest-Test für die Exportfunktion.“
• „Refaktoriere src/components/client/FilterPanel.tsx zu einer Client Component mit useState und useRouter. Achte auf 'use client' und entferne alle Server-only-Imports. Führe danach npm test und npm run lint aus.“
• „Ersetze alle <img> in src/components durch next/image und behebe alle Lint-Warnungen aus npm run lint.“
• „Schreibe einen Playwright-Test, der den Login-Flow in /login abdeckt. Nutze die bestehende Konfiguration und starte den Server nicht selbst.“

Die Prompts nennen Dateipfade, erwartete Exporte und Verifikationsbefehle. Dadurch bleibt der Agent fokussiert und liefert prüfbare Änderungen.

Typische Next.js-Aufgaben und Stolperfallen

Gut geeignet sind Aufgaben, die sich über mehrere Dateien erstrecken, aber klare Regeln haben: neue Seiten und Layouts, Route Handlers, Server Actions, Metadaten, Umstieg auf next/image oder next/link, Tests für Utilities und UI-Flows, Refactorings mit TypeScript. Die folgende Tabelle zeigt bewährte Prompts.

Beobachte den Agenten besonders an diesen Stellen: Er setzt 'use client' manchmal zu breit, wenn eine Komponente nur einen kleinen interaktiven Teil braucht. Er kann window oder document in einer Server Component verwenden, wenn die Anweisungen das nicht ausschließen. In App Router sind params und searchParams in vielen Fällen asynchron; der Agent muss sie mit await behandeln. Nach Mutationen vergisst er gelegentlich revalidatePath oder revalidateTag, sodass die UI veraltete Daten zeigt. Route Handlers benötigen benannte Exporte, keine Default-Exporte. Und bei Secrets besteht die Gefahr, dass sie in eine Client-Komponente wandern, wenn nur NEXT_PUBLIC_ dokumentiert ist.

Testen und Verifizieren

Nach jeder Agentenänderung solltest du mindestens npm test -- --run, npm run lint und bei strukturellen Änderungen npm run build ausführen. Der Build fängt TypeScript-Fehler und Probleme beim Server-Rendering, während ESLint viele Next.js-spezifische Regeln prüft, etwa falsche <img>-Nutzung oder fehlende alt-Attribute. Der Agent kann diese Befehle selbst starten, wenn sie in den Projektanweisungen stehen.

Für UI-Flows lohnt sich Playwright: Der Agent kann Tests schreiben und gegen einen laufenden Dev- oder Produktionsserver ausführen. Mehr dazu, wie ein Agent Browser-Tests selbst prüft, findest du im Artikel zu KI-Agent Browser-Tests. Wenn der Agent Dateien sucht oder du vor einem größeren Refactoring eine Übersicht brauchst, hilft eine Codebase-Map, wie im Beitrag Codebase-Map für KI-Agenten beschrieben. Prüfe zusätzlich den Diff gezielt auf Server-/Client-Grenzen: Client-Komponenten dürfen keine Server-only-Imports wie fs, server-only oder Datenbank-Clients enthalten.

Mehrere Agenten mit AgentVera

Wenn du an mehreren Next.js-Features parallel arbeiten willst, hilft AgentVera: Es führt GitHub Copilot CLI und andere CLI-Agenten in echten Terminal-Panels aus. Jeder Agent kann in einem eigenen Git-Worktree arbeiten, sodass sich parallele Änderungen an Server Components, Route Handlers und Tests nicht überschreiben. Nach jedem Turn prüft ein zweites Modell den Code und verlinkt Findings auf Datei und Zeile, was Server-/Client-Grenzen absichert. Checkpoints erlauben das Zurücksetzen einzelner Turns, und Token-Budgets stoppen Agenten bei Erreichen des Limits, ohne die Konversation zu verlieren.

Fazit

Mit einer klaren .github/copilot-instructions.md, kleinen Prompts und konsequenter Verifikation wird GitHub Copilot CLI zu einem nützlichen Werkzeug für Next.js-Arbeit. Starte mit eng umrissenen Aufgaben, lies jeden Diff und erweitere den Einsatz erst, wenn der Loop stabil läuft. So bekommst du die Produktivität eines Coding-Agenten, ohne die Kontrolle über Server-/Client-Grenzen, Routing oder Tests abzugeben.