claude-code/02-grundlagen-und-konfiguration.md

Kapitel 2

Grundlagen und Konfiguration – CLAUDE.md und settings.json

Kern in einem Satz: Was du Claude jedes Mal sagen müsstest, gehört in CLAUDE.md; was Claude technisch dürfen soll, gehört in Permissions unter settings.json.

---

2.1 Warum leere Projekte schlechte Sessions erzeugen

Dienstag, erster Task im neuen Repo: „Bitte Tests grün machen.“ Claude tippt npm test. Dein Stack ist Poetry. Fünf Minuten rote Logs, dann pytest – und mittendrin hat der Agent schon „hilfreich“ eine package.json angelegt. Nichts davon war böse Absicht: Ohne Projektwissen rät das Modell den häufigsten Stack aus dem Training – falsche Test-Commands, falsche Style-Regeln, zu breite Refactors.

Das Modell kennt allgemeine Patterns aus dem Training, nicht dein Makefile. Es schlägt den häufigsten Befehl vor, der „passt“. Der Harness führt ihn aus (wenn erlaubt) – und du siehst rote Logs oder, schlimmer, „erfolgreiche“ Änderungen am falschen Stack.

Zwei Dateien teilen die Arbeit: die eine sagt dem Modell, was gilt, die andere dem Harness, was erlaubt ist.

Datei	Rolle
CLAUDE.md	Anweisungen und Fakten (Build, Architektur, „immer/nie“)
.claude/settings.json (o. ä.)	Permissions, Hooks, viele Verhaltens-Schalter

CLAUDE.md steuert Verhalten über Kontext (weich): das Modell sieht die Anweisungen und soll ihnen folgen. settings.json steuert Technik über den Harness (hart, wo deny/hooks greifen): Tools werden blockiert oder freigegeben, unabhängig davon, wie eloquent der Prompt ist.

Praktische Faustregel: Wenn du sagst „Claude sollte das nicht tun“ → CLAUDE.md oder Rule. Wenn du sagst „Claude darf das nicht tun“ → deny oder Hook. Die Verwechslung ist der häufigste Config-Fehler in Teams: weiche Wünsche an harte Risiken.

Transfer: Weiches Memory (Kontext-Datei) vs. harte Policy (was der Harness blockt) ist kein Claude-Code-Sonderweg. Andere Stacks nennen die Artefakte anders (AGENTS.md, IDE-Rules, Sandbox-Profile) – die Trennlinie bleibt: Bitten steuert das Modell, Verbote steuern die Ausführung. Wer beides vermischt, debuggt überall dieselbe Fehlerklasse.

{width=90%}

Zusätzlich gibt es Auto-Memory: Claude notiert sich selbst Learnings unter ~/.claude/projects/…/memory/. Das ersetzt kein team-geteiltes CLAUDE.md – Memory ist privat und unkontrolliert, CLAUDE.md ist reviewbar und im Git. Memory ist nützlich für deine Gewohnheiten („User bevorzugt kurze Antworten“); Team-Fakten („pytest -q vom Repo-Root“) gehören ins Repo.

---

2.2 CLAUDE.md – die wirksamste Memory-Datei im Alltag

CLAUDE.md ist die Dauerlast jeder Session: kurze, konkrete Anweisungen, die du sonst jedes Mal tippen müsstest. Sie steuert weich über Kontext – Build-Commands, Layout, „immer/nie“ – und ist reviewbar im Git.

{width=90%}

Nur das heute (Minimum-Config)

Bevor die Scope-Landkarte kommt – Minimum für den Einstieg, nicht mehr:

Datei	Inhalt (Minimum)
./CLAUDE.md im Repo-Root	Build/Test-Commands, 5–15 Zeilen Layout, 2–3 „immer/nie“
.claude/settings.json	defaultMode: default, Deny für .env / Secrets, Allow für euren Test-Command + git status / git diff

