Unsere CLAUDE.md hat 162 Zeilen. Was drin ist — und was wir rausgeworfen haben.

Die teuerste Datei in deinem Repo, von der du es nicht wusstest

Wenn du Claude Code verwendest, ist deine CLAUDE.md im Projekt-Root die teuerste einzelne Datei in deinem Repository. Nicht wegen Speicherplatz — weil jedes Byte davon bei jedem Session-Start in den Kontext geladen wird, ohne Lazy Loading. Skills laden progressiv. MCP-Tools können verzögert werden. CLAUDE.md sitzt einfach da, immer geladen, belastet immer dein Fenster.

Unsere war 820 Zeilen. Wir haben sie auf 162 gestrippt, ohne eine einzige Leitplanke zu verlieren. Dieser Post ist genau das, was rausgekommen ist, was geblieben ist und die drei Muster, die die Arbeit gemacht haben.

Kernzahlen: 820 → 162 Zeilen, ~8.000 → ~1.200 Tokens und ein ~12 % → ~0,75 % Anteil am 200K-Kontextfenster.

Warum CLAUDE.md einen eigenen Post verdient

In unserem ausführlicheren Token-Optimierungsartikel war MCP Tool Search der größte Hebel. CLAUDE.md ist der zweite. Forschung zu großen Claude-Code-Frameworks berichtet, dass optimierte Root-Configs eine 54–62 % Reduktion des Baseline-Overheads erreichen, und ein dokumentiertes Anti-Pattern — eine 2.800-Zeilen-CLAUDE.md — verschwendete pro Session etwa 62 % der Tokens.

Der Mechanismus ist der Grund. CLAUDE.md-Inhalte auf jeder Ebene der Hierarchie laden bedingungslos:

Enterprise-Policy-Dateien
Projekt-Root-CLAUDE.md
User-Level-~/.claude/CLAUDE.md
Projektlokale Overrides
Jede via @path/to/file-Syntax importierte Datei (rekursiv bis zu 5 Ebenen tief)

Alles andere, was Claude Code rund um Kontext macht — progressives Skill-Loading, MCP Tool Search, Subagent-Isolation — ist darauf ausgelegt, der immer-geladenen Steuer auszuweichen. CLAUDE.md ist das eine Ding, für das du bedingungslos zahlst, bei jedem einzelnen Turn.

Unser Vorher: 820 Zeilen, etwa 12 % des Kontexts

Unsere originale CLAUDE.md las sich wie ein Unternehmenshandbuch. Sie dokumentierte jeden Skill, den wir verwendeten, jeden Release-Gate-Schritt, jede Nuance unserer WordPress-Coding-Standards-Konfiguration, jede Namenskonvention für React-Komponenten, jede Admin-Asset-Scoping-Regel. Das war wirklich nützliches Referenzmaterial. Es wurde auch in jede Session geladen, einschließlich Sessions, die mit dem meisten davon nichts zu tun hatten.

Hier ist eine grobe Aufstellung, was drin war:

Abschnitt	Zeilen	Approx. Tokens	Ladefrequenz gerechtfertigt?
Workspace-Map und Projektstruktur	90	900	Ja — Kontext für jede Session
Architektur und Tech-Stack	60	600	Ja
Datenschutzregeln (unveränderlich)	40	400	Ja — kritische Invarianten
Pro-Skill-Beschreibungen (30+ Einträge)	180	1.800	Nein — einzelne Skills laden on demand
Pro-Workflow-Protokolle (detailliert)	200	2.000	Nein — nur während dieses Workflows benötigt
Testing-Standards im Detail	120	1.200	Nein — nur für Test-schreib-Sessions relevant
Release-Gate-Walkthrough	80	800	Nein — lebt im Release-Skill
Troubleshooting-Notizen	50	500	Nein — selten benötigt

Alles mit „Nein” markierte zahlte bei jeder Session Steuer, um für einen Bruchteil davon verfügbar zu sein. Das sind etwa 6.300 Tokens Verschwendung — etwa 3 % des gesamten Kontextfensters, dauerhaft.

Unser Nachher: 162 Zeilen, etwa 0,75 %

Die neue CLAUDE.md deckt dieselbe Oberfläche mit drei Mustern ab: einer Trigger-Tabelle, verschachtelten CLAUDE.md-Dateien und pfad-beschränkten Regeln.

Muster 1: Die Skill-Trigger-Tabelle

Anstatt jeden Skill mit einem Absatz zu dokumentieren, haben wir ~30 Pro-Skill-Beschreibungen durch eine einzelne Lookup-Tabelle ersetzt:

## Skill triggers
| Trigger keywords | Skill | Domain |
|------------------|-------|--------|
| sprint, backlog, iteration | pm-sprint-plan | PM |
| story, acceptance criteria | pm-story-write | PM |
| deploy, release, ship | statnive-release | Dev |
| security, audit, CVE | sec-audit-remediate | Security |
| wireframe, mockup | ux-design | UX |
| benchmark, performance | wp-performance | WP |

Forschung zu großen Frameworks berichtet, dass dieses Muster ~800 Tokens vs. 3.000+ für ausführliche Pro-Skill-Prosa kostet. Claudes Routing funktioniert weiterhin korrekt, weil die Trigger-Keywords das sind, wogegen es tatsächlich matched — die Langform-Prosa „wann man diesen Skill verwendet und wann nicht”, die wir früher schrieben, hat das Routing nie geholfen, sie hat nur den Kontext gefüllt.

Alle detaillierten „wann zu verwenden / wann nicht”-Inhalte leben in den einzelnen SKILL.md-Dateien, die nur geladen werden, wenn Claude zu ihnen routet. Die Trigger-Tabelle ist der Index; die Skills sind die Kapitel.

Muster 2: Verschachtelte CLAUDE.md-Dateien für Domain-Regeln

Hier ist die kritische Eigenschaft, die die meisten Entwickler verpassen: verschachtelte CLAUDE.md-Dateien in Unterverzeichnissen werden lazy geladen. Sie treten in den Kontext nur dann ein, wenn Claude Dateien in diesen Subtrees liest.

Unser Repo-Layout sieht jetzt so aus:

statnive-workflow/
├── CLAUDE.md                    # 162 Zeilen — nur global
├── statnive/
│   ├── CLAUDE.md                # PHP / WordPress Plugin Konventionen
│   ├── src/
│   └── tests/
├── statnive-website/
│   └── CLAUDE.md                # Astro / MDX / Frontend-Konventionen
└── jaan-to/
    └── CLAUDE.md                # AI-Framework-Konventionen

Wenn wir PHP für das Plugin schreiben, lädt statnive/CLAUDE.md automatisch und bringt unsere WordPress-Coding-Standards-Notizen, die $wpdb->prepare()-Durchsetzungsregel und die Admin-Asset-Scoping-Regel mit. Wenn wir MDX-Blog-Inhalte schreiben, lädt statnive-website/CLAUDE.md mit Astro-Konventionen und House-Style-Notizen. Keines interferiert mit dem anderen.

Dieses Muster hat etwa 2.200 Tokens „nur manchmal relevanter” Inhalte aus dem Root entfernt.

Muster 3: Pfad-beschränkte Regeln in `.claude/rules/`

Der dritte Mechanismus ist .claude/rules/ — Regel-Dateien mit YAML-Frontmatter, die deklarieren können, für welche Pfade sie gelten:

---
paths: ["statnive-website/src/**/*.tsx", "statnive-website/src/**/*.astro"]
---
Use Tailwind utilities scoped under `#statnive-app`. Never import the default
Tailwind bundle — it restyles the WordPress admin chrome.

Regeln mit einem paths:-Feld laden bedingt — nur wenn Claude mit passenden Dateien arbeitet. Regeln ohne ein paths:-Feld laden bedingungslos, also halten wir sie auf eine kleine Handvoll beschränkt (Datenschutzregeln, Sicherheitsregeln, Commit-Konventionen).

Wir haben etwa 1.800 Tokens Framework-spezifischer Konventionen aus der Root-CLAUDE.md in pfad-beschränkte Regeln unter .claude/rules/ verschoben. Sie feuern weiterhin zuverlässig, wenn sie relevant sind, und kosten nichts, wenn sie es nicht sind.

Das Anti-Pattern, das wir entfernt haben: `@-Imports`

Unsere originale CLAUDE.md hatte drei @-Imports:

@jaan-to/docs/best-practices.md
@jaan-to/context/tech.md
@jaan-to/outputs/ROADMAP.md

Das sieht ordentlich aus. Es ist eine Falle. Die @-Syntax lädt rekursiv den vollen Inhalt jeder Zieldatei bei jeder Session, bis zu fünf Ebenen tief. Unsere drei Imports allein haben etwa 6.000 Tokens dauerhaften Overhead für Inhalte hinzugefügt, die das Modell vielleicht bei einer von zwanzig Sessions brauchte.

Wir haben jede durch einen Pointer ersetzt:

For architectural context see `jaan-to/context/tech.md`.
For the current roadmap see `jaan-to/outputs/ROADMAP.md`.

Claude liest diese Pfade, wenn es sie tatsächlich braucht — via Read-Tool, on demand. Null Baseline-Kosten, dasselbe praktische Ergebnis.

Was noch in der Root-Datei lebt

Nach den Kürzungen enthält die 162-Zeilen-Root-CLAUDE.md genau:

