Testgetriebene Entwicklung mit KI: die Regel einmal festlegen, für das ganze Projekt

Kurz gesagt

Niveau: Fortgeschritten

Ein KI Assistent schreibt zuerst Code, weil du genau darum gebeten hast, und er vergisst deine Regeln in jeder neuen Sitzung.

  • Schreib die TDD Regel einmal in AGENTS.md (oder CLAUDE.md, Cursor Regeln, Copilot Anweisungen): zuerst der Test, den roten Lauf zeigen, auf Freigabe warten, bestehende Tests nie anfassen, fertig heißt: die ganze Suite ist grün.
  • Gib jeden Test selbst frei, bevor Code entsteht. Im Test steckt die geschäftliche Bedeutung.
  • Lass die Tests selbst laufen und Maschinen prüfen: Pre Commit Hook, Hooks im Assistenten, CI bei jedem Push und Branch Protection, die einen roten Merge blockiert.

Du beschreibst ein Feature, und der Assistent liefert fertigen Code, mit einem Test hinterher oder gar keinem, und morgen hat er vergessen, wie du arbeitest. Dieses Kapitel zeigt, wie testgetriebenes Arbeiten zum Standard für das ganze Projekt wird: eine Regeldatei, ein menschlicher Kontrollpunkt und Prüfungen, die nicht davon abhängen, was die KI behauptet.

Die Frage hinter diesem Artikel

Du weißt, wie testgetriebene Entwicklung geht: erst ein Test, der fehlschlägt, dann gerade so viel Code, dass er grün wird, dann aufräumen, von vorn. Falls nicht, fängt testgetriebene Entwicklung erklärt bei null an, und die zehn Minuten lohnen sich vorher.

Jetzt öffnest du einen KI Assistenten fürs Programmieren, beschreibst ein Feature, und er liefert dir zweihundert Zeilen fertigen Code. Kein Test vorher. Vielleicht einer hinterher, geschrieben so, dass er zu dem passt, was der Code eh schon tut. Am nächsten Morgen startest du eine neue Sitzung und erklärst deine Arbeitsweise wieder von vorn.

Die Frage ist also schlicht: Wie bringe ich einen KI Assistenten dazu, immer zuerst den Test zu schreiben, in jeder Sitzung, über die ganze Laufzeit des Projekts, ohne dass ich mich wiederhole und ohne dass ich ihm einfach glaube?

Die kurze Antwort hat drei Teile. Schreib die Regel einmal auf, in die Datei, die jeder Assistent zu Beginn jeder Sitzung liest. Lass an der einen Stelle, die zählt, einen Menschen entscheiden: wenn der Test freigegeben wird. Und lass die Maschine das Ergebnis prüfen, damit "die Tests laufen durch" etwas ist, das du siehst, nicht etwas, das man dir erzählt.

Dieses Kapitel geht jeden Teil durch, mit dem erfundenen Betrieb, der die ganze Serie begleitet: das Teehaus am Grieskai, ein Onlineshop für Tee aus Graz, der unter teehausgrieskai.example losen Tee und Abos verkauft, mit Kartenzahlung über einen Zahlungsdienstleister, Rabattcodes, Lagerbestand und Bestellmails. Entwickelt wird er von Jana. Am Ende hat sie ein Repository, in dem der Assistent standardmäßig testgetrieben arbeitet und in dem er nicht still damit aufhören kann.

Warum KI Assistenten zuerst zum Code greifen

Ein Assistent tut, worum der Prompt bittet. "Versandkostenfrei ab € 40" bittet um ein Feature, also schreibt er das Feature. Ein Test ist eine zweite Bitte, die niemand ausgesprochen hat.

Der zweite Grund steht ganz offen in der Dokumentation von Anthropic zum eigenen Werkzeug Claude Code. Ein Assistent hört auf, wenn die Arbeit fertig aussieht. Hat er nichts, was er ausführen kann, um zu prüfen, ob sie wirklich fertig ist, bleibt ihm nur der Anschein. Die Dokumentation zieht daraus den trockenen Schluss, dass dann du selbst die Testsuite bist1. Ohne Test findest du also jeden Fehler von Hand.

Auch die Gegenrichtung ist gemessen. Zwei Forscher haben Sprachmodellen Programmieraufgaben mit und ohne die passenden Tests gegeben. Ihr Ergebnis: Mit Testfällen lösen die Modelle die Aufgaben durchgehend häufiger2. Ein Test ist also nicht nur ein Sicherheitsnetz für den Menschen. Er ist die klarste Beschreibung des Ziels, die ein Assistent bekommen kann.

Und es gibt einen dritten Grund, den alle früher oder später lernen, die mit diesen Werkzeugen arbeiten. Schlägt ein Test fehl, ist der schnellste Weg zu Grün nicht immer, den Code zu reparieren. Kent Beck, der Autor von Test Driven Development: By Example, hat 2025 beim Bauen mit einem KI Agenten eine Liste von Warnzeichen geführt. Eines davon: jeder Hinweis, dass der Agent schummelt, etwa indem er Tests abschaltet oder löscht3. Warum das passiert und wie du es erwischst, ist das ganze Thema von wenn die KI den Test statt den Code ändert. Hier reicht es zu wissen, dass es vorkommt. Die Regel muss es also verbieten.

Beispiel: eine Bitte, zwei Antworten

Jana tippt dieselbe Bitte zweimal in eine frische Sitzung.

