Wie die 8 Agenten zusammenarbeiten: Dispatch-Pattern, Batch-Strategie, Intermediate Files, Context-Injection und Normalisierung.
Der Hauptagent (gesteuert durch skill.md) fungiert als Dispatcher. Er liest die Phasen-Definition, bestimmt welcher Agent benötigt wird und startet ihn als Sub-AgentEine isolierte Claude-Instanz, gestartet über das Task-Tool. Sie erhält einen eigenen Prompt und arbeitet in einem begrenzten Kontext — nur die Dateien und Daten, die sie braucht. über das Task-Tool von Claude Code.
# Dispatch-Ablauf (Pseudocode)
def dispatch_agent(agent_name, batch_data):
# 1. Prompt-Template laden
template = read(f"agents/{agent_name}.md")
# 2. Context injizieren
prompt = template.replace(
"{{FILES}}", batch_data.files,
"{{README}}", project.readme,
"{{IMPORT_MAP}}", project.import_map,
"{{LANG_ADDENDA}}", get_addenda(batch_data)
)
# 3. Sub-Agent starten (Task-Tool)
result = task(
prompt=prompt,
description=f"{agent_name} batch {batch_data.id}"
)
# 4. Ergebnis als JSON parsen
return parse_json(result)
# Dispatch für Phase 2: file-analyzer x5
batches = split(inventory, size=25)
results = parallel(
dispatch_agent("file-analyzer", b) for b in batches
)
Schritt 1: Das Prompt-Template wird aus agents/file-analyzer.md geladen. Es enthält die Anweisungen, welche Nodes und Edges der Agent extrahieren soll.
Schritt 2: Platzhalter im Template werden mit echten Daten ersetzt: Die Dateien des Batches, README, Import-Map und sprachspezifische Hinweise.
Schritt 3: Claude Code startet eine neue Claude-Instanz (Task-Tool) mit dem vorbereiteten Prompt. Der Sub-Agent arbeitet isoliert.
Schritt 4: Das Ergebnis (JSON mit Nodes + Edges) wird geparsed und in die Intermediate-Datei geschrieben.
Der Dispatch-Pattern isoliert jeden Agenten vom Gesamtkontext. Ein file-analyzer sieht nur seine 25 Dateien, nicht die gesamte Codebase. Das spart Context-Tokens und erlaubt Parallelisierung.
Die Codebase wird in Batches aufgeteilt, weil ein einzelner Claude-Kontext nicht hunderte Dateien gleichzeitig analysieren kann. Die Batch-Strategie optimiert den Trade-off zwischen Kontext-Qualität und Parallelisierung:
# Batch-Konfiguration in skill.md
batch_config:
target_size: 25 # Dateien pro Batch
min_size: 10 # Minimum (nach Retry-Split)
max_parallel: 5 # Gleichzeitige Sub-Agents
sort_by: "directory" # Zusammengehörige Dateien im selben Batch
import_map_injection:
enabled: true
scope: "cross_batch" # Importe ALLER Dateien, nicht nur des Batches
purpose: "Ermöglicht cross-batch Edges"
# Warum Import-Map-Injection?
# Batch 1 enthält auth.js, Batch 3 enthält api.js
# api.js importiert auth.js → Edge nur möglich,
# wenn Batch 3 die Import-Map von auth.js kennt
Batch-Sortierung: Dateien werden nach Verzeichnis sortiert, damit zusammengehörige Module (z.B. alle Dateien in src/auth/) im selben Batch landen. Das verbessert die Qualität der erkannten Edges.
Import-Map-Injection: Das Schlüsselelement. Die Import-Map enthält ALLE Import-Beziehungen der gesamten Codebase. Jeder Batch erhält diese Map, damit Dateien in verschiedenen Batches trotzdem korrekte Edges zueinander erzeugen können.
Ohne Import-Map-Injection würden Cross-Batch-Beziehungen verloren gehen. Datei A in Batch 1 importiert Datei B in Batch 3 — ohne die Map wüsste Batch 1 nicht, dass B existiert. Die Map löst dieses Problem elegant.
Agenten kommunizieren nicht direkt miteinander, sondern über das Dateisystem. Jeder Agent schreibt seine Ergebnisse als JSON in den intermediate/-Ordner. Der nächste Agent liest diese Dateien als Input.
# Intermediate-Ordner-Struktur
.claude-learning/
intermediate/
manifest.json # P1: project-scanner
import-map.json # P1: project-scanner
dir-tree.txt # P1: project-scanner
batch-1.json # P2: file-analyzer
batch-2.json # P2: file-analyzer
batch-3.json # P2: file-analyzer
assembled-graph.json # P3: assemble-reviewer
architecture.json # P4: architecture-analyzer
domain.json # P4: domain-analyzer
tour.json # P5: tour-builder
review-log.json # P6: review-validator
# Datenfluss:
# P1 output → P2 input (manifest, import-map)
# P2 output → P3 input (batch-*.json)
# P3 output → P4 input (assembled-graph.json)
# P4 output → P5 input (architecture.json)
# P5 output → P6 input (tour.json)
# P6 output → P7 input (validierter Graph)
Warum Dateien statt Kontext? Claude-Subagenten haben isolierte Kontexte. Sie können keine Variablen teilen. Die einzige Möglichkeit, Daten zwischen Agenten zu übertragen, ist das Dateisystem.
Vorteil: Intermediate Files sind inspizierbar. Wenn etwas schiefgeht, kann man die JSON-Dateien öffnen und sehen, was jeder Agent produziert hat. Das erleichtert das Debugging enormm.
Aufräumen: Nach P7 (Save) werden die Intermediate-Dateien optional gelöscht. Der finale Knowledge Graph enthält alle relevanten Daten.
Dieses Pattern ist inspiriert von klassischen Unix-Pipelines: Jeder Prozess liest stdin, verarbeitet, schreibt stdout. Hier sind es JSON-Dateien statt Streams, aber das Prinzip ist identisch — lose Kopplung durch definierte Schnittstellen.
Jeder Agent erhält neben seinen spezifischen Daten auch gemeinsamen Kontext, der in sein Prompt-Template injiziert wird. Drei Dateien bilden den "Shared Context":
# agents/file-analyzer.md — Template-Auszug
---
name: file-analyzer
role: Extract nodes and edges from source files
output: JSON with nodes[] and edges[]
---
## Injected Context
### Project README
{{README}}
### Directory Tree
{{DIR_TREE}}
### Import Map (cross-batch)
{{IMPORT_MAP}}
### Language Addenda
{{LANG_ADDENDA}} # z.B. languages/python.md
## Your Task
Analyze the following {{BATCH_SIZE}} files:
{{FILES}}
For each file, extract:
- Nodes: type, id, name, description, filePath
- Edges: source, target, type, weight
README: Gibt dem Agenten Projekt-Kontext. Was macht das Projekt? Welche Technologien werden verwendet? Ohne README produziert der Agent generischere Beschreibungen.
Dir-Tree: Zeigt die gesamte Ordnerstruktur. Hilft dem Agenten, Abhängigkeiten zwischen Verzeichnissen zu erkennen (z.B. "src/api/ importiert src/models/").
Import-Map: Die Karte aller Import-Beziehungen. Erlaubt dem Agenten, Cross-Batch-Edges korrekt zu erzeugen.
Language Addenda: Sprachspezifische Anweisungen aus dem languages/-Ordner. Für Python-Dateien werden z.B. Decorator-Patterns und __init__.py-Konventionen erklärt.
Die Context-Injection stellt sicher, dass jeder Agent — obwohl isoliert — genug Wissen über das Gesamtprojekt hat. Die Kunst liegt in der Balance: Zu viel Kontext verschwendet Tokens, zu wenig Kontext produziert minderwertige Ergebnisse.
Nach der parallelen Batch-Analyse müssen die Ergebnisse zusammengeführt werden. Das ist nicht trivial: Verschiedene Batches können denselben Node unter leicht unterschiedlichen IDs erzeugen. Der Merge-ProzessAusgeführt vom assemble-reviewer. Kann optional durch das Python-Script merge-batch-graphs.py unterstützt werden, das deterministischere Ergebnisse liefert als rein LLM-basiertes Merging. besteht aus drei Schritten:
# merge-batch-graphs.py — Kernlogik
def normalize_node_id(node):
# Schritt 1: Konsistente ID-Generierung
# "src/auth/login.js::LoginForm" → "file:src-auth-login-js::class:LoginForm"
type_prefix = node["type"] # file, function, class, ...
path = node["filePath"].replace("/", "-").replace(".", "-")
name = node["name"]
return f"{type_prefix}:{path}::{name}"
def deduplicate_nodes(all_nodes):
# Schritt 2: Duplikate zusammenführen
seen = {}
for node in all_nodes:
nid = normalize_node_id(node)
if nid in seen:
# Merge: längere Beschreibung gewinnt
if len(node["description"]) > len(seen[nid]["description"]):
seen[nid]["description"] = node["description"]
else:
seen[nid] = node
return list(seen.values())
def clean_edges(edges, valid_node_ids):
# Schritt 3: Edges bereinigen
return [
e for e in edges
if e["source"] in valid_node_ids
and e["target"] in valid_node_ids
]
Schritt 1 — ID-Normalisierung: Node-IDs werden deterministisch aus Typ, Dateipfad und Name erzeugt. Dadurch erhalten identische Nodes in verschiedenen Batches dieselbe ID, unabhängig davon, wie der LLM sie benannt hat.
Schritt 2 — Deduplizierung: Nodes mit identischer ID werden zusammengeführt. Bei Konflikten gewinnt die längere (vermutlich informativere) Beschreibung.
Schritt 3 — Edge-Bereinigung: Edges, die auf nicht-existierende Nodes verweisen (z.B. weil ein Batch fehlgeschlagen ist), werden entfernt. Das stellt referentielle Integrität sicher.
Die Normalisierung ist der fragile Punkt der Pipeline. Wenn zwei Batches denselben Node unterschiedlich benennen (z.B. "LoginForm" vs. "loginForm"), entstehen Duplikate. Das Python-Script löst dies durch case-insensitive Vergleiche und Pfad-basierte Heuristiken — aber Grenzfälle sind unvermeidlich.
Subagent-Architektur vertiefen