CLAUDE.md Best Practices: KI-Setup frisch halten

Ihre CLAUDE.md begann sauber. Dann wuchs sie: hier eine Regel, dort eine Falle, dazu ein eingefügter halber Architektur-Doc. Jetzt ist sie lang, die Hälfte ist veraltet, und Claude Code ignoriert entweder die wichtigen Zeilen oder folgt einer Konvention, die Sie vor drei Monaten fallen gelassen haben. Eine gute CLAUDE.md ist eine der wertvollsten Dateien in Ihrem Repo. Eine aufgeblähte, veraltete macht Claude still und leise schlechter. So halten Sie Ihre schlank, nützlich und aktuell.

Die wichtigsten Erkenntnisse

CLAUDE.md ist eine Klartextdatei, die Claude Code zu Beginn jeder Sitzung liest. Legen Sie die dauerhaften Fakten und Regeln hinein, die nicht in den Code selbst passen.
Halten Sie sie schlank. Eine kurze, signalstarke Datei schlägt eine lange, weil alles darin um die Aufmerksamkeit des Modells konkurriert.
Strukturieren Sie sie mit klaren Überschriften: was das Projekt ist, Befehle, Konventionen und die Dinge, die Claude immer wieder falsch macht.
Die zwei häufigsten Fehler sind Aufblähung (das Einfügen von Docs, die die KI nicht braucht) und Veralten (Regeln, die nicht mehr zum Code passen).
CLAUDE.md sagt der KI, wie sie arbeiten soll; Ihre Fakten über sich selbst und Ihre Welt sind eine separate Sache. Beide veralten von Hand, sofern nicht etwas sie aktuell hält.

---

Was CLAUDE.md ist und wo sie lebt

CLAUDE.md ist eine Klartextdatei, die Claude Code zu Beginn einer Sitzung automatisch lädt und als dauerhafte Anweisungen behandelt. Sie ist das Nächste, was Claude Code an einem von Ihnen direkt kontrollierten Gedächtnis hat, weil Sie sie sehen, bearbeiten und wie jede andere Datei versionieren können.

Es gibt einige Orte, an denen sie leben kann, und sie stapeln sich:

Projekt-Root (./CLAUDE.md): Regeln für dieses Repo. Committen Sie es, damit das ganze Team es teilt.
Home-Verzeichnis (~/.claude/CLAUDE.md): Ihre persönlichen Regeln, die für jedes Projekt gelten.
Unterverzeichnis (./packages/api/CLAUDE.md): eng gefasste Regeln, die nur innerhalb dieses Teils des Baums zählen.

Claude liest die relevanten Dateien für den Ort, an dem es arbeitet, sodass die nähere Datei die breitere um Details ergänzt. Das hilfreiche mentale Modell: CLAUDE.md ist die Onboarding-Notiz, die Sie für einen scharfsinnigen neuen Freelancer schreiben würden, der Ihre Codebasis nie gesehen hat, aber ein starker Entwickler ist. Sie bringen ihm nicht neu bei, wie man programmiert. Sie sagen ihm die Dinge, die spezifisch für Sie sind und die er sonst eine Weile bräuchte, um sie zu entdecken.

Was in CLAUDE.md gehört

Die besten CLAUDE.md-Dateien halten die dauerhaften, projektspezifischen Fakten, die aus dem Lesen des Codes nicht offensichtlich sind. Konkret:

Was das Projekt ist, in zwei oder drei Zeilen. Der Ein-Satz-Zweck und die Form des Stacks.
Befehle, die zählen. Wie man Tests ausführt, den Dev-Server startet, lintet, baut. Die exakten Befehle, damit Claude nicht rät.
Konventionen, denen Sie immer folgen. "Nutze den bestehenden db.query-Helper, nie rohes SQL." "Bevorzuge hier Komposition über Vererbung." "Alle API-Antworten laufen durch formatResponse."
Dinge, die Claude immer wieder falsch macht. Dieser Abschnitt verdient sich seinen Platz. Jedes Mal, wenn die KI denselben Fehler zweimal macht, schreiben Sie die Korrektur hier einmal auf.
Grenzen. Was nicht anzufassen ist, was generiert ist, was veraltet, aber noch vorhanden ist.

Der Test für jede Zeile ist einfach: Müsste ein starker Entwickler, der neu in diesem Repo ist, das gesagt bekommen, und würde es echte Zeit sparen? Wenn ja, gehört es hinein. Wenn es generischer Rat ist, den jeder kompetente Entwickler bereits kennt, oder etwas, das die KI direkt aus dem Code lesen kann, lassen Sie es weg.

Was aus CLAUDE.md herausbleibt

Genauso wichtig ist, was nicht hineingehört, denn alles in der Datei konkurriert um Aufmerksamkeit.

Fügen Sie keine ganzen Docs ein. Ein Link oder eine einzeilige Zusammenfassung schlägt eine Wand eingefügter Architektur. Die Datei soll verweisen, nicht duplizieren.
Wiederholen Sie nicht das Offensichtliche. "Schreib sauberen Code" und "füge Tests hinzu" sind Rauschen. Das Modell weiß es bereits.
Nehmen Sie keine Geheimnisse auf. Keine Schlüssel, Tokens oder Zugangsdaten. Die Datei wird committet und jede Sitzung gelesen.
Lassen Sie sie kein Changelog werden. Historie gehört in Git. CLAUDE.md ist der aktuelle Stand, nicht die Geschichte, wie Sie dorthin kamen.

Jede zusätzliche Zeile verwässert das Signal der Zeilen, die zählen. Eine knappe 40-Zeilen-Datei, der Claude tatsächlich folgt, ist mehr wert als eine 300-Zeilen-Datei, die es überfliegt.

So strukturieren Sie sie: ein kopierbares Beispiel

Nutzen Sie klare Markdown-Überschriften, damit das Modell den relevanten Teil schnell findet. Hier ist ein echtes, kopierbares Grundgerüst, das Sie anpassen können. Es ist bewusst kurz.

# CLAUDE.md

## Projekt

Billing-Service für die App. Node + TypeScript, Postgres, deployt auf Fly.
Behandelt Abonnements, Rechnungen und Webhooks von Stripe.

## Befehle

- Install: `pnpm install`
- Dev-Server: `pnpm dev`
- Tests: `pnpm test` (vor jedem Commit ausführen)
- Type-Check: `pnpm typecheck`
- Lint: `pnpm lint`

## Konventionen

- Geld ist immer Ganzzahl-Cents, nie Floats. Nutze den `Money`-Typ.
- Aller DB-Zugriff läuft durch `src/db/queries.ts`. Schreibe nie rohes SQL in Handlern.
- API-Antworten werden von `formatResponse()` umhüllt. Gib keine nackten Objekte zurück.
- Neue Endpunkte bekommen einen Test in `test/api/` im selben PR.

## Aufpassen bei

- Die Retries in `stripe.ts` sind bewusst idempotent. Füge keine eigene Retry-Schleife hinzu.
- Der Ordner `legacy/` ist veraltet, aber noch live. Erweitere ihn nicht; melde, wenn angefasst.
- Webhook-Handler müssen schnell sein. Lagere echte Arbeit an die Queue in `jobs/` aus.

## Außerhalb des Rahmens

- Ändere keine bereits angewendeten Migrationen (alles in `migrations/`, datiert vor diesem Monat).

Diese Datei ist absichtlich kurz. Jede Zeile sagt Claude entweder, wie das Projekt läuft, eine Konvention, die es nicht kennen würde, oder einen Fehler, den es vermeiden soll. Nichts ist generisch. Wenn Sie einen schlankeren Ausgangspunkt wollen, deckt der Claude-Memory-Hub ab, wie CLAUDE.md neben Claudes anderen Memory-Formen passt.

Häufige Fehler, die sie verschlechtern

Zwei Fehler ruinieren die meisten CLAUDE.md-Dateien, und sie sind der Grund, warum die Datei mit der Zeit Claude oft weniger zuverlässig macht statt mehr.

Aufblähung. Die Datei wächst, weil das Hinzufügen einer Zeile sich kostenlos anfühlt. Ist es nicht. Ein Modell, das eine 300-Zeilen-CLAUDE.md liest, verteilt seine Aufmerksamkeit auf 300 Zeilen, und Ihre drei tragenden Regeln bekommen dasselbe Gewicht wie dreißig Wissensbröckchen. Wenn Claude anfängt, wichtige Anweisungen zu ignorieren, ist die Lösung meist, die Datei zu halbieren, nicht eine weitere Zeile hinzuzufügen, die ihm sagt, aufzupassen.

Veralten. Das ist der leise Fehler. Sie schrieben "nutze immer den useAuth-Hook" und sind dann davon migriert. Die Regel steht noch in der Datei. Jetzt folgt Claude voller Zuversicht einer Anweisung, die falsch ist, und Sie verbringen Zeit damit, sie rückgängig zu machen. Eine CLAUDE.md spiegelt die Realität nur an dem Tag wider, an dem Sie sie zuletzt bearbeitet haben. Sie weiß nicht, dass sich der Code geändert hat. Niemand plant eine "CLAUDE.md aufräumen"-Aufgabe, also driftet sie, und eine gedriftete Setup-Datei ist schlimmer als keine, weil Sie ihr vertrauen.

Die Pflege-Antwort ist langweilig, aber real: Behandeln Sie CLAUDE.md wie Code. Reviewen Sie sie, wenn Sie den umgebenden Code reviewen. Ändert sich eine Konvention, ändern Sie die Datei im selben PR. Und halten Sie sie klein genug, dass ihr Review keine Plackerei ist.

CLAUDE.md sagt der KI wie. Ihre Fakten sind eine separate Sache.

Hier ist eine Unterscheidung, die es zu behalten lohnt, denn sie erklärt, warum selbst eine perfekte CLAUDE.md eine Lücke lässt.