Beim ersten Mal hat das Repository keine Anweisungen für den Assistenten. Die Bitte lautet: "Versandkostenfrei ab € 40, sonst € 3,95." Der Assistent ergänzt eine Methode im Bestellmodell, ändert die Warenkorbseite und meldet: "Erledigt. Ab € 40 ist der Versand jetzt kostenlos." Kein Test. Jana muss den Shop öffnen, Tee für € 39,99 in den Warenkorb legen, die Versandkosten prüfen, auf € 40 aufstocken, wieder prüfen. Sie ist die Testsuite.

Beim zweiten Mal liegt eine Regeldatei im Repository (der nächste Abschnitt zeigt sie). Dieselbe Bitte. Der Assistent antwortet mit einer Testdatei von zwölf Zeilen, führt sie aus, zeigt, dass sie fehlschlägt, und hält mit einer Frage an: "Hier ist der fehlschlagende Test. Beschreibt er die Regel richtig, bevor ich den Code schreibe?" Jana liest zwölf Zeilen, statt einen Warenkorb von Hand zu prüfen, und ihr fällt etwas auf, das der Assistent nicht wissen konnte. Mehr dazu im ausführlichen Beispiel weiter unten.

Gleiches Werkzeug, gleiches Modell, gleiche Bitte. Der Unterschied ist eine Datei.

Die Regeldatei ist das Gedächtnis des Projekts

Jede Sitzung mit einem Assistenten beginnt mit leerem Gedächtnis. Die Dokumentation von Claude Code sagt es in einem Satz: Jede Sitzung startet mit einem frischen Kontextfenster4. Was du gestern im Chat erklärt hast, ist heute weg.

Was bleibt, ist eine Datei im Repository, die das Werkzeug zu Beginn jeder Sitzung von selbst liest. Jedes Werkzeug hat seinen eigenen Namen dafür, und sie wachsen zusammen:

  • AGENTS.md ist ein offenes Format, eine Art README für Agenten, das inzwischen die Agentic AI Foundation unter dem Dach der Linux Foundation betreut. Die Website nennt über 20 Werkzeuge, die es lesen, darunter OpenAI Codex, Cursor, Gemini CLI, Windsurf und den Coding Agent von GitHub Copilot. Gibt es mehrere Dateien, gewinnt die, die der bearbeiteten Datei am nächsten liegt5.
  • Claude Code liest CLAUDE.md (im Projektordner oder in .claude/CLAUDE.md) zu Beginn jeder Sitzung. Aktuelle Versionen lesen stattdessen AGENTS.md, wenn es keine CLAUDE.md gibt, und eine CLAUDE.md kann mit einer Zeile wie @AGENTS.md eine andere Datei einbinden4.
  • Cursor legt Projektregeln als .mdc Dateien in .cursor/rules ab. Eine Regel mit alwaysApply: true gilt in jeder Chatsitzung, und Cursor unterstützt außerdem AGENTS.md im Projektordner und in Unterordnern6.
  • GitHub Copilot liest Anweisungen für das ganze Repository aus .github/copilot-instructions.md, Anweisungen für bestimmte Pfade aus Dateien in .github/instructions/ mit einem applyTo Muster, und für seine Agenten AGENTS.md Dateien7.

Ein Satz aus der Dokumentation von Claude Code gehört vor jede dieser Dateien: Die Anweisungen werden als Kontext behandelt, nicht als erzwungene Konfiguration4. Eine Regeldatei ist ein sehr gutes Briefing. Sie ist kein Schloss. Deshalb hört dieser Artikel hier nicht auf.

Beispiel: eine Datei für alle Werkzeuge beim Teehaus am Grieskai

Jana arbeitet meistens mit Claude Code, ab und zu mit Cursor, und eine externe Entwicklerin, die gelegentlich aushilft, nutzt lieber Copilot. Alle sollen dieselben Regeln bekommen. Also schreibt Jana die Regeln einmal, in AGENTS.md im Hauptordner des Repositorys, und verweist die anderen Werkzeuge darauf:

teehausgrieskai/
├── AGENTS.md                      # die eine Regeldatei, die die meisten Werkzeuge lesen
├── CLAUDE.md                      # eine Zeile: @AGENTS.md
├── .github/
│   └── copilot-instructions.md    # ein Satz: "Folge AGENTS.md im Hauptordner."
└── docs/
    └── critical-path.md           # der kritische Pfad des Shops, siehe Kapitel 4

Zeile für Zeile:

  1. AGENTS.md enthält die eigentlichen Regeln. Jedes Werkzeug, das das Format kennt, liest sie direkt.
  2. CLAUDE.md enthält nur die Importzeile @AGENTS.md. Claude Code setzt den Inhalt dort ein, sodass derselbe Text auch dann geladen wird, wenn das Werkzeug sonst nur CLAUDE.md lesen würde.
  3. .github/copilot-instructions.md enthält einen Satz, der auf dieselbe Datei zeigt, für den Copilot Chat im Editor.
  4. docs/critical-path.md ist die Liste der Schritte, die nie brechen dürfen, vom Checkout bis zur Bestellmail. Wie du diese Liste findest und aufschreibst, steht in der kritische Pfad in Software. Die Regeldatei verweist darauf, damit der Assistent weiß, wo er besonders vorsichtig sein muss.

Eine Quelle der Wahrheit, drei Wege hinein. Ändert Jana eine Regel, ändert sie sie an einer Stelle.

Die Regel so schreiben, dass niemand sie missverstehen kann

Eine vage Regel bringt ein vages Ergebnis. "Bitte arbeite mit TDD" ist ein Wunsch. Der Assistent stimmt vielleicht zu, schreibt den Code, hängt einen Test dran und glaubt ganz ehrlich, er habe getan, worum du gebeten hast.

