Aufbau eines Coding-Agenten für 8K-Kontext: Planer/Ausführer-Aufteilung, Token-Budgetierung und parallele Ausführung

Die meisten KI-Coding-Tools setzen auf Modelle mit 200k Token, aber wenn Sie lokale LLMs über Ollama, LM Studio oder Free-Tier-APIs wie Groq oder OpenRouter betreiben, sind Sie auf etwa 8k Token beschränkt. Das reicht nicht für ein ganzes Projekt – kaum für eine einzelne große Datei. Ein Entwickler hat wochenlang einen CLI-Agenten gebaut, der auf diese Einschränkung ausgelegt ist, und die praktischen Erkenntnisse geteilt.

Kernarchitektur: Planer/Ausführer-Aufteilung

Der Agent zeigt dem LLM nie das gesamte Projekt. Stattdessen teilt er die Arbeit in drei Rollen auf:

• Planer: sieht nur eine leichtgewichtige Projektübersicht (Markdown-Zusammenfassungen jedes Ordners, insgesamt ~300-500 Token) plus die Benutzeranfrage und gibt eine Aufgabenliste aus.
• Ausführer: sieht pro Aufruf genau eine Datei plus eine Aufgabe – nie zwei Dateien gleichzeitig.
• Orchestrator: reiner Code (kein LLM), der aus der Aufgabenliste einen Abhängigkeitsgraphen erstellt und entscheidet, welche Aufgaben parallel oder sequenziell ausgeführt werden können.

Damit werden Refactorings über mehrere Dateien von einem Kontextfenster-Problem zu einem Planungsproblem. Der Planer muss den Code nicht sehen, und der Ausführer sieht immer nur eine begrenzte Menge Code auf einmal.

Token-Budgetierung im Code erzwungen

Jeder LLM-Aufruf durchläuft eine canFit()-Prüfung, die System-Prompt + reservierte Ausgabe-Token + Speicher + tatsächlichen Code misst. Wenn der Code nicht passt, greift der Agent auf einen Zeilenindex pro Datei zurück (einmalig für Dateien über ~150 Zeilen generiert) und zieht nur den relevanten Abschnitt.

Budget-Berechnung für 8192 Token:

System-Prompt + Anweisungen: ~1000
Reserviert für Antwort: ~2000
Kurzzeitspeicher (4 Einträge): ~360
Verfügbar für tatsächlichen Code: ~4800 (etwa 140-190 Zeilen)

Wenn das Budget knapp wird, wird zuerst der Ordnerkontext entfernt, dann der Speicher, bevor tatsächlicher Code gekürzt wird.

Parallele Ausführung als Geschwindigkeitsmultiplikator

Da jeder Ausführer nur eine Datei sieht, werden unabhängige Änderungen an verschiedenen Dateien gleichzeitig ausgeführt. Ein Refactoring von 5 Dateien dauert etwa so lange wie die längste einzelne Bearbeitung. Der Abhängigkeitsgraph (im Code aus der Aufgabenliste des Planers erstellt) bestimmt die Reihenfolge.

Problemstellen und Lösungen

• Frageartige Anfragen überschreiben Dateien: Die Frage „Wie viele Zeilen hat X?“ führte dazu, dass der Ausführer die Antwort in die Datei schrieb. Behoben durch Hinzufügen eines action_type: "query"-Feldes in der Ausgabe des Planers, das über einen Code-Pfad geleitet wird, der nie auf die Festplatte schreibt.
• Veraltete Projektübersichten führen zu stillen Fehlleitungen: Wenn der Benutzer eine umbenannte Datei erwähnte, die nicht in der Übersicht war, leitete der Planer still an den nächstgelegenen Treffer weiter. Jetzt validiert der Orchestrator, dass die erwähnten Dateipfade auf der Festplatte existieren, und wirft einen klaren Fehler, wenn nicht.
• Markdown-Codeblöcke in der Ausgabe des Ausführers: Kleinere Modelle umschließen Code mit dreifachen Backticks, selbst wenn sie angewiesen wurden, es nicht zu tun. Lösung: Entfernen in der Nachbearbeitung, anstatt gegen das Prompt anzukämpfen.
• Speicher-Token-Kosten: Dauerhafter Speicher kostet etwa 80-90 Token pro Eintrag. Ordnerkontext wird zuerst entfernt, wenn das Budget knapp ist, dann Speicher, bevor tatsächlicher Code gekürzt wird.

Offene Fragen

Ob die Planer/Ausführer-Aufteilung auf Codebasen mit über 50 Dateien skalierbar ist – der Abhängigkeitsgraph bleibt handhabbar, aber die Projektübersicht beginnt, echte Token zu kosten. Derzeit wird zuerst Ordnerkontext entfernt, aber tiefere Bearbeitungen verlieren Kontext. Die Implementierung ist Open Source, falls Sie eintauchen möchten.