CommunityCodierung & Entwicklunggithub.com

Verification Layer

Beweise, dass eine von einem Agenten geschriebene Änderung funktioniert, bevor sie committet wird, und baue die Prüfungen, die diesen Beweis günstig machen.

Was ist Verification Layer?

Das „Verification Layer“-Skill ist ein strukturiertes Framework, das KI-Agenten (z. B. Claude Code, Cursor, Codex) befähigt, vor dem Commit nachzuweisen, dass eine Codeänderung funktioniert – und die Prüfungen selbstständig aufzubauen, die diesen Nachweis in Zukunft billiger machen. Entwickelt für Teams mit hohem Automatisierungsgrad, verlagert es die menschliche Arbeit vom zeilenweisen Review hin zur Definition von „fertig“ und zur Prüfung der vorgelegten Beweise. Das Skill folgt einem zentralen Prinzip: Eine Änderung darf niemals ihren eigenen Richter bearbeiten. Es verlangt, die reale Anwendung zu starten, die richtige Testart (End-to-End, Property-basiert oder differentiell) auszuwählen und nur die durch den Diff ausgelösten Zuverlässigkeits-Checklistenelemente auszuführen. Nach drei fehlgeschlagenen Korrekturrunden übergibt es an einen Menschen und markiert jeden Commit mit einem Verifikationsstempel. Jeder Fehler, der durchrutscht, wird in eine neue Regel umgewandelt. Das Skill kann auch die gesamte Verifikationsschicht in einem Repository einrichten: ein eigenes `verify`-Skill, eine Feature-Map, eine diff-getriggerte Zuverlässigkeits-Checkliste, eine REVIEW.md und ein Commit-Gate. Es ist ideal für Szenarien wie „beweise, dass es funktioniert“, „mach ein verify-Skill“, „welche Tests sind sinnvoll?“ oder „dieser Test ist flaky“. Der menschliche Aufsicht bleibt eingebunden, indem Code-Owner finale Regeln genehmigen und der Prozess nach drei erfolglosen Versuchen nicht weiter automatisieren lässt. Das Skill wird aktiviert, wenn der Benutzer sagt: „Verify this change“, „Prove it works“, „How do I know this works“, „Is this actually done“, „Set up verification“, „Add a verify skill“, „Write a REVIEW.md“, „Build a reliability checklist“, „Add a commit gate“, „Which tests should I write“, „This test is flaky“, „The review missed this bug“, „Turn this miss into a rule“ oder „I want to run more agents without reading every diff“.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/kleenpulse/verification-layer/tree/main

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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

  1. 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.
  2. 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.
  3. 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.
  4. Lese Richter aus dem Basis-Branch. Review-Regeln, Checklisten und Gate-Konfiguration stammen aus dem Standard-Branch, niemals aus dem Branch unter Test.
  5. 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.
  6. Günstige Prüfungen zuerst und lokal. Tests, Build und Lint laufen vor der PR-Eröffnung, nicht in der Zeit des Reviewers.
  7. 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.
  8. Stemple jeden Commit damit, wie er verifiziert wurde, inklusive none. Ein ehrliches none kann später durchsucht werden. Ein fehlender Stempel kann es nicht.
  9. Ein flaky Test ist ein Fehler. Überspringe ihn nicht, füge keinen sleep oder retry hinzu. Finde die Ursache. Wenn du es nicht kannst, lösche den Test und schreibe auf, warum.
  10. 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.
  11. 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

SituationTestWas er beweist
Ein benutzerseitiger Ablauf (wenn du nur einen Test schreibst, schreib diesen)End-to-EndEin 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ällenProperty (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 funktioniertDifferentialAlt und Neu liefern identische Ausgaben bei identischen Eingaben.

Prüfenswerte Eigenschaften:

EigenschaftAussage
Round tripKodieren, dann dekodieren, ergibt das Original
InvarianteEtwas hält immer (ein Saldo ist nie negativ)
IdempotenzZweimaliges Ausführen ist dasselbe wie einmaliges
ÄquivalenzDie 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 e2e fü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)

  1. 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.

  2. Führe die günstigen Prüfungen aus. Build, Lint, Typprüfung, die schnellen Tests. Behebe Fehler. Das ist Runde eins.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

  1. 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.

  2. 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.

  3. Ein End-to-End-Test für den wichtigsten Ablauf. Danach Property- und Differential-Tests, wo die Tabelle sagt, dass sie passen.

  4. 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?“.

  5. 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.

  6. Lokale Durchsetzung. Ein Hook, der die Tests ausführt, wenn der Agent fertig ist, oder ein Ziel, das eine bestandene Suite erfordert.

  7. 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:

    ModusVerhalten
    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.

  1. 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.
  2. 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.
  3. 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.
  4. Lass sie von einem Menschen genehmigen. Der Code-Owner entscheidet, ob die Regel aufgenommen wird. Du schlägst vor; er genehmigt.
  5. 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, Nit oder Pre-existing. Höre mit der Optimierung auf, wenn mehr Recall nur noch zum Eval passt.
  6. 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:

pinned zum 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: pinned war undefined und der Komparator warf einen Fehler. Behoben durch Standard auf false beim 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

  1. Dein Bericht hat eine „fertig bedeutet“-Zeile, die aus Sicht des Benutzers geschrieben ist.
  2. Die App wurde gestartet und der geänderte Pfad ausgeführt, oder der Bericht sagt „nicht ausgeführt“ mit Begründung.
  3. 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.
  4. Es wurde kein .skip, .only, xit, sleep, retry oder erhöhtes Timeout hinzugefügt, um einen Test bestehen zu lassen (durchsuche den Diff nach jedem).
  5. Die von dir getroffenen Checklisten-Elemente sind mit Namen und einem Ergebnis für jedes aufgelistet.
  6. Es wurde beobachtet, dass jeder neue Test ohne die Änderung fehlschlägt.
  7. Die Rundenzahl ist drei oder weniger. Wenn die dritte Runde immer noch fehlschlug, übergibt der Bericht an einen Menschen und du hast nicht committet.
  8. Die Commit-Nachricht hat einen Verified-By:-Stempel, und jedes Wort darin stimmt mit etwas überein, das du tatsächlich ausgeführt hast.
  9. Die Belege wurden auf dem aktuellen HEAD gesammelt, nicht auf einem früheren Commit.
  10. Jedes neue Checklisten-Element oder jede neue Regel benennt den Vorfall oder PR dahinter.

Verwandte Skills