Eine Regel, die wirkt, hat vier Eigenschaften.

  1. Sie sagt, was in welcher Reihenfolge passiert. Erst der Test, dann der Fehlschlag zeigen, dann warten, dann Code. Eine Abfolge ist schwerer misszuverstehen als ein Wert.
  2. Sie sagt, was "fertig" heißt, als Befehl. "Fertig heißt: bin/rails test läuft ohne Fehlschläge durch, und du zeigst mir die Ausgabe." Genau das empfiehlt auch die Dokumentation von Claude Code: Verlang einen Beleg, also den ausgeführten Befehl und seine Ausgabe, denn ein bloßes "alle Tests grün" sagt dir sehr wenig1.
  3. Sie verbietet die Abkürzung beim Namen. "Ändere, überspringe oder lösche nie einen bestehenden Test, ohne mich zu fragen." Eine allgemeine Regel zur Qualität deckt das nicht ab. Ein ausdrückliches Verbot schon.
  4. Sie ist kurz. Anthropic empfiehlt, jede CLAUDE.md unter 200 Zeilen zu halten, weil längere Dateien mehr Kontext verbrauchen und schlechter befolgt werden4. Ein TDD Vertrag passt in 20.

Beispiel: der TDD Vertrag in der AGENTS.md vom Teehaus am Grieskai

Diesen Abschnitt setzt Jana ganz oben in ihre AGENTS.md:

## So arbeiten wir: immer zuerst der Test

1. Bevor du Produktivcode schreibst, schreib EINEN fehlschlagenden Test für das Verhalten, das ich beschreibe.
   Unit Tests: Minitest in test/models oder test/services. Abläufe im Browser: Capybara System Tests.
2. Führ nur diesen Test aus und füg die Ausgabe ein. Er muss an der Assertion scheitern,
   nicht an einem Tippfehler oder einer fehlenden Datei. Scheitert er aus dem falschen Grund, reparier zuerst den Testaufbau.
3. HALT und warte, bis ich den Test freigebe. Kein Produktivcode, bevor ich "freigegeben" schreibe.
4. Schreib den wenigsten Code, der den Test grün macht. Keine Extras, kein "wenn ich schon dabei bin".
5. Ändere, überspringe, lösche oder entschärfe nie einen bestehenden Test. Hältst du einen Test für falsch, sag warum und frag.
6. Fertig heißt: `bin/rails test:all` läuft grün durch. Füg die letzten Zeilen der Ausgabe als Beleg ein.
7. Refactoring nur, wenn alles grün ist, und in einem eigenen Commit, getrennt von Verhaltensänderungen.
8. Alles, was in docs/critical-path.md steht (Checkout, Zahlung, Bestellmail): vorschlagen, nie entscheiden.

## Befehle
* Eine Datei: `bin/rails test test/models/delivery_fee_test.rb`
* Alles: `bin/rails test:all`
* Nur Browsertests: `bin/rails test:system`

Zeile für Zeile, für alle, die so etwas noch nie geschrieben haben:

  • Regel 1 nennt das Framework und die Ordner, damit der Assistent keinen neuen Teststil erfindet. Minitest ist die Testbibliothek, die mit Ruby on Rails mitkommt. Ein System Test steuert mit einer Bibliothek namens Capybara einen echten Browser durch den Shop.
  • Regel 2 ist die, die man gern vergisst. Ein Test, der scheitert, weil es eine Klasse noch nicht gibt, beweist nichts über das Verhalten. Ein Test, der scheitert, weil er € 0 erwartet und € 3,95 bekommen hat, beweist, dass er tatsächlich etwas prüft. Das meint "aus dem richtigen Grund scheitern".
  • Regel 3 schafft den menschlichen Kontrollpunkt. Das Wort "freigegeben" ist ein klares Signal, das niemand mit Smalltalk verwechselt.
  • Regel 4 hält die Änderungen klein, und damit lesbar.
  • Regel 5 verbietet die Abkürzung ausdrücklich und gibt dem Assistenten einen legitimen Ausweg: es sagen und fragen.
  • Regel 6 definiert "fertig" als Befehl plus Ausgabe. bin/rails test:all führt alle Tests aus, auch die Browsertests, die ein einfaches bin/rails test standardmäßig auslässt8.
  • Regel 7 stammt direkt aus Kent Becks eigenen Anweisungen an seinen Agenten: nie strukturelle Änderungen und Verhaltensänderungen im selben Commit mischen3. Aufräumen und neues Verhalten lassen sich getrennt viel leichter prüfen.
  • Regel 8 verknüpft den Vertrag mit dem kritischen Pfad. Dort darf der Assistent entwerfen, entscheiden tut Jana.

Der Abschnitt mit den Befehlen ist wichtiger, als er aussieht. Ein Assistent, der raten muss, wie die Tests laufen, rät manchmal falsch und meldet dann, er habe die Suite "nicht ausführen können". Die genauen Befehle nehmen ihm das Raten ab.

Der Kreislauf, zuerst der Test, mit einem Assistenten

Steht die Regel, läuft jedes Feature durch denselben Kreislauf. Es sind sozusagen zwei Beteiligte: du und der Assistent. Jeder hat seine Aufgabe.

  1. Du beschreibst ein Verhalten, in einfachen Worten, mit der Geschäftsregel und ein, zwei Beispielen.
  2. Der Assistent schreibt einen fehlschlagenden Test und zeigt dir den roten Lauf.
  3. Du liest den Test und gibst ihn frei. Das ist die wichtigste Entscheidung. Der Test ist die Spezifikation. Sagt er das Falsche, tut der Code treu das Falsche.
  4. Der Assistent schreibt den wenigsten Code, der grün wird.
  5. Du lässt die ganze Suite selbst laufen, und nur ein grünes Ergebnis zählt.
  6. Bei Bedarf aufräumen, nochmal laufen lassen, committen.

