CLAUDE.md richtig designen: Die 2026 Architektur, die Claude Code endlich funktionieren lässt

Warum fühlt sich Claude Code bei den meisten Entwicklern nutzlos an?

Weil die meisten nur 1 von 4 Layern konfigurieren. Sie laufen /init, bekommen eine generische CLAUDE.md und wundern sich, warum Claude Datei-Strukturen halluziniert, falsche Libraries empfiehlt und den Coding-Stil verfehlt.

Die Wahrheit: CLAUDE.md ist nur die erste von vier Säulen. Das vollständige Setup 2026 umfasst 5 Scopes, das WHAT/WHY/HOW Framework, 7 Kern-Regeln und Advanced Patterns mit Hooks, Skills und Multi-Session-Workflows. Wer das orchestriert, arbeitet mit einem AI-Teammate, der mit der Zeit besser wird. Wer es ignoriert, prompted sich im Kreis.

Dieser Guide spiegelt exakt den Architecture Guide 2026, den ich als Cheat Sheet für Entwickler-Teams zusammengestellt habe. Konkret. Umsetzbar. In einem Nachmittag. Aber wirklich in kurzer Zeit!

Was ist CLAUDE.md eigentlich – und warum ist es keine README?

CLAUDE.md ist das persistente Gedächtnis deines AI-Teammates. Sie wird bei jedem claude-Start geladen und definiert, wie Claude dein Projekt versteht. Eine README dokumentiert für Menschen. CLAUDE.md onboarded deinen AI-Kollegen.

Der Unterschied ist fundamental, und Boris Cherny, Creator von Claude Code und Staff Engineer bei Anthropic, bringt es auf den Punkt:

«CLAUDE.md is not a README for humans. It’s onboarding docs for your AI teammate – and every correction you add is a bug that never happens again.»

– Boris Cherny, Creator of Claude Code · Staff Engineer @ Anthropic

Die Konsequenz: Jede Zeile muss sich ihren Platz verdienen. Boris‘ eigene CLAUDE.md hat laut InfoQ-Interview im Januar 2026 gerade mal 2’500 Tokens (rund 100 Zeilen) – und sein Team shipt damit Claude Code selbst (Quelle: InfoQ, Januar 2026).

Was sind die 5 Scopes von CLAUDE.md?

Claude Code lädt CLAUDE.md-Dateien aus mehreren Pfaden mit klarer Kaskade. Die Regel: Last scope wins on conflicts. Der spezifischste Scope setzt sich durch.

Die Kaskade ist strategisch wichtig. Universelle Regeln gehören in die Root. Modul-spezifisches Wissen in Subverzeichnisse. So werden sie nur geladen, wenn Claude in dem Ordner arbeitet – und sparen Context-Tokens.

Tipp zum Local Secret Scope

Der CLAUDE.local.md-Scope ist 2026 neu und gold wert: Hier kommen deine persönlichen Shortcuts, WIP-Notizen und sensitive Pfade hin, ohne dass sie je in Git landen. Die Datei gehört sofort in .gitignore, sobald du sie anlegst.

Was ist das WHAT/WHY/HOW Framework für CLAUDE.md?

Das WHAT/WHY/HOW Framework zwingt dich zur Vollständigkeit. Wenn du eines der drei weglässt, rät Claude. Und Claude rät falsch. Hier ist die exakte Struktur:

WHAT – Gib Kontext

Ohne diese Basis arbeitet Claude im Blindflug:

• Projektname und Purpose
• Tech Stack mit Versionen (nicht «React», sondern «React 18.3 + TypeScript 5.4 + Vite 5»)
• Repository-Struktur-Map (wo liegen Utils, Types, API-Endpoints?)
• Kritische Dependencies
• Bei Monorepos: was macht jede einzelne App?

WHY – Setze Prinzipien

Die Regeln, die dein Team über Monate etabliert hat:

• Architektur-Entscheidungen mit Begründung
• Code-Style und Lint-Rules
• Naming Conventions
• Anti-Patterns, die du vermeiden willst
• Security-Constraints

HOW – Definiere Workflows

Die operationalen Commands, die bei jeder Session zählen:

• npm run build – Build-Command
• npm test – nach jeder Änderung ausführen
• eslint . --fix – bei jedem Save
• Branch- und Commit-Strategie
• Deploy- und CI/CD-Steps

Konkretes HOW-Beispiel, das sofort funktioniert

## Workflow
- Run `npm test` after every code change
- Always create a new branch per task. NEVER commit to main directly
- Use Conventional Commits (feat:, fix:, refactor:, docs:)
- Run `eslint . --fix` before every commit
- Open a PR via `gh pr create` when work is complete

