Claude Code Rules Directory

Problem: Eine einzige CLAUDE.md macht zu viel. Darin stecken React-Hinweise neben API-Konventionen neben deinen Testing-Regeln, und jede Session lädt das komplette Ding, selbst wenn du gerade eine Migration bearbeitest.

Quick Win: Leg deine erste gezielte Regel-Datei an:

mkdir -p .claude/rules
echo "# Testing Rules
- Run tests before committing
- Mock external services in unit tests" > .claude/rules/testing.md

Claude nimmt diese Regel beim Session-Start auf, direkt neben CLAUDE.md, und die beiden Bereiche sind sauber getrennt.

Was ist das Rules Directory?

Ab Claude Code v2.0.64 hast du eine weitere Option für die Organisation deiner Anweisungen: das .claude/rules/-Verzeichnis. Statt einer überfüllten Memory-Datei legst du einfach mehrere Markdown-Dateien dort ab, und Claude lädt jede einzelne beim Session-Start ins Projektgedächtnis.

Wichtiges Detail von Anthropic: Dateien in .claude/rules/ laden mit derselben hohen Priorität wie CLAUDE.md. Das spielt eine Rolle, weil Claude's Kontextfenster nicht flach ist. Verschiedene Quellen haben unterschiedliches Gewicht bei der Generierung.

Kein Konfigurationsschritt nötig. Jede .md-Datei unter .claude/rules/ wird automatisch Teil des Projektkontexts.

.claude/rules/
├── code-style.md      # Formatting and conventions
├── testing.md         # Test requirements
├── security.md        # Security checklist
└── frontend/
    ├── react.md       # React-specific patterns
    └── styles.md      # CSS conventions

Trennung der Zuständigkeiten, aber auf der Ebene der Anweisungen. Bearbeite deine Sicherheitsregeln, ohne die Styling-Datei anzufassen, oder umgekehrt.

Pfadbezogene Regeln: Das Power-Feature

Hier zeigt das Verzeichnis seinen wahren Wert. Eine Regel-Datei kann über YAML-Frontmatter auf bestimmte Dateimuster zielen:

---
paths: src/api/**/*.ts
---
 
# API Development Rules
 
- All endpoints must validate input with Zod
- Return consistent error shapes: { error: string, code: number }
- Log all requests with correlation IDs

Die Regel wird nur aktiv, wenn Claude Dateien bearbeitet, die auf src/api/**/\*.ts passen. Bearbeitest du eine React-Komponente, bleiben diese API-Hinweise stumm.

Mehrere Pfadmuster

Eine Datei kann mehrere Muster gleichzeitig überwachen:

---
paths:
  - src/components/**/*.tsx
  - src/hooks/**/*.ts
---
 
# React Development Rules
 
- Use functional components exclusively
- Extract logic into custom hooks
- Memoize expensive computations

Häufige Pfadmuster

Warum Priorität wichtig ist: Das Problem der monolithischen CLAUDE.md

Nicht jeder Token in Claude's Kontext hat dasselbe Gewicht. Quellen werden eingestuft, und Anthropic ist klar: CLAUDE.md und Rules-Dateien sitzen auf hoher Priorität. Claude behandelt beide als maßgebliche Anweisungen.

Das hat eine Falle erzeugt. Alles in eine riesige CLAUDE.md zu stopfen bedeutete, dass all das erhöhte Behandlung bekam. API-Muster konkurrierten um Aufmerksamkeit mit React-Mustern, selbst wenn die Aufgabe eine Datenbankmigrierung war.

Überall hohe Priorität = nirgends Priorität.

Alles als wichtig markieren und Claude kann nicht mehr erkennen, was gerade wirklich relevant ist. Anweisungen verlieren den Fokus, der Kontext wird rauschig, und das Verhalten wird unvorhersehbar.

Die Kontextprioritätshierarchie

Ein schneller Überblick, wie Claude jede Quelle gewichtet:

Das Rules Directory löst das Monolith-Problem, indem es hochpriorisierte Anweisungen auf eng begrenzte Dateien verteilt. API-Regeln bleiben hochpriorisiert, aber nur während Claude in API-Dateien arbeitet.

Pfad-Targeting = Prioritäts-Scoping

