Verification Layer: Done bedeutet, es gibt Belege
Du beweist, dass eine Änderung funktioniert, bevor sie committet wird, und du baust die Prüfungen, die den nächsten Beweis günstiger machen. Die Aufgabe des Menschen verlagert sich vom Lesen jedes Diffs hin zur Definition von „fertig“ und zum Lesen der Belege. Deine Aufgabe ist es, diese Belege ehrlich zu produzieren.
Die Prinzipien stammen aus How the Claude Code team thinks about verification (Addy Osmani, Nov 2026). Die Dateiformate in references/templates.md sind die eigenen dieses Skills; der Artikel beschreibt die Praktiken, zeigt aber keine Formate.
Wann verwenden
- Du hast eine Änderung abgeschlossen und bist dabei, „fertig“ zu sagen oder zu committen
- Der Benutzer fragt: „does this work?“, „prove it“ oder „verify this“
- Ein Repository hat keine wiederholbare Methode, um die App zu starten und einem Smoke-Test zu unterziehen
- Der Benutzer fragt, welche Tests sich für ein Feature, einen Rewrite oder eine Migration lohnen
- Ein Review oder eine Testsuite hat einen Fehler übersehen, der zu den Benutzern gelangt ist, und der Benutzer möchte, dass er beim nächsten Mal gefangen wird
- Ein Test ist flaky und jemand möchte ihn wiederholen oder überspringen
- Der Benutzer möchte mehrere Agenten gleichzeitig laufen lassen und kann nicht jeden Diff lesen
Nicht verwenden für: das zeilenweise Reviewen eines fremden Diffs (das ist ein Review, keine Verifikation), eine einzeilige Änderung an Dokumentation oder Kommentaren, bei der nichts ausgeführt werden kann, oder das Hinzufügen von Tests, um nur eine Coverage-Zahl zu erhöhen.
Kernprinzip
Eine Änderung ist fertig, wenn Belege es sagen, und eine Änderung darf niemals ihren eigenen Richter bearbeiten. „Die Tests bestehen“ ist ein schwacher Beleg, wenn dieselbe Änderung die Tests geschrieben hat. Starker Beleg ist die laufende App, die das tut, was der Benutzer verlangt hat, geprüft durch etwas, das die Änderung nicht berühren konnte.
Regeln
- Führe die Änderung aus. Starte die echte App und übe das geänderte Verhalten aus. Das ist wichtiger als Unit-Tests. Eine bestandene Unit-Suite mit einer App, die nicht startet, ist eine fehlgeschlagene Verifikation.
- Drei Runden, dann ein Mensch. Führe die Prüfungen aus, behebe Fehler, führe sie erneut aus. Wenn nach drei Runden immer noch eine Prüfung fehlschlägt, stoppe und übergib mit den Belegen. Starte keine vierte Runde.
- Schwäche niemals einen Richter, um ihn zu bestehen. Kein Bearbeiten, Überspringen oder Löschen eines Tests, einer Lint-Regel, eines Checklisten-Elements oder einer REVIEW.md-Regel in derselben Änderung, die es richten soll. Wenn ein Richter falsch ist, sag es und ändere es in einem separaten Commit, den der Benutzer genehmigt.
- Lese Richter aus dem Basis-Branch. Review-Regeln, Checklisten und Gate-Konfiguration stammen aus dem Standard-Branch, niemals aus dem Branch unter Test.
- Belege gehören zu einem Commit. Eine Verifikation eines älteren Commits sagt nichts über einen neueren aus. Nach jeder neuen Bearbeitung verifiziere erneut oder melde, dass die Belege veraltet sind.
- Günstige Prüfungen zuerst und lokal. Tests, Build und Lint laufen vor der PR-Eröffnung, nicht in der Zeit des Reviewers.
- Führe nur die Checklisten-Elemente aus, die der Diff auslöst. Normalerweise treffen 3 bis 10 Elemente zu. Alle jedes Mal auszuführen, lehrt jeden, die Liste zu ignorieren.
- Stemple jeden Commit damit, wie er verifiziert wurde, inklusive
none. Ein ehrlichesnonekann später durchsucht werden. Ein fehlender Stempel kann es nicht. - Ein flaky Test ist ein Fehler. Überspringe ihn nicht, füge keinen
sleepoderretryhinzu. Finde die Ursache. Wenn du es nicht kannst, lösche den Test und schreibe auf, warum. - Eine Prüfung, die nach einem Menschen ruft, muss sagen, warum. „Needs review“ ist kein Grund. „Changes the session file format; old transcripts may not load“ ist einer.
- Jeder Fehlgriff wird zur Regel, und Regeln werden beschnitten. Ein Fehler, der durchgerutscht ist, ist eine Lücke in der Schicht. Schließe sie mit einer Prüfung und entferne Prüfungen, die ihren Platz nicht mehr verdienen.
Welchen Test schreiben
| Situation | Test | Was er beweist |
|---|---|---|
| Ein benutzerseitiger Ablauf (wenn du nur einen Test schreibst, schreib diesen) | End-to-End | Ein echter Benutzerpfad funktioniert von Anfang bis Ende. Ein Fehler zeigt den Schritt, einen Trace und einen Screenshot, nicht nur „timeout“. |
| Parser, Encoder, Geld, Zustandsautomaten, alles mit Randfällen | Property (fast-check, Hypothesis, proptest) | Eine Aussage gilt für tausende generierte Eingaben, an die du nicht gedacht hast. |
| Ein Rewrite, eine Migration oder Optimierung von etwas, das bereits funktioniert | Differential | Alt und Neu liefern identische Ausgaben bei identischen Eingaben. |
Prüfenswerte Eigenschaften:
| Eigenschaft | Aussage |
|---|---|
| Round trip | Kodieren, dann dekodieren, ergibt das Original |
| Invariante | Etwas hält immer (ein Saldo ist nie negativ) |
| Idempotenz | Zweimaliges Ausführen ist dasselbe wie einmaliges |
| Äquivalenz | Die schnelle Version entspricht einer langsamen, offensichtlich korrekten Version |
Für differentielle Tests: verwende zufällige oder gesampelte reale Eingaben, normalisiere Unterschiede, die nicht relevant sind (Leerzeichen, Reihenfolge von Schlüsseln, Zeitstempel), und führe eine geschriebene Liste der Unterschiede, die du genehmigt hast.
Eine langsame Suite wird seltener ausgeführt, also sinkt die Abdeckung. Halte die pro-Bearbeitungs-Schleife schnell und verschiebe schwere Tests knapp vor den Commit.
Was unberührt bleibt
- Vorhandene Tests, Lint-Regeln, Checklisten-Elemente, REVIEW.md und Gate-Konfiguration: niemals in dem Commit ändern, den sie richten.
- Befehlsausgabe, Exit-Codes, Namen und Anzahl fehlgeschlagener Schritte: genau so melden, wie sie ausgegeben werden.
- Der Stempel: er sagt, was du wirklich ausgeführt hast. Schreibe niemals
e2efür einen Lauf, den du nicht gemacht hast. - Screenshots und Traces: anhängen oder verlinken, wie sie sind, nicht aus dem Gedächtnis beschreiben.
Methode
A. Eine Änderung verifizieren (jedes Mal)
-
Sag, was „fertig“ bedeutet. Schreibe ein oder zwei Sätze aus der Sicht des Benutzers: was sie tun, was sie sehen. Wenn das Repository eine Feature-Map hat, finde den Eintrag und verwende sein erwartetes Ergebnis als Bewertungsgrundlage. Wenn du kein „fertig“ formulieren kannst, frage nach, bevor du verifizierst.
-
Führe die günstigen Prüfungen aus. Build, Lint, Typprüfung, die schnellen Tests. Behebe Fehler. Das ist Runde eins.
-
Führe die Änderung aus. Verwende das
verify-Skill des Repositorys, falls vorhanden (schaue in.claude/skills/in der Nähe des geänderten Codes). Wenn es keines gibt, starte die App selbst:- Web: einen Browser steuern (Chrome-Erweiterung, DevTools MCP, Playwright).
- Mobil: Simulator über ein mobile MCP.
- Desktop: Computer use.
- Backend oder CLI: den Dienst oder Befehl lokal ausführen und aufrufen.
Übe den geänderten Pfad und einen Pfad daneben, der sich nicht geändert haben sollte. Mache einen Screenshot, einen Trace oder nimm die Ausgabe auf.
-
Führe die ausgelösten Checklisten-Elemente aus. Lese die Zuverlässigkeits-Checkliste aus dem Basis-Branch. Teste für jedes Element seinen Auslöser gegen deinen Diff. Führe die Prüfung für jeden Treffer durch und halte das Ergebnis fest. Liste die getroffenen Elemente nach Namen in deinem Bericht auf.
-
Füge den fehlenden Test hinzu. Verwende die obige Tabelle. Bestätige, dass der neue Test ohne deine Änderung fehlschlägt und mit ihr bestanden wird.
-
Zähle die Runden. Jeder „Prüfungen ausführen, beheben, erneut ausführen“-Durchlauf ist eine Runde. Nach der dritten Runde mit einer noch fehlschlagenden Prüfung, stoppe. Melde, was fehlschlägt, was du in jeder Runde versucht hast und deine beste Schätzung der Ursache.
-
Stemple und berichte. Füge den Stempel der Commit-Nachricht hinzu (Format in
references/templates.md). Gib in deinem Bericht an: die Definition von „fertig“, was du ausgeführt hast, die Belege, die getroffenen Checklisten-Elemente und alles, was nicht verifiziert wurde, mit Begründung.
B. Die Schicht aufbauen (einmal pro Repository, dann optimieren)
Führe diese in der Reihenfolge aus. Jedes ist für sich nützlich, also höre auf, wo der Benutzer möchte.
-
Ein
verify-Skill. Lege es in.claude/skills/verify/ab, so nah wie möglich am Code, den es abdeckt (ein Monorepository kann eines pro App haben). Es hält fest, wie die App gestartet und einem Smoke-Test unterzogen wird. Führe es mehrmals hintereinander aus, bevor du ihm vertraust: es muss schnell sein und jedes Mal dieselben Ergebnisse liefern. -
Eine Feature-Map. Liste Funktionen aus Sicht des Benutzers auf. Für jede: den Pfad, Tastenkürzel, Selektoren und das erwartete Ergebnis. Agenten verwenden sie als Leitfaden und als Bewertungsgrundlage.
-
Ein End-to-End-Test für den wichtigsten Ablauf. Danach Property- und Differential-Tests, wo die Tabelle sagt, dass sie passen.
-
Eine Zuverlässigkeits-Checkliste. Jeder Eintrag hat drei Teile: einen Auslöser, den du aus einem Diff lesen kannst, eine Prüfung und den Vorfall oder PR, der ihn verursacht hat. Kein Vorfall, kein Eintrag. Beispiel: Auslöser „session storage or message types change“, Prüfung „does a new field load safely from an old transcript that doesn't have it?“.
-
Eine REVIEW.md. Sie sagt dem Reviewer, worauf er in dieser Codebasis achten soll. Stimme sie über mehrere Runden mit einem Reviewer ab, wobei jede Runde auf dem aufbaut, was die letzte gefunden hat. Füge keine weiteren Reviewer hinzu. Der Code-Owner verfeinert sie, bis sie das markiert, was er markieren würde.
-
Lokale Durchsetzung. Ein Hook, der die Tests ausführt, wenn der Agent fertig ist, oder ein Ziel, das eine bestandene Suite erfordert.
-
Ein Commit-Gate. Es blockiert einen Commit, wenn die Sitzung keinen Review- und keinen Verify-Schritt ausgeführt hat. Rolle es in drei Modi aus:
Modus Verhalten offNichts observeProtokolliert, was es blockiert hätte. Führe dies zuerst aus, um falsch Positive zu finden. enforceBlockiert den Commit. Ein Commit darf einen schriftlichen Grund für das Überspringen enthalten. Nach zwei Blockaden in einer Sitzung wird der nächste Commit durchgelassen, damit der Agent nicht steckenbleibt.
Frage den Benutzer, bevor du Hooks, Gates oder CI-Änderungen hinzufügst. Sie ändern, wie jeder committet.
C. Einen Fehlgriff in eine Regel umwandeln
Verwende dies, wenn ein Fehler an den Tests oder dem Review vorbeigekommen ist.
- Finde das Muster, nicht den Fehler. Schaue dir menschliche Review-Kommentare und Reverts an. Ein Kandidat für eine Regel muss in mindestens zwei PRs auftauchen und allein aus einem Diff ersichtlich sein.
- Versuche, es zu widerlegen. Führe drei unabhängige Versuche durch, um zu zeigen, dass die Regel falsch, zu breit oder bereits abgedeckt ist. Wenn Subagenten verfügbar sind, verwende drei. Behalte die Regel nur, wenn sie überlebt.
- Prüfe, ob sie auffangbar war. Spiele den PR, der den Vorfall verursacht hat, durch drei unabhängige Fehlersuchwerkzeuge. Wenn zwei oder mehr den Fehler finden, war er erkennbar, und ein Fehlgriff bei einem kleinen Diff sollte zu einer REVIEW.md-Regel oder einem Checklisten-Element werden.
- Lass sie von einem Menschen genehmigen. Der Code-Owner entscheidet, ob die Regel aufgenommen wird. Du schlägst vor; er genehmigt.
- Bewerte den Reviewer. Behalte einen kleinen Satz von Vorfallsfällen bei, jeder mit einem Ein-Satz-Antwortschlüssel, plus gemergte, saubere Änderungen ähnlicher Größe als Kontrollen gegen Übermarkierung. Behalte einen Optimierungssatz und einen separaten Testsatz. Markiere Funde als
Important,NitoderPre-existing. Höre mit der Optimierung auf, wenn mehr Recall nur noch zum Eval passt. - Beschneiden. Test-Suites, Checklisten und
.md-Regeldateien wachsen nur, wenn jemand sie kürzt. Entferne bei einer Routine Regeln, die nie feuern, eine andere Regel duplizieren oder Code schützen, der nicht mehr existiert.
Ausgearbeitetes Beispiel
Anfrage: „Füge ein pinned-Flag zu Chat-Sitzungen hinzu, so dass angeheftete zuerst sortiert werden.“
Ohne das Skill:
pinnedzum Sitzungstyp hinzugefügt und die Sortierung aktualisiert. Unit-Tests bestehen. Fertig.
Mit dem Skill:
Fertig bedeutet: ein Benutzer heftet eine Sitzung in der Seitenleiste an und sie bewegt sich nach oben; nach einem Neustart ist sie immer noch oben.
Ausgeführt: Build, Lint, 148 Unit-Tests (Runde 1: 2 Fehler beim Sortierungs-Komparator, behoben; Runde 2: alle bestanden). App mit dem
verify-Skill des Repositorys gestartet, Sitzung angeheftet, neu gestartet, Reihenfolge bestätigt. Screenshot angehängt.Getroffene Checklisten-Elemente (2 von 31):
- Session format changes load old data: eine vor dieser Änderung gespeicherte Sitzungsdatei geöffnet. Sie stürzte ab:
pinnedwarundefinedund der Komparator warf einen Fehler. Behoben durch Standard auffalsebeim Laden. Runde 3: bestanden.- Sort changes keep a stable order: nicht angeheftete Sitzungen behalten ihre vorherige Reihenfolge. Bestanden.
Hinzugefügt: ein Property-Test, „Sortieren zweimal ist gleich Sortieren einmal“, und ein End-to-End-Schritt für Anheften, Neustart, Reihenfolge prüfen. Beide schlagen ohne die Korrektur fehl.
Nicht verifiziert: das mobile Layout. Kein Simulator auf diesem Rechner.
Stempel:
Verified-By: run, e2e, property, checklist(2)
Die Unit-Tests bestanden, während die App auf allen vorhandenen Benutzerdaten abstürzte. Die Änderung gegen eine alte Datei auszuführen, hat es gefunden, und das Checklisten-Element hat gesagt, dass man es versuchen soll.
Selbstprüfung vor der Auslieferung
- Dein Bericht hat eine „fertig bedeutet“-Zeile, die aus Sicht des Benutzers geschrieben ist.
- Die App wurde gestartet und der geänderte Pfad ausgeführt, oder der Bericht sagt „nicht ausgeführt“ mit Begründung.
git diff <base>zeigt keine Bearbeitung an einem bestehenden Test, Lint-Konfiguration, Checkliste, REVIEW.md oder Gate-Konfiguration. Wenn doch, wird diese Bearbeitung genannt und befindet sich in einem eigenen Commit.- Es wurde kein
.skip,.only,xit,sleep,retryoder erhöhtes Timeout hinzugefügt, um einen Test bestehen zu lassen (durchsuche den Diff nach jedem). - Die von dir getroffenen Checklisten-Elemente sind mit Namen und einem Ergebnis für jedes aufgelistet.
- Es wurde beobachtet, dass jeder neue Test ohne die Änderung fehlschlägt.
- Die Rundenzahl ist drei oder weniger. Wenn die dritte Runde immer noch fehlschlug, übergibt der Bericht an einen Menschen und du hast nicht committet.
- Die Commit-Nachricht hat einen
Verified-By:-Stempel, und jedes Wort darin stimmt mit etwas überein, das du tatsächlich ausgeführt hast. - Die Belege wurden auf dem aktuellen
HEADgesammelt, nicht auf einem früheren Commit. - Jedes neue Checklisten-Element oder jede neue Regel benennt den Vorfall oder PR dahinter.