Building AI Coding Agents for the Terminal: Scaffolding, Harness, Context Engineering, and Lessons Learned

Die Arbeit stellt OPENDEV vor, einen Open-Source-Terminal-Agenten, der durch eine spezialisierte Architektur mit getrennter Planung und Ausführung, adaptivem Kontext-Management und automatischem Gedächtnis eine sichere und effiziente autonome Softwareentwicklung in der Kommandozeile ermöglicht.

Das Wesentliche

Stellen Sie sich vor, Sie haben einen hochintelligenten, aber etwas vergesslichen Assistenten, der Ihnen beim Programmieren helfen soll. Früher saß dieser Assistent immer direkt in Ihrer Entwicklungsumgebung (dem IDE) und wartete darauf, dass Sie ihm sagen, was zu tun ist.

Das Papier beschreibt OPENDEV, ein neues, revolutionäres Konzept: Ein KI-Assistent, der direkt in Ihrem Terminal (der Kommandozeile) lebt und eigenständig arbeitet. Er ist nicht nur ein Tipphilfe-Tool, sondern ein echter "Agent", der ganze Projekte planen, Code schreiben, testen und Fehler beheben kann – fast wie ein menschlicher Kollege, der an Ihrem Computer sitzt.

Hier ist die Erklärung der wichtigsten Ideen, übersetzt in einfache Bilder und Metaphern:

1. Das Problem: Der "Vergessliche" und der "Explosive"

KI-Modelle sind wie Genies mit einem sehr kurzen Gedächtnis.

• Das Gedächtnis-Problem: Wenn ein Gespräch zu lang wird, vergisst die KI die Anfangsinstruktionen. Sie weiß plötzlich nicht mehr, dass sie niemals Dateien löschen darf oder dass sie immer Tests schreiben soll.
• Das Sicherheits-Problem: Wenn die KI Zugriff auf Ihre Kommandozeile hat, kann sie theoretisch alles löschen (z. B. rm -rf /). Man muss sie also so steuern, dass sie nicht aus Versehen das Haus abbrennt.

2. Die Lösung: OPENDEV als "Baukasten-System"

OPENDEV ist nicht eine einzelne KI, die alles allein macht. Es ist eher wie eine Baustelle mit einem erfahrenen Bauleiter und spezialisierten Handwerkern.

A. Der "Baukasten" (Compound AI System)

Statt einen einzigen riesigen Roboter zu bauen, nutzt OPENDEV verschiedene kleine KIs für verschiedene Aufgaben:

• Der Denker: Ein KI-Modell, das nur nachdenkt und Pläne schmiedet (ohne zu handeln).
• Der Akteur: Ein KI-Modell, das die Hände in die Hand nimmt und Code schreibt.
• Der Kritiker: Ein KI-Modell, das den Plan des Denkers überprüft, bevor der Akteur loslegt.
• Der Seher: Eine KI, die Screenshots lesen kann.

Die Metapher: Stellen Sie sich vor, Sie wollen ein Haus bauen. Sie schicken nicht einen einzigen Handwerker los, der alles von der Fundamentgrube bis zum Dach machen soll. Stattdessen haben Sie einen Architekten (Denker), der den Plan macht, einen Bauarbeiter (Akteur), der baut, und einen Bauleiter (Kritiker), der prüft, ob alles stimmt. Jeder nutzt das Werkzeug, das er am besten beherrscht.

B. Der "Gedächtnis-Trick" (Context Engineering)

Da das KI-Gedächtnis begrenzt ist, muss OPENDEV clever damit umgehen.

• Adaptive Komprimierung: Stellen Sie sich vor, Sie führen ein Gespräch. Am Anfang ist alles wichtig. Nach 50 Sätzen sind die ersten Sätze weniger wichtig. OPENDEV fasst die alten Teile des Gesprächs automatisch zusammen (wie ein guter Zuhörer, der sagt: "Du hast vorhin über das Fundament gesprochen, das ist erledigt").
• Der "Notizblock" (Scratchpad): Wenn eine Datei zu groß ist, um sie im Gedächtnis zu behalten, schreibt die KI den Inhalt in eine externe Datei und merkt sich nur: "Die Datei ist da, ich kann sie nachlesen, wenn ich muss." Das spart Platz im Gedächtnis.
• Erinnerungs-Zettelchen (System Reminders): Damit die KI nicht vergisst, was sie soll, hakt das System kleine Erinnerungen direkt vor die nächste Frage. Statt den ganzen Regelkatalog am Anfang zu wiederholen, flüstert das System ihr kurz zu: "Vergiss nicht, vor dem Speichern zu testen!" genau in dem Moment, wo sie es braucht.

