code / werkzeug

Code Guard

Ein Script, das nach jeder Code-Änderung entscheidet, ob eine Aufgabe fertig ist. Nicht das Modell entscheidet das, sondern der Exit-Code.

KI-Agenten schreiben schnell Code, und sie melden genauso schnell „alles grün“, auch wenn es nicht stimmt. Deshalb nehme ich ihnen dieses Urteil ab. Nach jeder Änderung, egal ob sie von mir oder von einem Modell stammt, läuft der Code Guard. Erst wenn er durchläuft, gilt die Aufgabe bei mir als erledigt.

Was er macht

1. Er erkennt selbst, welche Prüfungen ein Projekt hat, und fährt die verfügbaren Standardprüfungen in fester Reihenfolge: PHPStan, phpcs, Tests, composer audit und mehr. Teure Prüfungen laufen nur mit --full.
2. Dazu kommen eigene Prüfskripte. Jedes ist aus einem Fehler entstanden, den ich irgendwann gemacht oder gefunden habe: Secrets im Repo, riskante Migrationen, Schriften von fremden Servern, veraltete Rechtstexte.
3. Was einem Projekt fehlt, meldet er als MISSING, statt zu raten.
4. Das Ergebnis landet maschinenlesbar in docs/.guard/results.json, damit ein Agent seine eigenen Fehler abarbeiten kann.
5. Er ändert keinen Projektcode. Er prüft nur.

So sieht ein Befund aus

Die Ausgabe hier ist ein vereinfachtes Beispiel aus der Startseite. Drei Prüfungen bestehen, eine findet Geheimnisse im Repo. Deshalb steht am Ende FAIL mit Exit-Code 1. Erst nach dem Beheben des Befunds und einem neuen Lauf kann der Exit-Code 0 sein. Ein Agent kann das Ergebnis zusätzlich in docs/.guard/results.json lesen; zu jeder Prüfung gibt es ein eigenes Log.

$ code-guard
PASS  Statische Analyse
PASS  Tests
FAIL  Geheimnisse im Repo
PASS  Rechtstexte
VERDIKT: FAIL · exit 1

Installation und Aufruf

Das GitHub-Repository enthält das Installationsskript. Nach dem Klonen kannst du mit --dry-run zuerst sehen, welche Verknüpfungen es anlegen würde. ./install.sh verlinkt den Code Guard anschließend in dein Benutzerkonto. Bereits vorhandene Dateien werden laut Installationsskript in ~/.claude-config-backups/ gesichert. Das Werkzeug erwartet in meinen Projekten ein Makefile und einen Docker-Compose-Service namens php.

git clone https://github.com/dasdomaindepot/ddd-code-guard.git
cd ddd-code-guard
./install.sh --dry-run
./install.sh

Im Projektverzeichnis startet der erste Befehl die verfügbaren Standardprüfungen. Mit --list siehst du vorab, welche Prüfungen erkannt wurden und welche als MISSING gelten. --install-make ergänzt ein make guard-Target im Makefile des Projekts. Für die zusätzlichen, zeitaufwendigen Prüfungen wie Coverage und Mutation Testing gibt es --full.

~/.claude/skills/code-quality/bin/code-guard
~/.claude/skills/code-quality/bin/code-guard --list
~/.claude/skills/code-quality/bin/code-guard --install-make
~/.claude/skills/code-quality/bin/code-guard --full

Welche Prüfungen sind dabei?

Das Inventar hängt vom Projekt ab. Für PHP-Projekte erkennt das Script unter anderem Composer-Validierung und Sicherheitsaudit, PHPStan, phpcs und Tests. Falls entsprechende Targets vorhanden sind, kommen Deptrac, Linter, Coverage, Infection und End-to-End-Tests hinzu. Bei Frontend-Projekten erkennt es npm-Skripte für Linting, Typprüfung, Tests und Build. Eine nicht vorhandene Prüfung wird im Inventar als MISSING angezeigt.

Die eigenen Checks suchen beispielsweise nach Geheimnissen in versionierten Dateien, riskanten neuen Migrationen, abgeschwächten Qualitätsregeln und statisch erkennbaren Fehlern in Anwendung und Konfiguration. Ist eine lokale Web-Instanz erreichbar, prüfen weitere Checks unter anderem Sicherheits-Header, unbeabsichtigte Datei-Freigaben, Seiteninhalt, externe Ressourcen und deutsche Rechtstexte. Diese Web-Prüfungen brauchen eine passende lokale URL; ohne sie erscheinen sie im Inventar als MISSING.

Der Exit-Code ist das Urteil

0 alles erfüllt, weiter · 1 Befunde, beheben und neu fahren · 3 unerwartete Nebenwirkung, sofort anhalten

Häufige Fragen

Was bedeutet MISSING?

Der Code Guard hat die Voraussetzungen für diese Prüfung im Projekt nicht gefunden. --list zeigt das Inventar und den jeweiligen Grund. Er erfindet keinen Ersatz für ein fehlendes Make-Target oder eine lokale Webseite.

Wann brauche ich --full?

Der normale Aufruf führt die verfügbaren Standardprüfungen aus. --full nimmt zusätzlich teure Checks wie Coverage, Infection, End-to-End-Tests und den Asset-Build dazu. Das dauert entsprechend länger.

Was mache ich bei Exit-Code 1?

Lies den gemeldeten Befund und das zugehörige Log, behebe die Ursache und starte den Code Guard erneut. Die Zusammenfassung liegt maschinenlesbar in docs/.guard/results.json; die einzelnen Logs stehen unter docs/.guard/logs/.

Was bedeutet Exit-Code 3?

Der Guard hat eine unerwartete Nebenwirkung im Worktree entdeckt. Halte an und prüfe die Änderung, bevor du weitere Schritte ausführst. Dieser Code ist kein gewöhnlicher Prüfungsbefund wie Exit-Code 1.

Zusätzlich gibt es einen Review-Agenten für Claude Code und opencode. Er fährt dasselbe Script und liest danach den Diff auf das, was kein Werkzeug findet: Erfüllt die Änderung die Anforderung? Erfindet sie Services oder Umgebungsvariablen? Ist die Berechtigung auf Objektebene geprüft?

Der Code Guard ist auf meine Projekte zugeschnitten: Symfony, Docker, Makefile, deutsche Rechtslage. Nimm ihn als Anregung, wie du deine eigenen Fehler in Prüfungen verwandelst. Wie das im Alltag aussieht, steht im Beitrag Ein guter Entwickler ist ein fauler Entwickler. Auch mit KI.

MIT-Lizenz · Bash und Python · für PHP/Symfony- und Vue-Projekte