Was in deinem .claude-Ordner steckt

Dein .claude-Ordner enthält zwei grundsätzlich verschiedene Arten von Dingen: Anweisungen, die zu Beginn jeder Sitzung in Claudes Kontext geladen werden (CLAUDE.md, rules/, skills/, agents/), und Konfiguration, die das Verhalten des Tools steuert (settings.json, Hooks, MCP-Server). Beide Arten verteilen sich auf ein Projektverzeichnis, das du committest, und ein ~/.claude-Verzeichnis in deinem Home-Ordner, das du niemals committest.

Der Ordner neigt außerdem dazu, von selbst zu wachsen. Wenn du eine Berechtigungsabfrage bestätigst, wird eine Datei geschrieben, die du nicht angelegt hast, /init legt eine CLAUDE.md ab, und ein Pull Request kann am Ende eine .claude/settings.local.json voller Allow-Regeln eines einzelnen Entwicklers mitschleppen.

Dies ist eine Tour Datei für Datei: was jeder Pfad tut, welche Datei gewinnt, wenn zwei davon dasselbe setzen, und ein Urteil pro Datei, ob sie ins Repository gehört.

Wo liegen die beiden .claude-Speicherorte?

Claude Code liest zwei .claude-Roots. Einer liegt im Projekt, wandert mit dem Repository mit und ist für das gesamte Team gedacht; der andere, ~/.claude in deinem Home-Ordner, gehört nur dir und begleitet dich in jedes Projekt auf dem Rechner. Diese Trennung ist das Nützlichste, was man verinnerlichen kann. Die Claude Code Directory Reference zieht dieselbe Grenze: Projektdateien committen, die im Home-Ordner dort belassen, wo sie sind. Unter Windows liegt der Home-Root unter %USERPROFILE%\.claude, und wenn du CLAUDE_CONFIG_DIR woanders hin zeigen lässt, verschiebt sich alles davon.

my-project/
├── CLAUDE.md                    # instructions loaded every session
├── CLAUDE.local.md              # private preferences, gitignored
├── .mcp.json                    # team-shared MCP servers
└── .claude/
    ├── settings.json            # permissions, hooks, env, model defaults
    ├── settings.local.json      # your personal overrides, gitignored
    ├── rules/*.md               # topic-scoped instructions, optionally path-gated
    ├── skills/<name>/SKILL.md   # reusable prompts invoked with /name
    ├── commands/*.md            # single-file prompts, same mechanism as skills
    ├── agents/*.md              # subagent definitions with their own prompt and tools
    ├── workflows/*.js           # workflow scripts saved from /workflows
    ├── output-styles/*.md       # instruction sets that adjust how Claude works
    └── agent-memory/<name>/     # persistent memory for subagents

~/.claude.json                   # app state, OAuth, personal MCP servers
~/.claude/
├── CLAUDE.md                    # your instructions, across every project
├── settings.json                # personal defaults
├── rules/*.md                   # user-level rules, applied to every project
├── keybindings.json             # custom keyboard shortcuts
├── themes/*.json                # custom colour themes
├── plugins/                     # cloned marketplaces and per-plugin data
├── projects/<project>/memory/   # auto memory Claude writes itself
└── .credentials.json            # login credentials

In der Praxis beanspruchen zwei Dateien nahezu die gesamte Bearbeitungszeit: CLAUDE.md und settings.json. Alles Übrige ist optional.

CLAUDE.md, Imports und pfadgebundene Regeln

CLAUDE.md ist die Datei, die Claude Code zu Beginn jeder Sitzung in den Kontext lädt, und sie wird von vier Orten gelesen: Managed Policy, ~/.claude/CLAUDE.md, dem Projekt (./CLAUDE.md oder ./.claude/CLAUDE.md) und ./CLAUDE.local.md für persönliche Notizen. Die Memory-Dokumentation stellt klar, dass diese sich stapeln, statt zu konkurrieren: Jede Datei, die Claude Code findet, wird der Reihe nach dem Kontext hinzugefügt, beginnend beim Dateisystem-Root und abwärts bis zu deinem Arbeitsverzeichnis, und innerhalb eines einzelnen Verzeichnisses kommt die CLAUDE.local.md nach der CLAUDE.md. Eine Datei in einem übergeordneten Verzeichnis wird beim Start geladen; eine in einem Unterverzeichnis wartet, bis Claude dort eine Datei öffnet.

Die Syntax @path/to/file zieht eine weitere Datei herein, aufgelöst relativ zur importierenden Datei, bis zu vier Ebenen tief. Eine lange Datei in Imports aufzuteilen schafft Ordnung, gewinnt aber keinen Kontext zurück, da alles Importierte ebenfalls beim Start expandiert wird. Das Import-Parsing ignoriert alles innerhalb von Backticks oder eines Code-Blocks – so benennst du einen Pfad in deinen Anweisungen, ohne die Datei hereinzuziehen.

Zwei Grenzen sind relevant. Die Zahl von 200 Zeilen ist eher ein Richtwert als eine Obergrenze: darüber hinaus frisst eine Datei mehr Kontext und Claude folgt ihr weniger zuverlässig. Die tatsächliche Obergrenze liegt bei 4 MiB. Claude Code lädt eine CLAUDE.md bis zu dieser Größe vollständig und überspringt eine, die darüber liegt.

.claude/rules/*.md ist die modulare Alternative. Rule-Dateien werden rekursiv gefunden, je eine pro Thema. Gib einer Regel kein Frontmatter, und sie wird beim Start geladen und rangiert gleichauf mit .claude/CLAUDE.md; gib ihr ein paths-Feld, und sie bleibt außerhalb des Kontexts, bis Claude eine Datei berührt, die dem Glob entspricht.

---
paths:
  - "src/components/**/*.tsx"