Warum der Mensch bei Schritt 3 und nicht erst am Ende? Weil ein Test viel schneller gelesen ist als Code, und weil dort die geschäftliche Bedeutung steckt. Zwölf Zeilen Test sagen genau, was der Shop seiner Kundschaft verspricht. Die 40 Zeilen Code danach sind nur das Mittel.

Zum Vergrößern antippen: Vollbild, frei verschiebbar

Beispiel: versandkostenfrei ab € 40, mit dem Assistenten testgetrieben gebaut

Hier der ganze Kreislauf beim Teehaus am Grieskai, mit jedem Prompt.

Schritt 1, Jana beschreibt das Verhalten.

Neues Verhalten: Versandkosten.
Bestellungen über € 40 sind versandkostenfrei. Darunter kostet der Versand € 3,95.
Beträge werden in Cent gespeichert. Leg die Regel in eine kleine Klasse, DeliveryFee.
Halte dich an den TDD Vertrag in AGENTS.md.

Schritt 2, der Assistent schreibt den Test und führt ihn aus. Er legt test/models/delivery_fee_test.rb an:

require "test_helper"

class DeliveryFeeTest < ActiveSupport::TestCase
  test "delivery is free over 40 euros" do
    assert_equal 0, DeliveryFee.for(4_001)
  end

  test "delivery costs 3.95 at 40 euros and below" do
    assert_equal 395, DeliveryFee.for(4_000)
  end
end

Von oben gelesen: require "test_helper" lädt die Testumgebung von Rails. Die Klasse fasst die Tests zu einem Thema zusammen. Jeder Block test "..." do ist ein Beispiel, benannt als Satz über ein Verhalten (die Namen bleiben wie aller Code auf Englisch). assert_equal 0, DeliveryFee.for(4_001) heißt: Ich erwarte, dass die Versandkosten für einen Warenkorb von 4.001 Cent (€ 40,01) bei 0 liegen. Der zweite Test legt die Kosten bei genau € 40,00 fest.

Nach Regel 2 legt der Assistent zuerst eine leere Klasse DeliveryFee an, deren Methode for den Wert nil zurückgibt, damit der Test an der Assertion scheitert und nicht an einer fehlenden Klasse. Dann führt er die Datei aus und fügt die Ausgabe ein:

$ bin/rails test test/models/delivery_fee_test.rb
Failure:
DeliveryFeeTest#test_delivery_is_free_over_40_euros [test/models/delivery_fee_test.rb:5]:
Expected: 0
  Actual: nil

2 runs, 2 assertions, 2 failures, 0 errors, 0 skips

Rot, und zwar aus dem richtigen Grund: Der Test hat eine Zahl erwartet und nichts bekommen. Der Assistent hält an und bittet um Freigabe.

Schritt 3, Jana liest den Test und findet die eigentliche Frage. "Über € 40" war in ihrem eigenen Prompt ungenau. Ist ein Warenkorb von genau € 40,00 versandkostenfrei? Der Test sagt nein. Sie fragt beim Inhaber vom Teehaus am Grieskai nach, der sofort antwortet: Im Banner auf der Seite steht "versandkostenfrei ab € 40", also muss genau € 40,00 frei sein. Wer genau € 40 im Warenkorb hat und € 3,95 Versand zahlt, fühlt sich zu Recht hintergangen und schreibt eine Mail.

Jana antwortet:

Noch nicht freigegeben. Die Regel heißt "ab € 40 frei". Ändere die Tests:
4_000 Cent ist frei, 3_999 Cent kostet 395. Dann führ sie nochmal aus.

Der Assistent ändert die beiden Tests auf DeliveryFee.for(4_000) mit Ergebnis 0 und DeliveryFee.for(3_999) mit Ergebnis 395, führt sie aus, zeigt wieder zwei Fehlschläge und wartet. Jana schreibt "freigegeben". Achte darauf, wer den Test geändert hat: der Assistent, weil ein Mensch ihn darum gebeten hat, bevor es überhaupt Code gab. Das ist in diesem Kreislauf der einzige Moment, in dem sich ein Test ändern darf.

Schritt 4, der Assistent schreibt den wenigsten Code, der grün wird.

class DeliveryFee
  FREE_FROM_CENTS = 4_000
  STANDARD_CENTS = 395

  def self.for(subtotal_cents)
    subtotal_cents >= FREE_FROM_CENTS ? 0 : STANDARD_CENTS
  end
end

Zwei benannte Zahlen, damit in einem Jahr niemand raten muss, was 4.000 bedeutet. Eine Methode: Liegt die Zwischensumme bei 4.000 Cent oder mehr, kostet der Versand 0, sonst 395. Das >= ist der ganze Sinn von Schritt 3. Mit > hätte der Shop sein eigenes Banner gebrochen.

Schritt 5, Jana lässt die Suite selbst laufen. Nicht der Assistent: Jana, in ihrem eigenen Terminal.

$ bin/rails test:all
...
214 runs, 389 assertions, 0 failures, 0 errors, 0 skips

Schritt 6, Commit. Aufräumen ist diesmal nicht nötig, passt. Jana committet Test und Klasse zusammen, mit der Nachricht "Versandkostenfrei ab € 40 (DeliveryFee)".

Zähl die Zeit. Den Prompt schreiben, zwölf Zeilen Test lesen, eine Frage an den Inhaber, acht Zeilen Code lesen. Ein paar Minuten. Erwischt hat sie eine Regel, die Kundschaft gegen das eigene Versprechen des Shops € 3,95 berechnet hätte, bei jeder Bestellung von genau € 40, bis sich jemand beschwert.