Eine Regel mit einem paths:-Eintrag lädt, und bekommt erhöhte Aufmerksamkeit, nur wenn Claude an passenden Dateien arbeitet:

---
paths: src/api/**/*.ts
---
 
# These instructions get high priority ONLY during API work

Das ist die eigentliche Erkenntnis. Du sortierst Dinge nicht nur ordentlich ab. Du bestimmst, wann Anweisungen extra Gewicht bekommen.

Rules vs CLAUDE.md vs Skills

Welche Aufgabe übernimmt welche?

CLAUDE.md enthält, was überall gilt: Routing-Logik, Qualitätsstandards, Koordinationsprotokolle. Halte sie kurz. Jede Zeile hier kämpft um dasselbe hochpriorisierte Budget.

Rules enthalten, was für einen Bereich gilt: API-Regeln für API-Dateien, Test-Regeln für Test-Dateien. Pfad-Targeting hält diese hohe Priorität auf den richtigen Moment begrenzt.

Skills enthalten, was über Projekte hinweg gilt: Deploy-Playbooks, Review-Checklisten, Brand-Guides. Sie bleiben still auf niedrigerer Priorität, bis etwas sie auslöst.

Praktische Beispiele

Sicherheitsregeln für sensible Verzeichnisse

---
paths:
  - src/auth/**/*
  - src/payments/**/*
---
 
# Security-Critical Code Rules
 
- Never log sensitive data (passwords, tokens, card numbers)
- Validate all inputs at function boundaries
- Use parameterized queries exclusively
- Require explicit authorization checks before data access

Test-Datei-Standards

---
paths: **/*.test.ts
---
 
# Test Writing Standards
 
- Use descriptive test names: "should [action] when [condition]"
- One assertion per test when possible
- Mock external dependencies, never real APIs
- Include edge cases: empty inputs, null values, boundaries

Datenbank-Migrations-Regeln

---
paths: prisma/migrations/**/*
---
 
# Migration Safety Rules
 
- Always include rollback instructions
- Test migrations on a copy of production data first
- Never delete columns in the same migration that removes code using them
- Add columns as nullable first, populate, then add constraints

Migration von der monolithischen CLAUDE.md

Eine aufgeblähte CLAUDE.md ist meist das Symptom von Prioritätssättigung. Alles ist als wichtig markiert, also nichts davon. Die Lösung: domänenspezifische Abschnitte herauslösen und jeweils in eine pfadbezogene Regel überführen.

Vorher (eine einzige 400-zeilige CLAUDE.md):

# Project Context
 
...
 
## API Guidelines
 
- Validate inputs with Zod
- Return consistent errors
  ...
 
## React Patterns
 
- Use functional components
- Extract hooks
  ...
 
## Testing Rules
 
- Mock external services
  ...

Nachher (schlanke CLAUDE.md + modulare Rules):

# CLAUDE.md - Operational Core Only
 
## Routing Logic
 
- Simple tasks: execute directly
- Complex tasks: delegate to sub-agents
 
## Quality Standards
 
- Correctness > Maintainability > Performance

.claude/rules/
├── api-guidelines.md      # API section with paths: src/api/**/*
├── react-patterns.md      # React section with paths: src/components/**/*
└── testing-rules.md       # Testing section with paths: **/*.test.*

CLAUDE.md behält ihren Fokus auf die Betriebsweise. Domänenwissen wandert in gezielte Regeln, die nur dann hohe Priorität bekommen, wenn die aktiven Dateien passen.

Prioritätssättigung ist das eigentliche Problem, das du löst. Zentrale Betriebsanweisungen sind immer aktiv. Domänenregeln erheben ihre Stimme nur, wenn Claude Dateien in ihrem Bereich bearbeitet. Überall sonst: Stille.

User-Level Rules: Persönliche Standards über alle Projekte hinweg

Projektregeln sind nicht die einzige Ebene. Persönliche Regeln, die dich in jedes Projekt begleiten, leben unter ~/.claude/rules/:

~/.claude/rules/
├── preferences.md     # Your personal coding preferences
├── workflows.md       # Your preferred workflows
└── shortcuts.md       # Custom patterns you always want

