# GitHub Copilot CLI Next.js: So arbeitest du effizient

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

Praktischer Guide: GitHub Copilot CLI in Next.js-Projekten konfigurieren, klare Prompts nutzen, Tests und Linting einsetzen und Fallstricke vermeiden.

**Kurz gesagt:**

- Eine klare .github/copilot-instructions.md hält den Agenten auf Kurs: App Router, Server Components und Route Handler folgen deinen Regeln.
- Kleine, testbare Schritte und ein kontrollierter Diff schützen vor kaputten Server/Client-Grenzen und fehlerhaftem Routing.
- AgentVera erlaubt parallele Agenten in getrennten Git-Worktrees und automatisches Code-Review mit Datei- und Zeilenverweisen.

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](/de/blog/how-to-use-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](/de/agents/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:

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

| Aufgabe | Bewährter Prompt |
|---|---|
| Neue Route | „Erstelle `src/app/checkout/page.tsx` als Server Component, die den Warenkorb aus `src/lib/cart.ts` liest und bei leerem Warenkorb zu `/cart` weiterleitet.“ |
| Route Handler | „Füge `src/app/api/webhook/route.ts` mit `POST` hinzu, der die Signatur prüft und das Event an `src/lib/events.ts` übergibt. Exportiere nur `POST`.“ |
| Client-Komponente | „Baue `src/components/client/SearchInput.tsx` mit `useState` und `useRouter`; setze `'use client'` und importiere keine Server-only-Module.“ |
| Test | „Schreibe einen Vitest-Test für `src/lib/pagination.ts`, der Edge Cases für Seite 0 und negative Werte abdeckt.“ |

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](/de/blog/ai-agent-browser-testing/). 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](/de/blog/codebase-map-for-ai-agents/) 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.

## Häufige Fragen

**Wie starte ich GitHub Copilot CLI in einem Next.js-Projekt?** Wechsle im Terminal in den Projektordner und führe copilot aus. Der Agent liest automatisch .github/copilot-instructions.md oder AGENTS.md und orientiert sich an den dort hinterlegten Befehlen und Konventionen.

**Welche Anweisungen braucht GitHub Copilot CLI für Next.js?** Definiere Build-, Test- und Lint-Befehle, die Ordnerstruktur, Server-/Client-Component-Regeln und den Umgang mit Route Handlers. So vermeidet der Agent falsche Imports und kaputte Builds.

**Kann der Agent Server Components und Client Components korrekt unterscheiden?** Ja, wenn die Regeln in den Projektanweisungen dokumentiert sind. Er setzt 'use client' gezielt ein und hält Server-only-Code aus Client-Komponenten fern; prüfe den Diff dennoch.

**Wie teste ich Änderungen von GitHub Copilot CLI in Next.js?** Lass den Agenten nach jeder Änderung npm test -- --run, npm run lint und bei Bedarf npm run build ausführen. Für UI-Flows eignen sich Playwright-Tests, die der Agent ebenfalls schreiben und starten kann.

---

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