Gab es in den vergangenen Monaten frustrierende Momente beim agentischen Programmieren? Ja ... bei mir auch.

Es ist besonders frustrierend, wenn ein Werkzeug so viel leisten kann, aber trotzdem immer wieder an dieselben Dinge erinnert werden muss, ein offensichtliches Designdetail übersieht oder einem anderen Agenten in die Quere kommt, der am selben Projekt arbeitet. Das Potenzial ist offensichtlich. Genauso wie die Zeit, die dafür draufgeht, herauszufinden, was schiefgelaufen ist.

Mein Hintergrund liegt im UX- und UI-Design; Softwareentwicklung kam vor etwa neun Jahren als Teil meiner Arbeit dazu. Als DALL·E 2 erschien, begann ich mit generativer KI zu experimentieren, 2023 dann mit KI-Programmierwerkzeugen. Seit zwei Jahren ist OpenMates.org mein Hauptprojekt – mit einer quelloffenen Web-App, einer CLI, SDKs sowie nativen Apple-Apps, die sich noch in Entwicklung befinden.

Die Arbeit an all diesen Oberflächen hat eines deutlich gemacht: Die bestehenden Agent-Harnesses – also die Werkzeuge rund um das KI-Modell, die Dateien lesen, Befehle ausführen und Code bearbeiten – kratzen noch immer nur an der Oberfläche dessen, wie gut sie sein könnten.

Vier Dinge, die immer wieder im Weg stehen

Intensives Multitasking ist noch immer umständlich

Ein Chat implementiert eine Funktion, ein anderer untersucht einen Fehler und ein dritter erkundet eine Idee. Kurz darauf laufen sechs oder zehn Unterhaltungen gleichzeitig, jede mit einem etwas anderen Verständnis des Projekts.

Genau hier fühlen sich Werkzeuge wie OpenCode und Claude Code in meinem Arbeitsablauf am wenigsten angenehm an. Worktrees helfen Agenten, an getrennten Kopien des Codes zu arbeiten, doch die umgebende Infrastruktur kann weiterhin gemeinsam genutzt werden. Zwei Agenten starten womöglich dieselben Docker-Container neu. Einer deployt auf Vercel, während ein anderer noch das vorherige Deployment prüft.

Die Dateien sind getrennt, die Umgebung ist es nicht. Nachzuverfolgen, welcher Agent gerade welche Version testet, wird schnell zu einer eigenen Aufgabe.

Mehrere nützliche Unterhaltungen lassen sich schnell nur noch schwer koordinieren.

Vibe Coding hat Grenzen

Vibe Coding eignet sich hervorragend, um etwas auszuprobieren. Eine kleine Funktion, ein Prototyp, eine Idee, die den Nachmittag vielleicht nicht überlebt – manchmal sind ein Prompt und ein paar Iterationen genau das Richtige.

Ein komplexes Produkt verlangt dem Prozess mehr ab. Was soll passieren, wenn eine Anfrage fehlschlägt? Welche Informationen dürfen das Gerät verlassen? Wie soll sich dieselbe Funktion auf einem Smartphone verhalten? Welche Teile sind bewusst nicht Teil des Umfangs?

Ohne eine vereinbarte Spezifikation fallen diese Entscheidungen meist während der Implementierung, oft ohne dass die Person, die das Produkt entwickelt, es bemerkt. Ein Ergebnis kann überzeugend aussehen und trotzdem an den Anforderungen scheitern, auf die es am meisten ankommt.

Bei komplexer Arbeit muss das Ziel ausdrücklich feststehen.

Intelligenz kann fehlenden Kontext nicht ersetzen

Ein Modell kann kein Figma-Design zuverlässig umsetzen, das es nie gesehen hat. Gib ihm über eine API Zugriff auf das Design oder zumindest ein exportiertes PDF, und es hat eine konkrete Grundlage. Bleibt ihm nur eine vage Beschreibung, ist ein großer Teil des Ergebnisses geraten.

Dasselbe gilt, nachdem der Code geschrieben wurde. Ein Agent braucht Zugriff auf einen Browser und Screenshots der gerenderten Seite, um zu sehen, ob die Oberfläche tatsächlich richtig aussieht. Konsolen- und Netzwerkinformationen helfen zu erklären, warum sie es nicht tut.