User-Regeln laden zuerst, dann kommen Projektregeln obendrauf. Deine persönlichen Standards reisen also mit dir mit, aber jedes Projekt kann sie bei Bedarf überschreiben.

Nützlich für alles, das widerspiegelt, wie du arbeitest: Einrückungsstil, Commit-Message-Format, bevorzugte Test-Muster, kleine Gewohnheiten, die du unabhängig vom Codebase immer dabei haben willst.

Brace Expansion in Pfadmustern

Pfadmuster unterstützen Brace Expansion, sodass ein Eintrag mehrere Erweiterungen oder Verzeichnisse auf einmal abdecken kann:

---
paths:
  - "src/**/*.{ts,tsx}"
  - "{src,lib}/**/*.ts"
---
 
# TypeScript/React Rules
 
- Use strict TypeScript
- Prefer interfaces over type aliases for public APIs

{ts,tsx} erfasst sowohl .ts als auch .tsx. {src,lib} deckt sowohl src/ als auch lib/ ab. Dein Frontmatter bleibt kompakt, wenn eine Regel verwandte Dateitypen oder Ordner umfasst.

Symlinks: Regeln über Projekte teilen

Symlinks funktionieren in .claude/rules/, was es dir erlaubt, eine kanonische Regelquelle zu pflegen und sie über Repositories hinweg zu teilen:

# Symlink a shared rules directory
ln -s ~/shared-claude-rules .claude/rules/shared
 
# Symlink individual rule files
ln -s ~/company-standards/security.md .claude/rules/security.md

Verlinkte Dateien werden genauso aufgelöst und geladen wie lokale. Zirkuläre Symlinks werden erkannt und behandelt, ein Endlos-Loop ist also kein Problem.

Gut geeignet für Teams, die Coding-Standards über Projekte hinweg teilen. Die kanonische Regeln-Repo an einem Ort halten und in jedes Projekt damit verlinken.

Rekursive Unterverzeichnis-Erkennung

Unterverzeichnisse sind erlaubt. Jede .md-Datei im Baum wird gefunden:

.claude/rules/
├── frontend/
│   ├── react.md
│   └── styles.md
├── backend/
│   ├── api.md
│   └── database.md
└── general.md

Verschachtelt oder flach, der Loader durchsucht das gesamte Verzeichnis. Gruppiere verwandte Dateien nach Belieben, ohne an Übersichtlichkeit einzubüßen.

Best Practices

Halte Regeln fokussiert: ein Thema pro Datei. Sicherheit an einem Ort, Styling an einem anderen.

Verwende aussagekräftige Dateinamen: api-validation.md bringt mehr als rules1.md.

Nutze Pfad-Targeting konsequent: Regeln ohne paths: laden überall. Füge ein Muster hinzu, sobald eine Regel in unverwandte Bereiche einzudringen beginnt.

Alles versionieren: Regeln sind Code. Review sie in PRs, verfolge die Historie, mache rückgängig, was schiefläuft.

Regel-Zweck dokumentieren: Öffne jede Datei mit einer Zeile, die erklärt, wann sie gelten soll.

Nächste Schritte

1. Deine CLAUDE.md prüfen: Markiere Abschnitte, die wirklich nur für bestimmte Dateitypen gelten
2. Eine Regel extrahieren: Hebe deinen domänenspezifischsten Block in .claude/rules/ heraus
3. Pfad-Targeting hinzufügen: Zeige diese Regel auf die Dateien, denen sie tatsächlich dient
4. Iterieren: Wann immer Claude Kontext lädt, den du nicht brauchst, extrahiere eine weitere Regel

Für die umfassendere Memory-Architektur und warum eine riesige Datei Probleme macht, lies CLAUDE.md Mastery. Wie Priorität in eine breitere Kontextstrategie passt, erfährst du bei Context Management und Memory Optimization.

Merke dir: Das Ziel ist, Claude genau die hochprioritären Anweisungen zu geben, die zu den aktuell offenen Dateien passen. Nicht mehr. Aufmerksamkeit wo sie zählt, Stille überall sonst. Kombiniere das mit einer Skills-Architektur, die Domänenwissen auf Abruf lädt, und dein Kontextfenster bleibt schlank, während deine Anweisungen ihr Gewicht behalten.