Claude Code Multi-Agent System aufbauen — Hierarchie, TEAM_COMMAND und 3 Monate Praxis

Seit drei Monaten betreiben wir ein Unternehmen das komplett von Claude-Code-Agents geführt wird. Vier Departments, über 20 Agents, kein manueller Eingriff für Routinetasks. In diesem Post zeige ich die Architektur — nicht als Konzept, sondern als das, was wir tatsächlich in Produktion laufen haben.

Der wichtigste Satz zuerst: Das Modell ist nicht der Engpass. Die Hierarchie ist der Engpass.

Warum Single-Agent-Systeme scheitern

Die meisten Leute starten mit einem einzelnen Claude-Code-Agenten und geben ihm alles. Marketing, Code, Strategie, Operations — eine einzige Session. Das Ergebnis: Der Agent verliert Kontext, macht inkonsistente Entscheidungen, und nach ein paar Stunden bricht das ganze zusammen.

Das fundamentale Problem ist nicht das Modell — es ist die fehlende Spezialisierung. Ein Mensch der gleichzeitig CFO, Entwickler und Social-Media-Manager ist, wird in allen drei Rollen mittelmäßig sein. Claude Code ist da nicht anders.

Die Hierarchie: CEO → Department Head → Worker

Unser System ist nach dem Vorbild einer echten Unternehmensstruktur aufgebaut:

• CEO-Agent — Überwacht Strategie, KPIs, eskaliert zu Daniel (dem menschlichen Gründer)
• Department Heads (HoDs) — ICT, Marketing, Operations, Strategy — je ein Agent pro Department
• Group Leads (HoGs) — Untergebene der HoDs, koordinieren Worker-Gruppen
• Worker-Agents — Führen konkrete Tasks aus: Code schreiben, Posts generieren, Daten analysieren

Die Hierarchie hat drei entscheidende Vorteile: Kontext-Isolation (jeder Agent kennt nur seinen Bereich), parallele Ausführung (alle Departments laufen gleichzeitig), und klares Eskalationsprinzip (Worker → Lead → HoD → CEO → Human).

TEAM_COMMAND.md — das Herzstück

Jeder Agent in unserem System hat eine eigene TEAM_COMMAND.md. Das ist sein "Vertrag" — was er tut, was er nicht tut, an wen er eskaliert und in welchem Format er berichtet.

Eine vereinfachte TEAM_COMMAND.md für einen Marketing-Worker sieht so aus:

# Social Media Worker — SpockyMagicAI

## Rolle
Du bist Social Media Worker im Marketing Department.
Du postest täglich auf Instagram und Twitter.

## Was du tust
- Lese täglich KI-News via WebSearch
- Generiere einen Instagram-Post (Bild + Caption)
- Generiere einen Twitter-Post (280 Zeichen)
- Submit beide via HIL-Queue zur Freigabe

## Was du NICHT tust
- Kein direktes Posten ohne HIL-Freigabe
- Keine Änderungen an anderen Departments
- Keine API-Kosten über €2/Tag

## Eskalation
Bei Blocker: sofort an Marketing HoD melden
Format: [MARKETING/SOCIAL] BLOCKER: Was | Seit wann | Was ich brauche

## Heartbeat
Alle 2 Minuten via ceo-watchdog.timer

Das klingt simpel — aber genau diese Einfachheit macht den Unterschied. Ein Agent der weiß was er nicht tun soll, ist wertvoller als ein Agent dem man alles erlaubt.

Wie Agents kommunizieren: Bottom-Up Reporting

In unserem System kommunizieren Agents nicht peer-to-peer, sondern strikt bottom-up. Ein Worker meldet Ergebnisse an seinen Group Lead, der Group Lead an den Department Head, der Department Head an den CEO. Nur der CEO kommuniziert mit Daniel (dem menschlichen Eigentümer) — via Telegram.

[MARKETING/SOCIAL] ERGEBNIS: IG-Post generiert
Details: Caption 180 Zeichen, Hashtags optimiert, Bild gerendert
HIL-ID: 4d4c716558708c88
Status: PENDING_REVIEW

Dieses Format erlaubt es jedem Lead auf jeder Ebene, den Status aller Worker auf einen Blick zu erfassen — ohne in einzelne Sessions schauen zu müssen.

Git als Gedächtnis: Prompts versionieren

Einer der nicht-offensichtlichsten Teile unserer Architektur: Alle TEAM_COMMAND.md-Dateien, CLAUDE.md-Dateien und Skill-Definitionen liegen in Git. Das hat drei Konsequenzen:

Der Watchdog: Selbstheilung statt manuelles Monitoring

Was passiert wenn ein Agent crasht oder hängenbleibt? In unserem System: nichts. Weil der Watchdog innerhalb von 2 Minuten eingreift.

Der ceo-watchdog.timer (systemd) läuft alle 2 Minuten und prüft den Heartbeat jedes aktiven Agents. Kein Heartbeat seit 15 Minuten? Agent wird neu gestartet. Kein Heartbeat seit 30 Minuten? CEO-Alert + Daniel Telegram-Nachricht.

Das Konzept heißt Self-Heal — Agents die Fehler erkennen, die Ursache finden, und sich selbst reparieren — oder zumindest eskalieren, bevor ein Mensch eingreifen muss.

Skills: Wiederverwendbare Agent-Fähigkeiten

Claude Code hat ein eingebautes Konzept namens Skills — Markdown-Dateien die einen Agent bei einem spezifischen Task anleiten. Wir haben über 30 Skills entwickelt:

• /commit — Strukturierter Git-Commit mit konventionellem Format
• /memory — Agent speichert Erkenntnisse in Qdrant-Vektor-DB
• /peer-review — Code-Review durch anderen Agent bevor Merge
• /tg — Telegram-Nachricht an Daniel mit richtigem Bot-Routing

Skills sind der Unterschied zwischen einem Agenten der jedes Mal "neu denkt" wie er einen Commit macht — und einem Agenten der eine bewährte Routine hat.

Was wir in 3 Monaten gelernt haben

Der nächste Schritt

Wenn du Claude Code für mehr als einfache Skripte nutzen willst — wenn du ein System aufbauen willst das läuft während du schläfst — dann ist die Hierarchie-Architektur der entscheidende Schritt.

Wir haben die komplette Architektur, alle TEAM_COMMAND.md-Templates, die n8n-Workflows und die Deployment-Anleitungen in einen Kurs gepackt. Alles was wir in 3 Monaten Produktion gelernt haben — nicht aufgeräumt, sondern so wie es wirklich aussieht.