claude-regelwerk/AI/Regelwerk/codeworkflow.md

type, status, title, summary, tags, created, updated

type	status	title	summary	tags	created	updated
resource	reference	Codeworkflow	Arbeitsweise für Code-Projekte — Standardschleife, Planaufteilung je Task, Subagenten und ihre Modellstufen, Gegenprüfung, Lauf mit echten Daten, Aufgabenmanagement.	regelwerk codeworkflow code-projekte	2026-08-03	2026-09-18

Codeworkflow

Gilt für alles unter /Code Projekte. Wird nur geladen, wenn tatsächlich an einem Code-Projekt gearbeitet wird — nicht bei IT-Workspace-Recherche, Reviews o. Ä.

Dateikopf, CHANGELOG-Regel und Codedoku stehen seit 2026-08-30 in AI/Regelwerk/codedoku. Die lädst du dazu, sobald Produktivdateien entstehen — nicht beim Planen und nicht beim Debuggen.

Standardschleife

Das ist der Regelfall für jede nicht triviale Code-Aufgabe, nicht die Ausnahme. Rollen sind fest verteilt: der Koordinator (Opus) denkt und prüft, der Executer (Sonnet) tippt.

1 Klären  →  2 Planen  →  3 Ausführen  →  4 Gegenprüfen  →  5 Korrigieren  →  6 Abschließen
 Koordinator  Koordinator   Executer       Koordinator      Koordinator      Koordinator
                                                                  ↑                 │
                                                                  └──── Befund ─────┘

1 Klären. Offene Entscheidungen vor dem Plan stellen, nicht mittendrin. Nur Fragen, deren Antwort die Arbeit verändert — alles andere selbst entscheiden und die Annahme benennen.

2 Planen. Detailplan unter docs/plans/JJJJ-MM-TT-<thema>/ mit echtem Test- und Implementierungscode, exakten Zieldateipfaden und Verifikationsbefehlen. Keine Platzhalter, kein „analog zu Task N". Der Executer sieht nur den Plan, nicht dieses Gespräch.

Plankritik vor dem ersten Executer. Ein Plan ab etwa drei Tasks wird, bevor ein Executer startet, von pruefer-Subagenten (Opus) mit getrennten Linsen gelesen: (1) Fixture-Arithmetik und Rot-Nachweise — jede Mindestzahl im Produktivcode gegen jede Fixture gerechnet, jede erwartete Fehlermeldung wörtlich; (2) Bezeichner, Signaturen über Taskgrenzen, Byte-Treue der Aus-Blöcke, Parsen der Codeblöcke, Prüf-greps nur auf Code; (3) Spec-Abdeckung in beide Richtungen. Der wirksamste Griff: Der Kritiker wendet alle Blöcke des Plans auf einer Kopie unter /tmp an und fährt die Suite dort. Beleg vom 2026-09-16/17 im Projekt „Trading Plattform" (Teil 9, fünf Tasks): 55 Befunde vor dem ersten Executer, darunter zwei blockierende Rechenfehler in Testerwartungen, dreimal ein grep auf die eigenen Kommentare und ein Fehler in der Referenzmessung des Koordinators; der Nachkritiker fand auf der materialisierten Fassung sechs weitere, darunter eine falsche Gültigkeitsgrenze („weit vor Zeile 30" — gemessen Zeile 60) und einen Mutanten, der nur ein zurückgespiegeltes Konfigurationsfeld traf. Danach liefen drei Executer-Wellen ohne eine einzige Abweichung durch. Ohne diese Runde wäre jeder dieser Befunde eine Executer-Meldung oder eine Korrekturrunde geworden — und der Koordinatorkontext ist die knappe Ressource (siehe Schritt 5).

