Multi-Agenten-Workflow — Zusammenarbeit von Claude Code + Codex CLI

Das Erste, was scheitert, wenn jemand von einem auf zwei oder mehr Agenten wechselt, ist die Annahme, dass sie Kontext teilen. Menschen überbrücken Lücken über Slack, Meetings und räumliche Nähe. Agenten können das nicht. Delegation darf nicht als Versprechen formuliert werden — sie muss als Gate im Code erzwungen werden.

Dieser Leitfaden fasst Muster aus mehr als einer Woche Betrieb mit Claude Code (Hauptagent) + Codex CLI (Subagent) zusammen. Dieselben Muster gelten für andere Kombinationen (Cursor + Claude Code, Aider + Claude Code usw.).

TL;DR

1. Aufgabenteilung — Analyse / Planung / Anweisungen gehen an Opus (Haupt); Ausführung geht an Sonnet / Codex (Sub). Dieselbe Aufgabe auf beiden divergiert unweigerlich.
2. Übergabedokument schreiben — keine Slack-Nachricht. Ein eigenständiges Dokument, das ein anderer Agent lesen und die Arbeit abschließen kann.
3. Verifikations-Gates als Code bündeln — npm run verify:{phase}-Skripte + CI-Checks. Ohne Gates akkumulieren sich Lücken.
4. Eine Aufgabe pro Agent — Sub-Ergebnisse nicht blind vertrauen. Haupt führt vor dem Merge erneut aus.

Warum Multi-Agenten

Ein Agent genügt für viele Aufgaben: Einzeldatei-Bearbeitungen, kurze Refaktorierungen, Code-Reviews. Multi-Agenten sind in diesen Fällen im Vorteil:

• Parallelisierbare unabhängige Arbeit — Frontend + Backend + Migration gleichzeitig
• Modell-ausgerichtete Aufteilung — Reasoning (Opus) und Ausführung (Sonnet/GPT) getrennt für Kosten und Geschwindigkeit
• Kontext-Isolation — den Kontext des Hauptagenten in großen Codebasen schützen
• Unabhängige Verifikation — Trennung von Autor und Prüfer erzeugt Objektivität

Multi-Agenten sind ein Verlust, wenn:

• Die Arbeit auf eine einzige Datei konvergiert — Merge-Konflikte fressen den Kollaborationsgewinn
• Der Kontext sehr klein ist — das Übergabedokument dauert länger als die Arbeit selbst
• Die Spezifikation mehrdeutig ist — zwei Agenten divergieren dann auf verschiedene Interpretationen

1. Aufgabenteilung — Wer macht was

Der häufigste Fehler: „beide machen denselben Job". Ergebnisse divergieren, und niemand ist verantwortlich.

Empfohlene Aufteilung:

Auch wenn dieselbe Person beide Agenten führt, Sitzungen trennen. Wenn Haupt seine eigenen Ergebnisse im eigenen Kontext verifiziert, geht die Objektivität verloren.

Was nur Haupt tut

• Plan + Abwägungsbewertung + Alternativenvergleich
• Das „Warum" hinter Entscheidungen dokumentieren
• Das Übergabedokument schreiben
• Ergebnisse des Sub vor dem Merge verifizieren (erneut ausführen, Gate-Rohausgabe prüfen)

Was nur Sub tut

• Klar definierte Aufgaben — Eingabe/Ausgabe/Abnahme in der Übergabe festgelegt
• Repetitive CLI-Arbeit (Build, Test, Migrations-Läufe)
• Große Codebase-Suchen (grep/find) — schützt den Kontext des Hauptagenten

Was nie beide tun

• „Herausfinden wie man das macht und berichten" — zwei verschiedene Antworten zum Abgleichen
• „Den Code schreiben und auch verifizieren" — Selbst-Review übersieht blinde Flecken

2. Übergabedokument-Muster

Eine Übergabe ist ein eigenständiges Dokument, das ein anderer Agent verwenden kann, um die Arbeit abzuschließen — keine Slack-Nachricht und kein kurzer Prompt.

Erforderliche Abschnitte

# Phase X — {Titel}
 
## Ziel
{Ein Satz: was fertiggestellt wird}
 
## Kontext
- Verwandte Dateien: `src/foo.ts:42`, `tests/foo.test.ts`
- Vorherige Arbeit: PR #123 gemergt, RFC-005 übernommen
- Externe Abhängigkeit: API-Spezifikation `docs/api.md` v2
 
## Umfang
1. Signatur von {Funktion B} in {Datei A} ändern
2. Neue Funktion D in {Datei C} hinzufügen
3. Vier Tests in {Datei E} aktualisieren
 