Das klingt selbstverständlich. Trotzdem findet erstaunlich viel agentisches Programmieren ohne diese Rückkopplung statt. Ein intelligenteres Modell macht eine unsichtbare Oberfläche nicht sichtbar.

Gib dem Agenten sowohl das Design als auch eine Möglichkeit, das Ergebnis zu prüfen.

Die Oberfläche verlangt der nutzenden Person zu viel ab

Mit meinem Hintergrund im UX- und UI-Design stört mich dieser Teil am meisten. Trotz einiger Fortschritte fühlt sich zu viel der Erfahrung noch immer so an, als käme zuerst die technische Funktion und Benutzerfreundlichkeit erst im Nachhinein.

Claudes Video Projects are now a conversation with Claude ist dafür ein gutes Beispiel. Es zeigt, wie große Technologieunternehmen weiterhin Produkte mit verwirrenden und schlecht gestalteten Oberflächen veröffentlichen – und dazu häufig Videos produzieren, die alle nur noch mehr verwirren. Nebenbei bemerkt: Ich finde es eigenartig, wie schön die Animationen sein können, während Inhalt und Geschichte gleichzeitig vollkommen verwirrend und schlecht gestaltet sind. Was für ein Kontrast. Und wie der Kommentarbereich zeigt, war ich bei Weitem nicht der Einzige, der das Video nicht verstanden hat.

Die Demo und ausgewählte Reaktionen aus den Kommentaren. Sie veranschaulichen die Verwirrung, ohne für alle Zuschauerinnen und Zuschauer zu sprechen.

Die tägliche Textwand in Antworten von KI-Agenten ist ein weiteres Beispiel für schlechte Benutzerfreundlichkeit ab Werk. Lange Antworten verlangen, dass du selbst liest, erinnerst, vergleichst und die Entscheidung herausarbeitest. Wenn mehrere Chats gleichzeitig laufen, vervielfacht sich diese Belastung.

Es gibt Gründe dafür, dass wir Diagramme, Mindmaps, Fragebögen und grafische Oberflächen erfunden haben und verwenden. Ein Wireframe kann eine Layoutentscheidung offensichtlich machen. Ein Diagramm kann eine Abhängigkeit sichtbar machen, die in drei Absätzen untergeht. Eine bessere Darstellung hilft Menschen, die Arbeit zu verstehen und Fehler zu erkennen.

Was heute hilft: ein eigener Arbeitsablauf

Nach reichlich Frust und Gesprächen mit anderen Entwicklern ist der folgende Ansatz die Grundlage, die ich empfehlen würde und die sich mit Claude Code, Codex, OpenCode und anderen agentischen Programmierwerkzeugen verwenden lässt.

1. Klare Anweisungen und getrennte Skills

Prüfe zuerst die Anweisungen, die deine Agenten bereits erhalten. Widersprechen sie einander? Verlangt eine Datei etwas, das eine andere verbietet? Sind alte Regeln noch vorhanden, obwohl sich der Arbeitsablauf längst geändert hat?

Halte die Hauptanweisungen kurz. Lagere detaillierte, aufgabenspezifische Abläufe in getrennte Dateien und Skills aus, damit ein Agent sie bei Bedarf laden kann. Eine AGENTS.md wird immer schwerer zu pflegen, wenn jede neue Erkenntnis einen weiteren Absatz hinzufügt.

Die Grundlagen gehören in die Hauptanweisungen; detaillierte Abläufe werden bei Bedarf geladen.

Es lohnt sich außerdem, wiederkehrende Arbeit rückblickend zu betrachten. Wenn derselbe Ablauf in der vergangenen Woche in mehreren Chats erklärt wurde, bitte einen Agenten, daraus einen wiederverwendbaren Skill vorzuschlagen. Prüfe das Ergebnis, bevor es Teil des Arbeitsablaufs wird.

2. Bitte um eine hilfreiche Darstellung der Arbeit

Wenn eine Entscheidung visuell oder strukturell ist, bitte um eine visuelle oder strukturelle Erklärung.

Wähle das Format, das die Entscheidung leichter macht.

Nutze eine Mindmap, um eine Idee zu erkunden, ein Diagramm, um Zusammenhänge zu verstehen, und einen Fragebogen, um offene Entscheidungen systematisch zu klären. Bitte vor der Implementierung einer neuen Oberfläche um ein Wireframe. Selbst eine ASCII-Zeichnung kann ausreichen, um zu bemerken, dass ein Button an der falschen Stelle sitzt oder der beabsichtigte Ablauf missverstanden wurde.