C. Die "Sicherheitsbarrieren" (Safety)

Wie verhindert man, dass die KI das Haus abbricht?

• Die "Werkzeugkiste": Wenn die KI einen Plan macht (Plan-Modus), bekommt sie eine Werkzeugkiste, in der nur Werkzeuge zum Ansehen enthalten sind (Lesen, Suchen). Werkzeuge zum Zerstören (Löschen, Überschreiben) fehlen einfach. Sie kann gar nicht zerstören, weil sie das Werkzeug nicht sieht.
• Die "Sicherheitskontrolle": Bevor die KI einen gefährlichen Befehl ausführt (z. B. "Server neu starten"), muss sie erst bei Ihnen (dem Menschen) anfragen.
• Der "Rückgängig-Knopf": Jedes Mal, wenn die KI etwas ändert, macht sie ein Foto davon (ein "Snapshot"). Wenn sie etwas falsch macht, können Sie mit einem Klick alles auf den Zustand vor der Änderung zurücksetzen.

3. Wie funktioniert das im Alltag?

Stellen Sie sich vor, Sie sagen zu OPENDEV: "Ich brauche eine neue Login-Funktion für meine App."

1. Planung: OPENDEV denkt erst nach (oder schickt einen "Planer"-Bot los), liest den bestehenden Code und erstellt einen Schritt-für-Schritt-Plan.
2. Genehmigung: Es zeigt Ihnen den Plan: "Ich werde erst die Datenbank prüfen, dann die Datei X ändern und dann Tests schreiben. Passt das?"
3. Ausführung: Wenn Sie "Ja" sagen, führt ein anderer Bot die Schritte aus. Er liest Dateien, schreibt Code und führt Tests aus.
4. Fehlerbehandlung: Wenn ein Test fehlschlägt, liest er den Fehler, denkt nach, korrigiert den Code und versucht es erneut – ohne dass Sie etwas tun müssen.
5. Parallelarbeit: Wenn es viele unabhängige Aufgaben gibt (z. B. "Prüfe Modul A und Modul B"), schickt OPENDEV zwei kleine Bots gleichzeitig los, die parallel arbeiten, statt nacheinander.

4. Warum ist das wichtig?

Bisher waren KI-Helfer oft wie "Co-Piloten", die nur Vorschläge machten, aber Sie mussten alles selbst bestätigen und ausführen. OPENDEV ist wie ein selbstständiger Mitarbeiter, der im Terminal arbeitet.

• Sicherheit: Es ist so gebaut, dass es nicht versehentlich Schaden anrichtet (durch die Werkzeug-Filter und Bestätigungen).
• Lange Aufgaben: Es kann Aufgaben erledigen, die Stunden dauern, ohne den Faden zu verlieren (durch die cleveren Gedächtnis-Tricks).
• Flexibilität: Es kann mit verschiedenen KI-Modellen arbeiten. Wenn morgen eine bessere KI auf den Markt kommt, muss man nur die Einstellung ändern, nicht den ganzen Code neu schreiben.

Fazit

OPENDEV ist der Versuch, die KI vom "passiven Tippgeber" zum "aktiven Handwerker" zu machen. Es nutzt eine Architektur aus vielen kleinen, spezialisierten KI-Teilen, die wie ein gut organisiertes Team zusammenarbeiten, um komplexe Software-Probleme zu lösen, während es gleichzeitig sicherstellt, dass nichts kaputtgeht und das Gedächtnis nicht überläuft. Es ist der Schritt von "KI hilft mir tippen" zu "KI arbeitet mit mir".

Technische Zusammenfassung

1. Problemstellung

Die Landschaft der KI-gestützten Programmierung befindet sich im Wandel: Von komplexen IDE-Plugins hin zu vielseitigen, terminalbasierten Agenten. Während traditionelle Tools oft reaktiv sind und nur Code-Vervollständigungen anbieten, sollen autonome Agenten komplexe Aufgaben planen, ausführen und mit der Entwicklungsumgebung interagieren.