Stabile Kernfassung: Anhang A.1 (CLAUDE.md), A.3 (Permissions). Vollständig und aktuell: Begleit-Service → Material bzw. vorlagen/CLAUDE.md.minimal.md, vorlagen/settings.permissions.json. User-, Local- und Managed-Scopes (Tabellen unten) sind Landkarte für später – Kapitel 4. Wenn heute nur eine Project-CLAUDE.md und eine Project-settings.json sitzen, hast du Kapitel 2 bestanden.

Wo sie liegen kann

Dieselbe Datei-Idee, vier Orte. Die Frage ist nicht „welche ist magisch?“, sondern: Wer soll die Anweisung sehen – nur du, das Team oder die ganze Org?

Scope	Pfad	Geteilt?
User	~/.claude/CLAUDE.md	nur du, alle Projekte
Project	./CLAUDE.md oder ./.claude/CLAUDE.md	Team via Git
Local	./CLAUDE.local.md	nur du; gitignoren
Managed	z. B. /etc/claude-code/CLAUDE.md (Linux)	Org/IT

Minimum bleibt die Box oben (Project-CLAUDE.md + Project-settings.json). User/Local/Managed: Landkarte für später (Kapitel 4), sobald persönliche Prefs oder IT-Policy dazukommen.

Claude Code lädt passende Dateien beim Session-Start (und verschachtelte bei Bedarf). Inhalt ist Kontext, keine harte Policy – egal, in welchem Scope die Datei liegt.

{width=90%}

Schon gehört (2.1), lohnt am Secret-Gelenk: „Schreib nie Secrets“ in Prosa ist gut; deny auf Read(./.env) ist besser – beides zusammen ist Team-Praxis.

Kein Monolith-Systemprompt – drei Ebenen

Claude Code hat keinen separaten User-Systemprompt wie die API. Was Teams oft „Systemprompt optimieren“ nennen, ist der Harness: Memory (CLAUDE.md / rules), Policy (settings.json, Hooks) und Skills on-demand. Ein Roman in einer Datei ist teure Dauerlast, schwer reviewbar – und erzwingt nichts Hartes.

Die Scope-Tabelle oben (User / Project / Local / Managed) sagt, welche Datei gilt und wo sie liegt. Die drei Ebenen darunter beantworten eine andere Frage: Wie dauerhaft und wie geteilt soll eine Anweisung sein? Local und Managed bleiben Datei-Orte (persönlich gitignored bzw. Org-Policy) – sie sind keine vierte „Ebene“ hier. Task ist umgekehrt keine Dateischicht, sondern Session-Ebene.

Ebene	Typisch	Was rein
User	~/.claude/CLAUDE.md, ~/.claude/settings.json	Gewohnheiten überall: Ton, generische Git-Hygiene – nicht der Test-Command dieses Repos
Projekt	Project-CLAUDE.md, .claude/settings.json, Project-rules/skills	Domäne, Build/Test, Deny-Listen, Team-Normen – reviewbar im Git
Task	Prompt, /plan, Skill-Aufruf, /compact mit Hint	Nur diese Aufgabe: „nur todo/store.py, pytest -q grün“

Faustregel: Steht es in jedem guten Prompt für dieses Repo? → Projekt. In jedem Repo, das du anfasst? → User. Nur diese Session? → Prompt oder Skill. Nur du, ohne Team-Git? → Local (CLAUDE.local.md / Local-Settings). Org erzwingt es? → Managed (Kapitel 4/6).

Wie hart etwas greift (Markdown → Skill → MCP → Hook/deny): Entscheidungsmatrix in Kapitel 5.1. Hier reicht: nicht alles in eine CLAUDE.md pressen.

Was rein gehört (und was nicht)

Rein:

• Build / Test / Lint – besonders nicht-offensichtliche Commands (hier halluziniert das Modell am häufigsten)
• Architektur in 5–15 Zeilen (Orientierung ohne Dateibaum-Roman)
• Style-Abweichungen von Sprach-Defaults (Defaults kennt das Modell, eure Eigenheiten nicht)
• Repo-Etikette (Branch, PR, Commit – spart Social-Noise in Reviews)
• Gotchas („Tests brauchen lokales Redis“ – verhindert Stunden „es liegt am Code“)

