claude-code/04-fortgeschrittene-konfiguration.md

Kapitel 4

Fortgeschrittene Konfiguration – Hierarchie, Rules und parallele Arbeit

Kern in einem Satz: Konfiguration ist geschichtet – Managed gewinnt, Local überstimmt Project für dich persönlich, Permission-Regeln mergen – und wer das nicht kennt, debuggt „warum greift meine Deny-Regel nicht?“ stundenlang.

---

4.1 Die Konfigurationshierarchie

Montag, 10:12. Dein Deny auf Bash(curl *) steht in .claude/settings.json. Die Kollegin sagt: „Bei mir greift’s.“ Bei dir fragt Claude trotzdem nach curl. Bevor du die Regel verdoppelst oder lauter promptest: Es gibt mehrere Schichten Settings – und die Datei, die du meinst, ist oft nicht die, die der Harness geladen hat.

Solo reicht oft „eine CLAUDE.md + settings“. Im Team und mit IT kommen mehrere Quellen dazu. Ohne Modell der Hierarchie fühlst du dich, als würde Claude „Einstellungen ignorieren“ – dabei gewinnt meist eine andere Schicht.

Welche Schicht lädt eigentlich?

Vier Scopes, ein Merge-Modell. Lies die Tabelle als Landkarte für Support-Tickets – nicht als Theorie.

Scope	Settings	CLAUDE.md / Rules	Typischer Zweck
Managed	managed-settings.json, MDM, server-managed	Org-CLAUDE.md, claudeMd in Policy	Compliance, nicht überstimmbar
User	~/.claude/settings.json	~/.claude/CLAUDE.md, ~/.claude/rules/	persönliche Defaults
Project	.claude/settings.json	CLAUDE.md, .claude/rules/	Team-Standards im Repo
Local	.claude/settings.local.json	CLAUDE.local.md	private Overrides

Als Nächstes prüfen: /status oder /doctor – welche Quellen sind aktiv? Dann erst die Regel anfassen.

Zusätzlich: CLI-Flags und manchmal --settings für einmalige Overrides.

Priorität (Skalar-Settings)

1. Managed (höchste)
2. Command-line
3. Local
4. Project
5. User (niedrigste)

Wie Merge vs. Override funktioniert: Skalare Werte (z. B. ein einzelnes Flag, ein defaultMode aus höherer Schicht) gewinnen. Permissions werden über Quellen zusammengeführt (Allow/Deny-Listen akkumulieren). Ein User-Allow kann ein Project-Deny nicht aushebeln, wenn Deny greift – Deny hat Vorrang in der Permission-Logik. Managed kann User/Project-Regeln sogar verbieten (allowManagedPermissionRulesOnly).

Stabile Kernfassung (Schalter + Hierarchie-Kurzform): Anhang A.4.

{width=90%}

Warum greift mein Deny nicht?

Fünf Checks in der Reihenfolge, die am häufigsten den Montag-10:12-Fall löst:

1. /status oder /doctor: Welche Settings-Quellen sind geladen?
2. Liegt die Regel in der Datei, die du denkst – oder in einer verworfenen kaputten JSON?
3. Gibt es ein breiteres Allow oder einen anderen Tool-Namen (Bash vs. mcp__…)?
4. Überschreibt Managed deine Project-Idee?
5. Workspace-Trust: Project-Allows greifen erst nach Trust.

Merksatz für Support-Tickets: „Claude ignoriert meine Settings“ ist fast immer „die Schicht, die du meinst, ist nicht die Schicht, die lädt“. Ein Screenshot von /status spart eine Stunde Hin-und-Her. Kaputtes JSON in Project-Settings kann die gesamte Datei verwerfen – dann greifen Defaults, und deine Deny-Zeile existiert nur noch auf der Platte, nicht im Harness.

Was wo hingehört (Faustregeln)

Wenn du unsicher bist, wo eine Zeile leben soll – erst den Zweck klären, dann den Scope:

Inhalt	Ort	Warum
„Nie curl | bash“ firmenweit	Managed deny	Compliance darf nicht pro Repo aushebelbar sein
Team-Testcommand + gemeinsame Allows	Project settings + CLAUDE.md	reviewbar, für alle gleich
Dein Lieblingsmodell, verbose	User settings	persönlich, nicht team-relevant
Sandbox-URL nur bei dir	Local / CLAUDE.local.md	privat, oft secret-nah
Format-on-edit fürs Team	Project hooks	erzwungen und geteilt