Ein grobes Wireframe kann ein Missverständnis beim Layout noch vor der Implementierung sichtbar machen.

Die nützliche Frage lautet: Was würde dies leichter verständlich und entscheidbar machen? Danach sollte sich das Format der Antwort richten. Denn der Engpass ist nicht die Fähigkeit der KI, Informationen auszugeben, sondern unsere Fähigkeit, komplexe Systeme und Ideen richtig zu verstehen und wirksam mit KI zu kommunizieren.

3. Wichtige Regeln mit Hooks durchsetzen

„Bitte halte dich an diese Regel“ ist ein fragiles Fundament für etwas, das zuverlässig passieren muss.

Hooks ermöglichen es der umgebenden Software, eine Aktion zu prüfen und an einem festgelegten Punkt einzugreifen. Ein Deployment-Befehl kann beispielsweise kontrollieren, ob die erforderlichen Prüfungen erfolgreich waren, bevor das Deployment fortgesetzt werden darf. Oder das Pushen von Git-Commits kann gesperrt werden, bis eine Reihe deterministischer Prüfungen bestätigt hat, dass bestehende Verarbeitungsabläufe nicht beschädigt wurden.

Eine Prüfung im Moment der Aktion ist verlässlicher als eine weitere Erinnerung.

Der Unterschied ist entscheidend: Eine Anweisung hängt davon ab, dass das Modell sich erinnert und ihr folgt. Eine deterministische Prüfung kann eine Bedingung auch dann durchsetzen, wenn das Modell sie vergisst. Wähle Bedingungen, die sich zuverlässig prüfen lassen, und sorge dafür, dass Fehler erklären, was geändert werden muss. Sonst wird die Leitplanke selbst zu einer weiteren Quelle von Frust.

4. Trenne auch die Umgebungen

Nutze Worktrees zur Trennung des Quellcodes und kümmere dich anschließend um die Laufzeitumgebung.

Bei einer Web-App kann jeder Testlauf eigene Backend- und Frontend-Container mit genau dem getesteten Code starten. Werden diese Jobs über GitHub CI oder andere CI-Werkzeuge ausgeführt, können sie unabhängig vom Entwicklungsserver oder Laptop laufen, auf dem die Agenten-Chats aktiv sind.

Damit verschwindet eine ganze Kategorie von Verwirrung: Der Neustart eines Containers durch einen anderen Chat sollte keinen Test mitten im Lauf ungültig machen. Das Ergebnis muss eindeutig zu dem untersuchten Code gehören.

Getrennte Quelldateien und getrennte Laufzeitumgebungen lösen unterschiedliche Teile des Problems.

5. Gib komplexer Arbeit eine Spezifikation

Es spielt keine Rolle, wie intelligent ein Modell ist, wenn es deine Anforderungen nicht kennt.

Beginne mit einem Brainstorming. Erstelle eine Mindmap, bevor du um die Implementierung bittest, und lass dir anschließend vom Agenten helfen, die Lücken aufzudecken. Ein nützlicher Prompt, den ich dafür und für viele andere Situationen sehr empfehlen kann:

Stelle vor dem Vorschlag einer Spezifikation fünf klärende Fragen, jeweils eine nach der anderen. Warte jede Antwort ab. Gib zu jeder Frage eine Empfehlung und ein konkretes Beispiel.

Ziel ist es, Entscheidungen sichtbar zu machen, solange Änderungen noch günstig sind, sicherzustellen, dass die KI den nötigen konkreten Kontext erhält, und ein gemeinsames Verständnis davon herzustellen, was wie gebaut werden soll. Das kann bei komplexen Funktionen, UI-Designs und sogar bei Marketing- oder Kommunikationsrichtlinien helfen.

Sobald die Absicht klarer ist, wird daraus eine Spezifikation mit drei Dingen, die du prüfen kannst.

Anforderungen, die tatsächliches Verhalten beschreiben

Halte jede Anforderung verständlich, mit einer kurzen Beschreibung und Beispielen in natürlicher Sprache.

Betrachte die Workflows-Funktion in OpenMates. „Nutzer können Workflows erstellen“ lässt viele Fragen offen. Eine nützlichere Anforderung unterscheidet zwischen dem Speichern eines unvollständigen Entwurfs und seiner Ausführung.

