Mein Workflow hielt sich nicht an seine eigenen Regeln

Mein Agenten-Workflow lief Anfang Oktober in mehreren Projekten, und er lief gut. Er war nur teuer: Ich stieß regelmäßig an mein Subscription-Limit. Der Kern des Workflows liegt in einem eigenen Template-Repository, kommt per Update in die Projekte und hat deshalb Versionsnummern. Damals war das Version 1.5.2.

Eine externe Analyse meines Blogposts brachte drei Studien ins Spiel. Zwei davon zitiere ich in Teil 1: Kontextdateien kosten mehr und heben die Erfolgsquote im Schnitt nicht, und unter den einzeln getesteten Regeln halfen nur Verbote. Die dritte hat untersucht, wie Repositories auf GitHub ihre Coding-Agenten konfigurieren: Kontextdateien dominieren, Skills und Subagents nutzen nur wenige (Galster et al. 2026). Mein Setup gehörte zu diesen wenigen, und es war teuer, ohne dass ich sagen konnte, warum.

Gefühlt teuer ist keine Diagnose. Aus der Analyse wurde deshalb ein Prüfauftrag.

Rückblick auf Teil 1

In Teil 1 habe ich meinen Workflow in drei Schichten zerlegt: einen Kern, der in jedem Projekt gleich bleibt, einen Adapter je Stack und die Inhalte des Projekts. Die zweite Trennlinie betrifft die Frage, wie Wissen zum Agenten kommt: als Rule, die jeder Agent beim Start lädt, als Skill, den nur bestimmte Rollen vorladen, oder als Skript, das außerhalb des Kontexts prüft. Den Kontext im ersten Turn nenne ich bei der Hauptsession Grundlast und bei einem Subagent Startlast. Dieser Teil zeigt, wie weit mein Setup im Oktober von der zweiten Trennlinie entfernt war und wie ich das geändert habe. Vorweg das Ergebnis: Im Template sank die Grundlast um 84 % und die Startlast je Durchlauf um 47 %. Im echten Projekt fiel der Gewinn kleiner aus, weil die Adapter dort groß sind.

Messen, bevor man spart

Ich wollte wissen, welche Datei wie oft in den Kontext lädt. Ein Audit darf dabei nichts verändern, sonst prüft es am Ende seine eigenen Reparaturen.

Den Auftrag habe ich deshalb als Datei geschrieben, nicht als Chat-Nachricht. Er hat 412 Zeilen, ist versioniert und lässt sich wiederholen und reviewen. Die Datei liegt bewusst außerhalb von .claude/ und wird nirgends importiert. Sonst würde sie in jede Session laden und genau das Token-Budget verfälschen, das sie messen soll.

Der Auftrag hat drei Ziele: Korrektheit, Übereinstimmung mit Anthropics Empfehlungen und Token-Effizienz. Dazu kommen harte Regeln. Das Audit ist read-only, die einzige Schreiboperation ist der Bericht. Jeder Befund braucht einen Beleg als Datei:Zeile oder als Befehl mit Ausgabe. Und das Audit hält selbst Token-Disziplin: erst eine Inventur, jede Datei höchstens einmal ganz lesen, höchstens drei Subagents. Als Referenz bekam die Session eine Tabelle „Was lädt wann in den Kontext“ mit CLAUDE.md, Rules mit und ohne paths:, Skills, Subagents, Memory, Hooks und MCP. Punkte, bei denen ich unsicher war, trugen die Markierung [VERIFY] und mussten gegen die Doku geprüft werden.

Gestartet habe ich das Audit in einer frischen Session:

claude --model claude-opus-5-5 --effort high
> Lies audit/SETUP_AUDIT_PROMPT.md vollständig und führe den Auftrag aus.

Die Session hat zuerst inventarisiert: claude --version, git ls-files auf die Konfigurationspfade, wc -lc je Datei. Tokens hat sie grob als Zeichen ÷ 4 geschätzt und im Bericht immer so gekennzeichnet. Ein kleines Python-Skript las das Frontmatter aller Agenten und Skills. Kein einziger Agent nutzte das Feld skills:, um Wissen vorzuladen. Danach hat die Session das „Required Reading“ jedes Agenten ausgewertet, also die Dateien, die ein Agent laut seiner Beschreibung vor der Arbeit lesen soll. Die Doku-Fragen gingen gebündelt in zwei Anfragen an den eingebauten Subagent claude-code-guide, der für Claude-Code-Fragen gemacht ist und auf einem günstigen Modell läuft.

Der Bericht von Anfang Oktober hatte 23 Befunde und das Urteil „handwerklich solide“ mit zwei großen Schwächen. Die erste war die Grundlast. Alle zwölf Rules hatten keine Pfadbindung und luden deshalb in der Hauptsession und in jedem Subagent, zusammen etwa 17.500 Tokens. Fast jeder Agent las sie über sein Required Reading ein zweites Mal. Ein Feature-Durchlauf belegte allein beim Start der Agenten etwa 312.000 Tokens, davon etwa 80.000 Dubletten. Gemessen ist das im Template mit leeren Adaptern: nur der Agentenstart, nur die Workflow-Konfiguration, Zeichen ÷ 4. Ein Durchlauf ist dabei ein angenommener Feature-Lauf mit einer festen Zahl von Agentenaufrufen, von der Anforderung bis zum Code-Review. „Leere Adapter“ heißt: Gezählt wird nur, was der Workflow selbst mitbringt, ohne Projektinhalt.

