Schreibe CLAUDE.md wie eine Verfassung: Verbote, Verhaltensregeln, Standardentscheidungen. 92 Commits in 5 Tagen, ohne Abweichungen.
In 5 Tagen habe ich 92 Commits gepusht und ein Produkt in Produktion gebracht (github.com/defi-io/smarts). Keine Aussetzer, keine Rollbacks, keine grossen Refactorings. Der Grund: nicht dass Claude genial ist. Der Grund sind die 565 Zeilen CLAUDE.md im Projekt-Root.
In diesem Beitrag geht es darum, wie man eine CLAUDE.md schreibt, die wie eine Verfassung wirkt — und was danach passiert.
Viele schreiben CLAUDE.md wie ein README — was das Projekt ist, wie man es startet. Das ist verschenkt.
Ein README ist für Menschen. CLAUDE.md ist für Claude. Claude lädt es zu Beginn jeder Session automatisch. Jede Zeile darin wird zur Vorbedingung jeder späteren Entscheidung.
Im README-Stil bekommst du: Claude weiss grob, was das Projekt ist, weiss, wie man Tests laufen lässt, fällt aber jede technische Entscheidung von Null an.
Im Verfassungs-Stil bekommst du: Claude weiss, welche Wege gesperrt sind, welche Konventionen verbindlich sind, an welcher Abzweigung der Default in welche Richtung liegt und wann es stoppen und nachfragen muss.
Der Unterschied: Der erste zieht „nebenbei" eine neue Abhängigkeit rein, fügt eine Abstraktionsschicht ein, fummelt am Gemfile. Der zweite nicht.
Mein aktuelles Projekt heisst smarts.md — eine Plattform, die Live-Docs und MCP-Server für Smart Contracts erzeugt. Ihre CLAUDE.md ist 565 Zeilen lang, in diesen Abschnitten:
1. Projekt-Identität (5 Zeilen)
2. Produktkern (Ein-Satz-Definition + strukturelle Unterschiede zur Konkurrenz)
3. Tech-Stack (harte Constraints, YAML)
4. Verbots-Liste (explizite ❌-Einträge)
5. Scope (harte MVP-Grenzen)
6. Architektur (mit ASCII-Diagramm)
7. Verzeichnisstruktur (Verantwortung pro Datei)
8. Ruby-Konventionen (mit Do/Don't-Snippets)
9. Caching-Strategie (als Tabelle)
10. Test-Anforderungen
11. Deployment-Details
12. Git-Workflow
13. Claude-Code-Nutzungsregeln (Verhaltensanweisungen)
14. 90-Tage-Meilensteine
15. Kernprinzipien
Kein Abschnitt ist Deko. Im Folgenden picke ich ein paar heraus und erkläre, warum sie so geschrieben sind.
Meine sieht so aus:
❌ Keine TypeScript- / Node.js-Services
❌ Kein ethers.js / web3.js
❌ Kein Sidekiq (Solid Queue verwenden)
❌ Kein React / Vue / Svelte (Hotwire verwenden)
❌ Kein Redis (Solid Cache / Solid Queue / Solid Cable decken alles ab)
❌ Keine unverifizierten Verträge (nur Etherscan-verifiziert)
❌ Kein Solana / Bitcoin / Move (nur EVM)
Das ist ein Web3-Projekt. Web3-Standard ist TypeScript + ethers.js + Redis + React. Ich gehe dagegen. Ich habe meine Gründe, aber Claude kennt sie nicht. Ohne Verbots-Liste empfiehlt Claude auf Basis des „Branchenkonsenses", der in seinen Trainingsdaten steckt — und das ist mit hoher Wahrscheinlichkeit der TypeScript-Pfad.
Mit der Liste hört Claude auf zu fragen „Sollen wir einen Node-Service für web3.js dazunehmen?". Dieser Weg ist per Default geschlossen.
Der Knackpunkt: jeder Eintrag muss explizit und absolut sein. Schreib nicht „TypeScript möglichst vermeiden". Schreib „Kein TypeScript". Was unscharf ist, liest Claude als verhandelbar.
Der letzte grosse Block in CLAUDE.md heisst „Claude-Code-Nutzungsregeln":
### Wenn ich sage "fang mit X an"
1. Prüfe zuerst, ob die CLAUDE.md-Constraints diesen Ansatz erlauben
2. Prüfe dann, ob es im Code schon eine verwandte Implementierung gibt (kein Rad neu erfinden)
3. Bevor du Code schreibst, leg einen neuen Branch an
4. Nach der Implementierung: Tests laufen lassen
5. Nicht automatisch committen — wenn der Code steht und Tests grün sind,
stoppen und Bericht erstatten. Auf mein explizites "commit" warten
### Wenn ich sage "ich habe eine Idee"
Nicht sofort Code schreiben. Erst:
1. Verständnis bestätigen (paraphrasieren)
2. Gegen die CLAUDE.md-Constraints prüfen
3. Mögliche Probleme oder bessere Alternativen aufzeigen
4. Auf meine Bestätigung warten, dann handeln
### Bei einer technischen Verzweigung
Wenn CLAUDE.md nichts vorgibt:
1. Per Default die "Rails-nativere" Variante wählen
2. Per Default die Variante mit weniger Abhängigkeiten wählen
3. Per Default die Variante wählen, mit der ein Solo-Entwickler schneller iteriert
4. Bei Zweifel stoppen und fragen
Dieser Teil ist zehnmal wichtiger als „benutze snake_case".
Code-Stil lernt Claude beim Lesen des Codes. Aber „wann stoppen und fragen", „bei 'ich habe eine Idee' erst paraphrasieren, nicht sofort Code schreiben" — das sind Verhaltensmuster. Code allein lehrt sie nicht.
Der wichtigste Satz: welche Richtung an einer Verzweigung Default ist. Diese eine Regel entscheidet, was Claude tut, wenn du nicht im Raum bist (wenn du nur „fang mit X an" sagst und gehst). Schreib das klar nieder, dann kannst du es unbeaufsichtigt arbeiten lassen.
Oben in der CLAUDE.md steht:
Dieses Dokument ist die „Primärquelle" des Projekts. Wird zu Beginn jeder Claude-Code-Session automatisch geladen. Bei Änderungen an technischen Entscheidungen: erst hier ändern, der Code zieht nach.
Das ist ein Workflow-Vertrag. Wenn ich eine technische Wahl ändere — etwa das Hauptmodell von gpt-5-mini auf gpt-5 heben — ist der erste Schritt nicht, am Initializer zu schrauben. Der erste Schritt ist, diesen Abschnitt der CLAUDE.md anzupassen:
ai:
fast: gpt-5-mini # vorher
fast: gpt-5 # nachher
Erst dann lasse ich Claude CLAUDE.md neu lesen und den Code anpassen.
Warum? Wenn du im Code einen Wert änderst und CLAUDE.md hinterherhinkt, sieht Claude beim nächsten Lesen von CLAUDE.md den alten Wert und „dreht hilfreich" deinen Code zurück. Wurzel des Konflikts: ein Single Point of Failure — CLAUDE.md ist nicht mehr synchron. Eine Verfassung, die hinter der Realität herhinkt, ist der Anfang vom Bürgerkrieg.
CLAUDE.md als Verfassung zu behandeln, heisst: sie läuft immer dem Code voraus.
smarts.md, 5 Tage, 92 Commits:
Durchschnittliche PR-Lebensdauer: 30 Minuten. Keine grossen Refactorings. Kein „warte, diese Richtung war falsch, rollback".
Nicht, weil Claude zaubert. Sondern weil es jede Session auf 565 Zeilen Schiene fuhr. Es wusste, kein TypeScript reinzubringen, wusste, Solid Queue ist die Default-Queue, wusste, View-Funktionen werden 60 Sekunden gecacht, wusste, jeder Service implementiert eine call-Klassenmethode, wusste, vor dem Commit auf meine Bestätigung zu warten.
Streich die Hälfte dieser Constraints und du bekommst: 30 Minuten am Tag, um „warum wir X nicht nehmen" zu erklären, 5 Minuten zum Reviewen der „nebenbei" reingerutschten Abhängigkeit, und ein Gemfile, das langsam zerbröselt.
Fang nicht mit einer leeren Datei an. Fang mit der jüngsten Entscheidung an, die wehgetan hat.
Wenn Claude in letzter Zeit „ständig neue Abhängigkeiten reinholt", schreib die Verbots-Liste.
Wenn es „bei jeder Kleinigkeit die Architektur ändert", schreib das Architekturdiagramm + „neue Microservices, DB-Wechsel etc. brauchen Bestätigung".
Wenn es „keine Tests schreibt", schreib „was zwingend Unit-getestet werden muss".
Wenn es „zu aggressiv committet", schreib „kein Auto-Commit, auf explizite Anweisung warten".
Pro Schmerz ein Eintrag. Sonst nichts.
Drei Monate später hast du eine 500 Zeilen lange CLAUDE.md, hinter jeder Zeile ein konkretes „das soll es nie wieder tun". Dieses Dokument schlägt jedes Template, weil es genau auf dein Projekt, deinen Workflow, dein Team (auch wenn es nur du bist) abgestimmt ist.
Eine Verfassung wird nicht in einem Zug geschrieben. Sie kristallisiert, Konflikt für Konflikt.
Quelle: github.com/defi-io/smarts