Wie sieht eine gute CLAUDE.md in der Praxis aus?

Du hast zwei Wege, CLAUDE.md zu erstellen: manuell schreiben oder /init in Claude Code laufen lassen. Keiner von beiden liefert ein produktionsreifes Resultat. /init generiert ein Bare-Bones-Scaffold. Manuell geschrieben fehlt meist die konsistente Struktur.

Die bessere Variante: Starte mit einem Template, das das WHAT/WHY/HOW Framework, die Hooks-Konfiguration und SKILL.md-Templates bereits abbildet. Mein Team hat ein Agentic Coding Meta-Prompt Repository auf GitHub veröffentlicht, das genau das liefert – github.com/obviousworks/agentic-coding-meta-prompt.

Das Repository enthält:

• CLAUDE.md Template (≤200 Zeilen)
• AGENTS.md für Multi-Agent-Workflows
• Hooks-Config in .claude/settings.json
• SKILL.md Templates und Beispiele

Wie schreibst du präzise Instruktionen statt vager Regeln?

Der einzige Unterschied zwischen einer CLAUDE.md, die ignoriert wird, und einer, die funktioniert: Präzision. Vage Instruktionen sind für Claude wie vage Tickets für einen Junior-Entwickler – beide halluzinieren eine Interpretation.

Präzision zwingt dich, deine impliziten Team-Standards zu artikulieren. Das ist wertvoll, auch wenn du Claude nie wieder nutzen würdest.

Was sind die 7 Regeln, die dein CLAUDE.md Setup wirklich funktionieren lassen?

Diese sieben Regeln stammen direkt aus den Claude Code Docs und aus Boris Chernys öffentlich geteiltem Workflow. Sie sind das Fundament:

1. Run /init first. Lass Claude das Baseline aus deiner Codebase scaffolden. Dann kuratieren. Starte nie bei null – du vergisst zu viel.
2. Stay under 200 lines. Zu lang = ignoriert. Claude attendet ~150 Instruktionen zuverlässig. Jede Zeile muss sich verdienen.
3. Hooks for 100% enforcement. CLAUDE.md ist advisory (~70% befolgt). Hooks sind deterministisch. Nutze sie für Lint, Test, Security.
4. Use @imports for modularity. Neu in 2026: Splitte Configs via @docs/git.md. Sauberer, scoped, wiederverwendbar über Projekte.
5. /compact & Plan Mode. Neu in 2026: /compact bei 50% Context-Fill. Plan Mode für jede Task mit 3+ Steps.
6. Update it monthly. CLAUDE.md ist ein Living Document. Jedes Mal, wenn Claude irrt: Regel hinzufügen. Boris nennt das Compound Engineering.
7. Reference, don’t duplicate. Verweise auf package.json und tsconfig. Nicht kopieren. Nutze die @path/to/file Syntax.

Wie funktioniert Compound Engineering mit CLAUDE.md?

Compound Engineering ist der Game Changer. Das Prinzip, das Boris Cherny bei Anthropic etabliert hat: Jede Code-Review, jede Korrektur, jeder Fehler wird zu einer neuen Regel in CLAUDE.md. Die Datei wächst mit der Erfahrung des Teams.

In Anthropic’s Workflow nutzt Boris den @.claude-Tag auf PRs von Kollegen – Claude fügt das Learning automatisch in CLAUDE.md ein (Quelle: Vibe Sparking AI, Januar 2026). Das Resultat nach drei Monaten:

• Claude macht denselben Fehler nie wieder
• Das Team-Know-how wird systematisch kodifiziert
• Neue Team-Mitglieder haben ab Tag 1 Zugriff auf alle Learnings

Das ist kein Hype. Das ist der eigentliche ROI.

Welche Advanced Patterns machen 2026 den Unterschied?

Jenseits der Basics gibt es drei Systeme, die erfahrene Teams trennen von Hobby-Nutzern: Hooks, Skills und Multi-Session. Alle drei sind Teil des Cheat Sheets und sollten bis Ende Q2 2026 in jedem professionellen Setup stehen.

⚡ Das Hooks System

Hooks sind deterministische Callbacks in .claude/settings.json. Wo CLAUDE.md advisory ist (Claude kann sie «vergessen»), sind Hooks zwingend. Exit Code 0 = erlaubt, Exit Code 2 = blockiert. Keine Diskussion.

Die vier wichtigsten Patterns:

• PreToolUse: Route risky Operations zu Opus für Approval – z.B. git push --force
• PostToolUse: Auto-Format Code nach jedem File-Edit (Boris nutzt bun run format)
• Stop Hook: Verifiziert die Arbeit, bevor Claude «done» markiert
• /careful: Blockiert destruktive Commands wie rm -rf

Browse die konfigurierten Hooks jederzeit via /hooks im laufenden Claude Code.

🧠 Das Skills System

Skills sind markdown-basierte Guides in .claude/skills/SKILL.md, die on-demand geladen werden, nicht bei jeder Session. Das ist der entscheidende Unterschied zu CLAUDE.md: Skills schonen deinen Context.

Die Kern-Features:

• Invocation via /skill-name oder automatisch, wenn die Description matcht
• Embed !`command` für Live-Shell-Output in den Prompt
• Transparenter als MCPs – auditable, keine Black Box
• Inklusive Libs, damit Claude komponiert statt from scratch baut

Typische Skills in produktiven Teams: Code-Review-Patterns, Testing-Konventionen, Migration-Guides, BigQuery-Analytics. Boris‘ Team hat einen BigQuery-Skill im Repo und nutzt ihn täglich für Analytics direkt in Claude Code.

🔀 Multi-Session Workflow (Boris’s Method)

Boris Cherny führt bei Anthropic 10 bis 15 Claude-Sessions parallel: 5 lokal in Terminal-Tabs, 5-10 auf claude.ai/code. Plus Sessions, die er morgens vom iPhone startet. Klingt verrückt, ist aber systematisch:

• Jede Session bekommt einen eigenen Git Worktree – Änderungen kollidieren nicht
• /compact bei 50% Context, /clear beim Task-Wechsel
• Plan → Execute → Verify (Tests + Linter + Build, immer)
• Nach jedem Fehler: Fix in tasks/lessons.md kodieren

Der Self-Improvement-Loop ist der wahre Hebel. Jede Korrektur wird zu einer Regel. Nach drei Monaten ersetzt dein CLAUDE.md Monate an Onboarding-Doku.

Was ist der Unterschied zwischen CLAUDE.md und AGENTS.md?

CLAUDE.md ist für Single-Agent-Workflows im primären Claude-Kontext. AGENTS.md ist der neue Standard für Multi-Agent-Workflows und Interoperabilität zwischen Claude, Cursor, Cline und anderen AI-Coding-Tools.

Wenn du Subagents orchestrierst – z.B. einen «Code Simplifier» Subagent nach jedem Feature oder einen «Verify App» Subagent für End-to-End-Tests – gehört die Konfiguration in AGENTS.md. Das macht dein Setup Tool-agnostisch und Team-übergreifend portabel.

Wie viele Zeilen sollte deine CLAUDE.md haben?

Unter 200 Zeilen. Maximal 150 Instructions. Das ist Anthropic’s offizielle Empfehlung und Community-Konsens 2026.

Die Begründung steht in den offiziellen Docs: Bloated CLAUDE.md-Files führen dazu, dass Claude die eigentlichen Instruktionen ignoriert (Quelle: Claude Code Docs, 2026). Wenn Claude eine Regel trotz YOU MUST wiederholt bricht, ist deine Datei zu lang geworden und die Regel geht unter.

Der Test für jede einzelne Zeile: «Würde das Entfernen dieser Zeile Claude Fehler machen lassen?» Wenn nein: löschen. Diese Disziplin ist unangenehm, aber essentiell.

Bei längerem Content nutzt du @imports für Modularität:

# CLAUDE.md (Root)
@docs/architecture.md
@.claude/git-conventions.md
@.claude/security-rules.md

FAQ: Die häufigsten Fragen zu CLAUDE.md

Brauche ich CLAUDE.md in jedem Projekt?

Ja, wenn du Claude Code ernsthaft nutzt. Die 2026 Community-Meinung ist eindeutig: CLAUDE.md ist so wichtig wie .gitignore. Essential Infrastructure, nicht optionale Doku.

Was ist der Unterschied zwischen CLAUDE.md und einer README?

Die README ist für Menschen, die das Projekt starten wollen. CLAUDE.md ist Onboarding-Doku für deinen AI-Teammate. Unterschiedliche Audience, unterschiedliche Struktur, unterschiedliche Länge.

Sollte CLAUDE.md in Git committed werden?

Ja – die projektspezifische ./CLAUDE.md gehört in Git für Team-Konsistenz. Persönliche Notizen und Secrets gehören in ./CLAUDE.local.md, die in .gitignore steht. Die Global-Scope-Datei ~/.claude/CLAUDE.md bleibt sowieso lokal.

