Cursor Composer: Multi-File-Bearbeitung, die tatsächlich funktioniert

Die meisten Cursor-Nutzer bleiben im regulären Chat. Sie fragen nach einer Funktion, kopieren die Ausgabe, fügen sie in eine Datei ein, wiederholen das. Für kleine Sachen funktioniert das. Aber wenn du fünf Dateien ändern musst, um ein Feature hinzuzufügen, fällt dieser Workflow auseinander.

Composer ist Cursors Antwort darauf. Es ist ein separates Panel, in dem du beschreibst, was du ändern möchtest, und Cursor schlägt Edits über mehrere Dateien auf einmal vor. Du prüfst, akzeptierst oder lehnst jede Änderung ab und gehst weiter. Kein Kopieren-Einfügen. Kein Kontextwechsel.

Diese Anleitung deckt reale Workflows aus dem Cursor-Forum ab. Kein Marketing-Sprech. Nur das, was funktioniert.

Composer vs Regulärer Chat: Der echte Unterschied

Regulärer Chat ist Q&A. Du fragst, Cursor antwortet. Du bist immer noch derjenige, der Code in Dateien verschiebt.

Composer ist Aktion. Du beschreibst das Ziel, Cursor ermittelt, welche Dateien angefasst werden müssen und was geändert werden soll. Es präsentiert einen Diff. Du entscheidest, was landet.

Funktion	Regulärer Chat	Composer
Schlägt Code vor	Ja	Ja
Bearbeitet Dateien direkt	Nein	Ja
Multi-File-Änderungen	Nein	Ja
Zeigt Diff vor dem Anwenden	Nein	Ja
Checkpoint/Rollback	Nein	Ja
Bestens für	Fragen, einzelne Snippets	Refactoring, Features, Batch-Updates

Das Schlüsselfeature sind Checkpoints. Composer speichert einen Snapshot, bevor es Änderungen vornimmt. Wenn der Edit schiefgeht, kehrst du mit einem Klick zum Checkpoint zurück. Regulärer Chat hat kein Sicherheitsnetz.

Wie man Composer öffnet

Drücke Cmd/Ctrl + I oder klicke auf das Composer-Icon in der linken Seitenleiste. Es ist ein separates Panel vom Chat — verwechsle die beiden nicht.

Wann Composer zu nutzen

Composer glänzt, wenn eine Aufgabe mehr als eine Datei berührt. Häufige Szenarien:

• Refactoring — eine Prop über Komponenten hinweg umbenennen, eine gemeinsame Utility extrahieren
• Feature-Arbeit — einen neuen API-Endpunkt hinzufügen, der Route-, Controller-, Service- und Testdateien benötigt
• Pattern-Updates — überall von fetch auf einen benutzerdefinierten apiClient umstellen
• Typ-Änderungen — ein Interface aktualisieren, das sich durch zehn Dateien zieht
• Import-Bereinigung — eine Modulstruktur reorganisieren

Wenn du Code aus dem Chat in mehr als zwei Dateien kopierst, hör auf. Nutze stattdessen Composer.

Composer ist nicht für alles

Schnelle Fragen, One-Liner oder "erkläre diesen Regex" — regulärer Chat ist schneller. Composer hat Overhead. Reserviere es für Multi-File-Arbeit.

Realer Workflow 1: Cross-File-Refactoring

Du hast einen User-Typ in types.ts. Du möchtest name in fullName umbenennen, weil du ein displayName-Feld hinzufügst und die Benennung jetzt verwirrend ist.

Das betrifft:

• src/types.ts — die Typdefinition
• src/components/UserCard.tsx — zeigt den Namen an
• src/components/UserProfile.tsx — zeigt ihn auch an
• src/api/users.ts — API-Aufrufe, die das Feld senden/empfangen
• src/lib/validators.ts — Zod-Schema für die User-Validierung

Schritt 1: Composer öffnen (Cmd/Ctrl + I).

Schritt 2: Die Änderung beschreiben:

Benenne das Feld `name` in `fullName` im User-Typ um und aktualisiere alle Verwendungen in der Codebase. Ändere kein Verhalten — das ist eine reine Umbenennung.

Schritt 3: Den vorgeschlagenen Diff prüfen. Composer zeigt jede Datei mit hervorgehobenen Änderungen. Prüfe, dass:

• Nur name im User-Kontext umbenannt wird (nicht andere name-Props)
• Die API-Schicht immer noch die richtigen Daten sendet/empfängt
• Keine Logik-Änderungen hereingeschlichen sind