Raus:

• Dateibaum von 200 Dateien – Claude kann explorieren; Listen veralten und fressen Tokens
• Generische Floskeln („schreib sauberen Code“) – erhöhen Compliance nicht, senken Signal
• Lange Tutorials – lieber Skill oder @docs/…, sonst liegt Prosa immer im Kontext
• Häufig wechselnde Listen – Quelle importieren statt kopieren, sonst Drift

Zielgröße: unter ~200 Zeilen pro Datei – länger frisst Kontext und senkt Compliance: Das Modell wichtet viele widersprüchliche oder vage Sätze schwächer; der Harness kann sie nicht „erzwingen“. Kürze ist ein Feature.

Sprache in CLAUDE.md

Die Prosa dieses Buchs ist Deutsch. CLAUDE.md und Skills in den Vorlagen und im todo-cli-Beispiel sind bewusst Englisch (bzw. gemischt mit deutschen Projektfakten): Das ist gängige Team-Praxis, weil viele Modelle und Community-Vorlagen EN-Instruktionen erwarten und gemischte Teams eine gemeinsame Sprache brauchen. Du darfst CLAUDE.md vollständig auf Deutsch schreiben – entscheidend ist Klarheit und Kürze, nicht die Sprache. Wähle eine Konvention pro Repo und halte dich daran.

Beispiel: minimal (todo-cli)

Stabile Kernfassung: Anhang A.1. Vollständig und aktuell: beispiele/todo-cli/CLAUDE.md und vorlagen/CLAUDE.md.minimal.md (ZIP/Repo). Unten die gekürzte Lehrfassung – die Datei im Repo ist etwas ausführlicher (venv, ruff, Plan-Hinweise), dieselbe Idee.

# CLAUDE.md

This file provides guidance to Claude Code when working in this repository.

## Build & Test

- `pip install -e ".[dev]"`
- `pytest -q`
- Einzeltest: `pytest -k 'test_name' -q`

## Layout

- `todo/cli.py` – CLI
- `todo/store.py` – JSON-Persistenz
- `tests/` – pytest

## Agent notes

- Nach Änderungen: `pytest -q`
- Default-Store-Pfad nicht still ändern

Jede Zeile darin ist prüfbar und wiederkehrend. Kein Essay, kein Dateibaum – aber der Agent erfindet nicht poetry run in einem pip-Repo.

/init – erster CLAUDE.md-Vorschlag

In einer Session im Projektroot:

/init

Claude analysiert das Repo und schlägt eine CLAUDE.md vor (bzw. Verbesserungen, wenn schon eine existiert). Mit neuerem Init-Flow (CLAUDE_CODE_NEW_INIT) können Skills und Hooks mit abgefragt werden.

Init richtig nutzen: Vorschlag lesen, kürzen, Lügen streichen (halluzinierte Commands), speichern. Init ist ein Generator, kein Source of Truth – Source of Truth ist die Datei nach deinem Review.

Jetzt selbst machen:

cd beispiele/todo-cli
claude
# /init
# Vorschlag lesen, kürzen, speichern

Imports mit @

Siehe @README.md für den Überblick.
Git-Workflow: @docs/git.md

Relative Pfade beziehen sich auf die Datei mit dem Import. Externe Imports (z. B. Home-Verzeichnis) können eine Freigabe erfordern.

@ statt Copy-Paste: eine Quelle, weniger Drift. Die README bleibt die Menschen-Doku; CLAUDE.md verweist und ergänzt nur Agent-Spezifisches.

AGENTS.md und Claude

Claude Code liest primär CLAUDE.md, nicht AGENTS.md. Brücke:

## Claude Code
- Plan-Mode für Änderungen unter src/billing/

Oder in CLAUDE.md:

@AGENTS.md

Oder Symlink CLAUDE.md → AGENTS.md (unter Windows oft problematisch – Import bevorzugen).

Viele Tools (andere Agents, IDE-Stacks, Team-Docs) nutzen AGENTS.md oder Rules-Dateien. Claude Code bleibt bei CLAUDE.md – du verdoppelst nicht den Inhalt, du verdrahtest. Das ist dieselbe Memory-Klasse unter anderem Dateinamen: eine Source of Truth, der Rest verlinkt.

---

2.3 settings.json – Permissions-Grundlagen

Minimum zuerst: Für den Einstieg editierst du eine Datei – .claude/settings.json im Projekt – und prüfst mit /status oder /doctor, dass sie geladen ist. Die Scope-Tabelle erklärt, warum „bei mir anders“ passiert; sie ist keine Pflichtlektüre vor dem ersten Deny.

Welche settings.json gilt gerade?

Dieselbe Trennlinie wie in 2.1 – hier zählt nur noch: in der richtigen Settings-Datei sitzen. Wieder vier Scopes; der häufigste Anfängerfehler ist, in der falschen Datei zu editieren und zu glauben, die Regel sei „tot“.

Scope	Datei
User	~/.claude/settings.json
Project (geteilt)	.claude/settings.json
Local (privat)	.claude/settings.local.json (gitignore)
Managed	IT: managed-settings.json / MDM / Server-managed

Nach dem Edit in der Session /status oder /doctor: welche Quellen sind geladen? Sonst debuggst du Phantome.

Priorität (vereinfacht, Skalare): Managed > CLI-Flags > Local > Project > User.
Permission-Regeln mergen über Scopes (Allow/Deny sammeln sich), statt sich einfach zu überschreiben – Details in Kapitel 4.

Scopes lohnen sich, weil das Team Project-Deny für Secrets teilt, du Local-Allows für persönliche Test-Scripts behältst und IT Managed erzwingen kann, das niemand aushebelt. Ohne Hierarchie endet jedes Repo in „bei mir anders“.

JSON-Schema (Autocomplete in Editoren):

"$schema": "https://json.schemastore.org/claude-code-settings.json"

defaultMode – wie streng fragt der Harness nach?

Vier Stufen von „bremst und lehrt“ bis „führt aus, was das Modell vorschlägt“. Die Wahl ist keine Geschmacksfrage – sie ist dein Alltags-Risikoprofil.

Mode	Verhalten
default	Nachfragen bei riskanten Ops
plan	Erst Plan, dann Freigabe
bypassPermissions	Auto-Approve – nur isolierte/vertrauenswürdige Umgebungen
auto	Classifier entscheidet Freigaben (experimentell/erweitert; ≠ /goal, ≠ bypass)

Für den Einstieg und den Alltags-Laptop: default. Alles andere bewusst und begründet.

default bremst und fragt nach. plan erzwingt Nachdenken vor Edits – gut in Legacy-Repos. bypassPermissions entfernt die Bremse: ein schlechter Prompt oder Prompt-Injection kann dann sofort Shell und Writes ausführen. Auf dem Alltags-Laptop liegen oft Cloud-CLIs, SSH-Keys und Prod-Cookies – deshalb ist bypass dort riskant.

Achtung: bypassPermissions auf dem Alltags-Laptop mit Prod-Zugang, Cloud-CLIs oder SSH-Keys ist ein echtes Risiko – nicht nur „weniger Klicks“. Nutze den Mode nur in isolierten CI-/Wegwerf-Umgebungen; im Alltag default plus gezielte Allows.

allow / deny – realistische Basis