Wie oft sollte ich CLAUDE.md updaten?

Mindestens monatlich, idealerweise sofort nach jedem wiederkehrenden Fehler. Boris‘ Faustregel: «Anytime we see Claude do something incorrectly, we add it to CLAUDE.md so it doesn’t repeat next time.» Das ist Compound Engineering in Reinform.

Wie viele Tokens verbraucht eine CLAUDE.md?

Boris Chernys CLAUDE.md bei Anthropic hat rund 2’500 Tokens (~100 Zeilen). Mehr als 5’000 Tokens ist fast immer zu viel – dann fängst du an, Claude’s echten Arbeitskontext zu verdrängen.

Funktioniert CLAUDE.md auch mit Cursor oder Windsurf?

Nicht direkt. Cursor nutzt .cursorrules, Windsurf hat eigenes Format. AGENTS.md ist der aufkommende offene Standard für Tool-übergreifende Konfiguration. Für reinen Claude Code Einsatz bleibt CLAUDE.md die kanonische Datei.

Muss ich Skills manuell befüllen?

Nein. Du kannst Skills explizit via /skill-name aufrufen oder Claude lässt sie automatisch triggern, wenn die Description zum aktuellen Task passt. Community-Skills gibt es auf GitHub für fast jeden Anwendungsfall – von Code-Review bis BigQuery-Analytics.

Was tun, wenn Claude die CLAUDE.md-Regeln trotzdem ignoriert?

Drei mögliche Ursachen in dieser Reihenfolge: (1) Die Datei ist über 200 Zeilen, Claude verliert wichtige Regeln im Noise. Kürzen. (2) Die Regel ist vage formuliert. Präzise machen mit «MUST» oder «NEVER». (3) Die Regel ist wirklich deterministisch kritisch – dann erzwinge sie via Hook in .claude/settings.json.

Dein 48-Stunden Action Plan

Setup-Zeit: ein Nachmittag. Wirkung: Monate.

Tag 1 – Fundament (90 Minuten):

1. Führe /init in deinem Hauptprojekt aus
2. Kürze die generierte CLAUDE.md auf unter 200 Zeilen
3. Strukturiere nach WHAT/WHY/HOW
4. Lege CLAUDE.local.md für persönliche Notizen an, ergänze .gitignore
5. Committe CLAUDE.md in Git

Tag 2 – Advanced Patterns (60 Minuten):

1. Identifiziere 3 wiederkehrende Korrekturen aus der letzten Woche
2. Kodiere sie als präzise Regeln in CLAUDE.md
3. Setup einen ersten PostToolUse-Hook für Auto-Lint
4. Lege einen ersten Skill in .claude/skills/ an (z.B. code-review.md)
5. Teste mit einer echten Task und verifiziere das Verhalten

Nach 30 Tagen – Review: Welche Regeln haben gezündet? Welche werden ignoriert (dann: zu lang, zu vage oder Hook fehlt)? Welche neuen Korrekturen gehören rein?

Das eigentliche Versprechen

Claude Code ist kein Tool. Es ist ein Teammate, der exakt so gut wird, wie du sein Onboarding gestaltest. Die 4 Layer – CLAUDE.md, Skills, Hooks, Subagents – sind dein Hebel. Die 5 Scopes, das WHAT/WHY/HOW Framework und Compound Engineering sind dein Betriebssystem.

Ein Nachmittag Setup. Dann verstehst du, warum Teams, die 2026 bereits umgestellt haben, nicht mehr zurückwollen – und warum die anderen täglich Kontext verlieren, den sie längst hätten kodifizieren können.

Die Frage ist nicht ob du diese Architektur brauchst. Die Frage ist, wie viele Monate du noch ohne sie arbeiten willst.

Matthias ist mit Herz, Seele und Verstand dabei. Er macht dich, dein Team und deine Firma fit für die Zukunft mit KI!

Zu Matthias Trainerprofil
Zu seinem LinkedIn Profil

Quellen

1. Anthropic – Best Practices for Claude Code (Official Docs), 2026
2. InfoQ – Inside the Development Workflow of Claude Code’s Creator, Januar 2026
3. Vibe Sparking AI – Boris Cherny’s Claude Code Workflow Revealed, Januar 2026
4. Pragmatic Engineer – Building Claude Code with Boris Cherny, März 2026
5. Push to Prod – How the Creator of Claude Code Actually Uses Claude Code, Februar 2026
6. Morph Labs – Claude Code Best Practices: The 2026 Guide to 10x Productivity, Februar 2026