Sieben Projekte, ein Workflow: wie ich meine Agenten in Kern und Adapter zerlegt habe

Ich entwickle zurzeit sieben Projekte allein: vier private (drei Flutter-Apps und eine Nuxt-Anwendung) und drei beim Arbeitgeber (eine Nuxt-Anwendung mit FastAPI-Backend, einen FastAPI-Service und ein VS-Code-Plugin in React). Alle laufen mit demselben Agenten-Workflow. Dieser Blog und die Landingpages von Atomin, Hamini und Mealkat sind damit gebaut und online. Die Apps Atomin und Hamini sind live und haben Kunden, Mealkat bereite ich gerade für den Release vor. Die Qualität halte ich für stark, auch wenn noch Fehler durchrutschen; wo, zeigt der Abschnitt „Wo ich noch eingreife".

Nur mit diesem Workflow kann ich mehrere Projekte parallel voranbringen, ohne dabei auszubrennen. Entstanden ist er aus einem Versuch, der mich seit der Agentic-Coding-Serie begleitet: auszuloten, wie weit sich Agenten treiben lassen und wie viel Autonomie ich ihnen Schritt für Schritt geben kann. Heute beschreibe ich ein Feature meist in drei bis fünf Sätzen, und die Pipeline bringt es bis zum PR.

Dieser Beitrag erzählt, wie der Workflow aus einem Projekt in sieben kam und was ich dafür an ihm ändern musste. Er ist der erste von drei Teilen. Teil 2 und Teil 3 zeigen, wie ich danach den Token-Verbrauch gemessen und gesenkt habe.

Ein Workflow, ein Repository

In der Agentic-Coding-Serie habe ich beschrieben, wie aus einem einzelnen Prompt ein Team aus spezialisierten Agenten wurde: Business Analyst, Solution Architect, Developer und Test-Agent, die sich ihre Arbeit über Dokumente wie den Realisierungsplan übergeben. Das funktionierte, und zwar in genau einem Repository, der Flutter-App von Mealkat.

Dann wollte ich das Team in ein zweites Projekt mitnehmen. Der Plan war unspektakulär: .claude/ kopieren, Claude Code starten, weiterarbeiten.

Der Solution Architect hielt 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 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.

Dieser Fehlermodus beschäftigt mich seither am meisten: Ein Agent, der keine Vorgabe findet, bricht nicht ab. Er improvisiert. Und improvisierter Output sieht aus wie richtiger. Eine Studie zeigt dasselbe Muster: Ohne ausdrückliche Aufforderung fragen Agenten bei unvollständigen Vorgaben kaum nach und arbeiten ohne die fehlenden Informationen weiter. Ob eine Vorgabe vollständig ist, erkennen die meisten Modelle schlecht (Vijayvargiya et al., ICLR 2026).

Die naheliegende Reaktion wäre gewesen, die Agenten für jedes Projekt umzuschreiben. Das habe ich zuerst getan. Nach dem dritten Projekt pflegte ich drei Agenten-Sets, die langsam auseinanderliefen, und für sieben Projekte wären es sieben geworden.

Zeile für Zeile: Stack oder Prozess?

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?

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 gilt unabhängig davon, ob darunter Dart, Python oder TypeScript liegt.

Stack-gebunden ist wenig, aber es ist überall verstreut: ein Befehl hier, ein Verzeichnispfad dort, eine Namenskonvention im Nebensatz. Deshalb ließ sich die Datei trotz des kleinen Stack-Anteils nicht umziehen. Das Stack-Wissen war im Prozesswissen eingerührt.

Drei Schichten

Aus dieser Übung wurde eine Trennung, die heute festlegt, was ein Workflow-Update anfassen darf und was nicht:

Die wichtigste Eigenschaft steckt in der Pfeilrichtung: Die Abhängigkeit zeigt in eine Richtung, der Kern liest den Adapter. Ein Kern-Agent referenziert project-context.md oder den Skill coding-guidelines, und es ist ihm egal, ob darin Flutter, Nuxt oder FastAPI steht. Der Name bleibt stabil, der Inhalt wechselt. Damit wird aus einer Konvention eine Schnittstelle, die den Umzug möglich macht.

