Anatomie des .claude-Ordners: Was er tut und warum er verwirrt
Wenn Sie nach „Anatomie des .claude-Ordners" gesucht haben, möchten Sie wahrscheinlich herausfinden, was dieser Ordner eigentlich tut, warum er Verwirrung stiftet und welche Teile Ihre Aufmerksamkeit verdienen.
Ein Reddit-Thread aus dem März 2026 hat das klar dargestellt. Ein Entwickler, der durch unklare Platzierungskonventionen Probleme bekommen hatte, erstellte ein Cheat Sheet zum .claude/-Verzeichnislayout, zu Hook-Ereignissen, settings.json, MCP-Konfiguration, Skill-Struktur und Kontextverwaltungsschwellenwerten.
Die Kernverwirrung: Global vs. Projektebene
Die größte Verwirrungsquelle ist der Unterschied zwischen dem globalen ~/.claude-Verzeichnis und dem projektspezifischen .claude/-Verzeichnis.
Das globale Verzeichnis liegt im Home-Ordner und definiert geteiltes Verhalten über alle Projekte hinweg. Das projektspezifische .claude/-Verzeichnis liegt innerhalb eines bestimmten Repositorys und überschreibt oder erweitert die globale Konfiguration.
Wenn Sie diese beiden Ebenen vermischen, wird der Ordner mysteriös. Er ist nicht mysteriös — er ist nur skopiert, und die Skopierung bestimmt die Priorität.
Platzierungskonventionen
Skills gehören in .claude/skills/. Jeder Skill bekommt sein eigenes Verzeichnis mit einer SKILL.md-Datei.
Agenten kommen in .claude/agents/, nicht als lose Dateien im Hauptverzeichnis.
Einstellungen liegen in .claude/settings.json auf Projektebene oder ~/.claude/settings.json global.
Hooks sind operativ, nicht passiv
Die häufigste Fehlkonfiguration ist eine zu enge Matcher-Definition. Ein PostToolUse-Hook, der nur „Write" matched, verpasst Änderungen über „Edit" oder „MultiEdit". Das breitere Matcher-Muster „Edit|MultiEdit|Write" fängt mehr ab.
Die vier wichtigsten Punkte
1. Skopierung — Global vs. Projektebene ist die erste Entscheidung.
2. Platzierungskonventionen — Skills brauchen SKILL.md, Agenten gehören in agents/.
3. Inhalt vs. Orchestrierung — Skills, Agenten, Einstellungen, Hooks und MCP-Konfigurationen sind nicht gleichwertig.
4. Anzeichen von Drift — Dokumentation ändert sich schnell. Wenn Ihr Setup plötzlich nicht mehr funktioniert, prüfen Sie, ob sich die zugrundeliegenden Konventionen geändert haben.
Der .claude-Ordner kombiniert Skopierung, Struktur und Verhalten. Sobald Sie dieses dreischichtige Modell verinnerlicht haben, sieht der Ordner nicht mehr wie versteckter Unrat aus, sondern wie eine Betriebskarte.