CLAUDE.md und .claude/rules: Architektur-Kontext schneiden

Jede neue Session beginnt gleich: Der Agent liest Ordner, greppt nach Service-Namen, rät, wie die Teile zusammenhängen, und rät oft daneben. Bevor die eigentliche Aufgabe anfängt, korrigierst du ihn. In einer Diskussion auf Reddit beschreiben mehrere Entwickler genau diesen Cold Start und kommen zum selben Schluss: Kein Prompt-Trick hat so viel gebracht wie aufgeschriebenes Architektur-Wissen. Die spannende Frage ist nicht, ob, sondern wie du es schneidest. Eine große Datei, viele kleine oder gar keine? Claude Code gibt dir dafür mehrere Ladewege, und die Doku (Stand Oktober 2026) ist ziemlich klar, welcher wofür taugt.

Was in die Root-CLAUDE.md gehört und was nicht

Die Projekt-CLAUDE.md liegt in ./CLAUDE.md oder ./.claude/CLAUDE.md und wird bei jedem Start geladen. Die Doku empfiehlt unter 200 Zeilen pro Datei, weil längere Dateien mehr Kontext kosten und die Treue zu den Anweisungen sinkt. Das deckt sich mit dem Reddit-Thread: Wer eine kompakte Repo-Map pflegt, beschreibt, dass das Explorieren zurückkommt, sobald die Datei über eine Seite wächst.

Rein gehört, was in jeder Session gilt: exakte Build- und Testbefehle, Konventionen, die von Tool-Defaults abweichen, ein paar harte Grenzen wie “Migrations nie von Hand ändern”. Formuliere prüfbar: “API-Handler liegen in src/api/handlers/” statt “Dateien ordentlich halten”.

Raus gehört, was der Agent aus dem Code selbst ableiten kann. Bemerkenswert: Der /doctor-Check schlägt für eine eingecheckte CLAUDE.md genau solche Kürzungen vor, also Verzeichnislayouts, Dependency-Listen und Architektur-Übersichten, und behält Fallstricke, Begründungen und abweichende Konventionen. Architektur-Wissen ist also nicht per se falsch, aber nur der Teil lohnt sich, der nicht im Code steht: wer welche Tabellen besitzt, in welche Richtung Daten fließen, welches Pattern abgelöst ist.

Bereichswissen: .claude/rules/ mit paths

Für alles, was nur einen Teil des Repos betrifft, gibt es .claude/rules/. Jede Markdown-Datei dort ist eine Rule, Unterordner werden rekursiv gefunden. Ohne Frontmatter lädt eine Rule beim Start wie die CLAUDE.md selbst. Mit paths lädt sie erst, wenn Claude eine passende Datei mit Read, Write oder Edit anfasst oder per cat/head liest:

<!-- .claude/rules/billing.md -->
---
paths:
  - "services/billing/**/*"
---

- Billing besitzt die Tabellen invoices und payments. Andere Services lesen nur über die API.
- Nicht mehr verwenden: den alten InvoiceBuilder. Neue Logik gehört in billing/core/.

Drei Details, die man kennen sollte. paths ist das einzige Feld, das Claude Code aus einer Rule liest, alles andere wird still ignoriert. Wenn das YAML nicht parst, lädt die Rule so, als hätte sie kein paths, also immer; den Parse-Fehler zeigt claude --debug. Und Brace Expansion wie src/*.{ts,tsx} funktioniert, hat aber ein Budget von 1.000 expandierten Patterns pro Rule.

Das ist die technische Antwort auf das, was im Thread mehrere Leute beschreiben: viele kleine Dateien pro Bereich plus eine kurze Übersicht. Der Agent zieht nur, was er für die Aufgabe braucht.

Nested CLAUDE.md und @-Imports

Alternativ legst du eine CLAUDE.md direkt in den Service-Ordner. Dateien in Unterordnern lädt Claude Code nicht beim Start, sondern sobald Claude dort eine Datei liest oder bearbeitet. Ein Vorschlag aus dem Thread passt gut dazu: Die Beschreibung liegt neben dem Code, den sie beschreibt, und fällt bei jeder Änderung ins Auge.

Vorsicht bei @path-Imports. Sie strukturieren eine lange CLAUDE.md, sparen aber keinen Kontext, weil importierte Dateien beim Start mitgeladen werden. Relative Pfade gelten relativ zur importierenden Datei, verschachtelt wird bis maximal vier Ebenen. Wer Kontext sparen will, nimmt Rules oder nested Files, nicht Imports.

Gegen Staleness: Fallen statt Ängste

Die ehrlichste Erkenntnis aus der Diskussion: Prosa veraltet schneller als alles andere. Ein Teilnehmer beschreibt, dass sein Abschnitt mit allgemeinen Fallstricken nach kurzer Zeit nutzlos war, weil er Befürchtungen aufgeschrieben hatte statt echter Vorfälle. Seine Regel heute: Nur was tatsächlich eine Session kaputt gemacht hat, kommt rein. Andere setzen auf eine explizite Do-not-use-Liste für abgelöste Patterns oder ein kurzes “zuletzt geprüft”-Datum oben in jeder Datei.

Für solche Wartungsnotizen hat Claude Code ein nützliches Detail: Block-HTML-Kommentare (<!-- ... -->) in CLAUDE.md werden vor der Injektion entfernt. Prüfdatum und Hinweise für Maintainer kosten so keine Tokens. Widersprüche sind das zweite Risiko, denn bei zwei gegensätzlichen Anweisungen wählt Claude laut Doku womöglich willkürlich eine. /doctor prompt-audit (ab v2.1.283) durchsucht CLAUDE.md, Rules, Skills und Subagent-Dateien nach veralteten Anweisungen, nicht existierenden Pfaden und Widersprüchen und schlägt Edits vor, ohne selbst etwas zu ändern.

Und vergiss nicht: CLAUDE.md ist Kontext, keine Durchsetzung. Was zu einem festen Zeitpunkt passieren muss, etwa vor jedem Commit, gehört in einen Hook.

Was das für deinen Workflow bedeutet

Sortiere dein vorhandenes Wissen nach Ladeweg:

1. Root-CLAUDE.md: Befehle, Grenzen, abweichende Konventionen. Unter 200 Zeilen, keine Verzeichnisbäume.
2. .claude/rules/ mit paths oder nested CLAUDE.md: Ownership, Datenfluss und Do-not-use-Liste pro Bereich.
3. HTML-Kommentare für Prüfdatum und Maintainer-Notizen.
4. /context starten und unter Memory files kontrollieren, was wirklich geladen ist. Nach /compact wird nur die Root-CLAUDE.md sofort neu gelesen, der Rest lädt bei Bedarf.
5. Regelmäßig /doctor prompt-audit laufen lassen.

Der Gewinn ist kein magischer Prompt, sondern ein Agent, der am richtigen Ort startet und weniger Kontext mit Raten verbrennt.

Du willst wissen, ob deine CLAUDE.md, Rules und Imports so laden und so geschnitten sind, wie du denkst? Das Agent-Setup-Review prüft sie zusammen mit Settings, Hooks und Subagents und liefert priorisierte Änderungsvorschläge. Setup-Review anfragen.