Beim Arbeitgeber hat die Trennung eine zweite Wirkung. Der Kern enthält die Standards, nach denen Agenten arbeiten: Ablauf, Freigaben und Guards, also Hook-Skripte, die verbotene Aktionen blockieren, etwa einen Commit auf main oder einen Schreibzugriff durch eine Rolle, die nur lesen darf. Diese Dateien kann eine Security-Abteilung prüfen und härten, ohne jedes Projekt zu kennen. Projektspezifische Regeln stehen im Adapter und berühren den Kern nicht. Auf den Satz „Wir haben aber ein ganz spezielles Setup" lautet die Antwort deshalb: Dann schreiben wir einen Adapter dafür, der Kern bleibt, wie er ist.

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.

Sie ist die direkte Lehre aus dem übernommenen Agenten, der nie lief. Alles andere gehört in den Adapter oder in ein optionales Modul. So ist bei mir das UI-Modul entstanden: drei Agenten, die ein Design-System und einen Komponentenkatalog voraussetzen. In einem FastAPI-Service haben sie nichts zu suchen, also bleiben sie eine Zusatzoption außerhalb des Kerns.

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

Was im Adapter steht

Der Adapter besteht aus fünf Dokumenten und einem Skript. Sie beantworten die Fragen, die ein Agent sonst rät:

Seit dem Umbau, den ich in Teil 2 beschreibe, liegt nur project-context.md als Rule immer im Kontext. Die anderen vier Dokumente sind Skills, die nur die Agenten vorladen, die sie brauchen.

Das Gates-Skript ist der wichtigste Adapter. Die fünf Dokumente beschreiben etwas, das Skript führt es aus. Weil die lokale Session, der Git-Hook und die CI es identisch aufrufen, kann ein Gate nicht lokal grün und in der CI rot definiert sein.

Das Referenz-Modul ist eine Pflichtangabe. Der Adapter benennt ein Modul, das die Architekturregeln vorlebt, und die Agenten lesen es, bevor sie bauen. Das ist der Unterschied zwischen „halte dich an Clean Architecture" und „so sieht das hier aus". Anthropic empfiehlt dasselbe: Claude auf bestehende Muster im Code zu verweisen (Claude Code Best Practices). In einem frischen Projekt ist das leicht. In einer gewachsenen Codebase lautet die Antwort oft: Es gibt keins. Dann benenne ich das am wenigsten schlechte Modul und liste seine Abweichungen auf. Das ist transparent, ersetzt aber kein sauberes Vorbild.

Trotzdem hilft die Struktur gerade in Brownfield-Projekten. Der Adapter hält fest, was in einer gewachsenen Codebase sonst nur in den Köpfen des Teams steckt: Architekturregeln, bekannte Altlasten, das am wenigsten schlechte Vorbild. Die Pipeline sorgt dafür, dass ein Agent erst recherchiert, plant und sich prüfen lässt, bevor er Code schreibt. Eine explorative Umfrage unter 52 Entwicklern, die überwiegend an Bestandssystemen arbeiten, deutet in dieselbe Richtung: Ad hoc genutzt fanden die meisten KI dort wenig hilfreich, mit einem festen Ablauf aus Recherche, Plan, Review und menschlicher Freigabe deutlich hilfreicher (Sharma 2025). Ein Beleg ist das nicht: Die Zahlen sind Selbsteinschätzungen ohne Kontrollgruppe, und untersucht wurden Chat-Werkzeuge, keine Agenten, die selbst Code ändern.

Die zweite Trennlinie: Wer braucht das Wissen, und wann?

Die drei Schichten legen fest, welches Wissen wohin gehört. Wie es zum Agenten kommt, hängt am Mechanismus. Claude Code bietet mehrere, und sie unterscheiden sich vor allem darin, wann sie in den Kontext laden und wer sie zu sehen bekommt.

