Das agentische Flywheel: selbstverbessernde Entwicklungs-Schleifen

Wer mit Coding-Agenten arbeitet, kennt den Frust: Der Agent macht denselben Fehler immer wieder, und man korrigiert ihn jedes Mal von Hand. Das skaliert nicht. Die Lösung ist ein Schwungrad-Effekt (Flywheel): Man steckt die Mühe nicht in den einzelnen Fix, sondern in das Gerüst, das den Fehler beim nächsten Mal von selbst verhindert. Dieses Gerüst nennt man Harness, und ein gut gebautes Harness wird mit jedem Durchlauf besser. Dieser Guide zeigt, wie man so eine Schleife generisch für ein Software-Projekt aufbaut.

1. 🎯 Das Problem: Agenten ohne Gedächtnis

Ein Sprachmodell hat kein dauerhaftes Gedächtnis über Sessions hinweg. Es lernt aus einer Korrektur heute nicht für morgen. Wer also einen Agenten dreimal darauf hinweist, dass Fehlerfälle getestet werden müssen, wird ihn ein viertes Mal hinweisen müssen, sofern dieser Hinweis nirgends festgehalten ist. Die Arbeit verpufft.

Der Denkfehler dabei: Man behandelt jede Agenten-Ausgabe als Endprodukt, das man von Hand nachbessert. Besser ist es, jede Korrektur als Information über das Gerüst zu lesen. Nicht “dieser Pull Request ist falsch”, sondern “mein Harness lässt diese Klasse von Fehlern durch”.

2. 🔁 Was ein Flywheel ist

Ein Flywheel ist eine Schleife, in der jeder Durchlauf den nächsten erleichtert. Vier Stationen drehen sich im Kreis:

  1. Generierung: Der Agent produziert etwas (Code, Spec, Diagramm).
  2. Verifikation: Ein automatischer Check sagt, ob es taugt (Tests, Build, Lint, Review).
  3. Harness-Verbesserung: Was die Verifikation aufdeckt, wird ins Gerüst zurückgespielt (eine neue Regel, ein neuer Test, ein besseres Template).
  4. Bessere Generierung: Der nächste Durchlauf startet von einem stärkeren Gerüst und macht den Fehler nicht mehr.

Der Witz: Station 3 ist die, die man meistens überspringt. Genau sie macht aus einer flachen Schleife ein Schwungrad. Kief Morris von ThoughtWorks fasst die Rolle des Menschen so: man arbeitet nicht in der innersten Schleife mit (jede Zeile prüfen), sondern darüber, indem man das Harness pflegt, das die Ausgabe erzeugt hat.

3. 🛠️ Der Bauplan in vier Bausteinen

Ein Harness besteht aus vier Teilen, die man explizit machen muss:

Instruktionen. Eine gepflegte Anweisungsdatei im Repo (Konvention: AGENTS.md), die Konventionen, Build-Schritte und wiederkehrende Regeln festhält. Sie ist das Langzeitgedächtnis, das dem Modell fehlt. Wichtig: knapp halten, sonst wird sie ignoriert.

Wiederverwendbare Vorlagen. Spec-Templates, Test-Templates, Definition-of-Done. Sie zwingen jeden Durchlauf in dieselbe Form. Ein rollenbasiertes Setup wie das agentische Rollen-Setup liefert genau solche Vorlagen (Use-Case- und Test-Spec-Templates).

Automatische Checks. Tests, statische Analyse, Build, Linter. Sie sind die Verifikationsstation. Ohne sie weiss der Agent nicht, ob seine Arbeit gut ist, und du musst alles von Hand prüfen. Mehr dazu im Guide zu Eval-driven Development.

Workflow-Regeln. Die Reihenfolge, in der gearbeitet wird (erst Spec, dann Test, dann Code), und wann eskaliert wird. Das ist das Drehbuch der Schleife.

4. 🍽️ Konkret: die Restaurant-Küche, die ihre Rezeptkarten pflegt