Transfer: Team-weit und reviewbar → Project. Privat und secret-nah → Local. Unumstößlich → Managed.

---

4.2 CLAUDE.md vs. .claude/rules/ vs. CLAUDE.local.md

Sechs Mechanismen, eine Entscheidungsfrage: Muss das in jeder Session liegen, nur bei bestimmten Pfaden, on-demand – oder hart erzwungen?

Mechanismus	Lädt wann	Für
CLAUDE.md	(fast) jede Session	Kernfakten, immer relevant
.claude/rules/*.md	immer, oder path-scoped	modular, teambar
CLAUDE.local.md	mit Projekt	private Prefs (Kern: Anhang A.2)
Auto-memory	Auszug aus MEMORY.md	Claude-Notizen, nicht Policy
Skills	on-demand	Workflows, die nicht immer im Kontext liegen müssen
Hooks / deny	erzwungen	harte Leitplanken

Wie du wählst: Alles, was jede Session braucht und kurz ist → CLAUDE.md. Längere Themenmodule und bereichsbezogene Normen → rules. Prozeduren mit vielen Schritten → Skills (Kapitel 5). Verbote → deny/hooks.

Keine Optimierung auf Vorrat. Wenn Sessions schiefgehen, schärfst du Schichten (Kap. 2: User / Projekt / Task) – nicht einen Monolith-Prompt. Ohne wiederkehrendes Symptom Config nicht „vollständiger“ machen: Roman-CLAUDE.md und ungenutzte Server sind teurer als ein fehlender Feinschliff.

Reihenfolge mit dem größten Effekt:

1. harte Policy (deny/hooks)
2. knappe Project-CLAUDE.md
3. path-scoped rules
4. Skills für Mehrschritt-Prozesse
5. MCP nur mit klarem Bedarf

Entscheidungsmatrix und Fehlgriffe: Kapitel 5.1.

Path-scoped Rules

---
paths:
  - "src/api/**/*.ts"
  - "tests/api/**/*.ts"
---

# API-Regeln

- Input-Validierung an jeder Boundary
- Fehler im Standard-JSON-Format
- Keine direkten DB-Calls aus Route-Handlern

Ohne paths: gilt global wie CLAUDE.md-Zusatz.

API-Regeln im Frontend-Kontext sind Rauschen und Tokens. Path-Scopes laden Relevanz, wenn der Agent in diesen Pfaden arbeitet. Risiko: Falscher Glob → „Claude ignoriert Regeln“ – dann /context und Glob testen.

{width=90%}

Beispiel-Struktur

.claude/
├── CLAUDE.md                 # optional alternativ zu Root-CLAUDE.md
├── settings.json
├── settings.local.json       # gitignore
├── rules/
│   ├── testing.md
│   ├── security.md
│   └── api.md                # mit paths-Frontmatter
└── hooks/
    └── format-changed.sh

Jetzt selbst machen: Lege in einem Demo-Repo .claude/rules/testing.md an mit dem einen Satz: „Neue Features brauchen mindestens einen failing-first Test.“ Starte eine Session und bitte Claude, die geladenen Instruction-Files zu nennen (/context, Memory-Abschnitt).

So siehst du, dass Rules Kontext sind – sichtbar in /context – und lernst den Debug-Einstieg, bevor echte Team-Rules wachsen.

---

4.3 Permissions richtig setzen

Pattern-Sprache (Praxis)

