Software-Factory mit Claude Code: Agenten, Hooks, Reviews

// Die Factory auf einen Blick

Issue (Backlog)
  │
  ▼ /spec – Spezifikation
  │  ideate
  │  refine ⇄ challenge   (max. 5)
  ▼
Ready
  │
  ▼ /ship – Umsetzung
  │  implement
  │  review ⇄ rework      (max. 3)
  │  qa ⇄ rework          (max. 2)
  │  codify (Learnings)
  ▼
Pull Request
  │
  ▼ Merge: nur ich → Deploy per CI

Der Ablauf hat zwei Phasen: Die Spezifikation stresstestet den Plan in höchstens fünf Runden, die Umsetzung durchläuft höchstens drei Review- und zwei Abnahmerunden. Merge und Deployment bleiben beim Menschen.

// Der Workflow: vom Issue zum Pull Request

Jedes Issue wandert über ein GitHub-Project-Board. Die Arbeit ist in Skills zerlegt – Arbeitsanweisungen für Claude Code, die als Befehl mit Schrägstrich aufgerufen werden:

• Spezifikation (/spec): Problem und Akzeptanzkriterien mit mir schärfen (ideate) → Lösung in Arbeitsschritten planen (refine) → Plan stresstesten (challenge).
• Umsetzung (/ship): testgetrieben bauen (implement) → prüfen lassen (review) → nacharbeiten (rework) → abnehmen (qa) → Learnings festhalten (codify).

/spec und /ship sind Dirigenten ohne eigene Fachlogik: Sie rufen die Skills auf und entscheiden anhand von deren Ergebnissen, wie es weitergeht. Jeder Umsetzungslauf arbeitet in einem eigenen Git-Worktree, sodass unabhängige Issues auch parallel laufen können.

// Rollen: Subagents als Planer, Berater, Umsetzer und Prüfer

Ein einzelner Agent, der plant, programmiert, testet und sich danach selbst bescheinigt, dass alles stimmt, ist das Gegenteil von Qualitätssicherung. Deshalb arbeitet die Factory mit Subagents: Ein Subagent ist ein eigener Agent mit frischem Kontextfenster, eigenem Auftrag und, wo nötig, eingeschränkten Werkzeugen.

• Orchestrator: die Hauptsession. Sie verteilt Aufgaben, prüft Ergebnisse nach und ist die Einzige, die Fortschritt im Issue abhakt.
• Kritiker: zerlegt den Plan aus Sicht eines erfahrenen Architekten. Schreibwerkzeuge hat er nicht.
• Umsetzer: ein Java-Entwickler und ein UI-Designer, der an eine verbindliche Design-Spezifikation gebunden ist.
• Review-Team: ein allgemeiner Code-Reviewer und Spezialisten für Architektur, Framework, Design, SEO, Sicherheit, Recht und die Factory selbst. Welche antreten, hängt von den geänderten Dateien ab: Eine Stylesheet-Änderung braucht keinen Rechts-Check, eine Änderung am Impressum schon.
• Tester: nimmt Oberflächen-Änderungen im echten Browser ab. Ohne Oberflächen-Änderung ordnet der Beleg jedes Akzeptanzkriterium einem Test zu.

Hinter der Rollentrennung steckt vor allem Context Engineering – die Frage, was ein Agent wissen soll und was nicht. Ein Reviewer kennt die gemeinsamen Projektregeln, sieht aber nicht den Gesprächsverlauf des Umsetzers, sondern das Ergebnis und einen Auftrag des Orchestrators. Umgekehrt bekommt der Orchestrator nur kurze Berichte zurück und behält so über einen langen Lauf den Überblick.

Unabhängig sind die Prüfer allerdings nur im Kontext, nicht im Modell: Alle Agenten stammen aus derselben Modellfamilie und teilen ähnliche blinde Flecken. Deshalb ergänzt die Factory KI-Urteile um deterministische Prüfungen – dazu unten mehr.

Für delegierte Arbeit gilt: Was ein Agent nicht selbst geprüft hat, steht als NICHT VERIFIZIERT im Bericht, und der Orchestrator führt die genannten Tests selbst noch einmal aus, bevor er sie abhakt.

// Prüfschleifen: KI-Review gegen Nacharbeit

Die Rollen greifen in drei Schleifen ineinander. Das Ergebnis jeder Prüfung – PASS, FAIL oder REVISE – steht als Kommentar in GitHub; der Orchestrator wertet es aus und startet gegebenenfalls eine neue Runde. Ist die Obergrenze erreicht, macht er nicht auf eigene Faust weiter, sondern legt mir die offenen Punkte vor.

Plan gegen Kritik (höchstens fünf Runden). Der Kritiker sucht falsche Annahmen, fehlende Sonderfälle und Konflikte mit den Projektregeln; seine Einwände fließen in die nächste Planungsrunde. Stimmt er zu, ist das Issue bereit zur Umsetzung. Ein Fehler, der hier auffällt, kostet ein paar Absätze Text statt einer Stunde Nacharbeit.

Review gegen Nacharbeit (höchstens drei Runden). Jeder Befund ist blockierend (Bug, Sicherheitsproblem, Regelverstoß, fehlende Tests) oder nicht blockierend (Stil, Vorschläge); nur blockierende Befunde erzwingen eine weitere Runde. Der Umsetzer darf einen Befund begründet ablehnen, und ein Reviewer darf ihn nur erneut melden, wenn sich der Code an der Stelle geändert hat – sonst drehen sich zwei Agenten im Kreis. Abgelehnte blockierende Befunde verschwinden aber nicht: Sie stehen gesondert in der Zusammenfassung, die ich vor dem Merge lese.