---

Prefer function components with explicitly typed props.
Co-locate the test file beside the component it covers.

Widersprüchliche Anweisungen über mehrere Dateien hinweg werden willkürlich aufgelöst, es gibt dort also keine Regel zum Merken. Führe /context oder /memory aus, um zu sehen, was tatsächlich geladen wurde, und wenn eine Anweisung wirklich an einem festen Punkt ausgeführt werden muss, schreibe sie stattdessen als PreToolUse-Hook. Ein Hook läuft als Shell-Kommando an einem festen Punkt der Sitzung, unabhängig davon, ob Claude sich dafür entschieden hätte.

Wo passt AGENTS.md hinein?

Ein Repository, das bereits eine AGENTS.md für andere Coding-Agents mitbringt, braucht nichts zusätzlich: Claude Code liest diese Dateien selbst, allein oder neben CLAUDE.md. Wenn das Arbeitsverzeichnis und seine übergeordneten Verzeichnisse keine CLAUDE.md enthalten, wird AGENTS.md geladen. Welche Dateien geladen werden, legt „Project instructions” in /config fest, und diese Einstellung erscheint nur in Sitzungen, die Anthropics Feature-Flags abrufen können – auf Bedrock, Vertex und Foundry fehlt sie daher.

Für eine Sitzung, die AGENTS.md nicht laden kann, oder wenn du eine bestehende CLAUDE.md behalten willst, lege eine CLAUDE.md neben die AGENTS.md, die diese importiert:

@AGENTS.md

## Claude Code

Run `pnpm typecheck` before proposing any change under `packages/api/`.

Ein Symlink funktioniert ebenfalls, wenn du keine Claude-spezifischen Inhalte brauchst: ln -s AGENTS.md CLAUDE.md. Windows legt einen solchen ohne Administratorrechte oder Entwicklermodus nicht an, dort ist der Import also der sicherere Weg. Eine direkt gelesene AGENTS.md erscheint nicht unter „Memory files” in /context oder /memory. Die Sitzung gibt stattdessen eine Zeile „AGENTS.md loaded” aus.

Verwechsle AGENTS.md nicht mit CLAUDE.local.md. Letztere ist das persönliche, per gitignore ausgeschlossene Gegenstück zu CLAUDE.md und hat nichts mit werkzeugübergreifender Interoperabilität zu tun.

Was ist der Unterschied zwischen skills/, commands/ und agents/?