Schritt 4: Pro Datei akzeptieren oder ablehnen. Wenn eine Datei falsch aussieht, lehne nur diese ab und behebe sie manuell.

Prüfe den Diff sorgfältig

Composer greift manchmal über das Ziel hinaus. Es könnte eine name-Prop in einer nicht verwandten Komponente umbenennen, wenn der Kontext ähnlich aussieht. Scanne den Diff immer, bevor du akzeptierst.

Realer Workflow 2: Feature über mehrere Dateien hinzufügen

Du möchtest "User-Rollen" zu deiner App hinzufügen. Admin-User sehen extra UI-Elemente und können auf extra API-Endpunkte zugreifen.

Beteiligte Dateien:

• src/types.ts — füge role: 'user' | 'admin' zu User hinzu
• src/api/auth.ts — Rolle in den JWT-Payload aufnehmen
• src/components/Navbar.tsx — Admin-Link nur für Admins anzeigen
• src/components/AdminPanel.tsx — neue Komponente
• src/hooks/useAuth.ts — isAdmin-Flag exposen
• src/middleware/auth.ts — neues Middleware zur Admin-Rollen-Prüfung

Schritt 1: Composer öffnen.

Schritt 2: Gib ihm einen Plan, nicht nur einen Wunsch:

Füge User-Rollen zur App hinzu:

1. Füge `role: 'user' | 'admin'` zum User-Typ in src/types.ts hinzu
2. Aktualisiere die Login-Antwort in src/api/auth.ts, um die Rolle im JWT-Payload aufzunehmen
3. Füge einen berechneten Wert `isAdmin` in src/hooks/useAuth.ts hinzu
4. Aktualisiere Navbar.tsx, um bedingt einen "Admin"-Link anzuzeigen, wenn isAdmin wahr ist
5. Erstelle src/components/AdminPanel.tsx mit einem Platzhalter-Admin-Dashboard
6. Erstelle src/middleware/auth.ts mit einer requireAdmin-Middleware, die die JWT-Rolle prüft

Nutze die bestehenden Patterns in der Codebase. Folge dem gleichen Fehlerbehandlungs-Stil wie andere API-Dateien.

Schritt 3: Composer generiert einen Multi-File-Diff. Prüfe jede Datei.

Schritt 4: Wenn das neue AdminPanel.tsx falsch aussieht, lehne es ab und behalte den Rest. Composer-Edits sind granulär.

Frag zuerst nach einem Plan

Bevor du Composer coden lässt, bitte ihn, den Plan zu skizzieren. Füge "Liste die Dateien, die du ändern wirst, und warum, bevor du Edits machst." hinzu. Das fängt Missverständnisse früh ab und kostet nichts.

Realer Workflow 3: Batch-Update von API-Aufrufen

Du hast mit rohen fetch-Aufrufen im Frontend begonnen. Jetzt hast du einen benutzerdefinierten apiClient mit Auth-Headern, Fehlerbehandlung und konfigurierter Basis-URL. Du musst alles migrieren.

Dateien: potenziell Dutzende von API-Aufruf-Stellen.

Schritt 1: Stelle sicher, dass apiClient existiert und in einer Datei korrekt importiert ist. Composer funktioniert besser, wenn es eine Referenzimplementierung hat.

Schritt 2: Composer öffnen und die Aufgabe abgrenzen:

Ersetze alle rohen `fetch`-Aufrufe in src/ durch den `apiClient` aus src/lib/apiClient.ts.

Regeln:
- Nutze die bestehenden `apiClient.get`, `.post`, `.put`, `.delete`-Methoden
- Entferne manuelles JSON.stringify und response.json()-Handling — apiClient macht das
- Behalte die gleichen Endpunkt-Pfade bei
- Bewahre alle benutzerdefinierten Header auf, die nicht bereits in apiClient enthalten sind

Beginne mit dem src/api/-Verzeichnis, dann src/hooks/ falls nötig.

Schritt 3: Batch für Batch prüfen. Akzeptiere nicht 20 Dateien auf einmal ohne Hinschauen. Composer ist gut, aber nicht perfekt.

Schritt 4: Führe deine Test-Suite nach dem Akzeptieren aus. Typfehler und Laufzeitverhalten können divergieren, selbst wenn der Diff sauber aussieht.

Migriere nicht alles auf einmal

Wenn du 50+ Dateien hast, zerlege es in Chunks. "Migriere src/api/ zuerst." Dann "Migriere src/hooks/ als Nächstes." Große Batches sind schwerer zu prüfen und leichter zu vermasseln.

Composer + Agent-Modus: Die Power-Kombi

