Wir bauen ein SaaS-Dashboard mit ~80 Seiten, und Claude Code ist unser primärer Coding-Agent.

Jede neue Seite war technisch "inspiriert" von einer bestehenden. Claude hat vorher bestehende Dateien gelesen. Wir hatten Component-Libraries, Shared Utilities, eine klare Ordnerstruktur.

Und trotzdem: Nach einer langen Session sah jedes Diff so aus:

• text-[13px] statt text-xs
• #f97316 direkt in JSX statt var(--color-brand)
• Watermark-Komponente inline neu gebaut statt den Shared Helper zu nutzen

Keine Bugs. Keine funktionalen Fehler. Nur stille Inkonsistenz, die sich über Hunderte von Dateien aufgebaut hat.

Die naheliegende Lösung — und warum sie scheitert

Wir haben das getan, was jedes vernünftige Team tut: Wir haben es aufgeschrieben.

STANDARDS.md. 500 Zeilen. Organisiert nach Abschnitten. Regeln mit Begründung. Beispiele für richtige und falsche Patterns. Cross-References. Eine Typografie-Skala. Eine Farb-Token-Referenz. Klare Komponentenzuständigkeiten.

Zu Beginn jeder Session die Anweisung: „Lies STANDARDS.md, bevor du eine Komponente bearbeitest."

Claude hat es gelesen. Hat die Regeln befolgt — am Anfang einer Session, wenn der Kontext frisch war.

Dann füllte sich die Session mit Code, Diffs, Fehlermeldungen, Hin und Her. Und nach und nach drifteten die Standards wieder heraus.

STANDARDS.md wurde zu dem, was wir jetzt Dokumentations-Theater nennen — der Anschein von Disziplin ohne die Substanz.

Warum Dokumentation allein für AI-Agenten scheitert

Das Problem ist nicht Claudes Aufmerksamkeitsspanne, und es ist kein Prompt-Engineering-Fehler.

Das Problem ist strukturell.

Eine Regel, die in einer .md-Datei lebt, setzt voraus, dass drei Dinge gleichzeitig funktionieren:

1. Claude liest den relevanten Abschnitt im richtigen Moment
2. Claude wendet die Regel korrekt an — unter Token-Druck, wenn der Session-Kontext dicht ist
3. Kein Context-Drift tritt auf — über eine lange Multi-File-Session hinweg

Drei probabilistische Fehlermodi übereinandergestapelt. Natürlich bricht das.

Menschliche Entwickler verinnerlichen Regeln über Zeit. Ein Senior-Dev, der seit Monaten in einer Codebase arbeitet, muss den Style Guide nicht vor jeder Dateiänderung neu lesen. Die Regeln sind Instinkt.

AI Coding Agents starten jede Session bei null. Jede Session ist Tag eins. Dokumentation muss jedes Mal neu gelesen, neu angewendet, neu priorisiert werden — von Anfang an.

Die echte Lösung: Verstöße unmöglich machen

Wir haben aufgehört, Claude an die Regeln zu erinnern.

Wir haben ein Programm geschrieben, das sie mechanisch durchsetzt.

Schicht 1 — Pre-Edit-Hook

Ein Script, das in den Claude Code Settings registriert ist und vor jedem Speichern einer Datei ausgeführt wird. Es prüft den geplanten Dateiinhalt auf verbotene Patterns:

• text-[Npx] in einer Komponente → „Nutze die 6-Stufen-Skala: text-xs, text-sm, …"
• watermarkBottom={…} als Prop → „Nutze ChartWatermark.tsx. Direktes Prop ist deprecated."
• Hardcodierte Hex-Werte in JSX → „Referenziere CSS-Variablen aus globals.css."

Wenn ein Verstoß erkannt wird: Der Edit wird blockiert. Claude bekommt eine spezifische Fehlermeldung, die das genaue Pattern benennt und die richtige Alternative zeigt.

Keine allgemeine Erinnerung. Kein „Denk an die Regeln." Ein präziser, unmittelbarer Fehler — direkt am Verstoß.

Schicht 2 — Commit Gate

Vor jedem git push läuft npm run verify:standards — 22 automatisierte Checks über die gesamte Codebase:

• Typografie: kein text-[Npx] nirgendwo
• Farb-Tokens: keine hardcodierten Hex-Werte in Component-Dateien
• Watermark: jeder Chart nutzt ChartWatermark.tsx, keine Inline-Neuerstellung
• Component Imports: Shared Utilities vom richtigen Pfad, nicht dupliziert
• Strategy-Coverage: jede neue Strategie in allen Touchpoints registriert

Rot bei einem Check = kein Push. Das ist kein Lint-Hinweis. Das ist ein hartes Gate.

Was sich verändert hat

Vorher: Claude schreibt text-[13px] in einer neuen Komponente. Es taucht vielleicht im Code Review auf — wenn jemand es bemerkt. Oft nicht. Inkonsistenz akkumuliert still.

Nachher: Claude schreibt text-[13px]. Der Pre-Edit-Hook feuert in derselben Runde. Claude liest die Fehlermeldung, versteht den genauen Fix, korrigiert sich selbst — bevor die Datei jemals gespeichert wird.

Die Korrektur passiert im Moment des Verstoßes, mit vollständigem Kontext darüber, was falsch war. Schneller als Code Review, günstiger als ein zweiter Durchgang, konsistent über jede Session — unabhängig von der Kontextlänge.

Das übergeordnete Prinzip

Dokumentation sagt: Mach X nicht.
Code sagt: Du kannst X nicht machen.

Für AI-Agenten ist dieser Unterschied wichtiger als für Menschen — weil Agenten zwischen Sessions keine Intuition aufbauen. Jeder Durchsetzungsmechanismus, der auf Gedächtnis oder Absicht beruht, degradiert über Zeit. Jeder Durchsetzungsmechanismus, der auf Code beruht, tut das nicht.

Das gilt nicht nur für Claude Code. Es gilt für Cursor, Copilot Workspace, jeden agentischen Coding-Workflow, bei dem ein AI-Agent Dateiänderungen in einer geteilten Codebase vornimmt. Das Prinzip ist dasselbe: Wenn du willst, dass eine Einschränkung hält, mach sie mechanisch.

Schreib einen Linter. Schreib einen Pre-Edit-Hook. Schreib ein Commit Gate.

Mach Verstöße unmöglich — nicht nur unerwünscht.

---

Standards, die durch Dokumentation durchgesetzt werden = Theater.
Standards, die durch Code durchgesetzt werden = Realität.