## Nicht-Ziele
- Nicht {verlockende Erweiterung} (nächste Phase)
- Nicht {Refaktorierungsversuchung} (separater PR)
 
## Abnahme
- [ ] `npm run verify:phase-X` besteht
- [ ] `npm run typecheck` sauber
- [ ] PR-Diff unter 300 Zeilen (kleiner aufteilen wenn größer)
 
## Verifikationsbefehle
\`\`\`bash
npm run verify:phase-X  # phasenspezifisches Gate
npm test src/foo        # Unit-Tests
\`\`\`
 
## Bei Blockierung
- Wenn dreimal auf denselben Fehler gestoßen wird, melden (kein endloser Selbst-Loop)
- Wenn externe API anders als erwartet antwortet, melden (keine gefälschten Antworten)
 
## Autor / Datum
csmarch · 2026-05-12

Kernprinzipien

1. Eigenständig — die Arbeit muss allein aus der Übergabe heraus möglich sein. „Wir haben das auf Slack besprochen" gilt nicht.
2. Umfang UND Nicht-Umfang angeben — blockiert gut gemeinten Scope-Creep.
3. Abnahme als Code — „Wenn es funktioniert, ist es OK" durch konkrete npm run verify:phase-X-Gates ersetzen.
4. Blockierungs-Melde-Regel — explizites Zeitlimit für Selbst-Debugging festlegen.

Die Länge der Übergabe skaliert mit der Aufgabengröße. Eine 100-zeilige Übergabe für eine einzeilige Aufgabe ist ineffizient. 5+ Dateien oder ein neues Modul → Übergabe erforderlich; 1–2-Datei-Bugfix → eine Chat-Zeile genügt.

3. Verifikations-Gates — Versprechen als Code

Der häufigste und teuerste Fehler: „Wir verifizieren nach dem Merge."

Wenn Sub die Fertigstellung meldet, vertraut Haupt und geht zur nächsten Phase über. Wenn die nächste Phase etwas bricht, muss zurückverfolgt werden. Lücken häufen sich und explodieren schließlich als großes Nachhol-Projekt.

Prinzip: Verifikationsskript und Merge-Gate im selben PR wie die Übergabe bündeln.

Drei Gates

1. Lokales Verifikationsskript — npm run verify:phase-X oder npm run verify:auth, pro Aufgabe ein Job
2. CI-Gate — GitHub Actions / GitLab CI führt verify:phase-X automatisch aus. Merge bei Fehler blockiert.
3. Haupt-Wiederholung — Haupt reproduziert Subs Ergebnis in der eigenen Umgebung. Gleiches Ergebnis → Merge.

Beispiel — verify:phase-X-Skript

// package.json
{
  "scripts": {
    "verify:phase-A": "tsc --noEmit && eslint src/phase-a && jest src/phase-a --coverage",
    "verify:phase-B": "...",
    "verify:assets": "node scripts/check-asset-sha256.mjs"
  }
}

GitHub Actions Gate-Beispiel

# .github/workflows/ci.yml
name: CI
on: [pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm build
      - run: pnpm verify:assets   # Phasen-Verify folgt demselben Muster

Format des Abschlussberichts des Sub

Wenn Sub eine Phase als abgeschlossen meldet, anhängen:

[Phase X abgeschlossen]
- Geänderte Dateien: 5 (src/foo.ts, ...)
- verify Rohausgabe:
  $ npm run verify:phase-X
  ✓ tsc sauber
  ✓ eslint sauber
  ✓ jest 23 bestanden
- PR: #234

Berichte ohne Rohausgabe → erneut anfordern. „Es funktioniert" als reine Textaussage nicht vertrauen.

4. Eine Aufgabe pro Agent — Ergebnissen nicht blind vertrauen

Nicht sofort weitergehen, sobald Sub die Fertigstellung meldet. Haupt erledigt drei Dinge:

1. Erneut ausführen — Subs verify-Rohausgabe nicht vertrauen; Haupt führt dieselben Befehle lokal aus. Bei abweichenden Ergebnissen untersuchen (Umgebungsunterschied? Race Condition? Cache?)
2. Diff-Review — den PR-Diff mit der gleichen Sorgfalt wie ein menschliches Code-Review prüfen. Auf Out-of-Scope-Änderungen, fehlende Kommentare und fehlende Tests achten
3. Gegenbeispiele testen — über die formale Abnahme hinaus 1–2 „das darf auf keinen Fall brechen"-Fälle selbst ausführen

Das bedeutet nicht, Subs Fähigkeiten zu bezweifeln — Agenten können die blinden Flecken ihres eigenen Kontexts grundsätzlich nicht erkennen. Menschen können ihren eigenen Code ebenfalls nicht objektiv reviewen.

5. Lehren aus echten Fehlern

Fall — Übergabe vorhanden, Gate fehlte

Situation: UI-Redesign Phase D delegiert. Die Übergabe listete 8 Abnahme-Punkte. Sub meldete „alles fertig". Haupt mergte. Phase E begann.

Problem: Abnahme-Punkt #4 von Phase D war faktisch nicht erfüllt — Sub hatte eine Teilimplementierung als OK bewertet. Phase E nutzte das Feature aus Phase D und brach. Das Debugging von Phase E erforderte die Rückkehr zu Phase D. Dasselbe Muster wiederholte sich in Phase F.

Wiederherstellung: Eine separate Nachhol-Phase für D–F, mit nachträglich geschriebenen verify:phase-D-Skripten. Hätte das Gate von Anfang an existiert, wäre es beim ersten Fehler gescheitert.

Lehre: Abnahme ohne Verifikationsskript bleibt schwammig. Übergabe + Verify-Skript + CI-Gate im selben PR bündeln.

Fall — Selbst-Endlosschleife

Situation: Sub wurde gebeten, „brechende Tests zu reparieren". Sub probierte 5 verschiedene Ansätze am eigenen Code, jeder erzeugte einen neuen Fehler. Nach einer Stunde: „Verschiedenes versucht, funktioniert nicht."

Problem: Keine Blockierungs-Melde-Regel. Sub hatte kein Kriterium, wann es um Hilfe bitten sollte.

Wiederherstellung: „Nach 3 gleichartigen Fehlversuchen sofort melden" zum Übergabe-Template hinzugefügt. Haupt lieferte eine alternative Hypothese mit breiterem Kontext.

Lehre: Blockierungs-Regeln in die Übergabe aufnehmen. „Weitermachen" → „Nach 3 Fehlern melden."

6. Onboarding-Checkliste

Erste Woche beim Wechsel zu Multi-Agenten:

1. Persona und Regeln des Hauptagenten definieren — CLAUDE.md oder äquivalent: Rolle, Autonomie, Verbote, Code-Stil
2. Mit einem einzigen Sub beginnen — Codex CLI oder ein Sonnet-Subagent. Nicht 3–4 gleichzeitig
3. Erste Übergaben kurz halten — 1–2-Datei-Arbeit, 2–3 Abnahme-Punkte, ein Verify-Skript
4. Ein Verify-Gate in GitHub Actions registrieren — weitere hinzufügen, sobald Phasen zunehmen
5. Blockierungs-Regel anwenden — nach 3 Fehlern melden, Haupt übernimmt
6. Retro nach jeder Phase — einzeilige Notiz über das Fehlende. Das Übergabe-Template entwickelt sich mit der Zeit

Fehlerbehebung

„Die Übergabe ist so lang, dass ich die Motivation verliere"

Die Aufgabe ist zu groß. Phase kleiner schneiden. Alles über 100 Zeilen signalisiert, dass die Arbeit länger als eine Woche dauern wird.

„Sub macht ständig Out-of-Scope-Arbeit"

Der „Nicht-Ziele"-Abschnitt fehlt oder ist zu vage. Statt „keine Refaktorierung" konkret schreiben: „src/legacy/ nicht anfassen."

„Keine Zeit, Verify-Skripte zu schreiben"

Das Verify-Skript beim Schreiben der Übergabe erstellen, nicht danach. Jeder Abnahme-Punkt entspricht einer Assertion in verify:phase-X.

„Zwei Agenten konfligieren ständig"

Kontext-Isolation gescheitert — die Umfänge überschneiden sich. Die Dateiliste im Übergabe-Abschnitt „Umfang" muss klar trennbar sein. Zwei Menschen, die dieselbe Datei gleichzeitig bearbeiten, konfligieren ebenso.

„Haupt wird zum Engpass"

Die Lösung ist nicht, dem Sub mehr Autorität zu geben. Haupt behält Verifikation und Merge-Entscheidungen. Stattdessen in Übergabe- und Gate-Automatisierung investieren und den Arbeitsumfang reduzieren (kleinerer Scope, einfacherer Plan).

Referenzen

• Claude Code einrichten — Hauptagenten-Einrichtung zuerst
• Anthropic — Claude Code Subagenten (Subagenten Best Practices)
• OpenAI Codex CLI — openai-codex GitHub

Changelog

• 2026-05-12: Erster Entwurf. Mehr als eine Woche Betriebserfahrung in sechs Abschnitte + fünf Fehlerbehebungsfälle.