Git Pre-Commit-Hook verhindert, dass KI-Coding-Agents veraltete Dokumentation committen.

Problem: KI-Codierungsagenten committen Code mit veralteter Dokumentation

Bei der Arbeit mit KI-Codierungsassistenten wie Claude Code über mehrere Sitzungen hinweg stoßen Entwickler auf ein spezifisches Problem: Die KI nimmt Codeänderungen vor (fügt Routen hinzu, refaktorisiert Komponenten, benennt Dinge um), aktualisiert aber keine Dokumentationsdateien wie ARCHITECTURE.md und README. Dies führt dazu, dass nachfolgende Sitzungen damit beginnen, dass die KI Dokumentation liest, die Code von vor Wochen beschreibt.

Die Konsequenzen umfassen:

• Claude halluziniert Funktionsnamen, die nicht mehr existieren
• Verweist auf API-Endpunkte, die umbenannt wurden
• Schlägt Muster vor, die der aktuellen Architektur widersprechen

Warnhinweise funktionieren nicht, weil niemand die stderr-Ausgabe sieht, wenn Claude committet.

Lösung: Ein blockierender Pre-Commit-Hook

Der Entwickler hat einen Git Pre-Commit-Hook mit diesem Workflow erstellt:

• Der Hook weiß, welche Dateiänderungen Dokumentationsaktualisierungen auslösen sollten (konfigurierbare Muster pro Projekt)
• Wenn Claude Code committet, erkennt der Hook dies über Umgebungsvariablen
• Der Hook verzichtet darauf, die Dokumentation automatisch zu reparieren (was zu einer Deadlock-Situation führen würde, weil Claude von innerhalb von Claude gestartet würde)
• Stattdessen beendet er mit Code 1 und zeigt eine klare Nachricht an: "Dokumentation ist veraltet, aktualisiere diese Dateien und versuche es erneut"
• Claude liest den Fehler, aktualisiert die Dokumentation, wiederholt den Commit und der Commit wird durchgeführt

Für menschliche Commits ruft der Hook die Anthropic-API direkt auf und patcht die relevanten Abschnitte (dauert etwa 20 Sekunden).

Jeder Commit generiert eine session-context.md-Datei mit einer Zusammenfassung der letzten Aktivitäten, sodass die nächste Sitzung Kontinuität hat.

Implementierungsdetails

Das Tool ist als npm-Paket verfügbar: @mossrussell/agent-guard

Wichtige Eigenschaften:

• Funktioniert mit Claude Code, Cursor, Windsurf und Copilot
• Keine Abhängigkeiten
• Verfügbar unter: https://www.npmjs.com/package/@mossrussell/agent-guard