Die Kopie mit dem angewendeten Plan bleibt stehen und ist der Vergleichsstand für jede Welle. Steht der Code wörtlich im Plan, wendet der Koordinator alle Blöcke vor der ersten Welle per Skript auf eine Kopie des Baums an, fährt dort Suite und Mutanten und vergleicht nach jeder Welle zwei Dinge: ob genau die Zieldateien der Taskdateien geändert sind, und ob jede byte-gleich mit der Kopie ist. Beleg vom 2026-09-17 („Trading Plattform", 15 Tasks, vier Wellen): acht abweichende Dateien, sechs davon aus Berichten mit „keine Abweichungen", eine davon ein sichtbarer Fehler bei grünen Tests. Der Vergleich zeigt je Datei nur die erste Abweichung — danach immer diff auf die ganze Datei. Abweichungen an Einzelstellen setzt der Koordinator aus der Kopie, statt denselben Executer-Typ ein zweites Mal an dieselbe Fehlerklasse zu lassen. Die Skripte dafür liegen unter .vault-tools/plan-kopie/ (Gebrauch in LIESMICH.md dort, samt der Warnung zur node_modules-Junction).

Ein Plan ab etwa drei Tasks wird als Ordner angelegt, nicht als eine Datei: 00-uebersicht.md mit Ziel, Architektur, globalen Vorgaben, Dateiübersicht, Tasktabelle und Abnahme, dazu je Task eine Datei task-NN-<thema>.md. Jede Taskdatei verweist im Kopf auf die globalen Vorgaben der Übersicht, statt sie zu wiederholen — zwei Fassungen derselben Vorgabe laufen auseinander.

Die Gründe, in der Reihenfolge ihrer Belastbarkeit. Erstens: Der Auftrag wird präzise. Ein Executer, der nur seine Taskdatei bekommt, kann nicht in einen Nachbartask abrutschen. Zweitens: Die Modellangabe je Task braucht einen Ort, an dem sie steht — das ist das Frontmatter der Taskdatei. Drittens, und schwächer als zunächst angenommen: Tokens.

Zur dritten Begründung die ehrliche Messung vom 2026-08-27 im Projekt „Authentik". Der Gesamtplan umfasste rund 16.300 Tokens, ein einzelner Task rund 1.500. Die Erwartung war, dass die Aufteilung damit den größten Hebel darstellt. Sie tat es nicht. Der erste Lauf ohne Aufteilung kostete 42.918 Tokens, der erste Lauf mit Aufteilung 40.962 — rund 2.000 weniger, obwohl rechnerisch 13.000 weniger Plan gelesen wurde, und obwohl die zweite Aufgabe zugleich die kleinere war. Der feste Aufwand eines Subagenten — Systemvorgaben, Werkzeugbeschreibungen, sein eigenes Nachdenken — dominiert den Einzellauf.

Die Lehre daraus gilt über diesen Fall hinaus: Eine gerechnete Ersparnis ist keine gemessene. Wer einen Hebel einführt, misst ihn nach, bevor er ihn als Regel festschreibt.

Beim programmatischen Aufteilen eines bestehenden Plans: an Überschriften schneiden, die ab dem Abschnittsanfang gesucht werden, und danach Codeblöcke und Überschriften gegen das Original zählen. Ohne diese Zählprobe fällt ein verrutschter Schnitt erst auf, wenn ein Executer nach einem Schritt sucht, der zweimal dasteht.

3 Ausführen. Ein Executer, sofern die Zieldateien nicht sauber trennbar sind; sonst mehrere parallel mit disjunkten Dateimengen. Er bekommt den Pfad seiner Taskdatei — nicht des Gesamtplans —, die erlaubten Zieldateien, die Verbote und den Verifikationsbefehl.

Der Extraktor kennt kein „erst die Tests“. plan_materialisiere.py wendet eine Taskdatei immer vollständig an; Testdateien und Produktivcode entstehen in einem Durchgang. Die Reihenfolge aus Schritt 7 der Taskform — Test anlegen, Fehlschlag im Wortlaut sehen, dann die Umsetzung — lässt sich damit nicht über zwei Aufrufe herstellen. Der belegte Weg steht deshalb in den Auftrag: die fertige Produktivdatei kurz beiseitelegen (etwa aus git show HEAD:<pfad>), den roten Lauf beobachten, die materialisierte Fassung byte-gleich zurücklegen — nie neu schreiben. Am 2026-09-17/18 im Projekt „Home Assistant Dashboard“ sind zwei Executer über diesen Widerspruch gestolpert; beide haben ihn gemeldet statt ihn still aufzulösen, und beide haben den roten Zustand auf diesem Weg belegt. Wer den Satz nicht in den Auftrag schreibt, lässt den Executer zwischen Plan und Werkzeug zerreiben.

Das Modell steht in der Taskdatei, nicht in der Gewohnheit. Jede Taskdatei trägt im Frontmatter modell: und modell_begruendung:. Die Begründung ist Fließtext und steht in Anführungszeichen, wie der Titel (AI/Regelwerk/frontmatter, „Quoting"). Fehlt der Eintrag, gilt die Vorgabe aus dem Stamm: Sonnet. Das Kriterium ist eine einzige Frage:

Braucht der Executer für diesen Task Ermessen, oder steht alles wörtlich im Plan?

Steht der Code wörtlich da, sind die Zieldateien namentlich genannt und die Verbote ausdrücklich, dann ist die Executer-Rolle Abschrift, nicht Autorschaft — dafür genügt Haiku. Bleibt Ermessen offen, ist es Fehlersuche, oder muss Fließtext formuliert statt abgeschrieben werden, dann Sonnet.

4 Gegenprüfen — der Kern der Schleife. Ein Agentenbericht ist eine Behauptung, kein Beleg. Pflicht sind drei Dinge:

• Testlauf selbst wiederholen, nicht die zitierte Ausgabe übernehmen.
• Die zentralen Artefakte selbst lesen (SKILL.md, README, die Hauptmodule) statt sie aus dem Bericht zu glauben.
• Einen eigenen Lauf mit echten Daten fahren, mit eigenem Prüfcode. Nicht die Tests des Agenten. Siehe „Lauf mit echten Daten" unten.

Mechanische Prüfungen brauchen einen Regressionsnachweis. Ein Prüfskript gilt erst als Gate, wenn du es mit absichtlich kaputter Eingabe hast anschlagen sehen — Exit-Code und Meldung selbst beobachtet, nicht aus einem Bericht übernommen. Ohne diesen Nachweis ist ein grüner Lauf kein Ergebnis, sondern eine unbelegte Zusicherung.

Für jede Prüfung, die eine offene Menge einschränkt (verbotene Aktionen, verbotene Wörter, unerlaubte Muster), gilt zusätzlich: Positivliste statt Negativliste. Was nicht ausdrücklich erlaubt ist, ist ein Befund. Eine handgepflegte Negativliste verliert prinzipiell gegen eine offene Menge — 2026-08-18 im Projekt „Logging" fünfmal hintereinander belegt: jede Fassung des Rollenprüfskripts schloss die genannte Lücke und riss eine neue auf. Der Kopfkommentar eines solchen Skripts benennt deshalb seinen Geltungsbereich: was es prüft, was es nicht sieht, und dass es ein Fangnetz ist und kein Nachweis. Wo der belastbare Nachweis erst in der Zielumgebung möglich ist, gehört er dorthin und wird bis dahin als offen geführt.

Sobald ein Skript entsteht, das etwas beurteilt statt etwas zu tun, gilt AI/Regelwerk/pruefwerkzeuge — und zwar vor der ersten Zeile Code. Dort steht der Entwurfsschritt, der die teuren Schleifen verhindert: je Frage, die die Prüfung beantworten soll, die Herkunft der Antwort benennen (Quelle, Projektvorgabe oder Annahme) und jede Annahme auflösen, bevor Code entsteht. Dazu die vollständige Angriffsliste, die Absturzfestigkeit und die Abbruchbedingung. Eine einzige Prüfung hat ohne diese Datei drei Fix-Runden und drei Re-Reviews gekostet.

5 Korrigieren. Befunde am Plan beheben, nicht direkt am Code — sonst laufen Plan und Umsetzung auseinander. Danach den Executer nachziehen lassen, mit dem gefundenen Fehlerbild und der erwarteten Fehlermeldung des neuen Regressionstests. Zurück zu Schritt 4, bis nichts mehr übrig ist.

Fortsetzen oder frisch starten — das ist eine Kostenfrage, und hier liegen Zahlen vor. Eine Nachricht an den bestehenden Executer zieht dessen gesamten bisherigen Kontext mit. Am 2026-08-27 im Projekt „Authentik", zwei Nachbesserungen von je drei Dateien: als Fortsetzung 66.398 Tokens, als frischer Subagent 51.072 — rund 23 Prozent weniger. Das Ergebnis überlebt die Vermischung der Versuchsbedingungen, weil es gegen die Erwartung läuft: Der frische Lauf lief auf dem teureren Modell und kam trotzdem günstiger heraus.

Faustregel: Lässt sich die Nachbesserung in einem Auftrag beschreiben, der für sich steht — geänderte Planstelle, Fehlerbild, erwartete Fehlermeldung —, dann ein frischer Subagent. Fortsetzen nur, wenn der Verlauf selbst gebraucht wird, etwa bei einer Fehlersuche über mehrere Runden.

Die Nachbesserung folgt derselben Reihenfolge wie der Task selbst: erst die neuen Tests, Fehlschlag im Wortlaut beobachten lassen, dann die Implementierung. Wer beides gleichzeitig schreiben lässt, bekommt einen grünen Lauf ohne Beleg, dass die neuen Tests je etwas gemessen haben.

Dabei die Ertragskurve mitschreiben: was hat Runde 1 gefunden, was Runde 2, was Runde 3. Fällt der Ertrag auf Umformulierungen, ist Schluss — und der Prüfer wird im Abschlussauftrag ausdrücklich gefragt, ob eine weitere Runde noch Substanz hat. Er hat darauf brauchbar geantwortet und einmal von sich aus empfohlen, ohne weitere Runde zu committen. Jede Nachbesserung ist selbst neuer, ungeprüfter Code und bekommt in derselben Runde ihren eigenen Regressionsfall.

Werkzeugdisziplin beim Ändern von Plänen und Dokumenten. Zwei Korrekturen sind in einer einzigen Sitzung nicht am Inhalt gescheitert, sondern am Werkzeug:

• Suchen ohne Anker. Eine Suche nach einem Schrittnamen ohne Suchanfang traf den gleichnamigen Schritt eines früheren Abschnitts, der vor dem Suchbeginn lag. Der Schnitt duplizierte alles dazwischen — ein ganzer Task stand zweimal im Plan. Regel: Anker immer ab dem Abschnittsanfang suchen, gegen die nächste Überschrift begrenzen, danach die Einmaligkeit der Überschriften zusichern.

• Globales Ersetzen in gemischten Dateien. In einem Dokument, das Prosa und einzubettenden Skriptcode enthält, war derselbe Ausdruck an einer Stelle der Defekt und an der anderen die Lösung. Positionsgenau ersetzen, danach jedes nicht betroffene Vorkommen einzeln ansehen.

• Escaping-Schichten vermeiden. Code, der in ein Dokument eingebettet wird, aus einer Datei einsetzen statt durch eine Zeichenketten-Schicht. Ein falsch maskiertes Zeilenumbruch-Zeichen machte einen Regressionstreiber im Plan unlauffähig — das dort protokollierte Ergebnis hätte mit der hinterlegten Fassung nie entstehen können.

• Keine gepflegten Zahlen in Erwartungstexten. „Erwartet: 6 Tests grün" muss bei jeder Testergänzung von Hand nachgezogen werden und wird dabei falsch — 2026-08-23 im Projekt „Linux Härtung Rocky Linux - KS" zweimal in einer Sitzung, beide Male als Kollateralschaden eines globalen Ersetzens, das für einen anderen Task gedacht war. Der Executer hat es gemeldet, aber erst nachdem er auf die falsche Zahl hin geprüft hatte. Stattdessen: „alle Tests dieser Datei grün, kein Fehlschlag". Das kann nicht driften und sagt dasselbe.

• Prüfbefehle im Plan treffen nur Code, nicht Prosa. Ein Plan verlangte grep -i killswitch ohne Treffer und enthielt das Wort zugleich in den Docstrings desselben Codeblocks — 2026-09-06 im Projekt „Trading Plattform" zweimal in einem Plan. Einmal hat der Haiku-Executer die Kommentare still umformuliert und „keine Abweichungen" gemeldet; erst der Byte-Vergleich Plan gegen Datei hat es gezeigt. Das andere Mal (Sonnet-Auftrag mit dem ausdrücklichen Satz, Widersprüche zu melden statt umzuformulieren) kam die Meldung. Regel: Ein Prüfbefehl sucht das, was er meint — Importzeilen (grep "^from trading.killswitch"), Aufrufe, Konstanten —, nie ein Wort, das auch in einem erklärenden Kommentar stehen darf. Und jeder Executer-Auftrag trägt den Satz, dass ein Widerspruch im Plan gemeldet und nicht still aufgelöst wird.

• Escape-Folgen und unsichtbare Zeichen überleben die Schreibschicht nicht verlässlich. Eine Unicode-Escape-Folge im Code (Backslash, u, vier Hex-Ziffern) wird auf dem Weg durch die JSON-Eingabe eines Schreibwerkzeugs mal zum echten Zeichen, mal bekommt sie einen zweiten Backslash — beim Executer wie beim Koordinator. Umgekehrt wird ein echtes unsichtbares Zeichen im Plan (etwa U+2028) beim Abschreiben zum Leerzeichen, und der Test dazu bleibt grün und blind. Am 2026-09-17 im Projekt „Trading Plattform" wichen vier von fünf Haiku-Tasks mit solchen Folgen ab, einmal mit sichtbarem Fehler auf der Seite bei grünen Tests; der Koordinator hat denselben Fehler beim Korrigieren des Plans selbst gemacht. Regel: Nach jedem Schreiben einer solchen Stelle die Bytes ansehen (od -c); Korrekturen daran per Skript mit chr()-Codepunkten; nach jeder programmatischen Plankorrektur die Codeblöcke auf Zeilen- und Absatztrenner, Format- und Steuerzeichen absuchen; der Planer vermeidet Escape-Folgen, wo ein sichtbares Zeichen erlaubt ist — und wo die Folge Absicht ist (Homoglyph, unsichtbares Zeichen), sichert ein Test den gerenderten Wortlaut. Die Selbstprüfung eines Executers läuft über das Read-Werkzeug, nicht über grep: Dort sieht man, ob ein oder zwei Backslashes dastehen.

Nach jeder programmatischen Änderung an einem Plan: eingebettete Codeblöcke parsen lassen und die Überschriften zählen. Beides kostet zwei Zeilen und hätte beide Fälle gefangen. Und nach jedem Executer-Lauf: jede vollständig ersetzte oder neu angelegte Datei byteweise gegen den Codeblock im Plan vergleichen — ein Bericht mit „keine Abweichungen" ist eine Behauptung, der Vergleich ist der Beleg.

Die Messung verformt die Arbeit, wenn sie mehr misst als gemeint war. Eine Nachweisvorgabe verlangte Zahlengleichheit über eine ganze Datei — damit musste ein Befehlszusatz auch in Überschriften stehen und machte das Kapitel unlesbar. Der Executer hat das als Abweichung gemeldet statt still davon abzuweichen; der Fehler lag in der Vorgabe, nicht in der Umsetzung. Prüfbefehle auf den Geltungsbereich einschränken, den sie meinen.

Ablaufdokumente werden in Ausführungsreihenfolge geprüft, nicht Block für Block. Ein Installationskapitel wechselte mitten im Text das Arbeitsverzeichnis. Jeder Codeblock war für sich richtig — genau deshalb fällt so etwas beim Lesen nicht auf und beim Kunden schon. Ein Dokument, das jemand von oben nach unten abarbeitet, wird einmal von oben nach unten durchgespielt.

6 Abschließen. Der Koordinator committet (Subagenten nie), ergänzt tasks/lessons.md um jeden Befund aus Schritt 4 und den Abschnitt „Review" in todo.md.

Lauf mit echten Daten

Grüne Tests beweisen, dass der Code tut, was die Tests erwarten — nicht, dass die Erwartung stimmt. Vor der Fertigmeldung deshalb einmal mit echten statt erfundenen Daten durchlaufen: Daten der Zielumgebung, des lokalen Rechners, ein realistischer Datensatz in voller Menge.

Zwei Belege aus einer einzigen Sitzung: 49 synthetische Tests waren grün, während eine Ampel verdreht war und gesunde Systeme gelb markierte — sichtbar erst mit echten Rechnerdaten. Und eine Statusberechnung wirkte korrekt, bis realistische Datenmengen zeigten, dass sie 9 von 11 Bereichen rot färbt und damit nichts mehr unterscheidet.

Was echte Daten aufdecken und Fixtures nicht: verdrehte Vorzeichen, Skalierungsprobleme bei realistischen Mengen, Annahmen über Wertebereiche, und Zusammenspiele, die im Kleinen unauffällig bleiben.

Drei Muster, die grüne Tests zuverlässig verstecken (alle 2026-08-05 in „Bookstack Upload" aufgetreten):

• Die Testumgebung verdeckt die Zielumgebung. capsys fängt stdout in UTF-8 ab, die echte Windows-Konsole läuft unter cp1252 — ein Sonderzeichen in der Ausgabe brach jeden Lauf ab, ohne dass ein Test es je sah. Prüfe Ausgabe, Pfade und Kodierung gegen die Zielumgebung, nicht gegen die Testumgebung.
• Testdoubles, die nur zurückspiegeln. Ein Fake, der beim Lesen zurückgibt, was er beim Schreiben bekam, bestätigt die Annahmen des Produktivcodes statt die echte Schnittstelle. Bei asymmetrischen APIs (Schreiben nimmt IDs, Lesen liefert Objekte) muss der Fake die Asymmetrie nachbilden. Im Zweifel in der API-Dokumentation nachschlagen statt Symmetrie anzunehmen.
• Schalterpaare. Wo ein Schalter Schreibzugriffe freigibt und ein anderer sie unterdrückt, ist die Kombination der Testfall — nicht jeder für sich. Für jeden Trockenlauf-Modus einen Test führen, der über das Testdouble jeden schreibenden Aufruf zählt und auf null prüft, statt nur das erwartete Endergebnis zu betrachten.
• Der Test misst den Inhalt, nicht den Rahmen. (2026-08-07, „Paketierung Intune") Die Layouttests prüften, ob der Text ins Fenster passt — grün. Ob das Fenster auf den Bildschirm passt, prüfte niemand: auf 1366×768 bei 125 % Skalierung lag die Fußzeile mit beiden Schaltflächen unter dem Bildschirmrand, der Benutzer hätte nichts mehr anklicken können. Wo etwas in einen Container gesetzt wird, immer beide Ebenen prüfen: passt der Inhalt hinein, und passt der Container dorthin, wo er landet. Die äußere Ebene gehört als reine Funktion mit den Maßen als Parameter getestet — der Entwicklungsrechner ist nie das kleinste Zielgerät.

Screenshots zur Fehlersuche. Vor CopyFromScreen immer SetProcessDPIAware() aufrufen und das Fenster gezielt über GetWindowRect abfotografieren. Ohne das liefert SystemInformation.VirtualScreen bei aktiver Skalierung die logische Größe, während physische Pixel kopiert werden — das Ergebnis ist ein Ausschnitt der linken oberen Ecke, kein verkleinertes Gesamtbild. Sieht ein Fenster auf einem Screenshot abgeschnitten aus: zuerst das Aufnahmeverfahren prüfen, dann den Code. Sonst wird am Produktivcode ein Fehler „behoben", den es nicht gibt.

Nur für Claude Fable 5.1

Läuft der Koordinator auf Fable 5.1, gelten in der Schleife zusätzlich die Punkte 3, 8, 10, 13 und 15 aus AI/Regelwerk/fable-5-1: unabhängige Werkzeugaufrufe in einer Antwort bündeln, einen entschiedenen Schritt ausführen statt ankündigen, Änderungen und Tests auf den Auftrag beschränken (der Regressionsfall je Nachbesserung aus Schritt 5 bleibt Pflicht — er ist beauftragt, kein Zusatz), Edit vor Write, und während ein Executer läuft das erledigen, was nicht von seinem Ergebnis abhängt. Opus 5, Sonnet 5 und Haiku 4.5 entscheiden selbst, ob sie etwas davon übernehmen — die Rollentabelle ändert sich dadurch nicht.

Haltung zwischen den Schritten

Drei Punkte, die überall in der Schleife gelten:

• Läuft etwas schief, hörst du auf und planst neu. Nicht weitermachen und hoffen. Das gilt auch mitten in Schritt 3, wenn der Executer etwas meldet, das den Plan in Frage stellt.
• Bei nicht trivialen Änderungen einmal innehalten: Gibt es einen eleganteren Weg? Fühlt sich eine Korrektur wie ein Hack an, baust du die Lösung, die du mit dem jetzigen Wissen von Anfang an gebaut hättest. Bei offensichtlichen Korrekturen entfällt die Frage — Eleganz ist kein Grund für zusätzliche Komplexität.
• Einen Fehlerbericht behebst du, statt nachzufragen. Fehlgeschlagene Tests, rote CI, Meldungen im Protokoll: benennen und beheben, ohne dass der Auftraggeber den Kontext wechseln muss.

Wann die Schleife entfällt

Situation	Vorgehen
Einzeiler, Tippfehler, offensichtliche Korrektur	Selbst umsetzen — der Auftragstext kostet mehr als die Änderung
Plan liegt vor, ≥ 2 Dateien oder nennenswerter Umfang	Volle Schleife
Offene Recherche, Architekturentscheidung, Debugging ohne Hypothese	Kein Executer — erst klären und planen

Was die Schleife bisher gefunden hat

Belege aus dem Projekt „Bookstack Upload" (2026-08-05), fünf Fehler, keiner davon aus der Testsuite — die war grün, während drei davon im Code saßen:

• Absturz auf jeder Windows-Konsole, weil capsys die cp1252-Kodierung verdeckt.
• Ein Testdouble, das Anfragen nur zurückspiegelte, machte einen ganzen Pfad nur scheinbar grün.
• Der Probelauf schrieb auf die Produktivinstanz, weil ein Schalterpaar nie gemeinsam getestet wurde.

Wer Schritt 4 auf „Tests laufen lassen" verkürzt, findet nichts davon.

Rollen und Subagenten

Lagere Recherche, Erkundung und parallele Analysen an Subagenten aus — das hält den Koordinatorkontext frei, und das ist die knappe Ressource. Ein Ansatz pro Subagent, sonst vermischen sich die Befunde.

Wie ein Auftrag an einen Subagenten formuliert wird — Imperativ statt „kannst du vorschlagen", Grund zur Regel, Beispiele in Tags, Subagenten nicht für das, was ein grep erledigt — steht in AI/Regelwerk/prompting (Abschnitte 3 und 5). Was das jeweilige Zielmodell daraus macht: AI/Regelwerk/opus-5 für planer und pruefer (keine Selbstprüf-Anweisungen, keine Schwere-Schwelle im Prüfauftrag — Abschnitte 5 und 8), AI/Regelwerk/sonnet-5 für executer und Recherche (wörtliches Befolgen, Geltungsbereich je Task nennen — Abschnitt 5). Verbindlich für Fable 5.1 als Auftraggeber; die Modelle selbst entscheiden.

Executer-Subagent (executer, Sonnet — bei reiner Abschrift Haiku, siehe Modellzuordnung unten) — definiert in .claude/agents/executer.md, eingesetzt in Schritt 3 der Standardschleife oben.

Der Executer setzt um, was bereits entschieden ist. Er plant nicht, er recherchiert nicht, er entscheidet nichts. Sein Auftrag enthält immer: Planpfad, exakte Zieldateipfade, ausdrückliche Verbote, Verifikationsbefehl. Er committet nicht und meldet am Ende Abweichungen und getroffene Annahmen — beides ist im Agent-Prompt als Pflichtfeld verankert.

Meldet er einen Widerspruch im Plan, ist das ein Treffer, kein Fehler: Plan korrigieren, ihn nachziehen lassen. Er darf Zweifelhaftes nie still zurechtbiegen.

Planer-Subagent (planer, Opus) — definiert in .claude/agents/planer.md. Liefert den Detailplan aus Schritt 2, wenn der Koordinator ihn nicht selbst schreibt: exakte Zieldateipfade, echter Test- und Implementierungscode, Verifikationsbefehle, keine Platzhalter. Er schreibt ausschließlich nach docs/plans/.

Prüfer-Subagent (pruefer, Opus) — definiert in .claude/agents/pruefer.md. Übernimmt Schritt 4 mit dem vollen Pflichtprogramm (Testlauf selbst wiederholen, Artefakte selbst lesen, eigener Lauf mit echten Daten und eigenem Prüfcode). Er ändert nichts und liefert eine Befundliste mit Schweregrad, Datei und Reproduktionsweg. Der Koordinator bleibt dabei in der Verantwortung: der Prüferbericht ist ein zweites Paar Augen, kein Ersatz für die eigene Gegenprüfung bei sicherheits- oder datenrelevanten Änderungen.

Quellenpflicht, Pflichtprogramm und Regressionsnachweis des Prüfers stehen maßgeblich in .claude/agents/pruefer.md. Das ist die Ausnahme aus dem Stamm: Der Subagent lädt das Regelwerk nicht, also steht die Regel dort, wo er sie liest, und wird hier nicht wiederholt. Ein Prüfauftrag nennt den tatsächlich eingesetzten Versionsstand, damit der Prüfer an der richtigen Quelle belegen kann.

Dieselbe Quellenpflicht gilt für dich als Koordinator. Was du nicht an einer Quelle belegt hast, wird nicht behauptet, sondern als offen geführt.

Modellzuordnung und Superpowers

Die Rollentabelle steht im Stamm (CLAUDE, Abschnitt „Agenten & Modelle"). Kurz: Denken und Prüfen auf Opus 5, Tippen und Suchen auf Sonnet 5.

Beim Start eines Subagenten das Modell immer explizit angeben. Ohne Angabe erbt der Subagent das Sitzungsmodell — bei Opus-Sitzungen laufen dann auch mechanische Umsetzungsaufgaben auf Opus, was die Zuordnung still aushebelt.

Superpowers-Skills sprechen von „dispatch a general-purpose subagent". Diese Anweisung wird hier auf die eigenen Agenten abgebildet:

Superpowers-Skill / Rolle	Hier verwenden	Modell
brainstorming, writing-plans	planer	opus
subagent-driven-development → Implementer	executer	sonnet, bei reiner Abschrift haiku (siehe Schritt 3)
subagent-driven-development → Task Reviewer / Re-Review	pruefer	opus
requesting-code-review → Code Reviewer	pruefer	opus
verification-before-completion	pruefer	opus
dispatching-parallel-agents (Recherche)	Explore / general-purpose	sonnet
systematic-debugging → Hypothese bilden	Koordinator selbst	Opus 5

Die Modellwahl-Empfehlung in subagent-driven-development („use the least powerful model that can handle each role") bleibt gültig und wird hier auf drei Stufen gebracht: alles Urteilende auf Opus, alles Ausführende auf Sonnet, reine Abschrift auf Haiku. Nur wenn der Executer in der Fehlerbehebungsschleife zweimal hintereinander scheitert, wird die Nachbesserung an einen Opus-Agenten hochgestuft.

Beleg für die dritte Stufe, damit sie nicht als Sparmaßnahme missverstanden wird. Am 2026-08-27 lief Task 1 der Authentik-Werkzeugkette mit Haiku statt Sonnet, inklusive einer Korrekturrunde: null Abweichungen, null stille Zurechtbiegungen, korrekte Testreihenfolge auch bei der Nachbesserung. Die drei Befunde der Gegenprüfung waren Fehler im Plan, nicht in der Umsetzung. Haiku hat keine einzige zusätzliche Korrekturrunde verursacht.

Zwei später gelaufene Tasks erlauben einen fast sauberen Vergleich, weil sie sich im Zuschnitt gleichen — je ein Modul mit Tests und Codedoku, je drei Dateien, je eine Korrekturrunde, beide mit aufgeteiltem Plan und frischem Subagenten für die Korrektur:

	Sonnet	Haiku
Umsetzung	40.962	31.854
Nachbesserung	51.072	36.413
Summe	92.034	68.267

26 Prozent weniger Tokens bei etwa einer Größenordnung geringerem Preis je Token — und ohne Qualitätsunterschied. Beide Modelle: null Abweichungen, null stille Zurechtbiegungen, erwartete Fehlschläge korrekt gemeldet. Haiku brauchte in der Korrektur vier Werkzeugaufrufe mehr.

Was das nicht belegt: Es sind zwei verschiedene Aufgaben, kein kontrollierter Versuch mit derselben. Die Aussage gilt für Tasks dieses Zuschnitts unter einem Plan, der dem Executer Ermessen bewusst wegnimmt — nicht für Executer-Arbeit allgemein. Wer die Stufe auf einen Task anwendet, in dem der Plan eine Lücke lässt, prüft etwas anderes als hier geprüft wurde.

Und der wichtigste Punkt zur Reihenfolge der Hebel: Die teure Ressource ist nicht der Executer, sondern der Koordinatorkontext, den jede zusätzliche Korrekturrunde verbraucht. Ein Modell, das eine Runde spart, schlägt jede Ersparnis am Tokenpreis. Deshalb steht die Frage „braucht dieser Task Ermessen" vor der Frage „welches Modell ist billiger".

Bei parallelem Einsatz zusätzlich:

• Disjunkte Zieldateien. Jeder Subagent bekommt die exakten Pfade genannt, die er anlegen darf, und die Anweisung, nichts anderes anzufassen. Gemeinsam benötigte Dateien (Paket-__init__.py, .gitignore) legt der Koordinator vorher an.
• Subagenten committen nicht. Mehrere gleichzeitige git commit im selben Repository kollidieren am Index-Lock. Der Koordinator committet nach dem Rücklauf, je Task einzeln.
• git status in der Taskdatei nennt die eigenen Zieldateien. „Genau diese Dateien im Baum und sonst nichts" scheitert in einer parallelen Welle an den Dateien der Nachbarn. In die Taskdatei gehört git status --porcelain -- <Zieldateien>; die Mengenprüfung über die ganze Welle macht der Koordinator nach dem Rücklauf.
• Ergebnisse unabhängig nachprüfen. Ein Agentenbericht ist eine Behauptung, kein Beleg. Testlauf selbst wiederholen, bei zentralen Zusicherungen eigenen Prüfcode schreiben statt den des Agenten zu übernehmen.
• Abweichungen abfragen. Jeder Subagent muss am Ende melden, was er anders gemacht hat als beauftragt und warum. Ohne diese Frage bleiben stille Abweichungen unentdeckt.

Aufgabenmanagement

• todo.md im Projektwurzelordner führt die Aufgaben als Checkboxen. Der Skill plane-abgleich setzt darauf auf — die Form ist also nicht kosmetisch.
• Punkte laufend abhaken, nicht gesammelt am Ende. Je Schritt eine Zusammenfassung in normaler Sprache: was sich geändert hat und warum.
• Zu Sitzungsbeginn tasks/lessons.md des Projekts lesen, bevor du planst.
• Nach jedem Durchlauf: Abschnitt „Review" in todo.md, jeder Befund aus Schritt 4 nach tasks/lessons.md — und zwar als Regel formuliert, die denselben Fehler das nächste Mal verhindert, nicht als Fallbeschreibung.

Was der Executer bei der Umsetzung einhält — kleinstmögliche Änderung, Ursachen statt Kaschieren, keine Scope-Erweiterung —, steht in .claude/agents/executer.md und wird hier bewusst nicht wiederholt.

Produktivdateien und Codedoku

Dateikopf, CHANGELOG statt Versionsnummern in der Datei, was aus dem Code verschwindet und was drinbleibt: AI/Regelwerk/codedoku.

Referenzen

• CLAUDE
• AI/Regelwerk/codedoku — Dateikopf und Codedoku
• AI/Regelwerk/pruefwerkzeuge — alles, was beurteilt statt tut
• AI/Regelwerk/fable-5-1 — nur für Fable 5.1: modellspezifische Verhaltensunterschiede
• AI/Regelwerk/prompting — Aufträge an Subagenten formulieren
• AI/Regelwerk/opus-5, AI/Regelwerk/sonnet-5 — Verhalten der Zielmodelle von Planer/Prüfer bzw. Executer
• Code Projekte/_MOC-Code-Projekte