Die Ladezeitpunkte stehen in der Doku zu Rules, Skills und Subagents.

Für jedes Stück Wissen stelle ich drei Fragen: Wer braucht es? Wann braucht er es? Muss es garantiert gelten? Wenn es garantiert gelten muss, gehört es in ein Skript.

Die Trennung wirkt direkt auf die Qualität der Ergebnisse:

• Jeder Agent startet mit frischem, schlankem Kontext. Laut Anthropic sinkt die Leistung, je voller der Kontext ist; Claude vergisst dann frühere Anweisungen oder macht mehr Fehler (Best Practices). Eine Studie mit 15 Modellen hat den Effekt gemessen: Kommen die Anforderungen verteilt über mehrere Nachrichten, sinkt die Leistung im Schnitt um 39 %. Stehen dieselben Informationen gebündelt in einer frischen Anweisung, erreichen die Modelle 95 % ihres Bestwerts (Laban et al. 2025). Ein Subagent, der mit dem freigegebenen Konzept startet, arbeitet im zweiten Fall. Styling-Regeln wären im Kontext des Business Analysten nur Rauschen.
• Rollen haben Grenzen. Ein Reviewer ohne Schreibrechte meldet jeden Fehler, den er findet, weil er ihn nicht selbst beheben kann. Werkzeuge je Subagent einzuschränken, nennt die Doku ausdrücklich als Zweck von Subagents (Subagents).
• Hooks laufen immer. Sie sorgen laut Doku dafür, dass eine Aktion passiert, statt sich darauf zu verlassen, dass das Modell sie ausführt (Hooks). Wo doch Text nötig ist, spricht eine Studie für Verbote: Sie wertete über 5.000 Läufe mit Claude Code aus. Von 18 einzeln geprüften Regeln waren drei nützlich und vier schädlich; die nützlichen waren alle Verbote, die schädlichen alle positive Direktiven (Zhang et al. 2026).
• Jeder Schritt ist prüfbar. Gates liefern grün oder rot. Dieselbe Doku empfiehlt, Claude eine Prüfung zu geben, die es selbst ausführen kann: Tests, einen Build, einen Screenshot zum Vergleich.
• Übergaben laufen über Dokumente. Use Case, Konzept und Plan sind Artefakte, die ein Reviewer prüft, bevor Code entsteht. MetaGPT beschreibt dasselbe Prinzip: Feste Abläufe, die Zwischenergebnisse prüfen, sollen Fehler beim Verketten von Agenten reduzieren (Hong et al., ICLR 2024).

Ein Team aus Agenten ist allerdings nicht per se besser als ein einzelner Agent. Eine Studie, überwiegend von der UC Berkeley, fand bei Multi-Agenten-Systemen auf gängigen Benchmarks oft nur minimale Gewinne. Ihre Fehler ordnet sie drei Kategorien zu: Systemdesign, Abstimmung zwischen den Agenten und Verifikation (Cemri et al. 2025). Mein Workflow setzt an diesen drei Stellen an: feste Rollen und der Adapter für das Design, Dokumente für die Übergabe, Gates und Reviews für die Verifikation. Dazu kommen meine Freigaben und eine Obergrenze für Review-Runden.

Ich richte das Setup an den offiziellen Empfehlungen von Anthropic aus und gleiche es gegen die aktuelle Doku ab, weil sich Claude Code schnell ändert. Die Varianten des Workflows für GitHub Copilot CLI und opencode erzeugt ein Skript aus denselben Quellen (derselbe Workflow in drei Werkzeugen), der Kern ist damit in Grenzen auch vom Werkzeug unabhängig.

Dass meine eigene Umsetzung diese Trennlinie lange verletzt hat und was mich das an Tokens gekostet hat, ist die Geschichte von Teil 2.

Wo ich noch eingreife

Wie viel ich selbst noch tue, habe ich an sechs Wochen Session-Transkripten aus zwei meiner Projekte nachgezählt. Ein Agent hat dafür jede meiner Nachrichten einer Kategorie zugeordnet. In dieser Zeit liefen 30 Vorhaben, Features und Bugfixes, durch die Pipeline, und ich habe 77 PRs gemergt. Ein Vorhaben kann mehrere PRs haben, wenn nach dem ersten PR noch Anpassungen folgen.