Commands und Skills laufen über denselben Mechanismus und reagieren beide auf /name. Die Directory Reference verweist neue Arbeit auf skills/<name>/SKILL.md, weil ein Skill-Verzeichnis unterstützende Dateien neben den Anweisungen bündeln kann, während ein Command eine einzelne Markdown-Datei ist. Ein vorhandenes commands/*.md-Verzeichnis funktioniert weiterhin. Wie du einen Skill für Frontend-Arbeit strukturierst, zeigt unser Leitfaden zu Claude Code Skills für Frontend-Workflows.

agents/*.md enthält Subagent-Definitionen, jede mit eigenem Prompt und eigener Tool-Liste. Beide Verzeichnisse existieren auf Projektebene und unter ~/.claude, und beide werden über ihren Speicherort erfasst und nicht über eine Registrierung in einer Settings-Datei.

Konfigurationsvorrang in Claude Code: settings.json gegen settings.local.json

settings.json ist die gemeinsame Projektdatei und settings.local.json dein persönliches Override pro Projekt; wenn beide denselben Schlüssel setzen, gewinnt die lokale Datei. Die Settings Reference nennt fünf Vorrangstufen, die höchste zuerst: Managed Settings, Kommandozeilenargumente, .claude/settings.local.json, .claude/settings.json und ~/.claude/settings.json. JSON, das du an --settings übergibst, ordnet sich direkt unter den Managed Settings und über allen drei eigenen Dateien ein.

Was viele überrascht: Nicht jeder Schlüssel folgt diesem Stapel. Listen-Schlüssel wie permissions.allow, permissions.ask und permissions.deny werden über Scopes hinweg kombiniert, statt einander zu ersetzen. Eine Deny-Regel in der gemeinsamen settings.json eines Teamkollegen greift also weiterhin, selbst wenn deine lokale Datei dasselbe Tool erlaubt. Vier Modell-Schlüssel bilden die Ausnahme von diesem Merge. fallbackModel ist eine geordnete Kette, daher liefert die Datei mit dem höchsten Vorrang, die ihn setzt, den gesamten Wert. modelPicker funktioniert genauso, liest aber nur Managed Settings, --settings und User Settings und ignoriert den Schlüssel in Projekt- und lokalen Dateien (Claude Code v2.1.242 und neuer). Eine verwaltete availableModels-Liste gilt so, wie sie ist, und deine eigenen Ergänzungen entfallen – über User-, Projekt- und lokale Dateien hinweg werden diese Arrays jedoch weiterhin zusammengeführt. modelSettings wird pro Modell einzeln aufgelöst.

Gemeinsame Datei:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "cleanupPeriodDays": 30,
  "permissions": {
    "deny": ["Read(./.env)"]
  }
}

Lokale Datei:

{
  "cleanupPeriodDays": 7,
  "permissions": {
    "allow": ["Bash(npm run lint)"]
  }
}

Die aufgelöste Sitzung verwendet cleanupPeriodDays: 7, weil die lokale Datei bei einem skalaren Schlüssel über der gemeinsamen rangiert. Beide Berechtigungsregeln bleiben aktiv: npm run lint läuft ohne Nachfrage und das Lesen von .env bleibt blockiert. Settings-Dateien sind striktes JSON: Füge einen //-Kommentar oder ein nachgestelltes Komma ein, und die Datei lässt sich nicht parsen. Die $schema-Zeile verschafft dir Autovervollständigung im Editor, und da das veröffentlichte Schema den neuesten CLI-Releases manchmal hinterherhinkt, sagt eine Warnung zu einem erst letzte Woche dokumentierten Schlüssel mehr über das Schema aus als über deine Datei. Führe /status aus, um zu prüfen, welche Settings-Dateien geladen wurden.

Wo liegen Hooks und MCP-Server?

Hooks sind keine eigenen Dateien. Sie leben unter dem Schlüssel hooks in settings.json, in dem Scope, in dem sie gelten sollen, und eine Änderung wird ohne Neustart der Sitzung wirksam. MCP-Server trennen sich nach Zielgruppe: .mcp.json liegt im Projekt-Root, wird mit dem Repository ausgeliefert und ist die teamweit geteilte Liste. Persönliche MCP-Server liegen in ~/.claude.json, die außerdem App-State, OAuth-Daten und Server im Local Scope nach Projektpfad enthält – behandle sie also als Maschinenzustand und nicht als Konfigurationsdatei, die du von Hand bearbeitest.

Was committen und was per gitignore ausschließen

Wenn Claude Code diese lokale Datei zum ersten Mal in einem Repository schreibt, das sie nicht bereits ignoriert, hängt es **/.claude/settings.local.json an deine globalen Git-Excludes an. Genau dieser Schreibvorgang passiert, wenn du bei einer Berechtigungsabfrage mit „Yes, and don’t ask again” antwortest. Erstellst du die Datei von Hand, wird nichts für dich hinzugefügt – mach den Eintrag also explizit:

# Claude Code personal config
# settings.local.json is usually auto-excluded already; this covers hand-created files
.claude/settings.local.json
CLAUDE.local.md