Die Einführung von Terminal-Nativen Agenten (CLI) birgt jedoch drei fundamentale ingenieurtechnische Herausforderungen, die bestehende Benchmarks (wie Terminal-Bench und LongCLI-Bench) als kritische Schwachstellen identifiziert haben:

1. Begrenzter Kontext: Lange Entwicklungssitzungen übersteigen schnell das Token-Budget von LLMs, was zu Kontext-Überlauf und dem Vergessen früherer Anweisungen führt.
2. Sicherheit: Agenten können beliebige Shell-Befehle ausführen und Dateien überschreiben. Ein einzelner Sicherheitsmechanismus reicht nicht aus, um destruktive Aktionen zu verhindern, ohne die Produktivität einzuschränken.
3. Erweiterbarkeit: Die Fähigkeit, neue Tools hinzuzufügen, ohne den Prompt-Budget zu überlasten oder die Agenten-Kognition zu überfordern.

Bisherige Systeme waren entweder geschlossene Quellen ohne technische Dokumentation, auf Benchmarks ausgelegt statt auf interaktive Nutzung, oder fehlten an technischen Berichten zu ihren Architekturentscheidungen.

2. Methodik und Architektur (OPENDEV)

Das Paper stellt OPENDEV vor, einen Open-Source-CLI-Agenten, der als Compound AI System (zusammengesetztes KI-System) konzipiert ist. Statt eines monolithischen LLMs besteht es aus einem strukturierten Ensemble von Agenten und Workflows, die jeweils unabhängig an benutzerkonfigurierbare LLMs gebunden sind.

Die Architektur gliedert sich in vier Hauptschichten:

A. Scaffolding (Gerüstbau) & Agent Core