Stell dir eine Küche vor, in der ständig neue Köche (Agenten) an die Station kommen. Würde jeder Koch nur nach Zuruf arbeiten, käme jeden Abend etwas anderes heraus. Eine gute Küche hat deshalb Rezeptkarten und ein eingerichtetes mise en place: das Harness.

Nun passiert ein Fehler: Ein Gericht geht ohne Allergie-Hinweis raus. Die schlechte Reaktion ist, dieses eine Gericht zurückzurufen und fertig. Die Flywheel-Reaktion ist, die Rezeptkarte zu ändern, sodass der Allergie-Check fester Schritt wird. Ab jetzt macht kein Koch diesen Fehler mehr, auch nicht der, der morgen neu anfängt. Die Karte (das Harness) wird mit jedem Vorfall besser, und jeder neue Koch startet von einem höheren Niveau.

Übertragen auf ein Software-Beispiel, einen Webshop: Der Agent vergisst wiederholt den Fall “Artikel nicht auf Lager”. Statt jeden Pull Request einzeln zu korrigieren, ergänzt man (a) eine Zeile in AGENTS.md (“Lagerbestand-Edge-Cases sind Pflicht”), (b) einen Eintrag im Test-Template und (c) einen automatischen Test, der bei fehlender Behandlung rot wird. Der nächste Durchlauf fängt den Fehler selbst ab.

5. 🪜 So baust du es selbst (auf hohem Niveau)

  1. Mach das Harness explizit. Lege AGENTS.md, Spec- und Test-Templates und eine Definition-of-Done an. Schreibe auf, was bisher nur in deinem Kopf war.
  2. Schliesse die Verifikationsschleife. Sorge dafür, dass jeder Task einen Check hat, den der Agent selbst laufen lassen kann (Test, Build, Linter). Ohne automatischen Check kein Flywheel.
  3. Wandle jede Korrektur in eine Harness-Änderung um. Die Leitfrage nach jedem Fix lautet: “Welche Regel, welcher Test oder welches Template hätte das verhindert?” Diese Änderung ist der eigentliche Output, nicht der Fix selbst.
  4. Lass den Agenten am Harness mitbauen. Fortgeschritten: Der Agent schlägt selbst Harness-Verbesserungen vor (neue Tests, präzisere Regeln), du gibst frei. Anthropic berichtet, dass ein Agent, der die eigenen Werkzeuge testete und verbesserte, die Bearbeitungszeit um rund 40 Prozent senkte.
  5. Bleib on the loop, nicht in the loop. Review nicht jede Zeile, sondern das Harness. Wenn die Qualität sinkt, änderst du das Gerüst, nicht das einzelne Artefakt.

6. 🔧 Konkret: ein Harness zum Anfassen

Genug Prinzip, jetzt zum Anfassen. Ein Harness ist kein einzelnes File, sondern ein paar zusammenspielende Teile im Repo. So sieht ein minimales Setup aus (am Beispiel der Claude-Code-Konventionen):

mein-projekt/
  AGENTS.md                 # die Regeln und Konventionen (das Langzeitgedächtnis)
  .claude/
    agents/
      qa.md                 # Subagent: leitet Test-Specs aus Use-Cases ab
      developer.md          # Subagent: implementiert per TDD
    commands/
      feature.md            # Slash-Command: der Flow für ein neues Feature
  tests/                    # die automatischen Checks (die Verifikationsstation)
  docs/
    usecases/  tests/  adrs/

Die vier Harness-Teile aus Abschnitt 3 sind hier sichtbar: Instruktionen (AGENTS.md), Vorlagen und Rollen (.claude/agents/), automatische Checks (tests/) und Workflow-Regeln (.claude/commands/feature.md).