Alles, was ein einzelner Agent brauchte, bekam jeder Agent, und die meisten bekamen es zweimal.

Die zweite große Schwäche war die Flutter-Kopplung, die ich in Teil 1 beschreibe. Dazu kamen Lücken in der Durchsetzung. Beides gehört in andere Beiträge dieser Serie: die Kopplung in den Beitrag über den Adapter als prüfbaren Vertrag, die Durchsetzung in den über Verbote als Mechanismus.

Umbauen, ohne Wissen zu verlieren

23 Befunde in einem Rutsch zu beheben, ist der sichere Weg, Wissen zu verlieren. Ein Agent, der aufräumen soll, löscht gern auch das, was ein anderer Agent braucht. Der zweite Auftrag, wieder als Datei, legte deshalb eine Rangfolge fest:

1. Qualität halten: Kein Agent verliert Wissen, keine Durchsetzung wird schwächer.
2. Befunde beheben.
3. Die Migration bestehender Projekte ermöglichen.

Bei einem Konflikt gewinnt das höhere Ziel, also Qualität halten vor dem Beheben der Befunde, und der Konflikt wird festgehalten.

Die harten Regeln dazu würde ich jedem empfehlen. Keine Zeile wird gelöscht, ohne dass sie verschoben wird, eine Dublette ist oder die Frage „Würde das Entfernen zu Fehlern führen?“ mit Nein beantwortet. Im Zweifel bleibt sie. Dieselbe Testfrage empfehlen Anthropics Best Practices für jede Zeile einer CLAUDE.md. Jeder Befund wird vor der Änderung am aktuellen Stand neu geprüft, weil sich das Audit auf einen älteren Commit bezog. Eine Fortschrittsdatei dient als Gedächtnis: Jede Session liest sie zuerst, und so überlebt der Arbeitsstand Session-Wechsel und Kontext-Kompaktierung.

Bevor sich eine Datei änderte, habe ich zwei Messwerkzeuge bauen lassen. measure-context.py schätzt die Grundlast der Hauptsession, die Startlast je Agent, die Dubletten und die Summe je Pipeline-Durchlauf. check-knowledge-reach.py prüft, ob jede Wissensstelle nach dem Umbau noch einen Leser hat, und findet tote Verweise wie „siehe Abschnitt 9“ auf Abschnitte, die es nicht gibt. Die Baseline: 23.162 Tokens Grundlast (die Rules plus alles andere, was die Hauptsession beim Start lädt), 311.804 je Durchlauf, 10 tote Verweise.

Dann kam die Doku. Die externe Analyse hatte vorgeschlagen, Rules per paths: an Dateipfade zu binden. So hatte ich es auch für die Styling-Regeln geplant. Die Doku zu Rules sagt dazu: „A path-scoped rule loads when Claude uses the Read, Write, or Edit tool on a matching file.“ Ob und wann eine Pfad-Rule in einem Subagent lädt, war zum Zeitpunkt des Audits aber nicht dokumentiert, und fast alle meine Agenten laufen als Subagents. Das Vorladen von Skills per skills: im Frontmatter eines Subagents ist dagegen dokumentiert, und ob es wirkt, lässt sich im Transkript prüfen. Damit war paths: aus dem Rennen.

Vor dem Umbau entstand eine Wissenslandkarte: eine Tabelle mit allen Rules, je Rule die Agenten, die sie lesen (mit Beleg), die Zielform, der neue Ort und das Risiko. Als Zielform kamen drei in Frage: Rule, vorgeladener Skill oder Skill, den ein Agent ausdrücklich aufruft. Ich habe die Tabelle freigegeben, bevor eine Datei bewegt wurde. Drei Entscheidungen kamen dabei heraus:

• Rule bleibt nur, was jeder braucht. Das erfüllte allein project-context.md.
• Neu dazu kam eine winzige Rule workflow-index.md mit etwa 300 Tokens: eine Tabelle „Situation → Skill“. Die Entscheidung, ob eine Änderung den kurzen Weg für Kleinigkeiten nimmt oder den vollen Ablauf mit allen Agenten, fällt in der Hauptsession, bevor irgendein Skill läuft. Ohne Index würde dieser Schritt still übersprungen.
• Vorladen per skills: ersetzt paths:.

Umgesetzt wurde in Paketen, und jedes Paket lief durch den Workflow selbst: Der Solution Architect schrieb Konzept und Plan, ein Reviewer-Agent prüfte, ich gab frei, der Implementierungs-Agent (der Developer aus Teil 1) setzte Schritt für Schritt um, der Code-Reviewer prüfte den Branch, ich habe gemergt. Für die Kontextlast hieß das:

• Elf der zwölf Rules wurden zu Skills. Jeder Agent lädt per skills: nur die vor, die er braucht, etwa die Coding-Guidelines beim Implementierungs-Agenten.
• Das Required Reading nennt nur noch Projekt-Dokumente wie den Use Case oder das Konzept, keine Regeldateien mehr.
• Drei Agenten, die keinen Code recherchieren, starten mit omitClaudeMd und damit ohne die CLAUDE.md.
• Lange Listen positiver Stil-Direktiven habe ich gestrichen.

Ein Fund aus der Vorbereitung hat ein eigenes Paket erzwungen: Verschiebt man Adapter-Dateien nach .claude/skills/, stuft das Manifest des Update-Mechanismus, also die Liste der Kern-Dateien, die ein Update überschreiben darf, sie als Kern ein, und ein Update würde befüllte Adapter überschreiben. Wie ich das gelöst habe, gehört zum Adapter-Vertrag.

Geprüft habe ich auf zwei Wegen. Automatisch liefen über 600 Tests (Unit-, Update-, Guard- und Migrationstests) gegen die echte 1.5.2-Baseline, dazu check-knowledge-reach.py mit null Fehlern. Und live in frischen Sessions: Die vorgeladenen Skills kamen an, omitClaudeMd wirkte. Zwei Tage nach dem Bericht ging das als Version 2.0.0 raus.

Was der Umbau im Template gebracht hat

Gemessen mit measure-context.py an beiden Release-Ständen: Template mit leeren Adaptern, nur die Workflow-Konfiguration ohne Systemprompt und Werkzeuge, Zeichen ÷ 4. Für einen Durchlauf nimmt das Skript feste Aufrufzahlen an: Business Analyst 1, Use-Case-Review 2, Solution Architect 1, Konzept-Review 2, Implementierung 2, Test 1, Code-Review 2.

Die Spalte 2.0.0 enthält etwa 20.000 Tokens, die nur rechnerisch entstehen: Manche Prozedur-Skills beginnen mit „Zuerst: Skill X aufrufen“, obwohl der Agent X schon vorgeladen hat. In den Transkripten hat das bei drei Gelegenheiten kein Agent getan, die Spalte ist also eher zu hoch angesetzt. Was ich mit diesen Zeilen gemacht habe, steht in Teil 3.

Der Kern war schlank, der Adapter nicht

Template-Zahlen mit leeren Adaptern sagen wenig über ein echtes Projekt. Also habe ich im ersten echten Feature nach dem Update nachgesehen, in einem meiner Flutter-Projekte (ich nenne es Zielprojekt A). Das Update lief per Skript, die drei Migrationsskripte für Bestandsprojekte danach mit Probelauf. Gemessen habe ich den Kontext im ersten Turn jedes Subagents. Er steht im Transkript unter ~/.claude/projects/<projekt>/<session>/subagents/ in der usage der ersten Antwort des Modells. Das ist eine andere Größe als im Template: der ganze Startkontext mit Systemprompt, Werkzeugen, befüllten Adaptern und Memory, so wie ihn die API zählt.

Die Ergebnisse aus den ersten zwei Tagen:

• Der Konzept-Reviewer startete unter 1.x mit 207.000 Tokens (ein Lauf) und nach 2.0 mit 85.000 bis 87.000 (drei Läufe).
• Der Implementierungs-Agent startete nach 2.0 mit 158.000 Tokens (ein Lauf). Unter 1.x lag sein Median bei 201.000 (20 Läufe). Die Last sank also, aber weit weniger als beim Reviewer.

Der Grund liegt in der Rangfolge von oben. Die Migration hat die Adapter-Inhalte absichtlich Byte für Byte verschoben, damit kein Wissen verloren geht. Die Adapter dieses Projekts waren aber groß (Stand kurz nach der Migration): coding-guidelines hatte 1.787 Zeilen, styling-guidelines 1.021, testing-strategy 776 und quality-gates 471. Der Implementierungs-Agent lädt davon coding-guidelines, testing-strategy und quality-gates vor, zusammen 3.034 Zeilen. Der Kern war jetzt schlank, der Adapter nicht.

Dazu kam ein Nebenbefund. Die Hauptsession dieses Laufs hatte ich kurz vor dem Update noch unter 1.x mit 228.000 Tokens gestartet und nach dem Update fortgesetzt, statt sie neu zu starten. Sie trug den alten Rule-Inhalt weiter im Kontext. Die Regel daraus: nach jedem Workflow-Update eine neue Session starten.

Der naheliegende nächste Schritt war, die großen Adapter-Skills nach Domänen aufzuteilen und nur bei Bedarf zu laden. Ob das funktioniert, habe ich vorher in einem Experiment geprüft, mit einer Abbruchgrenze, die vor dem ersten Lauf feststand. Das Experiment, was stattdessen half, und die Zahlen aus zwei echten Projekten auf dem heutigen Stand stehen in Teil 3.