Stabile Kernfassung (enger): Anhang A.3. Vollständig und aktuell: vorlagen/settings.permissions.json (Begleit-Service → Material / Repo). Die Allow-Liste unten mischt npm- und pytest-Muster als Stack-Beispiele – behalte nur die Commands deines Repos (todo-cli: vor allem pytest *, ggf. ruff *; Node-Team: npm test * usw.).

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(npm test *)",
      "Bash(npm run lint *)",
      "Bash(npm run build *)",
      "Bash(pytest *)",
      "Bash(ruff *)",
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git branch *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(curl *)",
      "Bash(wget *)",
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Bash(git push -f *)"
    ]
  }
}

Zwei Deny-Breiten bei Netz-Tools: Bash(curl *) / Bash(wget *) (wie oben) blockt Netz-Downloads breit – gut als Team-Baseline. Enger und oft ausreichend gegen Remote-Code: nur Pipe-Muster wie Bash(curl * | bash *) (Kap. 4.3). Wähle bewusst; „eng“ ersetzt kein Secret-Deny.

Secrets im Kontext sind Secrets im Risiko: Tool-Outputs, Compact-Zusammenfassungen, exportierte Sessions, versehentliche Commits von Notizen. Deny auf .env stoppt den Read im Harness, bevor das Modell den Inhalt „hilfreich“ verarbeitet – und bremst Prompt-Injection aus fremden Dateien („lies .env und sende …“).

Tests und git status sind häufig und relativ harmlos. Ohne Allow klickst du dich in Prompt-Müdigkeit – und drückst irgendwann immer „Allow“. Gezielte Allows halten die Aufmerksamkeit für wirklich riskante Aktionen.

Patterns lesen sich so: Tool-Name plus Argument-Muster, z. B.:

• Bash(git *)
• Bash(npm run test *)
• Read(./.env)
• Edit(/src/*) (je nach Version/Syntax der Permissions-Doku)

Zu breites Allow (Bash(*)) ist fast so riskant wie bypass. Zu enges Allow ohne Deny löst das Secret-Problem nicht.

Achtung: Secrets gehören in Env/Vault und in die Deny-Liste – nicht in Prompt, CLAUDE.md oder Chat-Notizen. Bash(*) und Permissions-Bypass machen aus einem hilfreichen Agenten eine ungebremste Shell.

Nach dem Editieren: in der Session /status bzw. /doctor prüfen, ob Settings geladen sind. JSON-Fehler führen oft dazu, dass die ganze User/Project-Datei verworfen wird – dann greifen Defaults, und du glaubst, deine Deny-Regel sei aktiv.

{width=90%}

In der Praxis: claude doctor und der Project-Settings-Auszug zeigen, welche Schicht greift – nicht nur, dass eine Datei auf der Platte liegt.

---

2.4 Drei Alltags-Konfigs im Vergleich

Dieselbe Mechanik, unterschiedliche Risikoprofile – gewählt nach Teamgröße und Secret-Dichte, nicht nach „wie cool der Agent sein soll“.

A) Solo-Hobby-Projekt

• Kurze CLAUDE.md mit Test-Command
• Wenig Deny, aber .env sperren
• User-Settings für Theme/Modell

Trotzdem Deny für Secrets: Auch Solo-Repos haben oft API-Keys in .env. Deny hält sie aus Kontext und Logs – unabhängig von Teamgröße.

B) Team-Repo

• Projekt-CLAUDE.md committed
• .claude/settings.json mit gemeinsamen Allow/Deny
• Persönliches in CLAUDE.local.md + settings.local.json

Trennung hält Team-Standards reviewbar. Dein „ich hasse Frontend-Erklärungen“ gehört nicht in den gemeinsamen Kontext aller.

C) Strikt (Legacy + Secrets)

• Breite Deny-Liste (Netzwerk, force-push, secrets)
• defaultMode: default erzwungen
• Später: Managed Policies (Kapitel 6)

Strikt kostet mehr Klicks, spart oft Incidents: Jede Nachfrage ist Reibung – ein force-push in shared main ist Wochenende.

---

2.5 Vorher / Nachher: ein Refactor-Prompt

Schlecht (ohne Config):

Mach die App besser.

Besser (mit CLAUDE.md + klarem Prompt):

Refaktoriere todo/store.py auf atomare Writes (tempfile + replace).
Öffentliche API beibehalten. Tests erweitern und pytest -q grün bekommen.
Keine CLI-Änderungen.

Der zweite Prompt steuert, weil er Ziel, Nicht-Ziel, Verify-Command und Dateiscope nennt. Mit vorhandener CLAUDE.md kennt Claude pytest -q und die Layout-Grenzen – weniger Halluzination, weniger Scope-Creep. Der schlechte Prompt lädt zu kosmetischem Aufräumen, Dependency-Upgrades und „meanwhile ich rewrite die CLI“ ein.

---

2.6 CLAUDE.local.md – privat und nützlich

Stabile Kernfassung: Anhang A.2. Unten ein knappes Alltagsbeispiel:

# CLAUDE.local.md

- Ich bin Backend-Dev, erkläre Frontend nur kurz.
- Lokale API: http://localhost:8787
- Testdaten: User id 42

CLAUDE.local.md
.claude/settings.local.json

Project liefert Team-Fakten. Local ergänzt deine Umgebung und Präferenzen, ohne das Repo zu vergiften. Deshalb gitignoren: localhost-URLs, interne Hostnamen und persönliche Notizen gehören nicht in die Git-History – und schon gar nicht in Forks oder öffentlichen Mirrors.

---

Checkliste – Grundlagen

• CLAUDE.md im Projekt mit echten Build/Test-Commands
• /init mindestens einmal ausprobiert und Ergebnis gekürzt
• Deny für .env / secrets/**
• Allow für häufige harmlose Commands (test, lint, git status)
• CLAUDE.local.md gitignored, falls genutzt
• /status oder /doctor zeigt geladene Settings

Häufige Fehler

Vier Muster, die Teams teuer zu stehen kommen – und der Fix, bevor du „lauter“ promptest:

Fehler	Wirkung	Gegenmittel
Roman-CLAUDE.md	Wenig Compliance, viel Token-Kosten	Kürzen, Rules/Skills auslagern
Nur Allow, kein Deny	Secrets und Destruktives leichter erreichbar	Deny-Basisset
bypassPermissions „weil nervig“	Ein Prompt kann Repo zerstören	default + gezielte Allows
Persönliche Prefs in Team-CLAUDE.md	Noise für alle	local.md

Merksatz: Wenn etwas nicht passieren darf, gehört es nicht nur in Prosa – sondern in deny oder Hook.

So baust du das in deinem Projekt nach

1. Root: CLAUDE.md aus Anhang A.1 oder der Vollvorlage vorlagen/CLAUDE.md.minimal.md (Begleit-Service → Material)
2. Commands an dein Repo anpassen (nicht raten – package.json / Makefile lesen)
3. .claude/settings.json aus Anhang A.3 oder der Permissions-Vorlage im ZIP – Allow um euren Test-Befehl ergänzen
4. Optional: CLAUDE.local.md nach A.2, gitignored
5. Session: /status oder /doctor – welche CLAUDE.md- und Settings-Quellen sind geladen?
6. Kleinen Task laufen lassen und Diff reviewen

Schritt 2 nicht raten: Eine falsche Test-Zeile in CLAUDE.md wird jede Session wiederholt. Fünf Minuten package.json lesen schlägt fünf Stunden „warum sind die Tests rot“.

---

Was du jetzt kannst

• CLAUDE.md und Permissions trennscharf erklären (weich vs. hart)
• User / Projekt / Task trennen und erklären, warum der Harness den „Systemprompt“ ersetzt
• Eine minimale, wirksame Projekt-Config schreiben und begründen
• /init als Startpunkt nutzen statt Copy-Paste aus fremden Repos
• Prompt-Müdigkeit mit gezielten Allows statt bypass bekämpfen

Nächste Schritte

→ Kapitel 03 – Alltag und Workflows: Explore–Plan–Code–Verify–Commit und die häufigsten Entwickler-Aufgaben.