Wiederverwenden statt neu erfinden. Hier die Antwort auf eine naheliegende Frage: Die .claude/agents/-Dateien musst du nicht von Grund auf schreiben. Die sechs Rollen-Prompts aus dem agentischen Rollen-Setup sind genau solche Subagenten-Definitionen und lassen sich direkt dort ablegen. Wichtig zu verstehen: Die Instruktionen unterscheiden sich nicht “je Guide”. Es ist ein Harness mit mehreren Schichten, und jeder Guide beschreibt eine andere Schicht desselben Systems: die Instruktionsdatei ist die globale Ebene, die Rollen/Subagenten sind die spezialisierte Ebene, die Evals sind die Prüf-Ebene, und das Flywheel ist die Schleife, die alles zusammenhält.

Eine Korrektur wird zur Harness-Änderung. Der eigentliche Trick in der Praxis. Angenommen, der Agent vergisst wiederholt den Fall “Artikel nicht auf Lager”. Statt den Pull Request von Hand zu fixen, machst du drei kleine, dauerhafte Änderungen:

  # in AGENTS.md, Abschnitt Konventionen
+ - Edge-Case "Artikel nicht auf Lager" ist bei jeder Bestell-Funktion Pflicht.

# in tests/ -> macht den Fehler künftig automatisch rot
def test_bestellung_nicht_auf_lager():
    with pytest.raises(OutOfStockError):
        bestelle(artikel_id="X", menge=1, lagerbestand=0)

Und optional den Edge-Case in die Standard-Checkliste des qa-Subagenten aufnehmen. Ab jetzt fängt das Harness diesen Fehler selbst ab, bei jedem künftigen Lauf, auch in sechs Monaten.

Der Flow in einem Befehl. Damit die vier Stationen nicht jedes Mal von Hand orchestriert werden, verdrahtet ein Slash-Command sie zu einem wiederholbaren Ablauf:

# Datei: .claude/commands/feature.md
---
description: Baut ein Feature spec-getrieben von Use-Case bis Implementierung.
argument-hint: <kurze Feature-Beschreibung>
---
Neues Feature: $ARGUMENTS

Gehe strikt in dieser Reihenfolge vor:
1. Nutze den qa-Subagenten: schreibe eine Test-Spec mit Happy Path und Edge-Cases.
2. Zeige mir die Spec zur Freigabe.
3. Nutze den developer-Subagenten: implementiere per TDD gegen die Spec.
4. Lass `pytest` und `ruff check .` laufen. Erst wenn beide grün sind, bist du fertig.

Aufruf: /feature Warenkorb-Rabattcode. Dieser eine Befehl ist die Schleife aus Abschnitt 2, festgehalten als wiederholbarer Ablauf. Genau hier dreht sich das Schwungrad.

7. ⚠️ Stolperfallen

Ein Harness kann auch zuwuchern. Wenn die Instruktionsdatei zu jeder Kleinigkeit eine Regel hat, ignoriert das Modell sie. Halte sie knapp und prüfe pro Zeile, ob ihr Wegfall wirklich Fehler verursachen würde. ThoughtWorks warnt zudem vor der “bitter lesson”: handgeschnitzte Detailregeln für KI skalieren irgendwann nicht mehr. Das Flywheel ist also kein Freibrief, endlos Regeln anzuhäufen, sondern eine Disziplin, die wenigen wirksamen Regeln zu finden und den Rest über automatische Checks statt über Prosa zu erzwingen.

Anwendung: Second Brain

Mein Brain-Repo ist selbst ein kleines Flywheel. Der Ingest-Lauf verarbeitet Captures, der Lint-Lauf findet Widersprüche und Waisen, und jede Korrektur an AGENTS.md oder an den Pflege-Regeln macht den nächsten Lauf besser. Der Mensch (ich) bleibt on the loop: ich pflege die Regeln und reviewe lokal, statt jede generierte Seite Wort für Wort zu schreiben. Das Konzept dahinter steht unter LLM-Wiki trifft OKF.

📚 Weiterführende Links & Quellen

Intern:

Extern: