.claude/rules/ mit Frontmatter-Pfaden

Mit zunehmender Größe Ihres Projekts sammelt eine einzelne CLAUDE.md oft Regeln für alles: React-Komponenten, SQL-Migrationen, CI-Skripte und Terraform. Jede dieser Regeln wird bei jeder Sitzung in den Kontext geladen, selbst wenn Sie gerade nur einen Dateityp bearbeiten.

Das verschwendet Tokens und lenkt die Aufmerksamkeit ab. Das Modell berücksichtigt den Anfang und das Ende des Kontexts am stärksten (Lost-in-the-Middle-Effekt). Eine riesige Regeldatei kann daher die Anweisung verbergen, die für die gerade bearbeitete Datei tatsächlich wichtig ist.

.claude/rules/ löst dieses Problem: Teilen Sie Regeln in kleine Dateien auf, die nur beim Bearbeiten passender Dateien geladen werden.

Eine Regeldatei liegt in .claude/rules/ und beginnt mit einem YAML-Block im Frontmatter. Das zentrale Feld ist paths: eine Liste von Glob-Mustern. Der Regeltext wird nur dann in den Kontext eingefügt, wenn die Dateien, an denen Sie arbeiten, einem dieser Muster entsprechen.

Betrachten Sie dies als bedingte, dateibewusste Anweisungen. Gibt es keine Übereinstimmung, bleibt die Regel vollständig außerhalb des Kontexts, sodass das Kontextfenster für die jeweilige Aufgabe schlank bleibt.

Hier sehen Sie eine minimale pfadbezogene Regel. Das Frontmatter wird durch Zeilen mit --- begrenzt; alles danach ist die Anweisung, die das Modell bei einer Übereinstimmung erhält.

Da paths hier auf Testdateien zielt, erscheint diese Vorgabe nur beim Bearbeiten von Tests, nicht beim Bearbeiten von Produktionscode.

Die paths-Globs entsprechen dem Stil, den das Tool Glob von Claude Code verwendet, zum Beispiel **/*.test.tsx. Einige praktische Muster:

• src/api/** — alles unterhalb des API-Verzeichnisses
• **/*.sql — jede SQL-Datei im Repository
• infra/**/*.tf — nur Terraform-Dateien innerhalb von infra

Beschränken Sie den Geltungsbereich eng. Eine Regel, die auf **/* zutrifft, verfehlt den Zweck: Sie ist lediglich Ihre alte monolithische CLAUDE.md mit einem Frontmatter-Hut.

Pfadbezogene Regeln werden zusätzlich zur CLAUDE.md-Hierarchie angewendet:

• Benutzerebene ~/.claude/CLAUDE.md — persönlich, NICHT über die Versionsverwaltung geteilt (neue Teammitglieder sehen sie nicht).
• Projektebene ./CLAUDE.md oder .claude/CLAUDE.md — über die Versionsverwaltung geteilt, immer geladen.
• Verzeichnisebene — auf einen Teilbaum beschränkt.
• .claude/rules/ mit paths im Frontmatter — für jede passende Datei bedingt geladen.

Beschränken Sie CLAUDE.md auf die wenigen Regeln, die universell gelten. Verschieben Sie dateitypspezifische Regeln nach .claude/rules/.

Organisieren Sie Regeln nach Themen, mit einer Datei pro Dateityp oder Fachgebiet. Jede Datei enthält eigene paths, sodass beim Bearbeiten einer Migration Datenbankregeln geladen werden, beim Bearbeiten einer Komponente dagegen React-Regeln — und niemals umgekehrt.

Datenbankregeln sind oft streng und werden leicht vergessen. Wenn Sie sie auf Migrationsdateien beschränken, stehen die Vorgaben genau dann im Kontext, wenn sie relevant sind, und fehlen, wenn Sie UI-Code schreiben.

Zwei Möglichkeiten zur Modularisierung – und sie sind nicht dasselbe:

• @path-Imports innerhalb von CLAUDE.md, z. B. @./standards/coding-style.md, binden diesen Inhalt immer ein. Ideal für gemeinsame Standards, die allgemein gelten.
• .claude/rules/ mit paths-Frontmatter wird bedingt geladen, und zwar nur beim Bearbeiten passender Dateien.

Als Faustregel gilt: Wenn die Anleitung für einen bestimmten Dateityp gilt, schränken Sie sie mit paths ein. Wenn sie überall gilt, ist ein Import (oder CLAUDE.md selbst) geeignet.

Der Vorteil ist zweifach. Erstens: weniger Tokens: Irrelevante Regeltexte gelangen nie in das Kontextfenster, sodass mehr Platz für den eigentlichen Code und die Toolausgabe bleibt. Zweitens: gezieltere Aufmerksamkeit: Die vorhandenen Regeln sind genau diejenigen, die zu Ihren aktuellen Dateien passen. Das Modell muss also nicht Terraform-Konventionen durchgehen, während es einen React-Fehler behebt.

Das ist dieselbe Disziplin wie beim Kürzen ausführlicher Toolausgaben auf relevante Felder – angewendet auf Ihre dauerhaft geltenden Anweisungen.

Da .claude/rules/ im Repository liegt, wird es wie eine projektweite CLAUDE.md über VCS geteilt. Neue Teammitglieder erhalten automatisch dieselben bereichsspezifischen Anleitungen, was bei der benutzerspezifischen ~/.claude/CLAUDE.md NICHT der Fall wäre.

Behandeln Sie Regeldateien wie Code: Prüfen Sie sie und fügen Sie niemals Geheimnisse ein. Wenn eine Regel auf eine Integration verweist, verweisen Sie auf Umgebungsvariablen wie ${GITHUB_TOKEN}, statt ein Token zu committen.

Wenn Sie eine monolithische CLAUDE.md in pfadbezogene Regeln aufteilen:

• Eine Datei pro Dateityp oder Domäne; halten Sie jede Datei fokussiert.
• Gestalten Sie paths-Globs so eng wie den tatsächlichen Gültigkeitsbereich der Regel.
• Lassen Sie nur universelle Fakten in CLAUDE.md; verschieben Sie dateispezifische Regeln nach außen.
• Verwenden Sie @imports für immer geltende gemeinsame Standards und paths für bedingte Regeln.
• Committen Sie die Dateien in VCS, damit das Team dasselbe Verhalten erhält.

Das Ergebnis ist ein Kontextfenster, das sich an die jeweils bearbeitete Datei anpasst.

Die wichtigsten Punkte:

• .claude/rules/*.md mit YAML-Frontmatter und paths lädt eine Regel nur beim Bearbeiten passender Dateien. Dadurch werden im Vergleich zu einer monolithischen CLAUDE.md Kontext und Tokens eingespart.
• paths verwendet Glob-Muster wie **/*.test.tsx oder db/migrations/**/*.sql; beschränken Sie den Gültigkeitsbereich möglichst eng.
• Regeldateien werden über VCS geteilt, anders als die benutzerspezifische ~/.claude/CLAUDE.md.
• Verwenden Sie @imports für immer geltende gemeinsame Standards und paths-Frontmatter für bedingte, dateitypspezifische Regeln.
• Halten Sie CLAUDE.md klein und universell; verschieben Sie dateispezifische Anleitungen für einen anpassungsfähigen, schlanken Kontext nach .claude/rules/.