Was ist eine CLAUDE.md-Datei? Und wie du eine schreibst, die dein Agent auch befolgt

Wenn du Claude Code länger als einen Tag genutzt hast, kennst du den Mehraufwand: In jeder neuen Sitzung erklärst du deinen Stack, deine Konventionen und die Dinge, die er ständig falsch macht, wieder von vorn. Die Datei CLAUDE.md existiert, um genau das zu beenden. Sie ist klein, sie ist langweilig, und sie ist die Datei mit der größten Hebelwirkung in deinem Repo.

Was ist eine CLAUDE.md-Datei?

Eine CLAUDE.md-Datei ist eine Markdown-Datei, die Claude Code zu Beginn jeder Sitzung automatisch liest. Sie ist das Langzeitgedächtnis für ein Projekt: die Regeln, der Kontext und die Befehle, die der Agent bei jeder Aufgabe automatisch berücksichtigen soll, ohne dass man es ihm extra sagen muss. Du schreibst sie einmal, committest sie, und sie wird jedes Mal geladen. Es ist die einzige Datei, die standardmäßig in jede Konversation einfließt.

CLAUDE.mdeinmal geschrieben

Sitzung 1geladen

Sitzung 2geladen

Jede Sitzunggeladen

Eine einzige Datei, die zu Beginn jeder Sitzung gelesen wird. Genau deshalb lohnt es sich, sie richtig aufzusetzen.

Warum eine bestimmte CLAUDE.md-Datei viral ging

Anfang des Jahres machte eine einzige CLAUDE.md-Datei die Runde, weil sie etwas tat, was die meisten nicht tun. Sie nahm eine Handvoll Beobachtungen darüber, wie KI-Agenten scheitern, zu wenig planen, fehlende Details einfach annehmen, einfache Aufgaben unnötig verkomplizieren und Dateien anfassen, nach denen niemand gefragt hat, und verwandelte sie in klare Regeln, an die sich der Agent halten musste. Es war keine Liste deiner Framework-Versionen. Es war eine Beschreibung des gewünschten Verhaltens.

Das ist die ganze Erkenntnis. Der Standard-Agent hat starke Instinkte und keinerlei Zurückhaltung. Eine CLAUDE.md voller Projekt-Details ändert daran nichts. Eine CLAUDE.md voller Verhaltensregeln schon.

Der kitstarter-Roboter, der an einem Laptop arbeitet, während daneben ein einzelnes Blatt Papier angepinnt und immer im Blick ist — Ein einziges Blatt, genau dort angepinnt, wo der Agent es nicht übersehen kann. Das ist das ganze Prinzip.

Was tatsächlich in eine CLAUDE.md-Datei gehört

Denk in drei Ebenen, und zwar in dieser Reihenfolge. Die Reihenfolge ist wichtig, weil das Modell dem, was ganz oben steht, die meiste Aufmerksamkeit schenkt.

Verhaltensregelnvor dem Coden nachfragen, die kleinstmögliche funktionierende Änderung, Lauffähigkeit beweisen, nicht nach KI aussehen

Projektkontextder Stack und nur die Konventionen, die vom Standard abweichen

Befehledie Dev-, Test- und Build-Befehle, die er tatsächlich ausführen soll

Erst das Verhalten, dann der Kontext, danach die Befehle. Die meisten Leute machen es genau umgekehrt und wundern sich, warum sich nichts ändert.

Beachte, was hier nicht steht: seitenlange Dokumentationen, deine gesamte Architektur, eine Kopie der README. Solche Dinge blähen die Datei nur auf, lenken die Aufmerksamkeit des Modells von den wichtigen Regeln ab und werden ignoriert. Eine CLAUDE.md ist kein Ort für reines Wissen. Sie ist der Ort für Verhalten.

So schreibst du sie, damit dein Agent sie auch befolgt

Einige Regeln, die darüber entscheiden, ob die Datei funktioniert oder einfach nur nutzlos herumliegt:

Halte sie schlank, unter 200 Zeilen. Modelle befolgen nur eine begrenzte Anzahl von Anweisungen zuverlässig, und der eigene System-Prompt von Claude Code verbraucht bereits einen Teil dieses Budgets. Eine CLAUDE.md mit 600 Zeilen ist eine 600-Zeilen-Datei, die der Agent nur überfliegt.
Setz die wichtigsten Regeln ganz nach oben. Die Datei wird von oben nach unten gelesen, und der Anfang erhält die konstanteste Aufmerksamkeit.
Dokumentiere nur, was vom Standard abweicht. Der Agent weiß bereits, wie man React schreibt. Sag ihm die Dinge, die er sonst bei deinem Projekt falsch machen würde.
Betrachte sie als lebendiges Dokument. Jedes Mal, wenn du den Agenten korrigierst, fügst du die entsprechende Regel hinzu, damit er diesen Fehler nicht noch einmal macht. Diese eine Gewohnheit zahlt sich schneller aus als alles andere.

