Ein einzelner KI-Agent kommt in einer kleinen Codebasis erstaunlich weit. In einem gewachsenen Projekt kippt das irgendwann: Der Agent sucht Dateien, liest Testausgaben, probiert Varianten – und irgendwann ist das Kontextfenster voll. Antworten werden ungenauer, der Agent vergisst frühere Entscheidungen, und jeder weitere Schritt wird teurer.
Multi-Agent-Entwicklung ist die Antwort darauf. Mehrere Agents teilen sich eine Aufgabe, jeder mit eigenem Kontext. Wichtig ist dabei eine Erwartung, die man gleich korrigieren sollte: Der Hauptgewinn ist Kontextisolation, nicht Geschwindigkeit. Fünf parallele Agents verbrauchen ungefähr das Fünffache an Tokens eines einzelnen Agents, und bei einfachen Aufgaben sind sie sogar langsamer, weil jeder bei null anfängt. (Cursor Docs)
Dieses Tutorial geht einen kompletten Workflow durch – an einem Beispiel, das nah an typischen Projekten liegt.
Das Beispiel: Audit-Log für ein Kundenportal
Ausgangslage ist ein bestehendes Kundenportal: Next.js im Frontend, FastAPI im Backend, PostgreSQL als Datenbank, rund 60.000 Zeilen Code. Die Fachabteilung möchte ein revisionssicheres Audit-Log: Jede schreibende Aktion wird protokolliert, Administratoren sehen eine filterbare Tabelle, und Prüfer können den Datenbestand als CSV exportieren.
Die Aufgabe zerfällt in vier Teile, die unterschiedlich viel Kontext brauchen:
- Recherche: Wo laufen schreibende Requests heute durch? Gibt es bereits eine Middleware? Wie sind Datenbankmigrationen organisiert?
- Backend: Datenmodell, Migration, Middleware, Abfrage-Endpoint.
- Frontend: Tabelle mit Filtern, Paginierung, CSV-Download.
- Absicherung: Tests, unabhängige Prüfung, Pull Request.
Genau diese Aufteilung ist der Grund, warum sich hier mehrere Agents lohnen. Die Recherche produziert viel Zwischenmaterial, das später niemand mehr braucht. Backend und Frontend berühren getrennte Dateien. Die Prüfung sollte jemand übernehmen, der nicht selbst geschrieben hat.
Warum ein Agent allein an Grenzen stößt
Bevor es losgeht, lohnt ein Blick auf den Context Ring – die runde Anzeige direkt neben dem Eingabefeld. Ein Klick darauf öffnet eine Aufschlüsselung, wie sich das Kontextfenster gerade füllt. Cursor unterscheidet dabei unter anderem zwischen System-Prompt, Tool-Definitionen, Rules, Skills, MCP-Servern, Subagent-Beschreibungen, zusammengefassten früheren Turns und der laufenden Konversation. (Cursor Docs)
Entscheidend ist, welche Anteile wachsen. System-Prompt und Tool-Definitionen sind weitgehend konstant. Rules und MCP-Kataloge legt man einmal fest – sie kosten dann aber bei jeder Anfrage erneut Tokens. Was wirklich explodiert, ist die Konversation selbst: jedes Suchergebnis, jede gelesene Datei, jede Testausgabe bleibt im Kontext stehen.
Wird es eng, verdichtet Cursor ältere Teile der Konversation automatisch zu einer Zusammenfassung (Compaction), um Platz zu schaffen. Das rettet die Sitzung, kostet aber Details. Besser ist, den Kontext gar nicht erst volllaufen zu lassen.
Schritt 1: Rules als gemeinsame Grundlage
Jeder Subagent startet mit leerem Kontext. Er kennt weder die bisherige Unterhaltung noch die Konventionen des Projekts. Was alle Agents wissen müssen, gehört deshalb in Rules – nicht in den Chat.
Projekt-Rules liegen als .mdc-Dateien unter .cursor/rules/. Nur diese Endung wird erkannt; eine .md-Datei im selben Ordner ignoriert Cursor, weil ihr das Frontmatter fehlt. Für reines Markdown ist AGENTS.md vorgesehen. (Cursor Docs)
Für unser Beispiel braucht das Backend-Team eine Regel, die nur für Backend-Dateien gilt:
---
description: Konventionen für FastAPI-Endpoints und Alembic-Migrationen
globs: backend/**/*.py, backend/alembic/**
alwaysApply: false
---
# Backend-Konventionen
- Jeder Endpoint bekommt ein Pydantic-Response-Modell, keine nackten Dicts.
- Migrationen werden mit `alembic revision --autogenerate` erzeugt und
anschließend von Hand geprüft. Niemals die Migration direkt editieren,
nachdem sie deployt wurde.
- Schreibende Endpoints laufen über `require_role("admin")`.
Welcher Rule-Typ daraus wird, ergibt sich aus der Kombination der drei Frontmatter-Felder:
Drei Details, die in der Praxis regelmäßig Ärger machen:
Mehrere Glob-Muster werden mit Komma getrennt, nicht mit Zeilenumbruch oder Array-Syntax: globs: docs/**/*.md, docs/**/*.mdx.
Eine Datei-Mention in einer Rule fügt deren Inhalt nicht ein. Schreibt man @migration-template.sql in eine Rule, sagt das dem Agent nur, wo er nachsehen soll. Er liest die Datei erst, wenn er sie braucht. Das spart Tokens, heißt aber auch: Was wirklich immer gelten muss, gehört direkt in den Regeltext.
alwaysApply: true ist teuer. Diese Rules landen in jeder einzelnen Anfrage, auch bei jedem Subagent. Cursor empfiehlt, Rules unter 500 Zeilen zu halten und große Regelwerke aufzuteilen. In unserem Beispiel bleibt nur eine kleine Always-Rule mit Projektstruktur und Testkommando; alles Fachliche hängt an Globs.
Ergänzend gibt es AGENTS.md – einfaches Markdown im Projektwurzelverzeichnis und zusätzlich in Unterordnern. Verschachtelte Dateien werden mit den übergeordneten kombiniert, wobei die spezifischere Vorrang hat. Für unser Portal liegt also eine allgemeine AGENTS.md im Root und je eine in frontend/ und backend/.
Zwei Einschränkungen sollte man kennen: User-Rules gelten nicht für Inline Edit per Cmd+K, und Projekt-Rules aus .cursor/rules/ gelten nicht für Bugbot-Durchläufe – der liest .cursor/BUGBOT.md.
Schritt 2: Erst planen, dann delegieren
Mit Shift+Tab wechselt man vom Eingabefeld in den Plan Mode. Cursor stellt Rückfragen, durchsucht die Codebasis und erzeugt einen Plan, den man im Chat oder als Markdown-Datei überarbeitet. Standardmäßig landen Pläne im Home-Verzeichnis; „Save to workspace" legt sie stattdessen ins Projekt. (Cursor Docs)
Für Multi-Agent-Arbeit ist dieser Schritt nicht optional, sondern die Voraussetzung. Der Plan ist das einzige Artefakt, das alle Subagents gemeinsam haben – jeder bekommt den für ihn relevanten Ausschnitt in seinen Prompt. Ohne Plan beschreibt man dieselbe Aufgabe viermal in Prosa und bekommt vier leicht unterschiedliche Interpretationen.
Ein nützliches Muster aus der Dokumentation: Hat ein Agent etwas Falsches gebaut, lohnt es sich oft mehr, die Änderungen zu verwerfen und den Plan zu schärfen, als den laufenden Agent nachzusteuern.
Schritt 3: Recherche auslagern
Die Recherche ist der Teil mit dem schlechtesten Verhältnis von Aufwand zu bleibendem Wert. Zwanzig Dateien werden gelesen, drei davon sind relevant – der Rest verstopft den Kontext. Genau dafür gibt es den eingebauten Explore-Subagent, der standardmäßig auf einem schnelleren Modell läuft und viele Suchen parallel ausführen kann. (Cursor Docs)
Man ruft ihn explizit auf, statt darauf zu hoffen, dass der Hauptagent delegiert:
Nutze drei Explore-Subagents parallel:
1. Finde alle Stellen, an denen schreibende Requests durch Middleware laufen.
Gib Dateipfade, Funktionsnamen und die Reihenfolge der Middleware zurück.
2. Beschreibe, wie Alembic-Migrationen in diesem Repo organisiert sind:
Ablage, Namenskonvention, wie sie im Deployment ausgeführt werden.
3. Finde die bestehenden Tabellenkomponenten im Frontend inklusive Filter
und Paginierung. Gib Pfade und Props-Signaturen zurück.
Fasse je Agent maximal 15 Zeilen zusammen. Keine Codeauszüge.
Drei Dinge passieren hier bewusst. Die Agents laufen gleichzeitig, weil der Hauptagent mehrere Aufrufe in einer Nachricht sendet. Jeder arbeitet in einem eigenen Kontextfenster und gibt nur seine Abschlussnachricht zurück – die zwanzig gelesenen Dateien bleiben bei ihm. Und die Längenbegrenzung im Prompt ist kein Stilwunsch, sondern Kostensteuerung: Was zurückkommt, bezahlt man im Hauptkontext.
Weil Subagents ohne Vorwissen starten, muss der Prompt alles Nötige enthalten. „Mach weiter wie besprochen" funktioniert nicht. Jeder Lauf liefert eine Agent-ID; damit lässt sich ein Subagent später fortsetzen, ohne dass er erneut alles erkundet.
Schritt 4: Parallel arbeiten – aber nicht im selben Verzeichnis
Jetzt kommt der Fallstrick, der die meisten ersten Multi-Agent-Versuche ruiniert: Standardmäßig teilen sich Subagents den Arbeitsordner des Hauptagents. Zwei Agents, die gleichzeitig schreiben, überschreiben sich gegenseitig.
Isolation muss man ausdrücklich anfordern. Dann bekommt jeder Agent einen eigenen Git-Worktree – ein zweites Arbeitsverzeichnis desselben Repositorys auf einem eigenen Branch – oder im Cloud-Fall eine eigene virtuelle Maschine.
Im Editor steuert man Worktrees über Slash-Kommandos: /worktree führt den restlichen Chat in einem separaten Checkout aus, /apply-worktree holt die Änderungen zurück in den Hauptordner, /delete-worktree räumt auf. Daneben gibt es /best-of-n, das dieselbe Aufgabe über mehrere Modelle laufen lässt – jeder Durchlauf in eigenem Worktree, zum Vergleichen, nicht zum automatischen Zusammenführen. (Cursor Docs)
Damit ein frischer Worktree sofort lauffähig ist, braucht er ein Setup. Das steht in .cursor/worktrees.json:
{
"setup-worktree-unix": [
"pnpm install --frozen-lockfile",
"cp $ROOT_WORKTREE_PATH/.env.local .env.local",
"uv sync --project backend"
]
}
Die Variable $ROOT_WORKTREE_PATH zeigt auf den Haupt-Checkout – praktisch, um lokale Konfigurationsdateien zu übernehmen, die nicht im Repository liegen. Die Dokumentation warnt ausdrücklich davor, Abhängigkeiten per Symlink zu teilen; das beschädigt den Haupt-Worktree. Stattdessen schnelle Paketmanager wie pnpm, bun oder uv nutzen.
Für unser Audit-Log heißt das: Backend-Agent und Frontend-Agent laufen in getrennten Worktrees, auf getrennten Branches. Der Hauptagent führt die Ergebnisse zusammen.
Wer lieber im Editor bleibt, kann mit /multitask mehrere asynchrone Subagents gleichzeitig arbeiten lassen, statt Anfragen in eine Warteschlange zu stellen. Aus einem fertigen Plan heraus gibt es dafür den Button Build in Parallel: Unabhängige Schritte starten gleichzeitig, voneinander abhängige bleiben in Reihenfolge. Das vollständige Worktree-Management mit Oberfläche steckt im Agents Window, das man über Cmd+Shift+P und „Open Agents Window" erreicht.
Schritt 5: Eigene Subagents definieren
Für wiederkehrende Rollen lohnt ein eigener Subagent-Typ. Diese liegen als Markdown-Dateien mit Frontmatter unter .cursor/agents/ im Projekt oder unter ~/.cursor/agents/ für alle Projekte. Projekt schlägt dabei Benutzer. (Cursor Docs)
Für das Audit-Log richten wir einen Prüfer ein, der ausdrücklich nichts verändern darf:
---
name: migration-reviewer
description: Prüft Alembic-Migrationen auf Rückwärtskompatibilität. Immer
verwenden, wenn eine Migration erzeugt oder geändert wurde.
model: inherit
readonly: true
---
Du prüfst Datenbankmigrationen in einem laufenden System.
Prüfe in dieser Reihenfolge:
1. Lässt sich die Migration ohne Tabellensperre auf einer großen Tabelle
ausführen? Nenne die betroffene Zeile, falls nicht.
2. Ist ein Downgrade implementiert und korrekt?
3. Laufen alte und neue Anwendungsversion gleichzeitig gegen dieses Schema?
4. Werden Spalten gelöscht oder umbenannt? Das ist nur in zwei Schritten
zulässig.
Antworte mit einer Liste von Befunden, je Befund: Datei, Zeile, Schweregrad,
Vorschlag. Keine Änderungen vornehmen.
Die wichtigsten Frontmatter-Felder sind name (Kleinbuchstaben und Bindestriche), description (steuert, wann automatisch delegiert wird), model (inherit oder eine Modell-ID), readonly und is_background. Beim Modell lassen sich Parameter in eckigen Klammern mitgeben, etwa ein größeres Kontextfenster über [context=300k].
readonly: true ist mehr als eine Vorsichtsmaßnahme. Ein Prüfer, der nicht korrigieren kann, meldet Probleme, statt sie still zu überschreiben – und man behält die Entscheidung. Aufgerufen wird er mit /migration-reviewer oder einfach durch Beschreibung der Aufgabe. Wer sich das Dateiformat sparen will, nutzt den eingebauten Skill /create-subagent.
Zur Abgrenzung: Ein Subagent lohnt sich, wenn eigener Kontext, Parallelität oder unabhängige Prüfung gebraucht wird. Ein Skill ist die bessere Wahl für eine wiederholbare Einzelaktion ohne eigenes Kontextfenster.
Schritt 6: Cloud Agents für alles, was dauert
Cloud Agents – früher Background Agents – laufen in isolierten virtuellen Maschinen unter Ubuntu, mit geklontem Repository, installierten Abhängigkeiten und Netzwerkzugriff. Sie arbeiten auf einem eigenen Branch und pushen das Ergebnis als Pull Request. (Cursor Docs)
Starten kann man sie aus dem Desktop-Client über den Dropdown unter dem Eingabefeld, über cursor.com/agents, aus der iOS-App, per @cursor in Slack, als Kommentar an einem GitHub- oder Bitbucket-Pull-Request, aus Linear heraus oder über die API. Voraussetzung ist, dass ein Konto-Administrator die Quellcodeverwaltung verbunden hat und der Tarif Cloud Agents enthält – in den kostenlosen Stufen sind sie nicht enthalten.
Die Umgebung beschreibt .cursor/environment.json:
{
"install": "pnpm install --frozen-lockfile && uv sync --project backend",
"start": "sudo service postgresql start",
"terminals": [
{ "name": "api", "command": "uv run uvicorn app.main:app --reload" },
{ "name": "web", "command": "pnpm dev" }
]
}
Das install-Kommando läuft bei jedem Build und muss deshalb idempotent sein. Erhalten bleibt nur der Zustand der Festplatte – laufende Prozesse, exportierte Shell-Variablen und Caches im Arbeitsspeicher überstehen den Build nicht. Alternativ zum Installationsschritt lassen sich ein Dockerfile oder ein Snapshot referenzieren.
Für unser Beispiel übernimmt ein Cloud Agent die undankbare Arbeit: die bestehenden 340 Tests gegen das neue Schema laufen lassen, Folgefehler reparieren, Migration auf einer Kopie der Datenbank testen. Das dauert, blockiert aber keinen lokalen Agent und keine lokale Maschine.
Zwei Funktionen lohnen sich besonders. Cloud Agents hängen Artefakte an den Pull Request – Screenshots, Videos, Logs –, mit denen man nachvollzieht, wie der Agent verifiziert hat. Und über Subscriptions beendet ein Agent seinen Zug und wacht wieder auf, wenn ein Ereignis eintritt: eine CI-Rückmeldung, ein Kommentar am Pull Request, eine Slack-Antwort.
Unterschiede zum lokalen Agent, die man einplanen sollte: Hooks funktionieren nur als kommandobasierte Hooks aus .cursor/hooks.json im Repository, nicht aus dem Benutzerverzeichnis. MCP-Server kommen aus der Team-Konfiguration, nicht aus der lokalen Sitzung. Persönliche Skills werden nur übertragen, wenn „Sync Skills for Cloud Agents" aktiv ist – zuverlässiger ist es, Skills unter .cursor/skills/ ins Repository zu legen.
Schritt 7: Tokens minimieren
Die Hebel wirken unterschiedlich stark. In dieser Reihenfolge lohnen sie sich:
1. Kontext isolieren statt teilen. Der größte Hebel. Recherche, Testläufe und Fehlersuche erzeugen viel Zwischenmaterial. Landet das in einem Subagent, zahlt man es einmal – und nicht in jedem weiteren Schritt der Hauptunterhaltung mit.
2. Rückgaben begrenzen. Ein Subagent gibt genau eine Abschlussnachricht zurück. Wie lang die ist, bestimmt der Prompt. „Maximal 15 Zeilen, keine Codeauszüge" ist eine Kostenentscheidung.
3. Rules richtig einhängen. Alles, was nicht wirklich immer gilt, bekommt Globs statt alwaysApply: true. Eine 300-Zeilen-Rule, die in jeder Anfrage mitläuft, kostet über einen Arbeitstag mehr als der Rest des Setups zusammen.
4. Modell und Kontextfenster zur Aufgabe wählen. Suchen und Routinearbeit laufen gut auf schnellen Modellen; tiefes Nachdenken braucht das stärkere. Der große Kontext ist kein Standardwert, sondern eine bewusste Entscheidung pro Aufgabe – früher über Max Mode, heute über die Wahl der Kontextfenstergröße beziehungsweise Parameter wie [context=300k].
5. Gezielt oder gar nicht mitgeben. @-Mentions für Dateien und Ordner lohnen sich nur, wenn man die relevanten Dateien wirklich kennt. Ist das unklar, lässt man sie weg – die Suche des Agents findet in der Regel weniger, aber passenderes Material. Verfügbar sind unter anderem Dateien und Ordner, @Terminals, @Chats, Git-Diffs über @Commit und @Branch sowie @Browser.
6. Zwischenfragen in Side Chats. Mit /side oder Shift+Cmd+S öffnet sich ein Nebenstrang, der die Haupthistorie als verstecktem Hintergrund nutzt, ohne den Hauptverlauf zu verlängern. Das Ergebnis holt man per @-Mention zurück.
7. Ballast ausschließen. .cursorignore arbeitet mit .gitignore-Syntax und hält Dateien aus Agent, Tab, Inline Edit und @-Mentions heraus. Eine Einschränkung muss man kennen: Terminal- und MCP-Tools des Agents können dadurch nicht zuverlässig blockiert werden – als Sicherheitsgrenze taugt die Datei also nicht.
Und der wichtigste Hebel ist ein negativer: Nicht parallelisieren, was sequenziell billiger ist. Für eine Änderung an zwei Dateien ist ein einzelner Agent schneller und günstiger als drei koordinierte.
Typische Fehler
Der Subagent weiß nichts. Er startet mit leerem Kontext. Verweise auf „die Datei von vorhin" laufen ins Leere. Jeder Prompt muss für sich stehen.
Zwei Agents, ein Arbeitsverzeichnis. Ohne ausdrücklich angeforderte Isolation schreiben parallele Subagents in denselben Checkout.
Parallelität als Reflex. Fünf Agents kosten das Fünffache. Das lohnt sich bei getrennten Arbeitsbereichen – nicht bei einer kleinen Änderung.
Rules als Dokumentationsablage. Rules sind kein Wiki. Cursor empfiehlt ausdrücklich, keine kompletten Styleguides hineinzukopieren – dafür ist der Linter da – und eine Rule erst dann anzulegen, wenn der Agent denselben Fehler wiederholt macht.
Prüfung durch den Autor. Ein Agent, der seinen eigenen Code bewertet, findet wenig. Ein zweiter Agent mit readonly: true oder ein Durchlauf von /agent-review liefert deutlich mehr.
Fazit
Multi-Agent-Arbeit in Cursor ist kein Schalter, den man umlegt, sondern eine Arbeitsteilung, die man entwirft. Das Muster, das sich in der Praxis bewährt, ist immer dasselbe: Rules legen die gemeinsame Grundlage, ein Plan macht die Aufgabe teilbar, Subagents übernehmen alles mit viel Zwischenmaterial, Worktrees verhindern Kollisionen, Cloud Agents nehmen die langen Läufe ab, und ein unabhängiger Prüfer schaut am Ende drüber.
Der Tokenverbrauch folgt daraus fast von selbst. Wer Kontext bewusst verteilt, statt ihn in einer langen Unterhaltung anwachsen zu lassen, bekommt bessere Ergebnisse und zahlt dabei weniger. Die Reihenfolge ist entscheidend: erst die Arbeitsteilung klären, dann an den Stellschrauben drehen.
Quellen
- Cursor: Subagents – Dateiformat, Frontmatter, Parallelität, Kosten. (Cursor Docs)
- Cursor: Prompting agents – Context Ring, Compaction, @-Mentions. (Cursor Docs)
- Cursor: Rules – Rule-Typen, Frontmatter, Best Practices. (Cursor Docs)
- Cursor: Plan Mode. (Cursor Docs)
- Cursor: Worktrees – Slash-Kommandos und
worktrees.json. (Cursor Docs) - Cursor: Cloud Agents und Umgebungs-Setup. (Cursor Docs)
- Cursor: Agent Skills – Abgrenzung Skill und Subagent. (Cursor Docs)
- Cursor: Agents Window – Multi-Workspace und parallele Agents. (Cursor Docs)