Zum Beispiel:

Eine Nutzerin erstellt einen leeren Workflow und speichert ihn. Das Speichern gelingt. Als sie versucht, ihn auszuführen, erklärt die Oberfläche, welche Schritte fehlen, und es wird kein Lauf gestartet.

Damit gibt es etwas Konkretes, das implementiert und überprüft werden kann. Die OpenMates-Workflows-Spezifikation enthält die zugrunde liegenden Anforderungen, einschließlich der Ausführungsbereitschaft und der Unterscheidung zwischen manuellen Läufen und geplanter Automatisierung. Sie ist ein echtes Projektbeispiel mit eigener Komplexität und Geschichte.

Die Workflows-Anforderung unterscheidet zwischen dem Speichern eines Entwurfs und seiner Ausführungsbereitschaft.

Vor der Implementierung geplante Tests

Einige dich darauf, was beweisen würde, dass die Funktion funktioniert. Beschreibe die Tests zuerst in natürlicher Sprache, damit ihre Bedeutung geprüft werden kann, ohne Testcode lesen zu müssen.

Beim Workflow-Beispiel könnte die Abfolge lauten: einen leeren Entwurf erstellen, ihn speichern, seine Ausführung versuchen, die Erklärung prüfen und bestätigen, dass keine Ausführung angelegt wurde.

Die Arbeitsreihenfolge lautet:

1. Lass den Agenten die Tests in natürlicher Sprache beschreiben.
2. Du als Mensch bestätigst oder korrigierst sie.
3. Lass den Agenten die Tests schreiben.
4. Lass den Agenten die Funktion implementieren.
5. Lass den Agenten die Tests ausführen und debuggen, bis das erwartete Verhalten erfüllt ist.

Beginne bei UI-Arbeit mit Komponententests. Eine eigene Vorschauseite, die eine Komponente oder eine kleine Gruppe zusammengehöriger Elemente rendert, macht Probleme deutlich leichter isolierbar. Dasselbe Prinzip funktioniert für Web- und native Oberflächen. Bring diese Teile in Ordnung, bevor du in längere End-to-End-Tests investierst.

Mach auch das Ergebnis sichtbar. Screenshots und Aufzeichnungen sollten neben Fortschritts- oder Fehlerberichten erscheinen, sodass du und die Agenten sie direkt prüfen können. Eine Playwright-Aufzeichnung oder die Aufzeichnung einer CLI-Interaktion kann ein Missverständnis zeigen, das ein grüner Status allein nie offenlegen würde. Prüfe bei UI-Änderungen früh das Erscheinungsbild, bevor du viel Zeit in breitere Tests investierst.

Prüfe Komponenten früh und zeige anschließend, was die Prüfungen tatsächlich ausgeführt haben.

Eine Spezifikation, die sich angenehm lesen lässt

Eine YAML-Datei kann für Software und Agenten nützlich sein. Menschen profitieren bei der Prüfung von einem gut lesbaren Dokument.

Bitte um ein PDF mit Anforderungen, Beispielen, Diagrammen und Wireframes. Lies es, korrigiere es und bestätige die Spezifikation, bevor die Implementierung beginnt. Das ist der richtige Moment, um zu erkennen, dass der Agent ein anderes Produkt verstanden hat.

6. Erstelle einen Plan vom aktuellen Stand bis zur Spezifikation

Sobald das Ziel klar ist, stellt sich die Frage, wie es ausgehend vom vorhandenen Code erreicht werden kann.

Ein Plan sollte Annahmen nennen, die recherchiert werden müssen, auf relevante Tests verweisen und die Arbeit in Aufgaben aufteilen. Die Annahmen verdienen besondere Aufmerksamkeit. Wenn ein Agent seinen Plan noch einmal überprüft, zeigt sich oft, dass er einen Teil der vorhandenen Architektur missverstanden hat oder dass veraltete Informationen zunächst weitere Webrecherche erfordern.

Eine Annahme darüber, wo Daten verschlüsselt werden, kann beispielsweise den gesamten Implementierungsansatz verändern. Dafür braucht es Belege aus dem Code, bevor abhängige Arbeit beginnt.

Ein nützlicher Plan verbindet geprüfte Annahmen, relevante Tests und konkrete Aufgaben.