Abschnitt	Zeilen	Warum es geblieben ist
Produktphilosophie (8 Prinzipien aus der Forschung)	28	Prägt jede Entscheidung; muss alle Sessions beeinflussen
Workspace-Map	18	Auf-einen-Blick-Orientierung, für jede Session geladen
Datenschutzregeln (unveränderlich)	16	Kritische Invarianten — Cookies, rohe IPs, Salts, SHA-256
Admin-Asset-Scoping-Regel	22	Hat uns schon gebissen, gilt breit
Commit-Policy (co-authored-by-Trailer ist verboten)	8	Globale Git-Konvention
`/simplify`-Workflow-Regel	18	Durchsetzung unseres Qualitäts-Gates
Skill-Trigger-Tabelle	32	Ersetzt ~30 ausführliche Pro-Skill-Abschnitte
Schlüsselpfade (Pointer, keine Imports)	20	Ein-Zeilen-Referenzen zu Docs

Alles andere ist entweder in verschachtelte CLAUDE.md, pfad-beschränkte Regeln oder individuelle Skill-Bodies ausgewandert.

Was wir nicht optimiert haben

Ehrliche Vorbehalte, gleiches Muster wie der Rest der Serie:

User-Level ~/.claude/CLAUDE.md liegt außerhalb unserer Kontrolle. Unsere Entwickler haben jeweils ihre eigene globale Konfiguration, und diese laden zusätzlich zur Projektdatei. Forschung nennt das als häufige Quelle versteckten Overheads — eine globale CLAUDE.md mit „denk daran, vor Commits Tests zu laufen” auf top eines Projekt-Level-Workflows, der genau das tut, kostet Tokens ohne Signal hinzuzufügen. Wir haben Teammitglieder gebeten, ihre zu prüfen. Deiner ist wahrscheinlich einen Blick wert.
Wir haben noch kein CI-Gate für die Root-CLAUDE.md-Größe. Forschung schlägt vor, den PR scheitern zu lassen, wenn Root-CLAUDE.md + alle @-Imports ~2.500 Tokens überschreiten. Wir erzwingen mit /context-Spot-Checks. Ein CI-Gate steht auf dem Roadmap.
IMPORTANT- und YOU MUST-Marker sind verlockend. Anthropic lässt intern CLAUDE.md-Dateien durch seinen Prompt-Improver laufen und verwendet Betonungsmarker für kritische Regeln. Wir verwenden sie sparsam — jeder ist dauerhafter Overhead, also reservieren wir sie für die Datenschutzregeln (keine Cookies, keine rohen IPs) und die Commit-Policy (kein Co-authored-by-Trailer).

Der Messschritt, den du nicht überspringen kannst

Wenn du deine eigene CLAUDE.md prüfst, ist der eine Befehl, der zählt, /context. Führe ihn ganz am Anfang einer frischen Session aus, vor jeglichen Prompts. Er schlüsselt deine Kontextnutzung nach Quelle auf: System-Prompt, Tools, Memory (das ist CLAUDE.md), Skills-Metadata und MCP-Tool-Schemas.

Zahlen, die wir für eine 200K-Fenster-Session anstreben:

Quelle	Ziel	Hard Cap
Root CLAUDE.md + unscoped rules	≤ 1.500 Tokens	2.500
Skill metadata	≤ 2.500 Tokens	5.000
MCP tool schemas (mit Tool Search)	≤ 3.000 Tokens	8.000
Hook stdout (SessionStart, UserPromptSubmit)	0 Tokens	300 pro Hook

Wenn dein /context eines davon um mehr als ~50 % überschreitet, hast du dasselbe Problem wie wir. Die Fixes sind die drei Muster oben plus MCP Tool Search.

Warum das für die Leute wichtig ist, die Statnive betreiben

Unsere CLAUDE.md ist öffentlich im Statnive-Repo auf GitHub — aus demselben Grund, aus dem unsere Test-Pipeline öffentlich ist. Eine schlanke Root-Konfiguration bedeutet schnellere Sessions, günstigere Runs und ein Modell, das tatsächlich liest, was wichtig ist, anstatt in „immer verfügbarem, selten benötigtem” Referenzmaterial zu ertrinken. Diese Effizienz summiert sich zu demselben, was unsere Benutzer interessiert: ein Plugin, das häufig ausgeliefert wird und unter seinem 5-KB-Tracker-Budget bleibt.

Statnive ausprobieren

Datenschutzfreundliche WordPress-Analytics, entwickelt von einem Team, das Token-Budgets genauso ernst nimmt wie Performance-Budgets. Statnive kostenlos von WordPress.org installieren — deine Daten bleiben auf deinem Server, unsere Engineering-Praktiken bleiben auf GitHub für jeden zum Prüfen.