Erst fragen, dann handelnImmer nur eine Frage auf einmal, präsentiert als Multiple-Choice-Auswahl inklusive Empfehlung, bis das Ziel lückenlos formuliert ist.

Direkt seinKomm sofort auf den Punkt. Empfiehl eine Option mit Begründung, statt fünf aufzulisten. Sag es offen, wenn eine Idee nicht funktioniert.

Keine typischen KI-Spuren hinterlassenKeine Gedankenstriche in den Texten, die er für dich schreibt, keine Emojis als Überschriften, keine flachen Farbverläufe als Deko, korrekt geladene Schriftarten.

Warnsignale, stoppen und korrigierenEine zweispaltige Tabelle, die gegenüberstellt, was der Agent tun will und was er stattdessen tun soll. Das macht die Regeln überprüfbar.

Konventionen (bitte befolgen)Nur die internen Regeln, die vom Standard abweichen: die Markenfarben, die Schriftarten, wie ein Screenshot geprüft wird.

Wo was zu finden istEine Übersicht der Dateistruktur und welche Datei die einzige Quelle der Wahrheit (Single Source of Truth) ist. Verweise auf den Code, niemals eine Kopie davon.

Befehle nutzenDer auszuführende Befehl für jede wiederkehrende Aufgabe, damit der Agent sich nicht selbst einen Workflow improvisiert.

Sieben echte Abschnitte aus den beiden AGENTS.md-Dateien in diesem Repo, dem Kit, das wir ausliefern, und dem Leitfaden für diese Website. Dieselbe Datei, toolübergreifender Dateiname. Verhalten belegt die ersten vier.

Leg Projektregeln in ./CLAUDE.md im Root-Verzeichnis des Repos ab, damit dein Team sie über Git teilen kann. Leg deine persönlichen Standardeinstellungen in ~/.claude/CLAUDE.md ab, damit sie dir in jedes Projekt folgen.

Die Abkürzung: Verhalten, fix und fertig

Gute Verhaltensregeln zu schreiben ist eine Kunst für sich, und sie so zu formulieren, dass ein Agent sie auch wirklich befolgt, erfordert viele Anläufe. Das ist die Idee hinter kitstarter: eine CLAUDE.md und eine Reihe von Befehlen, die dafür sorgen, dass Claude Code, Codex und Antigravity erst nachfragen, bevor sie etwas bauen, schlank bleiben und nicht mehr nach KI aussehen, schriftlich festgehalten, wo der Agent es auch liest. Du kannst absolut deine eigenen schreiben. Fang mit den vier Verhaltensregeln oben an, halte sie unter 200 Zeilen und füg jedes Mal eine Regel hinzu, wenn der Agent patzt. Wenn du die Formulierungen willst, die sich bereits bewährt haben: Wir haben sie fertig geliefert.

Häufige Fragen

Wo gehört die CLAUDE.md-Datei hin? Projektregeln in ./CLAUDE.md im Root-Verzeichnis des Repos, geteilt mit deinem Team über Git. Persönliche Standardeinstellungen in ~/.claude/CLAUDE.md. Beide werden automatisch geladen.

Wie lang sollte sie sein? Unter etwa 200 Zeilen. Darüber hinaus fängt das Modell an, den Text nur noch zu überfliegen, und deine wichtigen Regeln gehen unter.

Was ist der Unterschied zwischen CLAUDE.md und AGENTS.md? Dieselbe Idee, anderer Dateiname. AGENTS.md ist die toolübergreifende Konvention, die mehrere Agenten lesen, CLAUDE.md ist die von Claude Code. Viele Teams pflegen nur eine davon und verweisen mit der anderen darauf. Mehr dazu in unserem Best-Practices-Leitfaden.

Spar dir das mühsame Ausprobieren

kitstarter liefert die CLAUDE.md und die Befehle, die dafür sorgen, dass dein Agent erst nachfragt, schlank bleibt und nicht nach KI aussieht.

Get the kit · $20 $29 Dokumentation lesen