Lass die Tests selbst laufen, verlass dich nie auf das Wort des Assistenten

Ein Assistent, der "alle Tests grün" schreibt, hat vielleicht recht. Vielleicht hat er aber auch nur eine Datei statt aller ausgeführt, ein altes Ergebnis gelesen oder optimistisch zusammengefasst. Es zählt nur ein Ergebnis, das du selbst siehst.

Es gibt fünf Wege, die Tests zu starten, ohne überhaupt vom Assistenten abzuhängen. Nimm so viele, wie passen.

  1. Von Hand, im eigenen Terminal. In Rails führt bin/rails test die Unit und Integrationstests aus, bin/rails test pfad/zur/datei_test.rb:6 den einen Test in Zeile 6, und bin/rails test:all nimmt die Browsertests dazu8. Für ein JavaScript Frontend mit Playwright startet npx playwright test alle Browsertests9.
  2. Im Watch Mode. Vitest, ein Testrunner für JavaScript und TypeScript, startet in der Entwicklung im Watch Mode, wenn du einfach vitest aufrufst, und führt bei jedem Speichern die betroffenen Tests erneut aus10. Du siehst Rot und Grün, während der Assistent arbeitet.
  3. Vor jedem Commit. Git kann zu festen Zeitpunkten ein Skript ausführen, einen sogenannten Hook. Der Pre Commit Hook läuft, bevor ein Commit entsteht, und endet er mit einem Status ungleich null, bricht Git den Commit ab, bevor er angelegt ist11.
  4. In den Hooks des Assistenten selbst, dazu der nächste Abschnitt.
  5. In der CI bei jedem Push, ebenfalls im nächsten Abschnitt. CI (Continuous Integration, also fortlaufende Integration) ist ein Server, der bei jeder Änderung die ganze Suite ausführt, in einer sauberen Umgebung, auf die kein Laptop Einfluss hat.

Einen Pre Commit Hook kann man mit git commit --no-verify überspringen, das steht so in der Git Dokumentation11. Für einen Notfall ist das in Ordnung, und es ist genau der Grund, warum der Server das letzte Wort hat und nicht der Laptop.

Beispiel: Janas Pre Commit Hook

Jana legt ihre Git Hooks im Repository ab, damit die externe Entwicklerin sie auch bekommt. Sie erstellt .githooks/pre-commit:

#!/bin/sh
# Führt vor jedem Commit die schnellen Tests aus. Die ganze Suite läuft in der CI.
echo "Unit Tests laufen vor dem Commit..."
if ! bin/rails test test/models test/services; then
  echo "Tests fehlgeschlagen. Commit gestoppt. Code reparieren, dann neu committen." >&2
  exit 1
fi

Und aktiviert ihn einmal pro Rechner:

chmod +x .githooks/pre-commit
git config core.hooksPath .githooks

Zeile für Zeile: Die erste Zeile sagt, dass das Skript mit der Standardshell läuft. Die Zeile mit if ! führt die Modell und Servicetests aus, die schnellen, die in Sekunden fertig sind, und prüft, ob sie fehlgeschlagen sind. Wenn ja, schreibt das Skript eine klare Meldung in die Fehlerausgabe und endet mit 1, was den Commit stoppt. core.hooksPath sagt Git, dass die Hooks im Ordner .githooks liegen statt im versteckten Standardordner11. So stehen die Hooks unter Versionskontrolle wie alles andere.

Committet jetzt der Assistent in Janas Auftrag (viele Assistenten können Git bedienen), läuft derselbe Hook. Eine rote Suite stoppt den Commit, egal ob ein Mensch oder ein Assistent den Befehl getippt hat.

Durchsetzen mit Mechanik, nicht mit Vertrauen

Die Dokumentation von Claude Code zieht eine Linie, die für jedes Werkzeug gilt. Es gibt Anweisungen, die das Modell liest und über die es dann selbst entscheidet, etwa ein Prompt oder eine CLAUDE.md. Und es gibt Anweisungen, die das Werkzeug selbst jedes Mal ausführt, egal was das Modell entschieden hat, etwa Hooks und Verbotsregeln1. Die Regeldatei gehört zur ersten Art. Alles in diesem Abschnitt gehört zur zweiten.

Hooks im Assistenten

Claude Code kann deine eigenen Shellbefehle an festen Stellen ausführen: nach einem erfolgreichen Werkzeugaufruf (PostToolUse), davor (PreToolUse) und wenn Claude mit seiner Antwort fertig ist (Stop)12. Der Hook bekommt die Details als JSON über die Standardeingabe, darunter den Pfad der gerade bearbeiteten Datei12. Zwei Exitcodes zählen. Exit 0 heißt: kein Einwand. Exit 2 heißt bei PostToolUse, dass die Meldung aus der Fehlerausgabe Claude als Rückmeldung angezeigt wird, denn die Änderung ist ja schon passiert. Und bei Stop heißt es, dass Claude nicht aufhören darf und weiterarbeitet13.

Daraus ergeben sich zwei nützliche Hooks: nach jeder Änderung den passenden Test ausführen, und das Fertigwerden verweigern, solange die Suite rot ist. Andere Assistenten bieten ähnliche Mechanismen unter anderen Namen. Schau in der Dokumentation deines Werkzeugs nach dem Gegenstück.

Beispiel: zwei Hooks im Repository vom Teehaus am Grieskai

Jana legt .claude/settings.json ins Repository, damit die Hooks für alle gelten, die das Projekt in Claude Code öffnen:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-matching-test.sh" }]
      }
    ],
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/suite-must-pass.sh" }]
      }
    ]
  }
}