Über die Hälfte meiner Eingaben war geplant: der Auftrag in wenigen Sätzen, die Freigabe von Use Case und Konzept, Antworten auf Rückfragen und der Merge. Ungeplant eingegriffen habe ich in etwa jeder fünften Nachricht, meist wegen der Umgebung oder wegen eines Fehlers im Ergebnis. Gut die Hälfte der Vorhaben kam ohne eine einzige Korrektur aus.

Die 32 Fehler, die ich korrigieren musste, fand ich meist an Stellen, die kein Gate sieht: im Verhalten auf dem echten Gerät und in fachlichen Lücken der Spezifikation. Die CI hat nur vier davon gefunden.

Deshalb prüfe ich heute an zwei Stellen. Vor dem Code prüfe ich die Absicht, also Use Case und Konzept. Vor dem Merge prüfe ich das Ergebnis, also die E2E-Tests und einen Test auf dem Gerät. Den Code dazwischen prüfen der Code-Reviewer-Agent und die Gates.

Im Juni sah das noch anders aus. Beim Durchlauf in Post 15 habe ich bei einem einzigen Feature an vier von fünf Checkpoints eingegriffen. Heute kommt gut die Hälfte der Vorhaben ohne Korrektur durch. Erhoben sind die beiden Zahlen unterschiedlich, damals ein Feature, heute 30 Vorhaben, aber sie zeigen in dieselbe Richtung.

Kontrollarbeit bleibt trotzdem (darüber habe ich in Post 22 geschrieben): Statusfragen, die Pflege des Workflows selbst und die Abstimmung zwischen parallelen Sessions kosten weiterhin Aufmerksamkeit.

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. Sie stehen inzwischen als Tabelle vorn in der Doku, weil sie sonst erst 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.

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

Der Preis: Tokens

Das Setup verbraucht spürbar mehr Tokens als eine einzelne Session mit einem guten Prompt, und ich bin damit regelmäßig an mein Subscription-Limit gestoßen.

Die Kosten haben eine klare Herkunft. Jeder Subagent startet mit eigenem Kontext und lädt die Projekt-Konfiguration erneut, inklusive aller Rules ohne Pfadbindung. Was ein Agent schon im ersten Turn belegt, nenne ich seine Startlast. Ein Developer-Agent, der pro Plan-Schritt aufgerufen wird, zahlt sie bei jedem Schritt, und Subagents zählen auf dasselbe Nutzungslimit wie die Hauptsession (Subagents). Anthropic hat für sein eigenes Recherchesystem gemessen, dass Agenten etwa viermal und Multi-Agenten-Systeme etwa fünfzehnmal so viele Tokens verbrauchen wie ein Chat (Multi-agent research system).

Ich zahle den Preis trotzdem. Die Hauptsession bleibt klein, weil ein Subagent zwanzig Dateien liest und ihr nur sein Ergebnis zurückgibt. Anthropic beschreibt Subagents in seiner Anleitung zum Context Engineering genauso: Sie liefern eine verdichtete Zusammenfassung, oft 1.000 bis 2.000 Tokens (Effective context engineering). Das Gates-Skript und die Hooks laufen außerhalb des Kontexts, eine Regel, die ein Skript prüft, muss also nicht in jeder Session als Text mitreisen. Gates fangen Fehler früh ab: Ein Gate, das nach einem Plan-Schritt rot wird, kostet einen kurzen Korrekturlauf, ein Fehler, der erst im Review auffällt, eine lange Session voller Rückfragen. Und weil Stack-Wissen, Rollen und Prozess getrennt liegen, kann ich gezielt sparen: die Coding-Guidelines nur dem Developer mitgeben, die Styling-Regeln nur den UI-Agenten und mechanische Rollen auf ein günstigeres Modell legen. Eine einzige große CLAUDE.md lädt jeder Agent ganz.

