CLAUDE.md Best Practices: 9 Regeln, damit Claude Sie nicht ignoriert (2026)

CLAUDE.md Best Practices: 9 Regeln, damit Claude Sie nicht ignoriert (2026)

Die meisten Beiträge zu CLAUDE.md Best Practices liefern Ihnen eine Vorlage und sind fertig — aber die Datei, die Sie letzte Woche geschrieben haben, wird wahrscheinlich schon ignoriert, ohne dass Sie es merken. Der Fix lautet selten "mehr Regeln hinzufügen". Meistens ist es genau das Gegenteil. Wir haben Claude Code in allen unseren jüngsten Kundenprojekten eingesetzt, und diese 9 Regeln sind es, die tatsächlich den Unterschied machen: eine Hierarchie, die zum Ladeverhalten von Claude passt, ein Instruktionsbudget, das Sie nicht sprengen können, die AGENTS.md-Entscheidung und die sechs Gründe, warum Claude Ihre Datei mittendrin still fallen lässt.

Zusammenfassung

• CLAUDE.md ist Projektgedächtnis, das in den Kontext von Claude Code geladen wird — halten Sie die Datei unter 200 Zeilen, sonst fangen Regeln an, verloren zu gehen.
• Dateien werden von oben nach unten geladen: global, Projektstamm, Unterverzeichnis (lazy) und CLAUDE.local.md (persönlich, gitignoriert).
• Nutzen Sie AGENTS.md, wenn Sie auch Cursor oder Copilot einsetzen; symlinken Sie CLAUDE.md auf AGENTS.md, um beide Ziele auf einmal zu bedienen.
• Wenn Claude Ihre Datei ignoriert, liegt es in 90 % der Fälle an der Länge, vagen Formulierungen oder einem fehlenden "Warum".

Was CLAUDE.md eigentlich tut (und warum das wichtig ist)

Kurz gesagt: CLAUDE.md ist eine Markdown-Datei, die Claude Code zu Beginn jeder Sitzung als Projektgedächtnis liest. Sie ist kein System-Prompt, kein Hook und keine Skill-Datei — sondern ein empfehlender Kontext, der Claude auf die Konventionen Ihres Teams einstimmt. Denken Sie weniger an Dokumentation und mehr an eine Konfigurationsdatei, die Ihr KI-Pair-Programmer tatsächlich liest.

Viele Teams schreiben CLAUDE.md wie eine README. Das ist der erste Fehler. Eine README erklärt das Projekt Menschen, die querlesen und überspringen können. CLAUDE.md wird von Claude Code beim Sitzungsstart vollständig eingelesen — jede Zeile kostet Tokens und Regeladhärenz. Sie ähnelt eher einer Konfigurationsdatei oder einem Satz von Test-Fixtures als echter Dokumentation.

Außerdem ist sie nicht das einzige Steuerungsmittel. Hooks führen deterministische Aktionen aus (Formatierung, Commit-Blockierung). Skills bündeln wiederverwendbare Workflows. CLAUDE.md liegt dazwischen als empfehlender Kontext — Claude bewertet ihn, überschreibt ihn gelegentlich und vergisst definitiv Teile davon, wenn Sie zu viel schreiben. Diese Unterscheidung ist die Grundlage für alles Folgende, und sie erklärt, warum CLAUDE.md ein Werkzeug innerhalb der breiteren Praxis des Context Engineerings ist — kein Allheilmittel.

Regel 1: Behandeln Sie die Datei wie Code, nicht wie Dokumentation. Versionieren Sie sie. Überprüfen Sie Änderungen in Pull Requests. Kürzen Sie sie, wie Sie ein aufgeblähtes Modul refaktorieren würden. Laut dem Anthropic-Leitfaden zu CLAUDE.md wird die Datei mit derselben Priorität wie jede System-Instruktion geladen — was bedeutet, dass eine veraltete Regel von vor sechs Monaten noch heute aktiv jede Antwort prägt.

Wie CLAUDE.md lädt: Die 4-stufige Hierarchie

Kurz gesagt: Claude Code lädt CLAUDE.md aus vier Stufen: global (~/.claude/CLAUDE.md), Projektstamm, CLAUDE.local.md für persönliche Überschreibungen und Unterverzeichnisdateien, die lazy geladen werden — nur wenn Claude Dateien in diesem Verzeichnis öffnet. Benachbarte Unterverzeichnisse sehen die CLAUDE.md des jeweils anderen nie, was Claude Code Memory engmaschig hält.

Die Hierarchie ist der am häufigsten missverstandene Teil von CLAUDE.md — und genau hier fehlt den fünf Top-SERP-Ergebnissen die Tiefe. Das passiert wirklich unter der Haube:

Zwei Begriffe sind es wert, festgehalten zu werden: Lazy Loading und Geschwistertrennung.

Lazy Loading bedeutet, dass eine CLAUDE.md aus einem Unterverzeichnis erst dann in Claudes Kontext gelangt, wenn Claude tatsächlich eine Datei in diesem Verzeichnis öffnet. Wenn Sie "beheb den Login-Bug" fragen und Claude nur backend/ anfasst, lädt frontend/CLAUDE.md nie. Das ist gut — es hält das Kontextfenster sauber — aber es trifft Teams hart, die kritische Regeln in Unterverzeichnisse verlagert haben und davon ausgehen, dass sie immer gelten.

Geschwistertrennung ist das Gegenstück: frontend/CLAUDE.md und backend/CLAUDE.md laden sich nie gegenseitig. Sie teilen nur, was im Projektstamm steht. Wenn Ihre Frontend-Regeln also Ihren Backend-Regeln widersprechen, ist das kein Problem. Wenn sie eine Konvention teilen müssen, schieben Sie sie in die Stammdatei.

CLAUDE.local.md ist das Sicherheitsventil. Sie wird geladen, aber nicht eingecheckt — perfekt für Überschreibungen nach dem Motto "Ich bevorzuge pnpm, aber das Team hat sich auf npm geeinigt". Achtung: Sie wird nicht automatisch gitignoriert. Das müssen Sie selbst erledigen. Vergessen Sie es, und Sie checken Ihre persönlichen Regeln ins Team-Repository ein.

Regel 4: Passen Sie Instruktionen daran an, wo Claude sie tatsächlich liest. Style-Regeln für React-Komponenten gehören in frontend/CLAUDE.md, nicht in die Stammdatei. Datenbankmigrations-Regeln gehören in backend/. Die Anthropic Memory-Dokumentation (November 2025 aktualisiert) bestätigt das — das Lazy-Load-Verhalten ist bewusst so gestaltet und hat tragende Funktion.

Was in CLAUDE.md gehört (und was nicht)

Kurz gesagt: Hinein gehört alles, was Claude nicht aus Ihrem Code ableiten kann: Build-Befehle, Namenskonventionen, Anti-Muster, auf die Ihr Team hereingefallen ist, und das Warum hinter jeder Regel. Heraus gehört alles, was bereits in der README steht, alles in package.json und jede Regel, die sich wöchentlich ändert. Claude Code-Instruktionen sollten testbar und konkret sein.

Hier ist ein minimales CLAUDE.md, das tatsächlich etwas leistet:

# Project: techsy-app

## Commands
- Build: `pnpm build` (Turbopack — Webpack flags don't apply)
- Test: `pnpm test --run` (we use Vitest, not Jest)
- Lint: `pnpm lint` (will fail CI on warnings, not just errors)

## Conventions
- Server components by default. Add `'use client'` only when truly needed.
  Why: we hit 8s LCP last quarter from over-clienting.
- Database access only via `lib/db/` helpers — never raw SQL in routes.
  Why: row-level security policies live in those helpers.
- Tests colocate as `*.test.ts` next to the file under test.

## Don'ts
- Don't add a new dependency without opening a PR comment first.
- Don't use `any` — use `unknown` and narrow.

## Where to look
- Schema: `db/schema.ts`
- Auth flow: `lib/auth/README.md`

Vergleichen Sie das jetzt mit dem Anti-Muster, das die meisten Teams ausliefern:

# Project Rules

- Write clean, maintainable code.
- Follow best practices.
- Use TypeScript properly.
- Make sure tests pass.
- Be consistent with existing patterns.
- Document complex logic.

Die zweite Datei ist nicht falsch. Sie ist nutzlos. Claude will ohnehin sauberen Code schreiben. "Sei konsistent" sagt Claude nicht, mit welchem Muster es konsistent sein soll. Anthropic-Ingenieur Boris Chernys öffentliche Beispiele tendieren stark zum ersten Stil — konkrete Befehle, benannte Tools und das Warum hinter Entscheidungen, die aus der Codebasis allein nicht offensichtlich sind.

Regel 2: Sein Sie konkret, nicht aspirativ. "Schreib sauberen Code" ist aspirativ. "Server Components als Standard; 'use client' nur hinzufügen, wenn wirklich nötig" ist testbar. Dieselbe Disziplin trägt gutes Prompt Engineering: konkrete, testbare Anweisungen schlagen vage Absichtserklärungen, egal ob sie in einem Prompt oder einer CLAUDE.md stehen.

Regel 3: Erklären Sie das Warum hinter jeder Regel. Das "Warum" ist kein Fülltext — es ist der Mechanismus, mit dem Claude Grenzfälle entscheidet. Eine Regel mit Begründung ("wir hatten letztes Quartal 8s LCP durch zu viel Clienting") lässt sich auf ähnliche Situationen verallgemeinern. Eine Regel ohne Begründung wird ignoriert, sobald der Kontext wechselt. Das Muster ist auch im Builder.io-CLAUDE.md-Leitfaden dokumentiert.

Warum ignoriert Claude Ihre CLAUDE.md? Das Instruktionsbudget

Kurz gesagt: Claude ist nicht bösartig — es geht ihm schlicht die Aufmerksamkeit aus. Ab etwa 80 Zeilen bemerken Sie, dass Regeln fallen gelassen werden; ab 200 Zeilen werden ganze Blöcke ignoriert; ab 500 Wörtern dichter Regeln bricht die Regeladhärenz komplett ein. Der Fix: ein Instruktionsbudget. Behandeln Sie jede Zeile als Kosten für Claude Code Memory und die Einhaltung pro Regel.

Aktuelle Forschung bestätigt, was Produktionsnutzer immer wieder feststellen: Die Befolgung von Instruktionen verschlechtert sich nichtlinear mit der Regelanzahl. Das arxiv-Paper 2507.11538 zur Instruktionsbefolgungskapazität zeigt, dass die Adhärenz pro Regel sinkt, wenn Sie mehr Regeln stapeln — und HumanLayers Analyse von CLAUDE.md im Produktionseinsatz kommt zum selben Schluss.

Auf Deutsch: Jede Regel, die Sie hinzufügen, macht jede andere Regel ein kleines bisschen weniger wahrscheinlich befolgt zu werden. Eine 400-zeilige CLAUDE.md ist also nicht 4× so effektiv wie eine 100-zeilige. Sie ist oft weniger effektiv, weil die Regeln, die wirklich zählen, von den Regeln verwässert werden, die Sie an einem Freitag vor drei Monaten geschrieben und nie gelöscht haben.

In unseren eigenen CLAUDE.md-Dateien beginnt ab Zeile 150 sichtbar die Adhärenz nachzulassen. Ab Zeile 250 haben wir Claude beobachtet, wie es ganze Abschnitte übersprungen hat. Deshalb halten wir eine Obergrenze ein.

wc -l CLAUDE.md

Das ist das einzige Werkzeug. Führen Sie es aus. Wenn Sie über 200 liegen, haben Sie Ihr Budget überschritten. Die harte Regel, die wir an Kunden weitergeben:

Behandeln Sie CLAUDE.md wie ein 200-Zeilen-Budget. Jede Zeile kostet Adhärenz. Setzen Sie das Budget dort ein, wo es wirklich wichtig ist.

Regel 1 verstärkt: Halten Sie die Datei kurz. Unter 200 Zeilen. Unter 500 Wörtern dichter Regeln. Wenn Sie Automatisierungsregeln hinzufügen wollen ("immer Prettier nach Bearbeitungen ausführen"), gehören diese wahrscheinlich in Claude Code Hooks — Hooks sind deterministisch und kosten kein Instruktionsbudget.

CLAUDE.md, AGENTS.md, .cursorrules oder copilot-instructions — was soll ich verwenden?

Kurz gesagt: Wenn Sie nur Claude Code nutzen, reicht CLAUDE.md. Wenn Sie zwei oder mehr Agent-CLIs nutzen (Codex, Cursor, Copilot, Sourcegraph), wechseln Sie zu AGENTS.md und symlinken CLAUDE.md auf AGENTS.md. AGENTS.md hat sich Ende 2025 als geräteübergreifender Standard etabliert — die meisten modernen Agenten fallen auf sie zurück, sodass eine einzige Datei alle Ökosysteme bedient.

Das ist die Frage, die keines der fünf Top-Ergebnisse wirklich beantwortet. Hier die Matrix:

Der Dual-Target-Trick besteht aus einer Zeile:

ln -s AGENTS.md CLAUDE.md

Das war es. Jetzt lesen Claude Code, Codex und jedes AGENTS.md-fähige Tool dieselbe Datei. Einmal aktualisieren, jeder Agent übernimmt es. Die AGENTS.md-Spezifikation ist offen und bewusst minimal — es ist reines Markdown mit konventionellen Abschnitten.

Zwei Fallstricke aus der Praxis. Erstens: Wenn Ihr Team einen Cursor-Poweruser hat, verfolgt Cursors .cursorrules einen anderen Ansatz — eine einzige Datei, keine Hierarchie, ein starreres Format. Manche Teams behalten beides: AGENTS.md für die geteilten Regeln, .cursorrules für Cursor-spezifische Eigenheiten. Zweitens: Copilots .github/copilot-instructions.md fällt nicht auf AGENTS.md zurück — Copilot-lastige Teams brauchen also eine separate Datei.

Wenn Sie Ihren Agenten-Stack von Grund auf neu aufbauen, bietet unser Claude Code vs Cursor vs Copilot-Vergleich die Abwägungen auf Harness-Ebene. Kurz: Claudes Hierarchie ist am leistungsfähigsten für Monorepos, Cursors UX gewinnt bei der Solo-Arbeit, Copilots IDE-Integration ist nach wie vor am reibungslosesten für schrittweise Einführung.

Regel 9: Nutzen Sie AGENTS.md, wenn Sie mehr als eine Agent-CLI betreiben. Pflegen Sie nicht zwei Dateien mit demselben Inhalt. Entscheiden Sie sich für die Datei, die der Großteil Ihres Stacks liest, und symlinken Sie den Rest.

CLAUDE.md vs. Hooks vs. Skills: Das Entscheidungsdreieck

Kurz gesagt: CLAUDE.md = empfehlender Kontext. Hooks = deterministische Aktionen. Skills = gebündelte Fähigkeiten. Das falsche auswählen bedeutet: Instruktionsbudget verbrennen für etwas, das ein Hook erledigen sollte, oder eine CLAUDE.md-Regel für etwas schreiben, das nur ein Skill leisten kann. Das Dreieck ist der günstigste Weg, CLAUDE.md schlank zu halten.

Drei Tools, drei Jobs. Der Fehler, den wir am häufigsten sehen: "immer Prettier nach dem Bearbeiten ausführen" in CLAUDE.md schreiben. Claude liest es. Claude führt Prettier manchmal aus. Sie sind frustriert. Der Fix: Diese Zeile aus CLAUDE.md entfernen und in einen Hook verlagern — denn Hooks feuern deterministisch jedes Mal, ohne jede empfehlende Grauzone.

Wenn eine Regel immer feuern muss, gehört sie in einen Hook. Wenn es eine Stilpräferenz ist, die Claude gegen den Kontext abwägen kann, gehört sie in CLAUDE.md. Wenn es ein mehrstufiger Workflow mit gebündelten Assets (Vorlagen, Skripte, Prompts) ist, gehört er in einen Skill.

Regel 8: CLAUDE.md vs. Hooks vs. Skills richtig wählen — einen Hook in CLAUDE.md zu stecken, ist die häufigste Verschwendung von Instruktionsbudget. Konfigurieren Sie deterministische Aktionen mit Claude Code Hooks und verpacken Sie wiederverwendbare Workflows als Claude Skills. Ihre CLAUDE.md wird kürzer, Ihre Leitplanken werden fester, und Claude "vergisst" die wichtigen Regeln nicht mehr.

Monorepo-Muster: Verschachtelte CLAUDE.md, @imports und .claude/rules/

Kurz gesagt: In einem Monorepo halten Sie die CLAUDE.md im Stamm winzig — nur Zeiger und gemeinsame Konventionen. Schieben Sie das Spezifische in apps/*/CLAUDE.md, sodass jeder Teilbaum seine eigenen Regeln bekommt. Nutzen Sie @imports, um modulare Regeldateien über .claude/rules/ zu teilen. Das ist Progressive Disclosure — Claude zieht jedes Stück nur, wenn es relevant ist.

Ein typischer CLAUDE.md-Baum im Monorepo:

.
├── CLAUDE.md                        # 30 Zeilen — zeigt auf Unterverzeichnisse und gemeinsame Regeln
├── .claude/
│   └── rules/
│       ├── style.md
│       ├── testing.md
│       └── security.md
├── apps/
│   ├── web/
│   │   └── CLAUDE.md                # Next.js-spezifische Regeln
│   └── api/
│       └── CLAUDE.md                # Fastify-spezifische Regeln
└── packages/
    └── shared/
        └── CLAUDE.md                # Regeln für Library-Autoren

Die @import-Syntax lässt die Stammdatei gemeinsame Regelblöcke einziehen, ohne sie neu zu formulieren:

# Root CLAUDE.md

This is a Turborepo. See subdir CLAUDE.md for app-specific rules.

@import .claude/rules/style.md
@import .claude/rules/testing.md
@import .claude/rules/security.md

## Top-level commands
- `pnpm dev` runs all apps in parallel
- `pnpm test` runs every workspace's test script

Das ist Progressive Disclosure in der Praxis. Die Stammdatei ist ein 30-Zeilen-Zeiger. Jede Unterverzeichnis-CLAUDE.md ergänzt 50–80 Zeilen fokussierter Regeln. Die .claude/rules/-Dateien enthalten Konventionsblöcke, die mehrere Unterverzeichnisse einziehen können. Nichts wird dupliziert, nichts geht verloren, und keine einzelne Datei übersteigt das Instruktionsbudget.

Die Lazy-Loading-Regel von früher ist hier noch wichtiger: Wenn Claude an apps/web/Button.tsx arbeitet, sieht es die Stammdatei plus apps/web/CLAUDE.md plus die per @import eingebundenen Regeldateien. apps/api/CLAUDE.md sieht es nicht. Das ist der Sinn — Backend-Konventionen verschmutzen nicht den Frontend-Kontext, und Ihr Kontextfenster bleibt benutzbar.

Regel 6: Nutzen Sie @imports, um die Stammdatei unter 200 Zeilen zu halten. Der Anthropic-Leitfaden zu Best Practices für Claude Code behandelt das als Standardmuster im Monorepo. Subagenten erben auch den CLAUDE.md-Kontext des übergeordneten Elements — das ist wichtig zu wissen, wenn Sie Workflows verschachteln. Wie das mit dem Subagenten-Design zusammenspielt, erklärt der Leitfaden zum Context Engineering.

6 Gründe, warum Claude Ihre Datei ignoriert (und der Fix für jeden)

Kurz gesagt: Wenn Claude CLAUDE.md ignoriert, liegt es fast immer an einem von sechs Gründen: Datei zu lang, vage Formulierungen, fehlendes "Warum", Kontextkomprimierung, widersprüchliche übergeordnete Datei oder falscher Dateiname. Jeder hat einen 60-Sekunden-Fix. Testen Sie nach jeder Änderung in einer frischen Sitzung — das ist Regel 7.

1. Datei zu lang (>200 Zeilen / >500 Wörter)

Führen Sie wc -l CLAUDE.md aus. Wenn Sie über 200 liegen, kürzen Sie aggressiv. Verlegen Sie Automatisierungsregeln in Hooks. Verschieben Sie Workflows in Skills. Teilen Sie gemeinsame Blöcke in .claude/rules/ auf und ziehen Sie sie mit @import ein. Der häufigste Grund, warum Claude Ihre Regeln "nicht mehr befolgt", ist, dass die Datei mit der Zeit zu lang geworden ist und die Adhärenz still zusammengebrochen ist.

2. Vage Formulierungen ("schreib sauberen Code")

Ersetzen Sie jede aspirative Regel durch eine konkrete, testbare. "Sei konsistent" ist für Claude unsichtbar. "Standardmäßig Server Components verwenden; 'use client' nur für Formulare oder interaktive UI hinzufügen" ist etwas, das Claude tatsächlich anwenden kann.

3. Fehlendes "Warum"

Regeln ohne Begründung lassen sich nicht verallgemeinern. Claude kann nicht ableiten, wann es die Regel biegen soll, weil es nicht weiß, was die Regel schützt. Jede nicht-offensichtliche Regel bekommt eine Einzeiler-Begründung: "Wir verwenden unknown statt any, weil wir letztes Quartal drei Laufzeitabstürze durch als any typisierte API-Antworten hatten."

4. Kontextkomprimierung hat sie verworfen

Lange Sitzungen lösen Komprimierung aus — Claude fasst früheren Kontext zusammen, um ins Fenster zu passen, und CLAUDE.md-Inhalte werden dabei manchmal bis zur Unkenntlichkeit zusammengefasst. Der Fix: /clear nach größeren Kontext-Burns oder Neustart der Sitzung. Das ist genau das, was GitHub Issue #17530 immer wieder aufzeigt.

5. Widersprüchliche übergeordnete CLAUDE.md

Global sagt "4 Leerzeichen". Projektstamm sagt "2 Leerzeichen". Unterverzeichnis sagt nichts. Claude wählt eines — manchmal das falsche. Prüfen Sie ~/.claude/CLAUDE.md und Projektstamm auf Widersprüche. Das Spezifischere sollte gewinnen — aber nur, wenn Sie das ausdrücklich klarstellen.

6. Falscher Dateispeicherort oder Groß-/Kleinschreibung im Dateinamen

Claude.md und CLAUDE.md sind auf Linux und macOS unterschiedliche Dateien. Genauso claude.md und CLAUDE.md. Bestätigen Sie, dass der Pfad exakt ./CLAUDE.md (Großbuchstaben) lautet, und dass Claude Code aus dem Verzeichnis gestartet wird, das die Datei enthält. GitHub Issue #668 ist voll von Fällen, wo die Datei existierte, Claude sie aber wegen eines Pfadfehlers nicht sehen konnte.

Regel 7: Testen Sie in einer frischen Sitzung. Nach jeder CLAUDE.md-Änderung öffnen Sie eine neue Sitzung und bitten Claude, "die Regeln in CLAUDE.md zusammenzufassen". Wenn die Zusammenfassung etwas vermisst, leistet die Datei ihren Job nicht.

Ihre erste CLAUDE.md in 10 Minuten: Ein 5-Schritte-Einstieg

Kurz gesagt: Führen Sie /init aus, um einen Entwurf zu erstellen, kürzen Sie ihn auf 6–10 echte Regeln mit Begründungen, fügen Sie 3 Befehle hinzu, die Claude kennen sollte, fügen Sie 2 Anti-Muster hinzu, auf die Ihr Team gestoßen ist, und testen Sie dann in einer frischen Sitzung, indem Sie Claude bitten, die Datei zusammenzufassen. Zeitaufwand: etwa 10 Minuten. Das 5-Schritte-Rezept ist das, was wir am ersten Tag jedes neuen Repositories anwenden.

1. Führen Sie /init aus, um einen Entwurf zu erstellen. Der /init-Befehl von Claude Code scannt Ihr Repository und schreibt eine Starter-CLAUDE.md. Liefern Sie das Ergebnis nicht direkt aus. Die /init-Ausgabe ist ein Startpunkt, keine fertige Datei — und ehrlich gesagt kann das meiste, was sie generiert, weg.

2. Kürzen Sie auf 6–10 Zeilen echter Regeln mit Begründungen. Streichen Sie alles Generische. Streichen Sie alles, was in der README steht. Behalten Sie nur Regeln, die Claude nicht selbst aus dem Code ableiten kann.

3. Fügen Sie 3 Befehle hinzu, die Claude kennen sollte. Build, Test, Lint. Schreiben Sie den genauen Befehl und alle nicht offensichtlichen Flags. Wenn Sie Vitest statt Jest verwenden, sagen Sie es.

4. Fügen Sie 2 Anti-Muster hinzu, auf die dieses Team gestoßen ist. Echte. "Kein any verwenden, weil wir drei Laufzeitabstürze hatten" schlägt "TypeScript richtig verwenden" jedes Mal.

5. Öffnen Sie eine frische Sitzung und überprüfen Sie. Bitten Sie Claude, "die Regeln in CLAUDE.md zusammenzufassen". Wenn es etwas vermisst, ist die Datei zu lang, zu vage oder ein "Warum" fehlt. Korrigieren und wiederholen.

Regel 5: Nicht allein auf /init verlassen. /init ist ein Startpunkt, keine fertige Datei. Die 8 Minuten, die Sie mit Kürzen verbringen, sind der eigentliche Wert.

FAQ

Was ist eine CLAUDE.md-Datei?

Eine CLAUDE.md-Datei ist eine Markdown-Datei, die Claude Code zu Beginn jeder Sitzung als Projektgedächtnis liest. Sie teilt Claude Ihre Konventionen, Befehle und Anti-Muster mit, damit Claude nicht raten muss. Sie funktioniert auf vier Ebenen: global, Projektstamm, Unterverzeichnis (lazy geladen) und eine persönliche CLAUDE.local.md, die Sie gitignoriert halten.

Wie lang sollte eine CLAUDE.md-Datei sein?

Unter 200 Zeilen und unter 500 Wörtern dichter Regeln. Jenseits dieser Schwellenwerte lässt die Instruktionsbefolgung von Claude nach — jede Regel, die Sie hinzufügen, macht jede andere Regel ein kleines bisschen weniger wahrscheinlich befolgt zu werden. Behandeln Sie sie als festes Budget. Wenn Sie mehr benötigen, teilen Sie in Unterverzeichnis-CLAUDE.md-Dateien auf und nutzen Sie @import für gemeinsame Blöcke.

Wo soll ich CLAUDE.md ablegen?

Die Hauptdatei gehört in Ihr Projektstamm-Verzeichnis (./CLAUDE.md) und wird eingecheckt. Fügen Sie Unterverzeichnis-CLAUDE.md-Dateien für App-spezifische Regeln in Monorepos hinzu. Projektübergreifende Präferenzen gehören in ~/.claude/CLAUDE.md. Nutzen Sie CLAUDE.local.md für persönliche Überschreibungen, die Sie nicht einchecken wollen — aber vergessen Sie nicht, sie manuell zu gitignorieren.

Warum ignoriert Claude meine CLAUDE.md?

In 90 % der Fälle sind es drei Dinge: Die Datei ist zu lang (über 200 Zeilen), die Regeln sind vage ("schreib sauberen Code") oder Regeln haben kein "Warum", das Claude nutzen kann, um sie anzuwenden. Führen Sie wc -l CLAUDE.md aus und prüfen Sie dann auf Konkretheit. Testen Sie Änderungen in einer frischen Sitzung, indem Sie Claude bitten, die Datei zusammenzufassen.

Soll ich CLAUDE.md oder AGENTS.md verwenden?

Wenn Ihr Team nur Claude Code nutzt, bleiben Sie bei CLAUDE.md. Wenn Sie zwei oder mehr Agent-CLIs nutzen (Codex, Cursor, Sourcegraph), wechseln Sie zu AGENTS.md und symlinken CLAUDE.md darauf: ln -s AGENTS.md CLAUDE.md. Die meisten modernen Agent-CLIs fallen auf AGENTS.md zurück, sodass eine Datei alle Tools bedient.

Soll ich /init nutzen, um CLAUDE.md zu generieren?

Ja — als Entwurf. Nein — als fertige Datei. /init scannt Ihr Repository und produziert einen Startpunkt, aber er ist ausführlich und generisch. Anthropic und HumanLayer empfehlen beide, nach dem Ausführen von /init aggressiv zu kürzen. Die 8 Minuten, die Sie damit verbringen, zu kürzen und "Warum"-Zeilen hinzuzufügen, sind der Punkt, an dem die Datei tatsächlich nützlich wird.

Wie funktionieren CLAUDE.md-Dateien in einem Monorepo?

Die CLAUDE.md im Stamm bleibt winzig — nur Zeiger und gemeinsame Regeln. Jede App bekommt ihre eigene apps/*/CLAUDE.md mit bereichsspezifischen Konventionen. Unterverzeichnisdateien laden lazy — nur wenn Claude Dateien in diesem Teilbaum öffnet — sodass Geschwister voneinander getrennt bleiben. Nutzen Sie @import .claude/rules/style.md, um modulare Regelblöcke zu teilen, ohne sie über Apps hinweg zu duplizieren.

Was ist der Unterschied zwischen CLAUDE.md, Hooks und Skills?

CLAUDE.md ist empfehlender Kontext — Claude liest ihn und befolgt ihn in der Regel. Hooks sind deterministische Aktionen, die immer feuern (Formatierung, Commit-Blockierung). Skills sind gebündelte Fähigkeiten für wiederverwendbare Workflows mit Assets. Nutzen Sie CLAUDE.md für Stilempfehlungen, Hooks für harte Regeln und Skills für mehrstufige Jobs, die Sie projektübergreifend wiederholen.

Wie Techsy das handhabt

Bei Techsy hat jedes Claude Code-Projekt, das wir ausliefern, eine CLAUDE.md unter 150 Zeilen und einen AGENTS.md-Symlink. Wir behandeln die Datei wie Code — versionieren sie, prüfen Änderungen in Pull Requests und testen in frischen Sitzungen vor dem Merge. Benötigen Sie Hilfe dabei, KI-Agenten in Ihren Entwicklungs-Workflow zu integrieren? Kostenlose Beratung anfragen.