Composer und der Agent-Modus lösen unterschiedliche Probleme. Composer ist für gezielte Multi-File-Edits, bei denen du weißt, was du willst. Der Agent-Modus ist für offene Aufgaben, bei denen die KI erkunden, Befehle ausführen und Dinge herausfinden muss.

Aber sie arbeiten zusammen.

Pattern: Agent plant, Composer führt aus

Nutze den Agent-Modus, um den Umfang einer Änderung zu ermitteln:

Ich möchte von React Context zu Zustand für State Management migrieren. Liste alle Dateien auf, die AuthContext nutzen, und welche Änderungen jede benötigt.

Der Agent-Modus durchsucht die Codebase und gibt dir die Aufschlüsselung. Dann öffnest du Composer und führst die Änderungen Datei für Datei aus, mit vollständiger Diff-Prüfung.

Pattern: Composer für Refactoring, Agent für Verifizierung

Nach einem großen Composer-Refactoring, wechsle in den Agent-Modus:

Führe die Test-Suite aus und behebe alle defekten Imports oder Typfehler, die durch das kürzliche Refactoring verursacht wurden.

Der Agent-Modus übernimmt das Aufräumen, während du die Composer-Änderungen prüfst.

Agent-Modus kann Composer nutzen

Im Agent-Modus öffnet Cursor manchmal intern Composer für Multi-File-Edits. Du steuerst das nicht direkt, aber du wirst Composer-artige Diffs während Agent-Sessions auftauchen sehen. Prüfe sie auf die gleiche Weise.

Häufige Fehler und wie man sie vermeidet

1. Vage Prompts

Schlecht: "Mach die Auth besser."

Gut: "Füge ein role-Feld zum User-Typ hinzu, aktualisiere die Login-API, um es in den JWT aufzunehmen, und zeige einen Admin-Link in der Navbar für Admin-User an."

Spezifizität reduziert Überraschungen.

2. Ohne Prüfung akzeptieren

Composer-Diffs sehen sauber aus, aber sie könnten:

• Einen Kommentar löschen, den du behalten wolltest
• Formatierung in nicht betroffenen Zeilen ändern
• Einen Edge-Case in einer Datei übersehen

Scanne den Diff immer. Es dauert 30 Sekunden und spart Nacharbeit.

3. Zu viele Dateien auf einmal

Composer kommt mit 10-15 Dateien gut zurecht. Darüber hinaus wird das Kontextfenster strapaziert und die Qualität sinkt. Zerlege große Aufgaben in logische Chunks.

4. Checkpoints nicht nutzen

Bevor du eine große Composer-Session startest, drücke den Checkpoint-Button. Es ist ein Klick. Wenn die Session schiefgeht, ist der Rollback auch nur ein Klick. Es gibt keine Ausrede, das zu überspringen.

Checkpoints sind keine Git-Commits

Composer-Checkpoints leben innerhalb von Cursor. Sie ersetzen nicht git. Committe auch auf git vor großer Composer-Arbeit. Nutze beide Sicherheitsnetze.

5. Typfehler nach Änderungen ignorieren

Composer-Edits kompilieren vielleicht 90% der Zeit. Die anderen 10% führen subtile Typ-Mismatches ein, besonders beim Umbenennen oder Ändern von Interfaces. Führe tsc oder deinen Linter nach dem Akzeptieren von Änderungen aus.

Schnellreferenz

Aktion	Tastenkürzel
Composer öffnen	Cmd/Ctrl + I
Änderung akzeptieren	Cmd/Ctrl + Y
Änderung ablehnen	Cmd/Ctrl + N
Checkpoint erstellen	Auf das Checkpoint-Icon im Composer-Panel klicken
Zum Checkpoint zurückkehren	Auf das Revert-Icon neben dem Checkpoint klicken

Zusammenfassung

• Nutze Composer für Multi-File-Edits. Nutze regulären Chat für Fragen.
• Beschreibe genau, was du willst. Füge Dateipfade und Einschränkungen hinzu.
• Prüfe jeden Diff, bevor du akzeptierst.
• Erstelle Checkpoints vor großen Sessions.
• Zerlege große Aufgaben in Chunks.
• Kombiniere Composer mit Agent-Modus: Agent erkundet, Composer führt aus.

Composer ist keine Magie. Es ist ein Tool, das die Kopieren-Einfügen-Steuer vom Multi-File-Arbeiten entfernt. Richtig genutzt, spart es Stunden. Nachlässig genutzt, schafft es Aufräumarbeiten. Der Unterschied liegt im Prüfschritt — überspringe ihn nicht.