kmLoureiro/agent-verify

Was macht agent-verify?

Baue das, was du erstellst, mit dem günstigsten Mechanismus verifizierbar, der es widerlegen kann. Standardmäßig über die CLI verifizieren. Das Modell soll ~20 Tokens lesen (PASS / FAIL: Zeile), niemals einen DOM-Dump oder einen Screenshot.

Die eine Regel

Verwende den leichtesten Mechanismus, der eine Funktion als falsch nachweisen kann. Eskaliere nur, wenn er es nicht kann.

in-process assert  →  CLI / curl + Exit-Code  →  DB-Test (TAP)  →  Headless-Browser (nur visuell, zuletzt)
   günstigster                                                            teuerster

90 % dessen, was Agenten bauen (Logik, Daten, API-Verträge, Abläufe), ist ohne Browser verifizierbar. Hebe dir den Browser für Pixel auf.

Schleife (pro Funktion)

1. Einmal erkennen. Führe scripts/detect-stack.sh aus. Es gibt den Test-Runner und den Stack in wenigen Zeilen aus. Zwinge kein neues Framework auf – verwende das Vorhandene.
2. Baue die Funktion.
3. Schreibe EINEN token-minimalen Check mit dem in-process / CLI-Primitiv des Stacks (siehe reference/stacks/). Der Check muss PASS oder eine einzelne FAIL:-Zeile ausgeben – niemals Dumps.
4. Füge eine Zeile an VERIFICATION_MAP.md an: funktion | befehl | pass-signal. Das ist der Vertrag, den der Agent beim nächsten Mal liest.
5. Führe scripts/verify.sh [feature] aus und lese nur das Ergebnis. Bearbeiten → verifizieren → wiederholen auf dem Ergebnis, nicht auf Logs.

Was NICHT zu tun ist

• Greife nicht zu Playwright/dem Browser, um Logik, Daten oder API-Antworten zu prüfen. Das ist das Token-Leck, das dieser Skill zu stoppen versucht.
• Schreibe kein TDD-Ritual vor. Gib an, welcher Check diese Funktion nachweist, nicht eine Prozedur. (Prozedur ohne zielgerichteten Kontext schadet nachweislich – siehe reference/patterns.md.)
• Gib keine Rohausgabe in den Kontext zurück. Filtere in der Sandbox, gib das Ergebnis aus. (console.log(result), nicht die 10k Zeilen.)
• Lass Checks nicht wachsen. Eine Funktion, ein schneller deterministischer Check. Halte VERIFICATION_MAP.md kurz – kurze Maps übertreffen lange.

Ausgabe-Vertrag (immer)

PASS auth-login
FAIL create-invoice: erwartet 201, erhalten 500

Exit 0 = alle bestanden. Ungleich Null = etwas ist fehlgeschlagen. Das ist alles, was das Modell braucht.

Wenn der Browser UNVERMEIDBAR ist

Nur für wirklich visuelle UI (Layout, Styling, visuelle Regression) und nur ganz am Ende. Selbst dann: ein Headless-Durchlauf, gib ein PASS/FAIL oder ein Diff-Urteil zurück – niemals einen vollständigen Screenshot oder DOM in den Kontext. Siehe reference/stacks/nextjs.md.

Dateien

• scripts/detect-stack.sh – gibt Stack + Runner aus, token-minimal.
• scripts/verify.sh – führt die gemappten Checks aus, gibt nur PASS/FAIL + die fehlschlagende Zeile aus.
• VERIFICATION_MAP.md – die kurze Funktions→Befehl-Zuordnung (der Agent pflegt sie).
• reference/stacks/ – Copy-Paste-Rezepte: FastAPI (In-Process TestClient), Supabase (Seed + Reset + pgTAP), Next.js (Route Handler + letzter Ausweg visuell).
• reference/patterns.md – Token-minimale Verifikationsmuster + die Belege dahinter.
• reference/anti-patterns.md – Flaky Tests, falsches PASS, Overengineering-Absicherungen.
• templates/ – Startpunkte für die Map, einen FastAPI-Test, einen Supabase-Seed.