Bash(npm test *)
Bash(git commit *)
Bash(gh pr *)
Read(./.env)
Read(./secrets/**)
Edit(src/**)

Wie Patterns gelesen werden: Zuerst das Tool (Bash, Read, Edit, mcp__…), dann ein Muster für Argumente/Pfade. * ist Wildcard. Zu generisch (Bash(*)) entfernt die Bremse; zu eng ohne Deny löst Secret-Probleme nicht.

MCP-Tools erscheinen oft als:

mcp__github__*
mcp__plugin_my-plugin_db__query

Deine Bash-Deny-Liste stoppt kein mcp__db__query. Angriffsfläche und Allows müssen den echten Tool-Namen kennen.

Realistische Allow-Liste (Node-Team)

{
  "permissions": {
    "allow": [
      "Bash(npm run lint *)",
      "Bash(npm test *)",
      "Bash(npm run test *)",
      "Bash(npx tsc *)",
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git add *)",
      "Bash(gh pr view *)",
      "Bash(gh pr diff *)"
    ]
  }
}

Häufig, reviewbar, relativ wenig Blast Radius. Bewusst kein generelles git push, kein npm publish, kein freies curl.

Realistische Deny-Liste (Startpunkt)

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(**/id_rsa)",
      "Read(**/*.pem)",
      "Bash(rm -rf *)",
      "Bash(curl * | bash *)",
      "Bash(wget * | sh *)",
      "Bash(git push --force *)",
      "Bash(git push -f *)",
      "Bash(git reset --hard *)"
    ]
  }
}

Keys im Kontext = Exfil-Risiko. Force-push und hard reset sind History-Zerstörer – in Agent-Sessions oft „schnell sauber machen“ genannt.

Enger als die Basis-Deny in Kap. 2: hier zielen die Pipe-Muster (curl … | bash, wget … | sh) auf Remote-Code-Ausführung. Die Kap.-2-Vorlage deny’t curl/wget breit – strenger, mehr Nachfragen bei harmlosen Downloads. Teams mit legitimen curl-Scripts bevorzugen oft die engen Pipe-Denys plus Review.

Feinheiten ändern sich mit Versionen – im Zweifel: Permissions-Doku und /permissions.

Ask-Regeln und Trust

