Kern, Adapter, Inhalte – warum ich meinen Agenten-Workflow zerlegt habe

In der Agentic-Coding-Serie habe ich beschrieben, wie ich aus einem einzelnen Prompt ein Team aus spezialisierten Agenten gemacht habe: Business Analyst, Solution Architect, Realisierungsplan, Developer, Test-Agent. Das funktionierte. Es funktionierte allerdings in genau einem Repository.

Dieser Beitrag beginnt an dem Tag, an dem ich das Team in ein zweites Projekt mitnehmen wollte.

Der Umzug, der nicht stattfand

Der Plan war unspektakulär: .claude/ kopieren, Claude Code starten, weiterarbeiten. Was tatsächlich passierte, war interessanter — und im Rückblick offensichtlich.

Der Solution Architect hielt fröhlich Vorträge über Verzeichnisse, die es im neuen Projekt nicht gab. Der Developer-Agent bestand auf einem Codegen-Schritt, den der neue Stack nicht kennt. Der Test-Agent verlangte ein Framework, das nicht installiert war. Und der interessanteste Fall: Ein Agent, den ich aus einem anderen Setup übernommen hatte, war nie in irgendeinem meiner Projekte lauffähig gewesen — er trug Annahmen eines fremden Stacks, und niemandem war es aufgefallen, weil er nie einen harten Fehler produziert hat. Er hat einfach plausibel geantwortet.

Das ist der Fehlermodus, der mich seither am meisten beschäftigt: Ein Agent, der keine Vorgabe findet, bricht nicht ab. Er improvisiert. Und improvisierter Output sieht genau so aus wie richtiger.

Die naheliegende Reaktion wäre gewesen, die Agenten für das neue Projekt umzuschreiben. Genau das habe ich zuerst getan, und nach dem zweiten Projekt war klar, dass ich damit nicht drei Agenten-Sets pflege, sondern drei Sets, die sich langsam auseinanderentwickeln.

Die Frage war nicht „welcher Stack", sondern „welche Zeile"

Der Durchbruch kam über eine unbequeme Übung: Ich bin jede Agenten-Datei Zeile für Zeile durchgegangen und habe zwei Fragen gestellt.

1. Würde diese Zeile in einem FastAPI-Service genauso stimmen?
2. Wenn nein — ist sie Wissen über den Stack oder Wissen über den Prozess?

Das Ergebnis hat mich überrascht. Der weitaus größte Teil einer Agenten-Datei ist Prozesswissen: In welcher Reihenfolge arbeite ich, was lese ich vorher, wem übergebe ich das Ergebnis, wann eskaliere ich. Das ist unabhängig davon, ob darunter Dart, Python oder TypeScript liegt.

Stack-gebunden ist überraschend wenig — aber es ist überall verstreut. Ein Befehl hier, ein Verzeichnispfad dort, eine Namenskonvention im Nebensatz. Genau deshalb war die Datei nicht portierbar: nicht wegen ihres Umfangs, sondern weil das Stack-Wissen im Prozesswissen eingerührt war.

Drei Schichten

Daraus wurde eine Trennung, die inzwischen die Verzeichnisstruktur des Repos ist — und nicht nur eine Idee in meinem Kopf:

Die entscheidende Eigenschaft steckt in der Pfeilrichtung: Der Kern liest den Adapter, nie umgekehrt. Ein Kern-Agent referenziert project-context.md — und es ist ihm egal, ob darin Flutter, FastAPI oder Nuxt steht. Der Dateiname ist stabil, der Inhalt ist variabel.

Das klingt banal. Es ist aber der Unterschied zwischen „ich habe meine Agenten gut sortiert" und „ich kann sie umziehen", denn es macht aus einer Konvention eine Schnittstelle.

Die Regel, die den Kern sauber hält

Eine einzige Regel verhindert, dass die Schichten wieder verschmelzen:

Ein Agent kommt nur in den Kern, wenn er im Ziel-Stack ohne Änderung lauffähig wäre.

Das ist die direkte Lehre aus dem übernommenen Agenten, der nie lief. Alles andere gehört in die Adapter-Rules oder in ein optionales Modul — bei mir ist das UI-Modul so entstanden: Drei Agenten, die ein Design-System und einen Komponentenkatalog voraussetzen. In einem Backend-Projekt haben sie nichts zu suchen, also sind sie kein Kern, sondern eine Zusatzoption.

Die Regel ist unbequem, weil sie oft gegen den kurzen Weg entscheidet. Wenn ein Agent im aktuellen Projekt eine Kleinigkeit besser könnte, indem ich ihm einen Pfad mitgebe, ist das immer verlockend. Der Preis ist, dass genau dieser Agent beim nächsten Umzug wieder derjenige ist, der plausibel improvisiert.

Was Schicht B eigentlich enthält

Der Adapter ist keine Konfigurationsdatei mit ein paar Variablen. Es sind fünf Regel-Dokumente plus ein Skript, und sie beantworten die Fragen, die ein Agent sonst rät:

Zwei Dinge daran waren für mich Umdenken.

Erstens: Das Gates-Skript ist der wichtigste Adapter, nicht die Prosa. Alle fünf Regel-Dateien beschreiben etwas; das Skript tut etwas. Und weil es von der lokalen Session, vom Git-Hook und von der CI identisch aufgerufen wird, kann ein Gate gar nicht lokal grün und in CI rot definiert sein. Darüber schreibe ich im nächsten Beitrag mehr.

Zweitens: Das Referenz-Modul ist eine Pflichtangabe. Der Adapter benennt ein Modul, das die Architekturregeln vorlebt — die Agenten lesen es, bevor sie bauen. Das ist der Unterschied zwischen „halte dich an Clean Architecture" und „so sieht das hier aus". In einem frischen Projekt ist das leicht. In einer gewachsenen Codebase ist es die unangenehmste Frage des ganzen Setups, und die ehrliche Antwort lautet oft: Es gibt keins. Dann benennt man das am wenigsten schlechte Modul und listet seine Abweichungen explizit auf. Das ist ehrlich, aber es ist kein Ersatz für ein sauberes Vorbild.

Die Voraussetzungen, die nichts mit Technologie zu tun haben

Beim Zerlegen ist mir aufgefallen, dass der Workflow über Technologie generalisiert, aber stillschweigende Annahmen über den Kontext macht. Die stehen inzwischen als Tabelle vorn in der Doku, weil sie sonst genau dann auffallen, wenn es zu spät ist:

• Die Gates müssen billig sein. Der Takt „ein Commit pro Plan-Schritt, Gates nach jedem Schritt" setzt Laufzeiten in Minuten voraus. Bei teurem Codegen kippt die Ökonomie, und dann braucht es ein Schnellprofil pro Schritt und das Vollprofil am Ende.
• Eine Person hält alle drei Freigaben. Anforderung, Konzept, Merge — bei mir bin das ich. In einem Team müssen diese Gates Rollen zugeordnet werden, und der Workflow erzwingt die Trennung nicht.
• Der Repo-Host muss ein PR-Gate haben. Ohne Branch-Restrictions auf dem Default-Branch gibt es keine technische Durchsetzung des Merge-Gates — dann trägt wieder nur Disziplin.

Das sind keine Feinheiten. Wer den Workflow ohne diese Voraussetzungen übernimmt, bekommt die Struktur, aber nicht ihre Wirkung.

Der ehrliche Teil: Der Generik-Beweis fehlt

Und jetzt der Absatz, den ich am liebsten weggelassen hätte.

Der Workflow ist in einem produktiven Repository entstanden und gehärtet worden. Ein Port in ein Projekt mit demselben Stack beweist genau nichts — er beweist, dass Kopieren funktioniert. Die versteckten Annahmen zeigen sich erst bei einem stack-fremden Umzug, und der steht bei mir noch aus. Bis dahin sind auch die Installations-Prozedur und der Brownfield-Pfad gut durchdachte, aber ungetestete Wege.

Dazu kommt eine Metrik-Falle, in die ich selbst getappt bin. Um zu messen, wie generisch der Kern ist, habe ich Stack-Nennungen pro Datei gezählt — wie oft kommt „Flutter", „Dart", „pub" in einer Kern-Datei vor? Die Zahl ging schön nach unten. Nur misst sie Vokabular, nicht Kopplung. Eine Datei kann vollkommen stack-neutral formuliert sein und trotzdem eine Verzeichnisstruktur voraussetzen, die es woanders nicht gibt. Als Arbeitsliste war die Messung nützlich, als Beweis taugt sie nichts.

Der einzige echte Test ist ein bewusst feindseliger: ein Stack, den ich nicht mag, ein Mini-Feature, einmal komplett durch die Pipeline. Solange ich das nicht gemacht habe, ist „technologie-generisch" eine Hypothese mit guter Begründung — nicht mehr.

Fazit

Was ich gelernt habe, ist eigentlich eine alte Erkenntnis auf neuem Material: Wiederverwendbarkeit entsteht nicht dadurch, dass etwas gut ist, sondern dadurch, dass die Abhängigkeiten in eine Richtung zeigen. Meine Agenten waren von Anfang an ordentlich geschnitten — aber sie hingen kreuz und quer am Projekt, und deshalb ließen sie sich nicht heraustrennen.

Die Trennlinie, die ich mitnehme: Prozesswissen in den Kern, Stack-Wissen in den Adapter, Projektwissen ins Projekt. Und wenn ich unsicher bin, wohin etwas gehört, ist die Testfrage nicht „wo passt es am besten", sondern „was passiert, wenn diese Angabe im nächsten Projekt fehlt".

Im nächsten Beitrag geht es genau darum: Wie macht man aus dieser Ordnung einen Vertrag, der maschinell geprüft wird — statt einer Konvention, an die sich alle halten sollen?

Wie haltet ihr euer Agenten-Setup projektübergreifend? Kopiert ihr es und passt es an, pflegt ihr bewusst mehrere Fassungen — oder habt ihr eine Trennlinie gefunden, die bei euch trägt? Das würde mich ehrlich interessieren.