Eine CLAUDE.md-Datei wird in jede Claude Code-Sitzung geladen. Eine gute Datei zahlt sich also mehrfach aus, während eine überladene dich bei jeder Aufgabe unbemerkt etwas kostet. Hier sind die Best Practices, die wirklich einen Unterschied machen, sortiert nach ihrer Wichtigkeit.
1. Halte sie unter rund 200 Zeilen
Das ist der Punkt, der die meisten fehlerhaften CLAUDE.md-Dateien repariert. Frontier-Modelle befolgen nur eine begrenzte Anzahl von Anweisungen zuverlässig, und der eigene System-Prompt von Claude Code verbraucht bereits einen Teil dieses Budgets, bevor deine Datei überhaupt gelesen wird. Eine CLAUDE.md mit 600 Zeilen ist nicht sechsmal so hilfreich. Sie ist dann nur eine Datei, die der Agent überfliegt, während deine wichtigen Regeln irgendwo in der Mitte untergehen. Schlank zu bleiben ist hier keine Frage des Stils. Es ist das, was die Datei überhaupt erst funktionieren lässt.
2. Setze auf Verhalten, nicht auf Dokumentation
Der mit Abstand häufigste Fehler ist es, CLAUDE.md als Wissensdatenbank zu behandeln: Architektur, vollständige Konventionen, eine einkopierte README. Der Agent weiß bereits, wie man codiert. Was ihm fehlt, ist Zurückhaltung. Ganz oben in der Datei sollten daher Verhaltensregeln stehen, also die Dinge, die er sonst instinktiv falsch machen würde.
3. Dokumentiere nur, was vom Standard abweicht
Jede Zeile, in der du dem Agenten etwas erklärst, das er ohnehin schon weiß, zieht Aufmerksamkeit von den wirklich wichtigen Regeln ab. Sag ihm nicht, dass React Komponenten verwendet. Sag ihm, dass du nur Named Exports nutzt, dass du niemals ohne Rücksprache eine Dependency hinzufügst und dass Tests an einem ganz bestimmten Ort liegen. Gib ihm Kontext, den der Agent nicht erraten kann, und lass alles andere weg.
4. Setze die wichtigsten Regeln ganz nach oben
Die Datei wird von oben nach unten gelesen, und der Anfang erhält die meiste Aufmerksamkeit. Wenn eine Regel nicht verhandelbar ist, gehört sie nach ganz oben, nicht in Zeile 180. Die Reihenfolge ist ein Hebel, also nutze ihn.
5. Behandle sie als lebendiges Dokument
Die Gewohnheit, die sich am schnellsten auszahlt: Jedes Mal, wenn du den Agenten korrigierst, fügst du diese Korrektur als Regel hinzu, damit er denselben Fehler nie wieder macht. Nach ein paar Wochen wird deine CLAUDE.md zu einer präzisen Karte der typischen Fehler deines Agenten, und er hört auf, diese Fehler zu machen. Beende deine Korrekturen mit der einfachen Anweisung, die Datei zu aktualisieren.
6. Committe sie und trenne Persönliches vom Projekt
Projektregeln gehören in ./CLAUDE.md im Root-Verzeichnis des Repositories und werden in Git committet. So erhält dein gesamtes Team dasselbe Verhalten des Agenten, anstatt dass jeder seine eigenen Anpassungen vornimmt. Deine persönlichen Standardeinstellungen, also wie der Agent projektübergreifend für dich arbeiten soll, gehören in ~/.claude/CLAUDE.md und bleiben lokal bei dir.
Die Schwierigkeit liegt in der Formulierung
Keine dieser Praktiken ist kompliziert. Die eigentliche Arbeit liegt in der Formulierung: Verhaltensregeln zu schreiben, die ein Agent tatsächlich befolgt, statt solcher, die er nur abnickt und dann ignoriert, erfordert echtes Ausprobieren. Genau das ist kitstarter: eine CLAUDE.md und eine Reihe von Befehle, die so abgestimmt sind, dass der Agent nachfragt, bevor er baut, und schlank bleibt, sofort einsatzbereit. Schreibe deine eigenen Regeln mit den Tipps oben oder starte mit einer Vorlage, die bereits funktioniert.
Häufige Fragen
Wie lang sollte eine CLAUDE.md-Datei sein? Unter rund 200 Zeilen. Darüber hinaus überfliegt der Agent die Datei nur noch, und deine Regeln verlieren an Wirkung.
Was ist der häufigste Fehler? Sie mit Dokumentation statt mit Verhaltensregeln zu füllen. Setze Verhaltensregeln an den Anfang und beschränke den Kontext auf das, was vom Standard abweicht.
Sollte die CLAUDE.md in Git eingecheckt werden? Ja für Projektregeln (./CLAUDE.md). Persönliche Standardeinstellungen gehören in ~/.claude/CLAUDE.md und bleiben lokal auf deinem Rechner.
Eine CLAUDE.md, die bereits funktioniert
kitstarter liefert die Verhaltensregeln und Befehle, passend formuliert für Claude Code, Codex und Antigravity, damit dein Agent sie auch wirklich befolgt.