Abnahme gegen Nacharbeit (höchstens zwei Fehlschläge). Die Abnahme prüft das Verhalten, nicht den Code. Ihre Befunde werden nicht eingestuft, sondern gelten alle als zu beheben; ablehnen geht nur mit Begründung im Pull Request. Wer zweimal scheitert, hat meist ein Verständnisproblem, das kein dritter Versuch löst.

// GitHub Issues und Pull Requests als Gedächtnis

Die Factory hat keine eigene Datenbank. Alles, was ein Lauf entscheidet oder belegt, steht in GitHub:

• Issue: die Spezifikation, Akzeptanzkriterien als Checkboxen
• Sub-Issues: die Arbeitsschritte, jeder mit vollständigem Umsetzungsplan
• Board: der aktuelle Stand des Laufs
• Pull Request: das Prüfprotokoll mit Reviews, Schleifenergebnissen und begründeten Ablehnungen
• Abnahme-Beleg: Testskript, Schritte und Screenshots, im Branch und als Kommentar im Issue

Damit ist jede Entscheidung eines Agenten nachvollziehbar, ohne zusätzliches Werkzeug. Wird ein Lauf unterbrochen, erkennt eine neue Session aus Board und Kommentaren, wo es weitergeht. Beim Merge lese ich den Diff und den Abnahme-Beleg.

// Claude Code Hooks: Regeln technisch durchsetzen

Hooks sind Skripte, die Claude Code vor oder nach einem Werkzeugaufruf ausführt – und die einen Aufruf blockieren können.

Regeln in einem Prompt sind Wünsche. Regeln in einem Hook sind durchsetzbar.

Deterministisch laufen in der Factory Hooks, Skripte, Tests und die Coverage-Prüfung; Planung, Review-Urteile und die Orchestrierung entscheidet das Sprachmodell. Was mechanisch prüfbar ist, gehört auf die deterministische Seite.

Erzwungen wird:

• Kein Push ohne grünen Build. Ein vollständiger, grüner Build hinterlässt eine Marker-Datei. Der Hook sperrt git push, wenn sie fehlt oder älter ist als die zuletzt geänderte Quelldatei. Teil-Läufe, etwa mit übersprungenen Tests, setzen keinen Marker.
• Kein Push von Factory-Änderungen ohne grünen Selbsttest: Auch Hooks und Skripte haben eigene Testsuiten.
• Kein Merge von Oberflächen-Änderungen ohne Abnahme-Beleg.
• Testabdeckung darf nur steigen: Neuer Code braucht vollständige Abdeckung, die Liste der Altlasten wird nur kürzer.

Verlangt und im Review geprüft wird der Rot-Nachweis: Jeder Schritt beginnt mit einem Test, der ohne die Änderung fehlschlägt. Ein Test, der von Anfang an grün ist, beweist nichts.

Die Sperren haben Grenzen. Konstrukte wie bash -c oder eval rutschen durch die Hooks, und die Berechtigungsregeln von Claude Code, die etwa Force-Push oder rm -rf verbieten, sind einfache Muster, die sich ebenfalls umgehen lassen. Manche Regeln stehen bislang nur im Prompt, darunter die Rundengrenzen und das Merge-Verbot. Direkte Produktionszugänge hat kein Agent, deployt wird nur durch die CI nach dem Merge.

Bleibt die Frage, wer die Wächter bewacht. Die Factory darf ihre eigenen Hooks und Regeln ändern, aber vereinbart nur über denselben Weg wie jeden Code: im Pull Request, mit eigenem Review, grünem Selbsttest und meinem Merge. Ein geänderter Hook wirkt erst danach.

// Aus Fehlern werden Regeln

Der letzte Schritt jedes Issues ist /codify. Er sammelt, was neu oder überraschend war: Beim ersten Vorkommen landet ein Learning als Notiz zum Issue. Findet /codify beim Durchsuchen der bisherigen Notizen dasselbe Fehlerbild ein zweites Mal, wird es hochgestuft – in den Prompt des zuständigen Agenten, in das Regelwerk des Projekts oder, wenn es mechanisch prüfbar ist, als Folge-Issue für einen neuen Hook.

Ein Beispiel: Ein Agent hat einen mehrzeiligen Text mit Backticks über die Shell an GitHub übergeben. Die Shell hat die Backticks als Befehle ausgeführt und dabei einen kompletten Issue-Text zerstört. Seitdem werden Texte für GitHub immer als Datei übergeben.

Weil beide Projekte dieselbe Factory nutzen, fließen Verbesserungen in beide Richtungen: Beim Übertragen ins zweite Projekt hat das erneute Review zweimal eine Lücke in einer Sperre gefunden, die im Original niemand bemerkt hatte.

// Was ich gelernt habe

• Struktur schlägt Prompt-Länge. Kleine Skills, klare Rollen und feste Rundengrenzen machen Läufe vorhersagbarer als jede noch so ausführliche Anweisung.
• Ehrlich trennen, was erzwungen und was nur verlangt ist. Erst diese Trennung zeigt, wo der Mensch hinschauen muss.

// Fazit: überprüfbar statt klüger

Eine Software-Factory macht die KI nicht klüger, sondern überprüfbar. Die wichtigste Regel lautet: Ein Agent, der „fertig“ sagt, muss den Beleg mitliefern.

Wer nur eine Sache übernehmen will, fängt mit einem Hook an, der git push blockiert, solange die Tests nicht grün sind. Alles Weitere wächst aus den Fehlern, die danach noch durchkommen.