Mehr Konfiguration ist dabei nicht automatisch besser: Eine Studie mit Beteiligung der ETH Zürich hat gemessen, dass Kontextdateien die Erfolgsquote nicht signifikant verbessern, die Inferenzkosten aber erhöhen: automatisch erzeugte im Schnitt um 20 bis 23 %, von Entwicklern geschriebene um bis zu 19 % (Gloaguen et al. 2026).

Wo der Workflow heute läuft

Inzwischen läuft der Workflow in sieben Projekten auf vier Stacks: Flutter, Nuxt, FastAPI und React. Die drei Flutter-Projekte teilen den Stack mit dem Ursprungsrepository und zeigen vor allem, dass Kopieren funktioniert und sich das UI-Modul sauber zuschalten lässt. Die eigentlichen Umzüge waren Nuxt, FastAPI und das VS-Code-Plugin in React: andere Sprachen, andere Verzeichnisstrukturen, andere Werkzeuge für Tests und Gates. Dort entstanden nur die Adapter neu, der Kern blieb.

Ob ein Agent improvisiert, zeigt ein laufendes Projekt nicht. Um zu messen, wie generisch der Kern ist, habe ich anfangs Stack-Nennungen pro Datei gezählt, also wie oft „Flutter", „Dart" oder „pub" in einer Kern-Datei vorkommen. Die Zahl ging schön nach unten und hat das Vokabular gemessen. Eine Datei kann stack-neutral formuliert sein und trotzdem eine Verzeichnisstruktur voraussetzen, die es woanders nicht gibt.

Auch der Umzug nach Nuxt hat das nicht aufgedeckt. Der Workflow lief dort, ohne dass etwas laut kaputtging. Die verbliebene Kopplung fand erst das Audit aus Teil 2, das jede Kern-Datei mit Beleg geprüft hat: Der Test-Agent und zwei Templates setzten noch Flutters Testverzeichnis, Test-API und Selektoren voraus. Das ist derselbe Fehlermodus wie am Anfang dieses Beitrags.

Seitdem prüfe ich Kopplung direkt: Bei Änderungen am Setup-Weg spielt ein Selbsttest Installation und Prüfung an kleinen Beispielprojekten in drei Stacks durch. Wie das aufgebaut ist, beschreibe ich im Beitrag über denselben Workflow in drei Werkzeugen.

Offen ist eine Frage, die keines dieser Projekte beantwortet: Alle habe ich allein gebaut. Ob der Workflow genauso trägt, wenn die drei Freigaben im Team auf mehrere Rollen verteilt sind, habe ich noch nicht erprobt.

Was ich mitnehme

Wiederverwendbar wird etwas, wenn seine Abhängigkeiten in eine Richtung zeigen. Meine Agenten hingen kreuz und quer am Projekt, auch wenn jeder einzeln ordentlich geschnitten war, und ließen sich deshalb nicht heraustrennen. Seit sie in einer Richtung hängen, kann ich sie in sieben Projekten einsetzen und muss selbst nur noch an zwei Stellen prüfen.

Die Trennlinien, die ich mitnehme:

• Prozesswissen in den Kern, Stack-Wissen in den Adapter, Projektwissen ins Projekt. Wenn ich unsicher bin, wohin etwas gehört, frage ich: Was passiert, wenn diese Angabe im nächsten Projekt fehlt?
• Jedes Wissen nur dorthin, wo es gebraucht wird, und alles, was garantiert gelten muss, in einen Mechanismus.

In Teil 2 zeige ich, wie ich mit einem Audit gemessen habe, wohin meine Tokens gingen, an welchen Stellen mein eigenes Setup die zweite Trennlinie verletzt hat und was der Umbau gebracht hat. Teil 3 zeigt, was danach noch half, welches Experiment ich abgebrochen habe und was die Zahlen aus zwei echten Projekten sagen.

Wie viele Projekte betreut ihr mit eurem Agenten-Setup, und an welchen Stellen greift ihr selbst noch ein?