Hierarchie & Regeln

Wissen

Die 4-Ebenen-Hierarchie im Detail

Claude Code lädt CLAUDE.md-Dateien aus vier verschiedenen Orten. Die Grundregel ist einfach: Spezifischer gewinnt. Wenn eine globale Regel sagt "Nutze Tabs" und eine Projekt-Regel sagt "Nutze Spaces", dann gelten Spaces -- genau wie bei CSS-Spezifität.

Ebene 1: Global (~/.claude/CLAUDE.md)

Diese Datei gilt für alle deine Projekte. Hier gehören Dinge rein, die du immer willst -- unabhängig davon, an welchem Projekt du arbeitest.

# Globale Regeln

- Antworte auf Deutsch, wenn ich Deutsch schreibe
- Nutze immer TypeScript statt JavaScript
- Bevorzuge funktionale Programmierung
- Commit-Messages auf Englisch im Conventional-Commits-Format

Ebene 2: Projekt-Root (./CLAUDE.md)

Die wichtigste Ebene. Diese Datei liegt im Root deines Repositories und wird über Git mit dem Team geteilt. Hier stehen projektspezifische Regeln, die für alle Teammitglieder gelten.

# Projekt: Meine App

## Befehle
npm run dev          # Entwicklungsserver
npm run test         # Tests mit Vitest
npm run lint         # ESLint

## Architektur
- App Router mit [locale] Segment
- Zustand für State Management
- Tailwind CSS 4 für Styling

Ebene 3: Projekt-Config (./.claude/CLAUDE.md)

Diese Datei liegt im .claude/-Verzeichnis deines Projekts, das normalerweise in .gitignore steht. Sie ist user-spezifisch -- hier kannst du persönliche Präferenzen festlegen, die das Team nicht betreffen.

# Meine persönlichen Regeln für dieses Projekt

- Ich bevorzuge ausführliche Erklärungen in Kommentaren
- Zeige mir immer die Diffs vor einem Commit
- Nutze Vim-Keybindings in Code-Beispielen

Ebene 4: Unterverzeichnis (subdir/CLAUDE.md)

Claude lädt diese Dateien on-demand, wenn es in einem Unterverzeichnis arbeitet. Perfekt für Monorepos oder Projekte mit unterschiedlichen Bereichen.

# src/api/CLAUDE.md

- Alle API-Routen nutzen Zod für Validierung
- Fehler-Responses folgen dem RFC 7807 Format
- Rate Limiting ist Pflicht für öffentliche Endpunkte

Verstehen

Enterprise: Managed Policies

In Unternehmensumgebungen gibt es eine zusätzliche Ebene: Managed Policies. Administratoren können unter /Library/Application Support/ClaudeCode/policies/CLAUDE.md (macOS) organisationsweite Regeln definieren, die nicht überschrieben werden können.

# Managed Policy (von der IT-Abteilung)

- Keine API-Keys im Code
- Alle externen Abhängigkeiten müssen aus dem Firmen-Registry kommen
- Keine Ausführung von rm -rf Befehlen

Diese Policies werden von Claude Code als unveränderliche Regeln behandelt -- sie haben die höchste Priorität und können von keiner anderen CLAUDE.md überschrieben werden.

Die @-Import-Syntax

Du kannst andere Dateien in deine CLAUDE.md importieren, um sie modular zu halten:

# CLAUDE.md

@docs/coding-standards.md
@.cursor/rules/api-conventions.md
@scripts/README.md

Jeder @-Import muss auf einer eigenen Zeile stehen. Claude löst diese Referenzen rekursiv auf, allerdings mit einem Maximum von 5 Verschachtelungsebenen, um Endlosschleifen zu vermeiden.

Lazy-loaded Regeldateien

Für große Projekte bietet Claude Code .claude/rules/*.md -- Regelfiles, die nur geladen werden, wenn sie relevant sind. Mit YAML-Frontmatter kannst du definieren, für welche Dateipfade eine Regel gilt:

---
paths:
  - "src/api/**/*.ts"
---
# API Conventions

- Nutze express-validator für Input-Validierung
- Alle Endpunkte brauchen JSDoc-Kommentare
- Error-Handler müssen den HTTP-Status loggen

Diese Regeln werden nur in den Kontext geladen, wenn Claude an Dateien arbeitet, die zum paths-Muster passen. Das spart wertvolles Context-Budget.

Technische Details

Überleben bei /compact: Ja. Wenn du /compact ausführst, um den Kontext zu komprimieren, werden alle CLAUDE.md-Dateien danach neu geladen. Deine Regeln gehen also nie verloren.

HTML-Kommentare: Kommentare wie <!-- TODO: Diese Regel aktualisieren --> werden automatisch herausgefiltert und nicht an Claude gesendet. Du kannst sie für interne Notizen nutzen.