Von Code zu Kontext
Wie ich Agenten-Teams das „Navigieren“ in Repositories beibringe
Stell dir vor, du hast ein riesiges Ökosystem gebaut: Python-Tools für Transkription, KI-Server mit LLMs, Frontends, Backends und Datenbanken. Alles wächst. Und plötzlich stehst du vor dem Problem: Wie behalten meine KI-Agenten den Überblick, wenn das Projekt immer komplexer wird?
Ich habe mich genau das gefragt und bin tief in das Kaninchenloch der „Multi-Agent-Orchestration" eingetaucht. Hier ist das Logbuch meiner Reise – von der Vision bis zur harten Realität der Implementierung.
🧭 Die Vision: Der „Repository-Skill"
Die Idee war simpel: Ich gebe meinem Haupt-Agenten einen Link zu einem Repository. Dieser erkennt automatisch: „Ah, hier ist Backend, da ist Frontend, dort die Datenbank." Er gründet ein Sub-Agenten-Team, in dem Spezialisten (der Backend-Agent, der Frontend-Agent) unter der Leitung eines Koordinators zusammenarbeiten.
Das Ziel: Ein Workspace in OpenClaw, in dem jedes Projekt eine eigene „Soul", eine History und ein Memory hat.
⚠️ Die harten Lektionen: Woran es fast gescheitert wäre
In der Theorie klingt das super. In der Praxis (und nach ein wenig kritischem Feedback von Claude und Kimi) traten drei massive Probleme auf:
1. Ordnernamen lügen
Wenn man Agenten sagt: „Suche den Ordner backend/", finden sie nichts, wenn der Ordner plötzlich src/ oder app/ heißt.
2. Das Chaos im Kopf (Shared State)
Wenn drei Agenten gleichzeitig in die gleiche „Erinnerung" schreiben, entsteht Daten-Matsch. Wer hat was wann geändert?
3. LLM-Würfelspiel
Wenn der Koordinator-Agent jedes Mal frei entscheiden darf, was als Nächstes passiert, wird das System unberechenbar.
🏗️ Die Lösung: Drei Säulen für robuste Agenten
Ich habe das System im Dialog radikal umgeplant. Wenn du so etwas baust, achte auf diese drei Dinge:
1. Dateisignaturen statt Ordnernamen
Statt nach Ordnernamen zu suchen, schaue ich in die Dateien. Eine package.json schreit „Frontend/Node", eine requirements.txt flüstert „Python/Backend". Das ist deterministisch und sicher.
2. Event-Sourcing (Das Logbuch)
Ich nutze keinen „geteilten Speicher“, den jeder überschreiben darf. Stattdessen schreiben alle Agenten in ein Append-only Logbuch (Event-Log).
Vorteil: Man kann jederzeit „zurückspulen" und sehen, welcher Agent welchen Fehler gemacht hat. Es ist die „Blackbox" für deine KI-Flotte.
3. Die State-Machine (Die Leitplanken)
Der Koordinator darf nicht alles. Er arbeitet wie eine Schaltung: Es gibt klare Phasen (Initial Scan → Analyse → Validierung → Abschluss). Das LLM darf entscheiden, wie es eine Phase ausführt, aber es darf die Reihenfolge nicht eigenmächtig würfeln.
- → Initial Scan: Repository erkennen und klassifizieren
- → Analyse: Abhängigkeiten und Strukturen verstehen
- → Validierung: Ergebnisse prüfen und korrigieren
- → Abschluss: Dokumentation und Übergabe
💡 Der „Aha-Moment": Die Workpapers sind der Schlüssel
Am Ende meiner Reise merkte ich: Die Lösung lag schon die ganze Zeit vor mir. Ich nutze bereits sogenannte Workpapers – strukturierte Protokolle über den Status Quo.
Das Problem ist nicht, dass die Agenten nicht schlau genug sind. Das Problem ist der „Zombie-Zustand": Ein Agent startet eine neue Session und weiß nicht, was der Agent davor bereits erledigt hat, weil er das Protokoll (das Workpaper) nicht liest.
Die wichtigste Erkenntnis:
Bevor ein Agent auch nur eine Zeile Code anfasst, braucht er ein „Session-Start-Ritual":
- Lies die letzten drei Workpapers.
- Welche Dateien wurden neu erstellt?
- Welche Aufgaben sind noch offen (🔄)?
🔐 Ein Wort zur Sicherheit (Der Realitätscheck)
Während ich darüber nachdachte, fiel mir ein kritischer Punkt auf: In meinen Protokollen standen manchmal echte Passwörter oder API-Token. Vorsicht! Sobald diese Workpapers in den Kontext eines Agenten fließen, landen sie im Prompt der LLM-Anbieter. Hier muss ich dringend filtern, bevor die „Agenten-Soul“ mit sensiblen Daten gefüttert wird.
Sicherheitsregel: Niemals ungefiltertes Kontext-Material an LLM-Provider senden. Workpapers müssen vor der Einspeisung in den Agenten-Kontext automatisch nach Secrets, API-Keys und Credentials gescannt und bereinigt werden.
🧭 Fazit für heute
Ein Agenten-System zu bauen bedeutet weniger, „schlaue Prompts" zu schreiben, sondern robuste Infrastruktur zu schaffen. Es geht um saubere Protokolle, klare Zuständigkeiten und das Vermeiden von Daten-Chaos.
Was ist dein nächster Schritt?
Ich werde jetzt mein „Session-Start-Ritual" automatisieren. Mein Ziel: Der Agent begrüßt mich mit: „Ich habe die letzten Workpapers gelesen. Ich weiß, dass der KoFi-Service zur Hälfte fertig ist. Soll ich da weitermachen?"
Wäre das auch was für dein Projekt? Lass uns in den Kommentaren drüber quatschen!
Dieser Artikel entstand im kreativen Austausch zwischen @Ogerly und seinen KI-Kollaborateuren für die Alexander Friedland-Community.