Der erste Block sagt: Nach jedem Edit oder Write läuft run-matching-test.sh. Der zweite sagt: Immer wenn Claude fertig werden will, läuft suite-must-pass.sh. $CLAUDE_PROJECT_DIR ist der Projektordner, damit die Pfade von überall funktionieren12.

Das erste Skript sucht den Test zum bearbeiteten Modell und führt ihn aus:

#!/bin/bash
# Nach jeder Änderung: den Test zur geänderten Modelldatei ausführen.
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

case "$FILE" in
  */app/models/*.rb)
    TEST="${FILE/\/app\/models\//\/test\/models\/}"
    TEST="${TEST%.rb}_test.rb"
    ;;
  *) exit 0 ;;
esac

if [ ! -f "$TEST" ]; then
  echo "Kein Test für $FILE gefunden. Schreib zuerst den fehlschlagenden Test (AGENTS.md Regel 1)." >&2
  exit 2
fi
bin/rails test "$TEST" >&2 || exit 2

In einfachen Worten: Lies das JSON, das der Hook bekommt, und hol mit jq, einem kleinen Werkzeug zum Lesen von JSON, den Pfad der bearbeiteten Datei heraus. Ist es ein Modell in app/models, rechne aus, wo sein Test liegen müsste, etwa test/models/delivery_fee_test.rb für app/models/delivery_fee.rb. Alles andere bleibt unberührt. Gibt es keinen Test, sag dem Assistenten, dass er zuerst einen schreiben soll, und ende mit 2, damit die Meldung ankommt. Sonst führ den Test aus, und ende mit 2, wenn er scheitert, damit die Fehlerausgabe direkt zurück an den Assistenten geht.

Das zweite Skript ist das Tor am Ende:

#!/bin/bash
# Bevor Claude fertig wird: die ganze Suite muss grün sein.
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # schon einmal zurückgeschickt: aufhören lassen, die CI ist das nächste Tor
fi

if ! OUTPUT=$(bin/rails test 2>&1); then
  echo "Die Suite ist rot. Reparier den Code, nicht die Tests. Letzte Zeilen:" >&2
  echo "$OUTPUT" | tail -n 30 >&2
  exit 2
fi

Die Prüfung auf stop_hook_active kommt aus der Dokumentation: Sie verhindert ein endloses Hin und Her, und Claude Code setzt sich ohnehin über einen Stop Hook hinweg, der achtmal hintereinander blockiert12. Scheitert die Suite, gehen die letzten 30 Zeilen der Ausgabe mit einer klaren Anweisung zurück an den Assistenten, und Exit 2 hält ihn bei der Arbeit. Scheitert sie ein zweites Mal, darf der Assistent aufhören und meldet eine rote Suite. Das ist ehrlich, und das nächste Tor wartet schon.

CI und Branch Protection

Das letzte Tor läuft auf keinem Rechner im Büro. Ein CI Workflow führt bei jedem Push die ganze Suite auf einem Server aus. Die Branch Protection auf GitHub verweigert dann das Mergen einer Änderung in den Hauptbranch, bis alle Prüfungen, die du als erforderlich markiert hast, bestanden sind14. Ist zusätzlich ein Review vorgeschrieben, gelangen Änderungen nur noch über einen Pull Request auf den geschützten Branch14.

Diesem Tor ist egal, wer den Code geschrieben hat, mit welchem Werkzeug, und ob ein Hook übersprungen wurde. Genau das macht es zur letzten Absicherung.

Beispiel: der CI Workflow und die Branchregel beim Teehaus am Grieskai

Jana legt .github/workflows/ci.yml an, mit GitHub Actions, dem in GitHub eingebauten CI Dienst15. So sieht es aus:

name: CI
on:
  push:
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:17
        env:
          POSTGRES_PASSWORD: postgres
        ports: ["5432:5432"]
    env:
      RAILS_ENV: test
      DATABASE_URL: postgres://postgres:postgres@localhost:5432/teehausgrieskai_test
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          bundler-cache: true
      - run: bin/rails db:prepare
      - run: bin/rails test:all

Zeile für Zeile: on: push und pull_request heißen, dass der Workflow bei jedem Push und jedem Pull Request läuft. Der Job test läuft auf einer frischen Linux Maschine, daneben startet eine PostgreSQL Datenbank als Dienst. Der Block env sagt Rails, dass es die Testumgebung nutzen soll und wo die Datenbank liegt. Die Schritte holen den Code, installieren Ruby und die Gems des Projekts (mit Cache, damit spätere Läufe schneller sind), legen die Testdatenbank an und führen jeden Test aus, die Browsertests eingeschlossen.

Dann, einmalig, legt sie in den Einstellungen des Repositorys auf GitHub eine Schutzregel für main an: Pull Request vor dem Mergen erforderlich, und die Statusprüfung test muss bestehen. Ab jetzt landet nichts mit roter Suite auf main. Nicht ihr eigener Fix am späten Abend, nicht die Änderung der externen Entwicklerin, nicht die des Assistenten.

Warum sich die Schichten multiplizieren

Jede Schicht übersieht manches. Die nützliche Frage ist, wie oft ein Fehler an allen vorbeikommt. Sind die Schichten ungefähr unabhängig voneinander, ist die Wahrscheinlichkeit, dass ein Fehler durch alle Schichten rutscht, das Produkt der Wahrscheinlichkeiten, dass jede einzelne ihn übersieht:

Pdurch=q1⋅q2⋅q3P_{\text{durch}} = q_1 \cdot q_2 \cdot q_3

Dabei ist PdurchP_{\text{durch}} die Wahrscheinlichkeit, dass ein Fehler alle Schichten passiert, q1q_1 die Wahrscheinlichkeit, dass die erste Schicht ihn übersieht, q2q_2 die Wahrscheinlichkeit, dass die zweite ihn übersieht, und q3q_3 dasselbe für die dritte. Wie man Wahrscheinlichkeiten so multipliziert, erklärt Grundlagen: Wahrscheinlichkeit von Grund auf.

Echte Schichten sind nie ganz unabhängig: Einen Test, den es nicht gibt, übersehen alle Schichten gleichzeitig. Deshalb steht der Test selbst, von einem Menschen freigegeben, ganz am Anfang. Die Formel zeigt aber, warum drei unvollkommene Prüfungen eine gute schlagen.

Beispiel: drei Schichten beim Teehaus am Grieskai, mit erfundenen Zahlen

Die Zahlen hier sind erfunden, um die Rechnung zu zeigen, nicht gemessen. Angenommen, die Regeldatei allein wird bei einem von fünf Fehlern ignoriert, also q1=0,2q_1 = 0{,}2. Der Stop Hook übersieht einen von zehn, etwa wenn er nach dem zweiten Versuch aufgibt, also q2=0,1q_2 = 0{,}1. CI mit Branch Protection übersieht einen von 20, meist über langsame Browsertests, die jemand abgeschaltet hat, also q3=0,05q_3 = 0{,}05.

Pdurch=0,2×0,1×0,05=0,001P_{\text{durch}} = 0{,}2 \times 0{,}1 \times 0{,}05 = 0{,}001

Also ist Pdurch=0,001P_{\text{durch}} = 0{,}001, ein Fehler von 1.000. Mit der Regeldatei allein wäre es einer von fünf gewesen. Jede Schicht für sich ist alles andere als perfekt. Zusammen machen sie aus einem wöchentlichen Ärgernis ein seltenes Ereignis.

Zum Vergrößern antippen: Vollbild, frei verschiebbar

Was sich in einem langen Projekt ändert

Am ersten Tag passt alles in den Kopf des Assistenten. Im vierten Monat hat das Projekt Hunderte Dateien, Dutzende Entscheidungen und einen Gesprächsverlauf, den kein Werkzeug ganz behalten kann.

Zwei Dinge passieren. Lange Sitzungen werden verdichtet: Das Werkzeug fasst das Gespräch zusammen, um Platz zu schaffen, und Details, die nur im Chat standen, können dabei verschwinden. Und neue Sitzungen beginnen leer, jeden Morgen. Die Dokumentation von Claude Code ist genau darin, was überlebt: Die CLAUDE.md im Projektordner übersteht die Verdichtung, weil das Werkzeug sie neu von der Platte liest. Eine Anweisung, die danach verschwunden ist, stand nur im Gespräch4. Der Rat ist ebenso klar: Was zählt, gehört in die Datei, damit es bleibt4.

Die Regeldatei ist also nichts zum Anlegen und Vergessen. Sie ist das Langzeitgedächtnis des Projekts und verdient dieselbe Sorgfalt wie Code:

  • Halt sie unter Versionskontrolle und prüf Änderungen daran wie jede andere Änderung. Eine gelöschte Zeile in der Regeldatei ändert das Verhalten jeder künftigen Sitzung.
  • Korrigierst du den Assistenten zweimal wegen derselben Sache, schreib es auf. Die zweite Korrektur ist das Signal.
  • Halt sie kurz. Regeln, die nur für einen Teil des Codes gelten, gehören in Regeln für diesen Teil (.claude/rules/ mit Pfaden, Cursor Regeln mit globs, Copilot Dateien mit applyTo), damit sie nur laden, wenn sie gebraucht werden467.
  • Verweis auf lebende Dokumente, statt sie zu kopieren. Die Liste des kritischen Pfads steht in docs/critical-path.md, und die Regeldatei sagt nur, wo.

Beispiel: Monat vier beim Teehaus am Grieskai

Im vierten Monat merkt Jana, dass der Assistent in zwei verschiedenen Sitzungen einen Integrationstest für die Abo Verlängerung grün gemacht hat, indem er den ganzen Zahlungsdienst durch ein Ersatzobjekt (einen "Mock") ersetzt hat, das immer ja sagt. Der Test war grün und hat über Verlängerungen nichts bewiesen.

Sie erklärt es nicht nochmal im Chat, wo es morgen vergessen wäre. Sie ergänzt zwei Zeilen in AGENTS.md:

9. Integrationstests für Checkout und Abo Verlängerung nutzen FakePaymentProvider (test/support).
   Ersetz in diesen Tests nie den Zahlungsdienst selbst durch einen Mock oder Stub.

Sie committet die Änderung mit der Nachricht "Regeln: Integrationstests nutzen FakePaymentProvider". Am nächsten Tag in der Früh öffnet sich eine frische Sitzung, liest die Datei und schreibt den nächsten Verlängerungstest gegen den Fake Provider, ohne dass es jemand sagen muss. Die Sitzungen der externen Entwicklerin in Cursor bekommen dieselbe Regel aus derselben Datei. Die Korrektur ist einmal passiert und gilt jetzt für alle und jede Sitzung danach.

Was du als Auftraggeber fragen solltest

Lässt du Software bauen, statt sie selbst zu schreiben, musst du weder Hooks noch YAML lesen. Du musst wissen, dass die Absicherungen da sind. Fünf Fragen reichen, und wer gut arbeitet, beantwortet jede in einem Satz und kann sie am Bildschirm zeigen.

  1. Gibt es im Repository eine Regeldatei für die KI Werkzeuge, und steht darin, dass Tests zuerst kommen? Lass sie dir zeigen. Es ist einfacher Text.
  2. Wer gibt einen Test frei, bevor der Code geschrieben wird? Die Antwort sollte eine Person mit Namen sein, nicht "die KI prüft sich selbst".
  3. Laufen die Tests bei jeder Änderung automatisch, auf einem Server? Frag, was mit einer Änderung passiert, deren Test fehlschlägt. Die richtige Antwort: Sie kann nicht gemergt werden.
  4. Was gehört zum kritischen Pfad, und wer entscheidet über Änderungen dort? Die richtige Antwort nennt Checkout, Zahlung und Ähnliches, und eine Person, kein Werkzeug. Was du erwarten kannst, steht in der kritische Pfad in Software.
  5. Kannst du mir das letzte Release zeigen und die Tests, die dafür gelaufen sind? Hier kommen Release Register und Sicherheitstests pro Release ins Spiel.

So arbeite ich übrigens selbst. Ich baue mit Ruby on Rails und Solidus, testgetrieben mit BDD Szenarien, jedes Release geht durch ein Test Gate, und ich nutze KI jeden Arbeitstag nach Risikostufe: Bei niedrigem Risiko baut die KI, bei mittlerem entwirft die KI und ich überarbeite, bei hohem entscheide ich und die KI berät nur. Warum diese Aufteilung zählt und wer die Verantwortung für KI geschriebenen Code trägt, steht in KI schreibt den Code, wer ist dafür verantwortlich.

Beispiel: der Inhaber vom Teehaus am Grieskai stellt die fünf Fragen

Der Inhaber vom Teehaus am Grieskai stellt Jana die fünf Fragen bei einem Verlängerten. Sie öffnet AGENTS.md und zeigt die Regeln 1 bis 3: zuerst der Test, und sie gibt jeden Test frei. Sie öffnet den letzten Pull Request auf GitHub, wo ein grüner Haken neben "test" zeigt, dass die CI bestanden hat, und die Einstellungsseite, auf der main genau diese Prüfung verlangt. Sie öffnet docs/critical-path.md, wo Checkout, Zahlung, Bestellmail und Abo Verlängerung stehen, und Regel 8, nach der der Assistent dort vorschlägt und sie entscheidet. Die Änderung mit den Versandkosten steht in der Historie, samt Test. Zehn Minuten, und der Inhaber weiß, wie eine Änderung in den Shop kommt und wer dafür geradesteht.

Die Regel einmal festlegen, jedes Mal prüfen

Ein KI Assistent arbeitet testgetrieben, wenn du es ihm sagst, in einer Datei, die er in jeder Sitzung liest, mit Worten, die er nicht missverstehen kann. Dieser Teil kostet einmal eine Stunde.

Testgetrieben bleibt er nur, wenn etwas prüft. Ein Mensch gibt jeden Test frei, weil im Test die geschäftliche Bedeutung steckt. Hooks führen die Tests aus, während der Assistent arbeitet. Ein Pre Commit Hook stoppt einen roten Commit. CI und Branch Protection stoppen einen roten Merge, egal wer den Code geschrieben hat.

Die Regel einmal festlegen. Jedes Mal prüfen. Das nächste Kapitel, wenn die KI den Test statt den Code ändert, widmet sich dem einen Weg, auf dem ein Assistent eine rote Suite grün machen kann, ohne irgendetwas zu reparieren, und wie du ihn erwischst.

Wenn dein Projekt so aufgesetzt sein soll, dass die KI testgetrieben arbeitet und nichts Rotes in Produktion kommt, buch den kostenlosen Workshop: Wir zeichnen deinen kritischen Pfad und deine Absicherungen gemeinsam auf, und die ersten zwei Wochen Arbeit gehen auf mich.

Quellen

  1. 1.

    Anthropic, Best practices for Claude Code, Claude Code documentation, 2026, https://code.claude.com/docs/en/best-practices

  2. 2.

    Noble Saji Mathews and Meiyappan Nagappan, Test-Driven Development for Code Generation, arXiv 2402.13521, 2024, https://arxiv.org/abs/2402.13521

  3. 3.

    Kent Beck, Augmented Coding: Beyond the Vibes, newsletter, 25. Juni 2025, https://newsletter.kentbeck.com/p/augmented-coding-beyond-the-vibes

  4. 4.

    Anthropic, How Claude remembers your project, Claude Code documentation, 2026, https://code.claude.com/docs/en/memory

  5. 5.

    Agentic AI Foundation (Linux Foundation), AGENTS.md, 2026, https://agents.md/

  6. 6.

    Cursor (Anysphere), Rules, Cursor documentation, 2026, https://cursor.com/docs/context/rules

  7. 7.

    GitHub, Adding repository custom instructions for GitHub Copilot, GitHub Docs, 2026, https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions

  8. 8.

    Rails Core Team, Testing Rails Applications, Ruby on Rails Guides, 2026, https://guides.rubyonrails.org/testing.html

  9. 9.

    Microsoft, Running and debugging tests, Playwright documentation, 2026, https://playwright.dev/docs/running-tests

  10. 10.

    Vitest, Command Line Interface, Vitest documentation, 2026, https://vitest.dev/guide/cli

  11. 11.

    Git project, githooks: hooks used by Git, Git documentation, 2026, https://git-scm.com/docs/githooks

  12. 12.

    Anthropic, Automate actions with hooks, Claude Code documentation, 2026, https://code.claude.com/docs/en/hooks-guide

  13. 13.

    Anthropic, Hooks reference, Claude Code documentation, 2026, https://code.claude.com/docs/en/hooks

  14. 14.
  15. 15.

    GitHub, Workflow syntax for GitHub Actions, GitHub Docs, 2026, https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax