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.
Ergänzung: Ein praktischer Maßstab für solche AI-Meldungen
Die englische Fassung ergänzt mehr Prüffragen: zuerst die Primärquelle, dann die Reproduzierbarkeit, danach der Nutzen im echten Workflow. Lassen Sie sich nicht nur von großen Zahlen, Screenshots oder einem zugespitzten Satz führen. Fragen Sie: Läuft die Fähigkeit stabil? Was passiert bei einem Fehler? Gibt es offizielle Dokumentation, ein Paper, Produktunterlagen oder eine überprüfbare Demo? In einem Team muss außerdem klar sein, wer prüft, wer veröffentlicht und wer die Folgen eines Fehlers trägt.
Wertvoll ist nicht jede AI-Nachricht, sondern die Information, die Entscheidungen verbessert: Tool-Auswahl, Prozessänderungen, Risikoabbau. Reine Empörung darf schnell veralten.