Eine CLAUDE.md sagt der KI, wie in diesem Projekt zu arbeiten ist: die Befehle, die Konventionen, die Regeln. Sie ist prozedural. Sie handelt von der Codebasis, nicht von Ihnen.

Ihre Fakten sind anders. Wer Ihre Nutzer sind, was Sie letzte Woche zur Preisgestaltung entschieden haben, Ihre Meinung zu einer Bibliothek, der Grund, warum ein Feature existiert, der Kontext aus dem Meeting, der es nie in ein Dokument geschafft hat. Dieses Wissen ist es, was die Ergebnisse einer KI spezifisch für Ihre Situation macht, und es gehört nicht in eine projektbezogene Setup-Datei. Es ist keine Prozedur. Es ist Memory.

Beide haben denselben Fehlermodus: Sie veralten von Hand. Eine CLAUDE.md driftet, wenn sich der Code ändert und Sie vergessen, sie zu bearbeiten. Ihre Fakten driften in dem Moment, in dem sich Ihre Welt bewegt und niemand die Notiz aktualisiert. Der Unterschied ist, dass eine CLAUDE.md klein genug ist, um sie mit Disziplin zu pflegen, während Ihre Fakten zu viele und zu schnelllebig sind, um sie durch Bearbeiten von Dateien aktuell zu halten. Genau dort verdient sich ein Memory, das sich selbst aktualisiert, seinen Platz: Es beobachtet Ihre echte Aktivität, markiert den alten Fakt als überholt, wenn sich etwas ändert, und hält die KI aus der aktuellen Wahrheit arbeitend, ohne dass Sie ein Ticket gegen Ihre eigenen Notizen einreichen. Eine gut gepflegte CLAUDE.md plus ein sich selbst pflegender Speicher Ihrer Fakten ist ein Setup, das frisch bleibt, statt zu verfallen.

Häufig gestellte Fragen

Was gehört in eine CLAUDE.md-Datei?

Die dauerhaften, projektspezifischen Fakten, die aus dem Code nicht offensichtlich sind: was das Projekt ist, die Befehle zum Ausführen, die Konventionen, denen Sie immer folgen, und die Fehler, die Claude immer wieder macht, damit Sie sie einmal korrigieren können. Lassen Sie Geheimnisse, eingefügte Docs, generischen Rat und Historie, die in Git gehört, draußen.

Wo sollte die CLAUDE.md-Datei liegen?

Im Projekt-Root für repo-weite Regeln (committen Sie sie, damit das Team sie teilt), in Ihrem Home-Verzeichnis (~/.claude/CLAUDE.md) für persönliche Regeln über alle Projekte und optional in einem Unterverzeichnis für Regeln, die auf einen Teil des Baums begrenzt sind. Claude kombiniert die relevanten Dateien für den Ort, an dem es arbeitet.

Wie lang sollte eine CLAUDE.md sein?

Kürzer, als Sie denken. Alles in der Datei konkurriert um die Aufmerksamkeit des Modells, also schlägt eine knappe, signalstarke Datei, der Claude tatsächlich folgt, eine lange, die es überfliegt. Wenn Claude anfängt, Anweisungen zu ignorieren, hilft das Kürzen der Datei meist mehr als das Hinzufügen.

Warum funktioniert meine CLAUDE.md mit der Zeit nicht mehr?

Meist durch Veralten oder Aufblähung. Die Datei beschreibt die Realität an dem Tag, an dem Sie sie zuletzt bearbeitet haben, sodass Claude, wenn sich der Code ändert und die Datei nicht, Regeln folgt, die nun falsch sind. Und wenn die Datei wächst, werden Ihre wichtigen Regeln verwässert. Reviewen Sie sie zusammen mit dem Code und halten Sie sie schlank.

Ist CLAUDE.md dasselbe wie Claudes Memory?

Nein. CLAUDE.md ist eine Datei, die Sie schreiben und pflegen und die Claude sagt, wie es in einem Projekt arbeiten soll. Claude hat außerdem ein Memory-Tool, in das es selbst schreibt, und ein Memory über Chats hinweg in den Verbraucher-Apps. CLAUDE.md behandelt die Prozedur; Ihre persönlichen Fakten und Entscheidungen sind eine separate Art von Kontext.

---

Eine großartige CLAUDE.md ist es wert, knapp gehalten zu werden, denn sie ist das eine Stück Ihres KI-Setups, das Sie vollständig kontrollieren. Aber Ihr Setup ist mehr als eine Datei, und die Fakten, die die Ergebnisse Ihrer KI spezifisch für Sie machen, driften schneller, als Sie sie von Hand bearbeiten können. Locul ist ein Second Brain, der sich aus dem aufbaut, was Sie ohnehin produzieren, und sich auf Ihrem Rechner aktuell hält, und diesen Kontext dann Claude Code und Ihren anderen Werkzeugen bereitstellt. Memory Packs helfen, die Wissensseite Ihres Setups frisch zu halten. Sehen Sie, wie es funktioniert.

CLAUDE.md Best Practices: So veraltet Ihr KI-Setup nicht