Bevor der erste Prompt gesendet wird, wird der Agent aufgebaut („Scaffolding"):

• Dual-Agent-Architektur: Trennung von Planung und Ausführung.
  • Plan-Modus: Ein dedizierter „Planner"-Subagent (nur Lesezugriff) erstellt strukturierte Pläne.
  • Normal-Modus: Der Hauptagent führt die Pläne mit vollem Schreibzugriff aus.
• Per-Workflow LLM-Bindung: Unterschiedliche Phasen (Denken, Handeln, Kritik, Kompaktion) nutzen spezialisierte Modelle (z. B. ein günstiges Modell für Zusammenfassungen, ein leistungsstarkes für komplexes Denken). Dies ermöglicht eine Optimierung von Kosten, Latenz und Fähigkeiten.
• Erweiterter ReAct-Loop: Der klassische Reason-Act-Zyklus wird um explizite Phasen erweitert:
  1. Thinking: Ein separater LLM-Aufruf ohne Tool-Zugriff für tiefes Nachdenken.
  2. Self-Critique: Optionaler Schritt zur Bewertung des Denkprozesses.
  3. Action: Ausführung mit Tools.

B. Context Engineering (Kontext-Management)

Dies ist ein zentraler Beitrag des Papers. OPENDEV behandelt Kontext als ersten Ingenieursaspekt:

• Adaptive Context Compaction (ACC): Statt einer binären Notfall-Kompaktion bei 99% Auslastung nutzt OPENDEV einen fünfstufigen Prozess (70% bis 99%), der von Warnungen über das Maskieren alter Beobachtungen bis hin zur vollständigen LLM-basierten Zusammenfassung reicht.
• Dual-Memory-Architektur: Trennung von episodischem Gedächtnis (zusammengefasste Historie für strategische Ziele) und Arbeitsgedächtnis (verbatime letzte Nachrichten für operative Details).
• System Reminders: Um das „Attention Decay" (Nachlassen der Aufmerksamkeit für initiale Anweisungen) zu bekämpfen, werden kontextsensitive Erinnerungen (als User-Nachrichten injiziert) genau dann eingefügt, wenn eine Entscheidung ansteht (z. B. bei unvollständigen Aufgaben oder Fehlern).
• Lazy Tool Discovery: Externe Tools (via MCP) werden nicht alle beim Start geladen, sondern nur bei Bedarf durch Suchanfragen entdeckt, um den Kontext-Budget zu schonen.

C. Tool-System & Sicherheit

• Defense-in-Depth-Sicherheit: Fünf unabhängige Sicherheitsschichten verhindern Schäden:
  1. Prompt-Level-Guardrails.
  2. Schema-Level-Filterung (Tools werden aus dem Schema entfernt, wenn sie nicht erlaubt sind – der Agent kann sie gar nicht sehen).
  3. Runtime-Genehmigungssystem (manuell/semi-automatisch/auto).
  4. Tool-Level-Validierung (z. B. Erkennung von „Doom Loops" bei wiederholten Fehlern).
  5. Lifecycle-Hooks für benutzerdefinierte Skripte.
• Fuzzy Matching bei Datei-Edits: Da LLMs oft kleine Formatierungsunterschiede haben, verwendet OPENDEV eine Kette von 9 Matching-Strategien, um Änderungen erfolgreich anzuwenden, ohne dass der Agent neu versuchen muss.

D. Persistenz

• Sitzungshistorien werden in JSON/JSONL gespeichert.
• Ein „Shadow Git"-Snapshot-System ermöglicht eine Undo-Funktion auf Dateiebene für jeden Schritt, unabhängig vom Git-Status des Benutzers.

3. Schlüsselbeiträge

1. Per-Workflow LLM-Konfigurierbarkeit: Eine Architektur, die es erlaubt, für jede Denkphase ein anderes Modell zu wählen, was Kosten und Qualität optimiert.
2. Erweiterter ReAct-Loop: Integration von expliziten Denk- und Kritikphasen sowie integrierter Kontext-Kompaktion direkt in den Reasoning-Loop.
3. Verhaltenssteuerung über lange Zeiträume: Event-gesteuerte System-Erinnerungen, die das Vergessen von Anweisungen in langen Sitzungen verhindern.
4. Token-effiziente Erweiterbarkeit: Lazy Discovery von Tools via MCP und eine Registry-Architektur, die den Kontext-Budget nicht durch unnötige Tool-Definitionen sprengt.
5. Kontext-Engineering als First-Class-Citizen: Systematische Ansätze wie adaptive Kompaktion, Dual-Memory und Erinnerungsinjektion, die auf Prinzipien der Entropie-Reduktion basieren.

4. Ergebnisse und Lessons Learned

Das Paper liefert keine neuen algorithmischen Durchbrüche, sondern dokumentiert ingenieurtechnische Entscheidungen und Trade-offs:

• Kontext als Budget: Kontext muss aktiv gemanagt werden. Ein gradueller Ansatz (Maskieren, Pruning) ist effektiver als eine einmalige Notfall-Zusammenfassung.
• Sicherheit durch Architektur: Es ist robuster, gefährliche Tools aus dem Schema zu entfernen (so dass der Agent sie nicht einmal sehen kann), als sie nur zur Laufzeit zu blockieren.
• Annäherung an LLM-Ausgaben: Tools müssen so designed sein, dass sie die Unschärfe von LLM-Ausgaben absorbieren (z. B. durch Fuzzy-Matching bei Datei-Edits), statt strikte Übereinstimmung zu fordern.
• Lazy Loading: Das Laden aller Metadaten beim Start führt zu Ineffizienz. Lazy Discovery reduziert den Overhead drastisch.
• Erinnerungen funktionieren besser als System-Prompts: Kurze, kontextsensitive Erinnerungen (als User-Nachrichten) sind effektiver als lange, statische System-Prompts, die im Laufe der Zeit vergessen werden.

5. Bedeutung

OPENDEV dient als Blaupause für robuste, autonome Software-Engineering-Systeme im Terminal. Es füllt die Lücke zwischen geschlossenen industriellen Lösungen (wie Claude Code) und akademischen Forschungsprototypen, indem es einen vollständig dokumentierten, Open-Source-Ansatz bietet.

Die Arbeit zeigt, dass der Erfolg autonomer Agenten weniger von der reinen Leistung des zugrundeliegenden LLMs abhängt, sondern vielmehr von der Systemarchitektur: Wie Kontext gemanagt, wie Sicherheit durch Design gewährleistet und wie Agenten über lange Zeiträume hinweg gelenkt werden. Die vorgestellten Muster (Compound AI Systems, Adaptive Compaction, Schema-Gating) bieten eine fundierte Grundlage für die Entwicklung zukünftiger agenter Systeme, die komplexe, mehrstufige Softwareaufgaben in realen Umgebungen bewältigen können.