Claude Code: Alle Markdown-Dateien zur KI-Ausrichtung im Überblick

Wer Claude Code produktiv einsetzt, merkt schnell: Die Qualität der Ergebnisse hängt weniger am Prompt des Tages als an der dauerhaften Ausrichtung des Werkzeugs. Und diese Ausrichtung lebt in Markdown-Dateien — von der allgegenwärtigen CLAUDE.md über pfad-gebundene Rules bis zum Auto-Memory, das Claude selbst pflegt.

Dieser Beitrag ist eine vollständige Referenz aller .md-Dateien, die Claude Code liest, prüft und in den Kontext lädt. Stand: Juli 2026 (Claude Code v2.1.x), basierend auf der offiziellen Dokumentation unter code.claude.com/docs.

Grundprinzip: Wie Claude Code lädt

Es gibt zwei Scopes:

• Project — im Repo unter .claude/ (bzw. im Root für CLAUDE.md, .mcp.json, .worktreeinclude). Wird per Git geteilt → Team.
• Global — unter ~/.claude/. Gilt über alle Projekte hinweg, wird nie committet. Konkret liegt das Verzeichnis unter macOS in /Users/<name>/.claude, unter Linux in /home/<name>/.claude und unter Windows in %USERPROFILE%\.claude (also C:\Users\<name>\.claude). Mit der Umgebungsvariable CLAUDE_CONFIG_DIR ist es auf allen drei Systemen verschiebbar.

Directory-Walk: Beim Session-Start läuft Claude vom aktuellen Verzeichnis (cwd) den Baum hoch bis / und sammelt jede CLAUDE.md / CLAUDE.local.md ein. Additiv, nicht überschreibend. Dateien in Unterordnern unterhalb von cwd werden nicht beim Start geladen, sondern erst, wenn Claude eine Datei in diesem Unterbaum anfasst.

Konflikt-Regel: Globale und Projekt-CLAUDE.md liegen beide gleichzeitig im Kontext. Bei Widerspruch gewinnt Project — spezifischer schlägt allgemeiner.

Faustregel der Doku: Die meisten Anwender editieren nur CLAUDE.md und settings.json. Der Rest ist optional — nach Bedarf dazunehmen.

Übersicht: Alle MD-Dateien auf einen Blick

Datei	Scope	Commit	Wann geladen	Zweck
CLAUDE.md	Project + Global	✓	Jede Session, komplett	Projekt-Kontext & Konventionen
CLAUDE.local.md	Project (Root)	✗ (gitignore)	Jede Session	Private Präferenzen pro Projekt
.claude/rules/*.md	Project + Global	✓	Start (ohne paths:) / on-demand (mit paths:)	Themen-Regeln, optional pfad-gated
.claude/skills/<name>/SKILL.md	Project + Global	✓	Bei /name oder Auto-Invoke	Wiederverwendbare Prompts/Workflows
.claude/commands/*.md	Project + Global	✓	Bei /name	Single-File Slash-Commands (Alt, → Skills)
.claude/agents/*.md	Project + Global	✓	Bei Delegation / @-Mention	Subagenten mit eigenem Kontext
.claude/output-styles/*.md	Project + Global	✓	Start, wenn via outputStyle gewählt	System-Prompt anpassen
MEMORY.md (+ Topic-Files)	Global (auto)	✗	Erste 200 Zeilen / 25 KB beim Start	Auto-Memory — Claude schreibt selbst
agent-memory/<name>/MEMORY.md	Project + Global	✓/✗	Beim Subagent-Start	Persistentes Subagent-Gedächtnis

Zusätzlich gibt es @-Imports innerhalb von CLAUDE.md (siehe unten).

1. CLAUDE.md — die wichtigste Datei

Was: Projekt-Instruktionen, die jede Session automatisch komplett in den Kontext geladen werden. Kein Pasten, kein Referenzieren nötig — die Datei ist einfach da.

Wann: Start jeder Session, in voller Länge.

Aufsetzen:

• Ziel: unter 200 Zeilen. Längere Dateien laden zwar komplett, aber die Adhärenz sinkt. Produktionserprobte Teams halten die Root-CLAUDE.md eher bei ~60 Zeilen — jede Zeile wird jede Session neu geladen.
• Häufig genutzte Commands hineinschreiben (build/test/lint), damit Claude sie kennt.
• Kein Doku-Dump: CLAUDE.md ist ein Verhaltensvertrag, kein Changelog. Jede Zeile soll das Verhalten ändern — sonst raus.
• Was nur bei bestimmten Tasks relevant ist → in eine Skill oder pfad-gated Rule auslagern.
• Alternativ nutzbar unter .claude/CLAUDE.md, falls der Repo-Root sauber bleiben soll.
• In-Session editieren: /memory.

Beispiel (CLAUDE.md):

# Project conventions

## Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

## Stack
- TypeScript strict mode
- React 19, nur functional components

## Rules
- Named exports, nie default exports
- Tests neben der Source: `foo.ts` -> `foo.test.ts`
- API-Routes geben `{ data, error }`-Shape zurück

Global-Variante (~/.claude/CLAUDE.md): Nur persönliche Defaults, die überall gelten — Antwortstil, Commit-Format, eigene Konventionen. Kurz halten: Sie lädt in jedes Projekt zusätzlich zur Projekt-CLAUDE.md.

2. CLAUDE.local.md — private Projekt-Präferenzen

Was: Wie CLAUDE.md, aber persönlich und nicht committet. Für Workflow-Eigenheiten, die niemanden sonst im Team interessieren.

Aufsetzen:

• Liegt im Projekt-Root, wird manuell angelegt und selbst in .gitignore eingetragen.
• Wird beim Directory-Walk zusammen mit CLAUDE.md eingesammelt.

Layering-Empfehlung: CLAUDE.md (Team/Stack) → CLAUDE.local.md (persönliche Eigenheiten). Das hält beide Dateien kurz und fokussiert, statt alles in eine große Datei zu kippen.

3. .claude/rules/*.md — modulare, pfad-gebundene Regeln

Was: Projekt-Instruktionen, aufgeteilt in Themen-Dateien. Können bedingt nach Dateipfad laden.

Wann:

• Ohne paths:-Frontmatter → Start jeder Session (wie CLAUDE.md).
• Mit paths:-Frontmatter (Globs) → nur wenn Claude eine passende Datei in den Kontext holt.

Aufsetzen:

• Sobald CLAUDE.md an die 200 Zeilen kommt: aufsplitten nach .claude/rules/.
• Unterordner werden automatisch entdeckt: .claude/rules/frontend/react.md funktioniert.
• Wie CLAUDE.md sind Rules Guidance, keine erzwungene Config. Garantiertes Verhalten → Hooks/Permissions.

Beispiel (.claude/rules/testing.md):

---
paths:
  - "**/*.test.ts"
  - "**/*.test.tsx"
---

# Testing Rules
- Deskriptive Test-Namen: "should [expected] when [condition]"
- Externe Dependencies mocken, nicht interne Module
- Side effects in afterEach aufräumen

Hinweis: Es gab (Berichte aus Q4 2025/Q1 2026) einen Parser-Bug, bei dem die YAML-Array-Syntax für paths: still fehlschlagen konnte. Wenn eine pfad-gated Rule nicht greift: mit /memory prüfen, welche Dateien geladen sind, und ggf. die Claude-Code-Version aktualisieren.

Global: ~/.claude/rules/*.md — gleiches Prinzip, gilt überall (z. B. persönlicher Code-Style, Commit-Format).

4. .claude/skills/<name>/SKILL.md — wiederverwendbare Prompts

Was: Jede Skill ist ein Ordner mit SKILL.md plus optionalen Begleitdateien (Referenz-Docs, Templates, Scripts). Aufrufbar per /name — oder Claude invoked sie passend zum Task automatisch.

Wann: Bei /skill-name oder Auto-Invoke.

Aufsetzen (Frontmatter):

• description: → bestimmt, wann Claude die Skill selbst invoked. Sauber formulieren.
• disable-model-invocation: true → nur der User kann triggern (z. B. /deploy).
• user-invocable: false → aus dem /-Menü versteckt, Claude kann aber invoken.
• argument-hint: <...> → UI-Hinweis auf das erwartete Argument.
• Argumente: /deploy staging → staging landet in $ARGUMENTS. Positional: $0, $1, …
• !`shell-command` führt einen Shell-Befehl aus und injiziert die Ausgabe in den Prompt.
• Begleitdateien: Der Skill-Ordnerpfad wird der SKILL.md vorangestellt → Claude kann checklist.md etc. bei Bedarf lesen. Für Scripts in Bash-Injection: Platzhalter ${CLAUDE_SKILL_DIR}.
• Bei Namensgleichheit gewinnt Skill vor Command.

Beispiel (.claude/skills/security-review/SKILL.md):

---
description: Reviewt Code-Changes auf Security-Lücken, Auth-Gaps und Injection
disable-model-invocation: true
argument-hint: <branch-or-path>
---

## Diff to review
!`git diff $ARGUMENTS`

Audit die Changes oben auf:
1. Injection (SQL, XSS, Command)
2. Auth-/Authorization-Gaps
3. Hardcoded Secrets

Nutze checklist.md in diesem Skill-Verzeichnis für die volle Checkliste.
Findings mit Severity + Remediation ausgeben.

Wichtig: Skills sind invocation-only und werden laut Evals nicht 100 % zuverlässig getriggert. Kritische Instruktionen gehören NICHT in Skills — dafür CLAUDE.md oder Rules nutzen.

5. .claude/commands/*.md — Single-File Slash-Commands

Was: Eine Datei commands/deploy.md erzeugt /deploy. Funktional identisch zu Skills, nur ohne eigenen Ordner und Begleitdateien.

Status: Commands und Skills sind derselbe Mechanismus. Für neue Workflows empfiehlt die Doku Skills (gleiche /name-Invocation, plus Bundling). Commands bleiben supported.

Aufsetzen: $ARGUMENTS für Parameter (/fix-issue 123), Positional $0/$1.

Beispiel (.claude/commands/fix-issue.md):

---
argument-hint: <issue-number>
---

!`gh issue view $ARGUMENTS`

Untersuche und fixe das Issue oben.
1. Bug bis zur Root Cause tracen
2. Fix implementieren
3. Tests schreiben/aktualisieren
4. Zusammenfassen, was & warum geändert wurde

6. .claude/agents/*.md — Subagenten

Was: Jede MD-Datei definiert einen Subagenten mit eigenem System-Prompt, eigenem Tool-Zugriff und optional eigenem Modell. Läuft in einem frischen Kontext-Fenster → hält die Hauptsession sauber. Gut für parallele oder isolierte Tasks.

Wann: Claude delegiert selbst, oder Sie @-mentionen den Agenten aus dem Autocomplete.

Aufsetzen (Frontmatter):

• name: — Identifier.
• description: — sagt Claude, wann automatisch delegiert wird.
• tools: — schränkt den Tool-Zugriff ein (z. B. Read, Grep, Glob = read-only).
• memory: — aktiviert persistentes Gedächtnis (siehe Abschnitt 9).
• Der Body wird zum System-Prompt des Subagenten.

Beispiel (.claude/agents/code-reviewer.md):

---
name: code-reviewer
description: Reviewt Code auf Korrektheit, Security und Wartbarkeit
tools: Read, Grep, Glob
---

Rolle: Senior Code Reviewer. Prüfe auf:
1. Korrektheit: Logikfehler, Edge Cases, Null-Handling
2. Security: Injection, Auth-Bypass, Data Exposure
3. Wartbarkeit: Naming, Komplexität, Duplikate

Jedes Finding braucht einen konkreten Fix.

7. .claude/output-styles/*.md — System-Prompt-Stile

Was: Jede MD-Datei definiert einen Output-Style: einen Abschnitt, der an den System-Prompt angehängt wird und — per Default — die eingebauten Software-Engineering-Instruktionen ersetzt. Damit lässt sich Claude Code für Nicht-Coding-Zwecke oder Teaching-/Review-Modi umbauen.

Wann: Start der Session, wenn via outputStyle-Setting oder /config gewählt. Änderungen greifen erst in der nächsten Session — der System-Prompt wird beim Start fürs Caching fixiert.

Aufsetzen:

• Eingebaut: Explanatory, Learning.
• keep-coding-instructions: true im Frontmatter → behält die Default-Task-Instruktionen zusätzlich zu den eigenen Ergänzungen.
• Auswahl über den Dateinamen (ohne .md) oder das name:-Feld.

Beispiel (~/.claude/output-styles/teaching.md):

---
description: Erklärt Reasoning und lässt den User kleine Teile selbst umsetzen
keep-coding-instructions: true
---

Nach jedem Task eine kurze "Warum dieser Ansatz"-Notiz zur zentralen
Design-Entscheidung ergänzen.

Bei Changes unter 10 Zeilen: nicht selbst schreiben, sondern einen
TODO(human)-Marker setzen und den User bitten, es umzusetzen.

8. Auto-Memory: MEMORY.md + Topic-Files

Was: Claude sammelt selbstständig Wissen über Sessions hinweg — Build-Commands, Debugging-Insights, Architektur-Notizen. Diese Dateien schreiben Sie nicht selbst, Claude legt sie an und pflegt sie.

Wo: ~/.claude/projects/<project>/memory/ — pro Repo (bzw. pro cwd außerhalb eines Git-Repos). Ordnername = Pfad mit / → -, also /Users/x/proj/app → -Users-x-proj-app.

Wann geladen:

• MEMORY.md = Index, erste 200 Zeilen / 25 KB beim Session-Start.
• Topic-Files (debugging.md, architecture.md, …) → on-demand, wenn der Task passt.

Steuerung:

• Default an (ausgeliefert mit v2.1.59, 26.02.2026).
• Toggle: /memory oder "autoMemoryEnabled": false in den Settings.
• Deaktivieren per Env: CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.
• Es ist plain Markdown → jederzeit editier- und löschbar.
• Version/Status checken: claude doctor.

Beispiel-Index (MEMORY.md, von Claude geschrieben):

# Memory Index

## Project
- [build-and-test.md](build-and-test.md): npm run build (~45s), Vitest, Dev-Server auf 3001
- [architecture.md](architecture.md): API-Client Singleton, Refresh-Token-Auth

## Reference
- [debugging.md](debugging.md): Auth-Token-Rotation & DB-Connection-Troubleshooting

9. agent-memory/<name>/MEMORY.md — Subagent-Gedächtnis

Was: Subagenten mit memory:-Frontmatter bekommen ein eigenes, vom Haupt-Auto-Memory getrenntes Gedächtnis. Jeder Subagent liest und schreibt seine eigene MEMORY.md.

Scopes (per Frontmatter):

• memory: project → .claude/agent-memory/<name>/ (committet, teamgeteilt).
• memory: local → .claude/agent-memory-local/<name>/ (nicht in Git).
• memory: user → ~/.claude/agent-memory/<name>/ (projektübergreifend).

Wann: Die ersten 200 Zeilen (max. 25 KB) der MEMORY.md werden beim Subagent-Start in dessen System-Prompt geladen. Der Subagent pflegt die Datei selbst.

10. @-Imports in CLAUDE.md

Memory-Dateien können weitere Instruktionen importieren:

Siehe @README für Projekt-Überblick und @package.json für npm-Commands.

## Additional Instructions
- Git-Workflow @docs/git-instructions.md
- Persönliche Prefs @~/.claude/project-preferences.md

• Relative, absolute und Home-Pfade (@~/...) sind erlaubt.
• Importierte Dateien können rekursiv weiter importieren — maximal 5 Hops Tiefe.
• Imports werden nicht innerhalb von Markdown-Code-Spans/-Blöcken ausgewertet.

Empfohlene Projekt-Struktur

your-project/
├── CLAUDE.md                    # Team-Kontext & Konventionen (committet)
├── CLAUDE.local.md              # private Prefs (gitignored)
├── .mcp.json                    # team-geteilte MCP-Server (committet)
├── .worktreeinclude             # gitignored Files für neue Worktrees
└── .claude/
    ├── settings.json            # Permissions/Hooks/Model (committet)
    ├── settings.local.json      # persönliche Overrides (gitignored)
    ├── rules/                   # pfad-gated Themen-Regeln
    │   ├── testing.md
    │   └── api-design.md
    ├── skills/
    │   └── security-review/
    │       ├── SKILL.md
    │       └── checklist.md
    ├── commands/                # Single-File Slash-Commands (Alt)
    ├── agents/
    │   └── code-reviewer.md
    ├── output-styles/
    └── workflows/               # dynamische Workflow-Scripts (*.js)

~/.claude/                       # Global, gilt überall, nie committet
├── CLAUDE.md                    # persönliche Defaults
├── settings.json
├── rules/
├── skills/
├── agents/
├── output-styles/
├── keybindings.json
├── themes/
└── projects/<project>/memory/   # Auto-Memory (Claude schreibt)

Nicht-MD-Config (Kontext)

Diese Dateien sind keine Markdown-Instruktionen, gehören aber zum Ausrichtungs-System:

Datei	Zweck
settings.json / settings.local.json	Permissions, Hooks, Env-Vars, Modell-Default. Erzwungen, nicht nur Guidance.
.mcp.json	Team-geteilte MCP-Server (Projekt-Root).
~/.claude.json	App-State, OAuth, UI-Toggles, persönliche MCP-Server.
.worktreeinclude	Gitignored Files, die in neue Worktrees kopiert werden.
.claude/workflows/*.js	Dynamische Workflows, die viele Subagenten orchestrieren.
keybindings.json, themes/*.json	Tastaturkürzel, Farbthemes.
managed-settings.json	Vom Unternehmen erzwungen, überschreibt alles.

Präzedenz (Settings): Managed Settings > CLI-Flags (--permission-mode etc.) > settings.local.json > Projekt-settings.json > Global-settings.json.

Debugging & Best Practices

• /memory — zeigt geladene Memory-Dateien, öffnet CLAUDE.md zum Editieren. Der erste Reflex, wenn eine Regel ignoriert wird (evtl. steckt sie in einer nested Datei, die noch nicht geladen ist).
• # am Prompt-Anfang — der schnellste Weg, eine Memory hinzuzufügen; Claude fragt, wo gespeichert werden soll.
• Subdir-Rules laden on-demand — sie tauchen in /memory erst auf, nachdem Claude eine Datei im Zielordner gelesen hat.
• CLAUDE.md überlebt /compact vollständig. Für frische Arbeit lieber /clear als /compact.
• Jede CLAUDE.md unter 200 Zeilen halten; alles Selten-Relevante nach rules/ mit paths:-Globs.
• Kritische, nicht-überspringbare Anweisungen NICHT in Skills (unzuverlässiger Auto-Invoke) → CLAUDE.md/Rules.
• ~/.claude/ als eigenes Git-Repo versionieren (beim Teilen vorher prüfen, was gitignored gehört).
• claude doctor — Version & Update-Status prüfen.

Hinweis zu AGENTS.md: Steht nicht in der offiziellen File-Liste von Claude Code und wird nicht nativ geladen. Manche Teams nutzen es als tool-übergreifende „Single Source of Truth” mit Adaptern zu CLAUDE.md, Cursor etc. — das ist ein Workaround, kein natives Feature.

---

Am Ende ist das ganze System ein einziges Prinzip in neun Ausprägungen: Kontext, der immer da sein muss, gehört in CLAUDE.md — Kontext, der nur manchmal relevant ist, gehört in Rules, Skills oder Memory, wo er on-demand lädt. Wer diese Trennung sauber zieht, bekommt ein Werkzeug, das sich jede Session korrekt verhält, ohne dass der Kontext an Doku-Ballast erstickt.