Project-allow-Regeln aus dem Repo können an Workspace-Trust gebunden sein: Beim ersten Mal musst du dem Projekt vertrauen, bevor Team-Allows greifen. Local-Allows, die Claude für dich speichert („don't ask again“), liegen typischerweise in settings.local.json und sind dein Risiko.

Ohne Trust könnte ein geklontes Repo stille Auto-Approves unterschieben. Trust heißt: „Diesem Code und seinen Team-Settings vertraue ich.“

defaultMode im Team

Dieselbe Mode-Liste wie in Kapitel 2 – hier die Team-Lesart: Was darf auf dem gemeinsamen Laptop-Standard stehen, was nur in CI?

Mode	Team-Empfehlung
default	Standard für Menschen am Laptop
plan	Gute Default-Disziplin für heikle Repos
bypassPermissions	CI-Sandbox, Wegwerf-Container – nicht Dev-Laptop mit Prod-Credentials
auto	Classifier-Freigaben – nur wenn verstanden/org-konfiguriert; ≠ bypass, ≠ /goal

Was du im Repo committest: default oder bewusst plan. bypassPermissions gehört in Runner-Config, nicht in die Project-Settings für Entwickler-Laptops.

---

4.4 ~/.claude.json und Projektzustand

Neben settings.json speichert Claude Code Zustand in ~/.claude.json (OAuth-Session, MCP user/local, Trust-Flags, Caches). Nicht von Hand „kaputtoptimieren“, wenn du nicht weißt warum. Backup: Claude Code hält timestamped Backups der Configs.

Projekt-MCP: häufig .mcp.json im Repo (geteilt). User-MCP: in User-Config.

Settings steuern Policy und Verhalten; ~/.claude.json hält Session-Zustand. Wer OAuth und Trust manuell ediert, erwischt leicht Login-Loops – doctor und offizielle Reset-Wege sind sicherer.

---

4.5 Sessions, Resume, Compact, Checkpoints

Lange Arbeit zerfällt nicht an „zu wenig Intelligenz“, sondern an Session-Hygiene: falsches Thema im selben Chat, volles Fenster, Entscheidungen nur gesprochen. Die Tabelle ist der Werkzeugkasten – Kapitel 7 vertieft den Alltag damit.

Werkzeug	Nutzen	Warum
/resume / /session	Alte Conversation fortsetzen	Kontext und Entscheidungspfad bleiben
/rename	Session benennen	Wiederfinden wie bei Git-Branches
/compact [hint]	Kontext zusammenfassen, Platz schaffen	Tokens/Qualität – verlustbehaftet; Hint steuert Fokus
/clear	Frischer Faden im selben Projekt	Themenwechsel ohne alten Ballast
/plan	Plan-Mode	Explore/Plan ohne Source-Edits
/goal	Bis messbarer Bedingung arbeiten	Loop ohne „und jetzt?“-Prompts
/btw	Side-Question	ohne History-Kosten
/export	Gespräch sichern	Audit, Postmortems, Lernen
/cost /usage	Verbrauch beobachten	Budgets steuern
/rewind / Checkpoints (UI-abhängig)	Zu früherem Stand zurück	Experimente – kein Git-Ersatz

Wenn du nur drei behältst: /plan vor multi-file, /compact mit Hint wenn unscharf, /clear bei Themenwechsel.

Compact mit Hint (ausführlich Kapitel 7.3):

/compact Behalte freigegebenen Plan, geänderte Dateien und den Verify-Command.
Verwirf Explore-Umwege und gescheiterte Zwischenversuche.

Was nach Compact typischerweise bleibt: Root-CLAUDE.md, unscoped Rules und Auto-Memory werden von Disk neu geladen. Path-scoped Rules und nested CLAUDE.md erst wieder bei passendem Dateizugriff. Chat-only-Entscheidungen überleben nur, soweit die Summary sie behält – deshalb PLAN.md (Kapitel 7.4).

Parallele Sessions: Zwei Terminal-Tabs, zwei Worktrees, Desktop-App mit Side-by-Side. Vermeide, dass zwei Agenten dieselbe Branch-Datei gleichzeitig beschreiben – sonst Merge-Chaos.

Session-Steuerung als Best Practice (Kontext-Hygiene, Goal-Conditions, Persistenz-Ritual): Kapitel 07.

Worktrees (empfohlen bei Parallelität)

git worktree add ../proj-feature-a feature-a
cd ../proj-feature-a && claude

Jeder Agent hat eigenes Working Tree. CLAUDE.md aus dem Repo gilt; CLAUDE.local.md ist ggf. worktree-lokal (gitignored) – bei Bedarf Home-Import nutzen (offizielle Memory-Doku: code.claude.com/docs/en/memory).

Zwei Agenten auf demselben Working Tree überschreiben sich – Git-Status lügt, Diffs mischen Features. Worktrees geben jedem eine eigene Sandbox-Branch-Ansicht: parallel, ohne sich ins Gehege zu kommen.

{width=90%}

---

4.6 Modelle und Effort

Der Plan war gut – und die Umsetzung frisst trotzdem das teure Modell bei jedem Turn. Oft reicht ein günstigeres Modell für die Routine und ein stärkeres nur an den Knoten, an denen Planqualität zählt. Genau darum geht es hier: Modell und Effort pro Task, und optional den experimentalen Advisor.

/model
/effort

Faustregeln (produktabhängig, 2026):

• Alltag / viel Iteration: schnelleres, günstigeres Modell
• Architektur, heikle Reviews: stärkeres Modell
• Subagents können eigene Modellwahl haben

Org-Policies können availableModels einschränken.

Wie du wählst: Nicht „immer das stärkste“. Enge Tasks mit gutem Plan brauchen oft weniger Modellkraft als unklare Architekturfragen. Modellwahl steuert Qualität/Kosten pro Task; CLAUDE.md und Permissions steuern Steuerbarkeit – das eine ersetzt das andere nicht.

Advisor (experimental)

Dein Hauptmodell (Executor) erledigt den Agent-Loop; an Knoten – vor einem Ansatz, bei wiederkehrendem Fehler, vor „fertig“ – holt es sich Rat von einem zweiten, typisch stärkeren Modell. Der Advisor sieht die volle Conversation inkl. Tool-Ergebnisse und liefert Orientierung; das Hauptmodell arbeitet danach weiter.

/advisor          # Picker / Status
/advisor opus     # Advisor setzen (Alias; speichert als Default)
/advisor off      # abschalten und Default löschen

Alternativen: Setting advisorModel in den User-Settings, Session-Flag claude --advisor opus. Subagents erben die Advisor-Config und prüfen die Modell-Paarung gegen ihr Modell.

Wann sinnvoll: lange Multi-Step-Tasks (Refactor, zäher Bug, Abschluss-Check), bei denen die meisten Turns Routine sind, die Planqualität aber entscheidet. Wann nicht: Einzeiler und klarer Scope (Overhead); wenn jeder Turn das starke Modell braucht → /model statt Advisor; Hosting ohne Anthropic-API (Bedrock/Foundry/…) – der Advisor ist ein Server-Tool nur über die Anthropic API.

Ansatz	Wann das stärkere Modell läuft	Steuerung
Advisor	Mid-task an Entscheidungspunkten	Claude ruft; du kannst im Prompt um Beratung bitten
Plan-Mode (/plan)	Phasengrenze vor Code	du (und ggf. stärkeres Plan-Modell)
Subagent	ganzer Subtask, eigenes Kontextfenster	Delegation / Rolle
/model	alle folgenden Turns der Session	du

Wie & Warum: Advisor ersetzt weder Plan (menschliche Freigabe an der Phasengrenze) noch Subagents (Rollen- und Kontext-Isolation). Er spart oft Kosten gegenüber „durchgängig Opus“, weil nur die Beratung am teuren Modell hängt – jede Advisor-Runde kostet aber extra Tokens am Advisor-Tarif (/usage). Feature ist experimental; Labels und Verfügbarkeit können driften – /help und die Advisor-Doku gelten. Org-availableModels kann den Advisor-Kandidaten blockieren; komplett abschalten: Env CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1.

---

4.7 Vollständiges Project-Setup (Referenz)

Die folgenden Dateien bilden Schichten, keine Dekoration:

Datei	Schicht
CLAUDE.md / Team-Vorlage	Weiche Team-Fakten
.claude/settings.json	Harte Team-Permissions (+ später Hooks)
.claude/settings.local.json	Deine privaten Overrides (gitignore)
CLAUDE.local.md	Deine privaten Prefs (gitignore)
.claude/rules/*	Modularisierte Normen

.claude/settings.json:

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

Root-CLAUDE.md: Team-Vorlage aus vorlagen/CLAUDE.md.team.md – nur online (Begleit-Service → Material / Repo), nicht Teil der stabilen Kerne in Anhang A. Minimale Project-Baseline: A.1 + A.3; Settings-Hierarchie-Kern: A.4.

.gitignore ergänzen (vgl. A.2):

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

Walkthrough nach dem Anlegen: Session starten → /status zeigt Project-Settings → /context zeigt CLAUDE.md/Rules → kleiner Edit → git diff → nichts Local-Privates im Diff.

---

Checkliste – Fortgeschritten

• Du kannst sagen, welcher Scope eine Einstellung gewinnt
• Team-Settings committed, Local gitignored
• Mindestens eine path-scoped Rule
• Deny-Basis aktiv
• Parallel-Arbeit über Worktrees oder klare Branch-Trennung
• /status oder /doctor nach Config-Änderungen geprüft

Häufige Fehler

Fehler	Symptom	Fix
Local-Datei committed	Secrets/Prefs im Repo	gitignore + History cleanen
Rule mit falschem Glob	„Claude ignoriert Regeln“	paths testen, /context
Zu viele Allows	Keine Nachfragen mehr bei Riskantem	Allows auf Routine begrenzen
Zwei Agenten, eine Datei	Überschreib-Chaos	Worktrees

So baust du das in deinem Projekt nach

1. Inventur: existierende CLAUDE.md / Cursor-Rules / AGENTS.md
2. /init oder manuell konsolidieren
3. .claude/rules/ für 2–3 Themen
4. Permissions-Vorlage committen
5. Team-README-Abschnitt „AI setup“ mit 10 Zeilen

Viele Repos haben schon AGENTS.md, .cursor/rules oder Contributing-Abschnitte. Konsolidieren schlägt „noch eine Datei dazu“. Artefakt-Familien: Anhang, Agenten-Landschaft.

---

Was du jetzt kannst

• Config-Scopes und Merge-Verhalten erklären (Skalare vs. Permissions)
• Modular rules und Local-Overrides einsetzen und begründen
• Config symptomgetrieben schärfen (Policy → Memory → Rules → Skills), ohne Optimierung auf Vorrat
• Parallele Sessions ohne Dateikollisionen orchestrieren
• Compact mit Hint und Session-Werkzeuge (/plan, /goal, /btw) grob einordnen
• Modellwahl, Effort und den experimentalen Advisor von Plan-Mode und Subagents abgrenzen
• Das Debug-Muster „welche Quelle gewinnt?“ anwenden

Nächste Schritte

→ Kapitel 05 – MCP, Skills und Hooks: Erweiterbarkeit, die den Harness an eure Welt anschließt.