Der OpenMates-Implementierungsplan für Workflows ist das passende Gegenstück zur Spezifikation. Seine Annahmen, Aufgaben und Prüfbereiche zeigen, wie eine umfangreiche Funktion aufgeteilt wird. Es ist ein großes, fortlaufend weiterentwickeltes Dokument; die hilfreiche Erkenntnis liegt in der Beziehung zwischen diesen Teilen, nicht in der Menge der Dokumentation.

7. Lass Agenten die Aufgaben und Erkenntnisse der anderen sehen

Aufgaben machen die einzelnen Arbeitsschritte sichtbar: eine bestehende Implementierung recherchieren, eine Komponente bauen oder einen Fehler untersuchen.

Gib jeder Aufgabe ein klares Ergebnis und mache ihren Status über Chats hinweg verfügbar. Agenten sollten Erkenntnisse festhalten können, die andere Arbeit beeinflussen. Eine Entdeckung über einen vorhandenen Dienst, eine Einschränkung oder eine geänderte Annahme sollte nicht in der einen Unterhaltung verborgen bleiben, in der sie gefunden wurde.

Das ist besonders wichtig, wenn mehrere Agenten gleichzeitig arbeiten. Gemeinsamer Aufgabenkontext kann Überschneidungen früh sichtbar machen und das Risiko verringern, dass zwei Chats unabhängig dasselbe Problem lösen – oder unvereinbare Änderungen vornehmen.

Mach Erkenntnisse über Aufgaben hinweg sichtbar, damit andere Agenten darauf reagieren können.

Das sollte von Haus aus einfacher sein

Ein eigener Aufbau kann die Erfahrung erheblich verbessern. Er verlangt aber auch unverhältnismäßig viel Arbeit.

Menschen sollten mit einem leistungsfähigen, verständlichen Arbeitsablauf beginnen können und nur wenige Details an ihr Projekt anpassen müssen. Wochen mit dem Zusammenstellen von Anweisungen, Hooks, Vorschauen, Tests und Koordinationsskripten sollten nicht der Eintrittspreis für verlässliches agentisches Programmieren sein.

Dieser Frust über bestehende agentische Programmierwerkzeuge und KI-Chatbots ist ein großer Teil meiner Motivation, OpenMates zu entwickeln.

Heute bringt OpenMates KI-Modelle und spezialisierte Apps für praktische Aufgaben zusammen, etwa um Arzttermine, Wohnungen und Veranstaltungen zu finden – innerhalb von Sekunden. Ergebnisse lassen sich direkt in der Oberfläche erkunden, neben Werkzeugen für Dateien, Reisen und weitere alltägliche Aufgaben. Datenschutz und Unabhängigkeit von einzelnen Ökosystemen stehen im Zentrum der Produktentwicklung.

OpenMates bringt praktische Werkzeuge und ihre Ergebnisse in einer Oberfläche zusammen.

Doch die Ambition reicht deutlich weiter: OpenMates soll eine leistungsfähige Umgebung für agentisches Programmieren und andere komplexe Arbeit werden, in der Spezifikationen, Pläne, Aufgaben, Durchsetzung und Automatisierung von Anfang an Teil der Erfahrung sind. Projects, Tasks und Workflows gehören zu dieser Richtung. Die Oberfläche muss den Prozess verständlich und handhabbar machen.

Die Richtung für Projects, Tasks und Workflows: laufende Arbeit leichter sichtbar und handhabbar machen.

OpenMates ist weiterhin ein Ein-Personen-Projekt. Ich möchte, dass sich das ändert und mehr Menschen dabei helfen, sowohl die Werkzeuge als auch ihre Nutzungserfahrung zu gestalten.

Eine offene Frage lohnt ebenfalls die Diskussion: Wann reicht schnelles Vibe Coding aus, wann zahlt sich eine vollständige Spezifikation aus, und was sollte zwischen diesen Extremen liegen? Jede kleine Änderung mit zusätzlicher Komplexität zu belasten, würde das Ziel verfehlen. Der Prozess sollte auf der Komplexitätsstufe helfen, die die jeweilige Arbeit tatsächlich hat.

Wenn du ebenfalls an diesen Problemen arbeitest, komm zu einem der nächsten Berliner Meetups oder zu einer Online Community Hour über den OpenMates-Veranstaltungskalender. Du kannst außerdem OpenMates.org ausprobieren oder auf GitHub den Code und die Möglichkeiten zum Self-Hosting erkunden.