Die gemeinsamen Settings sind zugleich das, was Cloud-Sitzungen sehen, denn diese laufen gegen einen frischen Clone. User- und lokale Dateien bleiben auf deinem Rechner und erreichen sie nie.

Alles unter ~/.claude ist Klartext

Sitzungstranskripte, Tool-Ausgaben, eingefügter Text und das Prompt-Log history.jsonl landen allesamt als Klartext auf der Festplatte, und nur die Dateiberechtigungen stehen davor. Wenn ein Kommando während einer Sitzung ein Token ausgegeben hat, liegt dieses Token in einem Transkript. .credentials.json enthält deine Anmeldedaten und übersteht die Aufbewahrungsbereinigung, die andernfalls infrage kommende Dateien löscht, sobald sie cleanupPeriodDays überschreiten: standardmäßig 30 Tage, minimal 1, und 0 wird als ungültiger Wert abgelehnt.

Der Ordner ist kleiner, als er aussieht, sobald man ihn sortiert: Anweisungen werden aneinandergereiht, Settings folgen einem Vorrang, Berechtigungen werden zusammengeführt, und das Home-Verzeichnis kommt nie in die Versionsverwaltung. Vergleiche dein eigenes .claude/ mit dem Baum oben, lösche die Dateien, die niemand absichtlich geschrieben hat, und füge den zweizeiligen .gitignore-Block hinzu, bevor der nächste Pull Request es für dich tut.

FAQs

Muss ich MCP-Server freigeben, die über die committete .mcp.json eines Teamkollegen hereinkommen?

Ja. In einer interaktiven Sitzung fragt Claude Code nach, bevor es einen projektbezogenen Server verwendet, den eine .mcp.json deklariert, und jeder Entwickler antwortet für sich selbst statt einmal für das gesamte Repository. Führe claude mcp reset-project-choices aus, um diese Antworten zurückzusetzen. Nicht-interaktive Kontexte können die Abfrage nicht anzeigen: claude -p-Läufe, Agent-SDK-Sitzungen und Cloud-Sitzungen laden projektbezogene Server ohne Nachfrage. Nutze daher disabledMcpjsonServers, um einen Server in jedem Permission-Modus zu blockieren.

Wie überschreibe ich eine Claude-Code-Einstellung für eine einzelne Sitzung, ohne eine Datei zu bearbeiten?

Übergib --settings entweder mit einem Pfad zu einer JSON-Datei oder mit einem Inline-JSON-String. Es rangiert unter den Managed Settings und über deinen User-, Projekt- und lokalen Dateien. Manche Schlüssel haben zusätzlich ein eigenes Flag oder eine eigene Umgebungsvariable, und welches davon gewinnt, wird Schlüssel für Schlüssel entschieden: --model und /model schlagen ANTHROPIC_MODEL, während CLAUDE_CODE_EFFORT_LEVEL /effort schlägt.

Wird eine Änderung an settings.json mitten in der Sitzung sofort wirksam?

Manche Schlüssel werden im laufenden Betrieb neu geladen, andere nur einmal beim Sitzungsstart gelesen – eine Änderung kann also ignoriert wirken, bis zum nächsten Start. Permissions und Hooks werden ohne Neustart neu geladen, während model, effortLevel und modelSettings einmalig beim Start gelesen werden. Eine Änderung an outputStyle gilt ab v2.1.251 ab deiner nächsten Nachricht, wobei im Terminal eine Style-Datei, die du mitten in der Sitzung anlegst oder bearbeitest, erst nach einem Neustart erfasst wird. Sieht ein Wert auch nach dem Neustart noch falsch aus, führe /status aus und prüfe den Vorrang: Eine Datei mit höherem Scope wie .claude/settings.local.json setzt möglicherweise denselben Schlüssel.

Was verliere ich, wenn ich den projects-Ordner unter ~/.claude lösche?

Das Löschen von projects/ entfernt aufbewahrte Transkripte und kann verhindern, dass du frühere Sitzungen fortsetzen kannst; neue Sitzungen sind davon nicht betroffen. Das Kommando claude project purge ist die gezielte Alternative: Es löscht die Transkripte, den Auto-Memory, die Tasks und die File-History-Einträge für ein Projekt, die zugehörigen Prompt-Zeilen in history.jsonl sowie den Projekteintrag in ~/.claude.json. Sowohl shell-snapshots/ als auch backups/ bleiben unangetastet. Übergib -i, um den Löschplan Schritt für Schritt durchzugehen.