Analyse der Struktur des `.claude/`-Ordners

• Der Ordner .claude/ ist das zentrale Steuerungsverzeichnis von Claude Code und verwaltet projektbezogene Regeln, Befehle, Berechtigungen und Speicherzustände
• CLAUDE.md ist die zentrale Datei zur Definition von Verhaltensprinzipien und Projektregeln für Claude; mehrere Konfigurationsebenen werden zusammengeführt und angewendet
• Die Ordner commands/, skills/ und agents/ definieren jeweils benutzerdefinierte Befehle, automatische Workflows und spezialisierte Sub-Agenten, um die Zusammenarbeit effizienter zu machen
• settings.json steuert Berechtigungen zur Befehlsausführung und den Bereich des Dateizugriffs; mit settings.local.json sind persönliche Overrides möglich
• Die gesamte Struktur fungiert als Protokoll, das Claude die Identität und Regeln eines Projekts vermittelt, sodass klare Konfigurationen Produktivität und Zusammenarbeit maximal verbessern

---

Struktur und Komponenten des .claude/-Ordners

• Der Ordner .claude/ ist das Kernverzeichnis zur Steuerung des Verhaltens von Claude Code und verwaltet projektbezogene Regeln, Befehle, Berechtigungen und Speicherzustände
• Der Ordner im Projekt-Root enthält teamweite Einstellungen und wird in Git committet
• Der Ordner im Home-Verzeichnis (~/.claude/) speichert persönliche Einstellungen und Sitzungsverläufe und umfasst automatischen Speicher sowie persönliche Befehle

• CLAUDE.md — Claudes Leitfaden

  • Die Datei, die beim Start einer Claude-Code-Sitzung zuerst gelesen wird, und die Claudes Verhaltensprinzipien und Projektregeln definiert
  • CLAUDE.md im Projekt-Root ist für gemeinsame Teamregeln zuständig, ~/.claude/CLAUDE.md für globale persönliche Regeln, und CLAUDE.md in Unterordnern für ordnerspezifische Regeln
  • Claude führt mehrere CLAUDE.md-Dateien zusammen und wendet sie gemeinsam an
  • Empfohlene Inhalte sind Build- und Testbefehle, wichtige Architekturentscheidungen, nicht intuitive Einschränkungen sowie Regeln für Benennung und Fehlerbehandlung
  • Es wird empfohlen, unter 200 Zeilen zu bleiben, da übermäßige Länge Claudes Befolgung der Anweisungen verschlechtert

• CLAUDE.local.md — persönliche Overrides

  • Eine Datei, mit der sich persönliche Präferenzen getrennt von teamweiten Regeln abbilden lassen
  • Wenn im Projekt-Root eine CLAUDE.local.md erstellt wird, liest Claude sie ebenfalls mit
  • Sie wird automatisch in .gitignore aufgenommen und nicht ins Repository committet

• rules/ Ordner — modulares Regelmanagement

  • Wenn CLAUDE.md zu groß wird, kann es zur Verwaltung in den Ordner .claude/rules/ aufgeteilt werden
  • Jede Regeldatei ist nach Themen getrennt, was die Wartung erleichtert
    • Beispiel: code-style.md, testing.md, api-conventions.md, security.md
  • Mit dem Feld paths im YAML-Frontmatter lassen sich Regeln festlegen, die nur für bestimmte Pfade gelten
    • Beispiel: API-Regeln nur auf den Pfad src/api/**/*.ts anwenden
  • Regeln ohne Pfadangabe werden in allen Sitzungen immer geladen

• commands/ Ordner — benutzerdefinierte Slash-Befehle

  • Jede Markdown-Datei im Ordner .claude/commands/ wird als Slash-Befehl (/) registriert
    • Beispiel: review.md → /project:review, fix-issue.md → /project:fix-issue
  • Mit der !-Backtick-Syntax lassen sich Ergebnisse von Shell-Befehlen in den Claude-Prompt einfügen
    • Beispiel: !git diff main...HEAD
  • Mit der Variablen $ARGUMENTS können beim Ausführen des Befehls Argumente übergeben werden
    • Beispiel: /project:fix-issue 234 → lädt automatisch den Inhalt von GitHub-Issue 234
  • Projektbefehle werden mit dem Team geteilt; persönliche Befehle werden in ~/.claude/commands/ gespeichert und sind in allen Projekten verfügbar

• skills/ Ordner — automatisch ausgeführte Workflows

  • Funktioniert als Workflow ähnlich zu Befehlen, der jedoch automatisch ausgelöst wird
  • Claude analysiert den Gesprächsinhalt und führt ihn in passenden Situationen automatisch aus
  • Jede Skill wird durch die Datei SKILL.md in einem Unterordner definiert; per YAML-Frontmatter werden Trigger-Bedingungen und erlaubte Tools festgelegt
    • Beispiel: Die Skill security-review wird bei sicherheitsbezogenen Gesprächen automatisch ausgeführt
  • Ein Skill-Ordner kann zusätzliche Dokumente oder Vorlagendateien wie DETAILED_GUIDE.md enthalten
  • Persönliche Skills werden in ~/.claude/skills/ gespeichert und sind global verfügbar

• agents/ Ordner — spezialisierte Sub-Agenten

  • Im Ordner .claude/agents/ werden Sub-Agenten (Personas) für bestimmte Rollen definiert
  • Jeder Agent verfügt über einen eigenen System-Prompt, ein eigenes Modell und eigene Tool-Zugriffsrechte
    • Beispiel: code-reviewer.md, security-auditor.md
  • Über das Feld tools lässt sich der Zugriff auf verfügbare Tools einschränken, um Sicherheit und Rollentrennung umzusetzen
  • Über das Feld model kann ein für die Aufgabe passendes Claude-Modell gewählt werden, z. B. Haiku, Sonnet oder Opus
  • Claude kann den jeweiligen Agenten bei Bedarf in einem separaten Kontext ausführen und anschließend nur die Ergebnisse zusammengefasst berichten

• settings.json — Berechtigungen und Projekteinstellungen

  • .claude/settings.json definiert Berechtigungen für die Ausführung von Befehlen und den Bereich des Dateizugriffs für Claude
  • Das Feld $schema unterstützt Autovervollständigung und Validierung in VS Code und ähnlichen Tools
  • Die Liste allow legt automatisch genehmigte Befehle fest, die Liste deny vollständig blockierte Befehle
    • Beispiel: erlaubt — Bash(npm run *), Read, Write, Edit
    • blockiert — Bash(rm -rf *), Bash(curl *), Lesen von .env-Dateien
  • Für Befehle, die in keiner Liste stehen, wird vor der Ausführung eine Bestätigung des Nutzers angefordert
  • Persönliche Änderungen an Berechtigungen werden in .claude/settings.local.json gespeichert und nicht in Git aufgenommen

• ~/.claude/ Ordner — globale Einstellungen und Speicher

  • ~/.claude/CLAUDE.md enthält persönliche Anweisungen, die für alle Projekte gemeinsam gelten
  • ~/.claude/projects/ speichert projektbezogene Sitzungsverläufe und automatischen Speicher
    • Claude behält dabei gelernte Befehle, Muster und strukturelle Erkenntnisse bei
    • Abfrage und Bearbeitung sind mit dem Befehl /memory möglich
  • ~/.claude/commands/, ~/.claude/skills/, ~/.claude/agents/ sind Speicherorte für globale persönliche Befehle, Skills und Agenten

• Beispiel für die Gesamtstruktur

  your-project/  
  ├── CLAUDE.md  
  ├── CLAUDE.local.md  
  └── .claude/  
      ├── settings.json  
      ├── settings.local.json  
      ├── commands/  
      ├── rules/  
      ├── skills/  
      └── agents/  
  ~/.claude/  
  ├── CLAUDE.md  
  ├── settings.json  
  ├── commands/  
  ├── skills/  
  ├── agents/  
  └── projects/  
  

• Erste Einrichtungsschritte

  • Schritt 1: Mit dem Befehl /init eine grundlegende CLAUDE.md erzeugen und nur die Kernelemente behalten
  • Schritt 2: .claude/settings.json erstellen und Regeln für erlaubte und blockierte Ausführung definieren

  • Schritt 3:Befehle hinzufügen, die zu häufig genutzten Workflows passen (z. B. Code-Review, Issue-Fix)

    • Schritt 4: Wenn CLAUDE.md zu groß wird, in .claude/rules/ aufteilen
    • Schritt 5: Persönliche Präferenzregeln in ~/.claude/CLAUDE.md ergänzen

Zentrale Erkenntnisse

• Der Ordner .claude/ ist ein Protokoll, das Claude die Identität und Regeln eines Projekts vermittelt
• CLAUDE.md ist die wichtigste Datei; je klarer sie definiert ist, desto stärker wird Claudes Produktivität maximiert
• Die übrigen Komponenten bilden eine ergänzende Optimierungsschicht und lassen sich schrittweise erweitern
• Klare Konfigurationen führen zu weniger Korrekturanfragen durch Claude und effizienterer Zusammenarbeit

Zusätzliche Diskussion

• Die deny-Liste in settings.json ist bei menschlicher Nutzung sicher, benötigt im Agent-Modus jedoch zusätzlichen Schutz, da dort Bash-Zugriff möglich ist
• OneCLI bietet auf Netzwerkebene eine Proxy-Schicht, die Credential-Tokens ersetzt, um das Offenlegen von Geheimnissen zu verhindern
• Künftig könnte es notwendig sein, eigene .claude-Einstellungen nur für den Agent-Modus einzuführen, etwa getrennte Regeln, Berechtigungen und Skills
• Laut aktueller Dokumentation werden Befehle (commands) und Skills (skills) zusammengeführt: .claude/commands/deploy.md und .claude/skills/deploy/SKILL.md erzeugen beide denselben Befehl /deploy, wobei Skills Zusatzfunktionen wie Hilfsdateien und automatische Trigger unterstützen

[GN⁺]

Hacker-News-Kommentare

• Das Bauen von Toolkits für AI-Agenten fühlt sich an wie die Suche nach dem perfekten Produktivitäts-Setup.
  Man schaut Blogposts und YouTube-Videos und baut sich Routinen, aber am Ende kommt oft die Person weiter, die einfach konsequent mit einer simplen To-do-Liste arbeitet.
  Meiner Erfahrung nach funktioniert der einfache Ansatz immer noch am besten: Plain Claude planen und prüfen lassen und dann ausführen lassen.

  • Bei großen Codebasen oder verteilten Systemen sieht die Sache anders aus.
    Die technischen Fähigkeiten eines Agenten, Daten zu pipen, Requests zu erstellen, Systeme zu verfolgen und Code zu aktualisieren, erhöhen die Entwicklungseffizienz sprunghaft.
    Bei Code im Umfang von 10 Millionen Zeilen hat sich die Produktivität deutlich verbessert, und der eigentliche Anteil der Codegenerierung liegt dabei bei unter 5 %.
    Der Großteil kommt von der Fähigkeit, schnell Toolchains für Tests und Validierung zu bauen.
  • Viele Leute tappen in diese Falle und geben Geld aus.
    Tatsächlich kann man mit AI schon sehr viel erreichen, wenn man klar weiß, was man will, und es gut kommunizieren kann.
    Die meisten können das nicht. Deshalb wird der Planungsprozess zu einer Abkürzung für besseres Verständnis.
  • Als PM hoffe ich, dass Agenten Zeit sparen und einen Zinseszinseffekt bei der Ausgabe (compounding) erzeugen.
    Aber es ist ineffizient, in jeder Session wieder Kontext zu wiederholen und .md-Dateien zu kopieren.
    Mein aktuelles Ziel ist, genau diese Wiederholungen zu eliminieren.
    Mich interessiert, wie andere ihre „context bank“ mit angesammeltem Kontext verwalten — etwa Basisinfos wie „meine Rolle, mein Produkt, neueste Dokumente“.
    Es gibt viele doppelte und veraltete Dokumente, deshalb kann ich nicht einfach den gesamten Drive anbinden.
    Wenn derselbe Kontext mehr als zweimal auftaucht, frage ich mich, ob ich eine Skill-Datei daraus machen sollte oder ob ich die Dokumente sammeln und in einem Ordner verwalten sollte.
  • Ich habe Ähnliches erlebt. Die meisten Artefakte, die während der Arbeit entstehen, werden später weggeworfen.
    Überkonfiguration (over-configuration) führt zu Qualitätsverlust und Loop-Problemen.
    Weil die Modelle immer besser werden, können Anweisungen, die früher nötig waren, die Leistung heute sogar behindern.
    Ich habe auch gehört, dass das Anthropic-Team alle 30 Tage claude.md zurücksetzt.
  • Umgekehrt arbeite ich gerade an einem Projekt, bei dem ich eine lokale Buchhaltungs-API integrieren muss, und das ist eine komplett benutzerdefinierte API, die das LLM nicht kennt.
    Deshalb habe ich Claude einen MCP-Server bauen lassen, und jetzt automatisiert er die Buchhaltungsaufgaben.
    Nach dem Monatsabschluss habe ich Claude die wichtigsten Aufgaben extrahieren und als Skill anlegen lassen, und jetzt arbeitet es, als hätte ich einen Junior-Buchhalter.
    Benutzerdefinierte MCPs und Skills sind aus meiner Sicht wirklich nützlich.

• Es wirkt so, als würden viele Menschen vor dem Einstieg ins agentische Coden erst einmal eine riesige Wand an Konfiguration aufbauen.
  Aber am Anfang sollte man besser mit leerer .claude und AGENTS.md starten und direkt lernen, wie man damit umgeht.

  • Ich finde sogar, man sollte nur selbst erstellte Skills verwenden.
    Wenn man wahllos fremde Skills installiert, steigt die Nichtdeterministik (nondeterminism) und außerdem wird das Kontextfenster verschwendet.
    Als Ausnahme würde ich höchstens playwright-cli von extern empfehlen.
  • In großen Teams braucht man gewisse Guardrails (Regeln).
    Wenn man zum Beispiel so konfiguriert, dass Vorbedingungen geprüft werden, wie in dieser Regel, ist das stabiler.
    Ich glaube, auch Security-Teams würden so einen Ansatz bevorzugen.
    Ich habe beim Definieren von Regeln ebenfalls dafür gesorgt, dass Claude nicht ohne GPG-Signatur committet.
    Solche Regeln sind aber nicht statisch, sondern müssen sich ständig weiterentwickeln.
  • Dieser Beitrag fordert keine riesige Konfiguration.
    Im Gegenteil: Er betont immer wieder, dass man klein anfangen und alles kurz halten soll.
    Selbst Anfänger helfen schon ein paar zusätzliche Zeilen in AGENTS.md, damit die AI die Absicht des Nutzers besser versteht.
    Ein simples Setup reduziert AI-Fehlverhalten erheblich.
  • Allein Code zu bearbeiten und als Team an einem gemeinsamen Projekt zu arbeiten, sind völlig unterschiedliche Dinge.
    Wenn jeder Entwickler agentische Tools nutzt, verändert das die Art der Zusammenarbeit insgesamt.
  • Schon allein der plan mode löst 90 % der Probleme.
    Ich glaube, diese Diskussionen über komplexe Setups werden mit besseren Modellen innerhalb eines Jahres größtenteils verschwinden.

• Der Ordner ~/.claude/projects ist der wirklich interessante Teil.

• Bei mir waren die Ergebnisse umso besser, je weniger unnötige Konfiguration es gab.
  Menschen neigen dazu, Dokumente zu stark zu reglementieren, aber AI ist wie ein kompetenter, aber nervöser Erwachsener.
  Gibt man zu viele Anweisungen, wird sie eher dümmer.

• Dieser Beitrag wirkt eher generiert als aus echter Erfahrung entstanden.
  Claude.md sollte kurz sein und nur ein paar Links enthalten.
  Wenn sich Kontext ansammelt, wird die Leistung schlechter, daher sollte man Planung und Implementierung trennen und jedes Mal neu starten.

  • Der Einstieg klang stilistisch so sehr nach Claude, dass ich dachte, ich könnte auch einfach direkt Claude fragen.
  • Der Unterschied zwischen Skills und Commands ist verwirrend.
    Es ist nicht klar, ob Skills immer im Kontext sind und Commands nur manuell aufgerufen werden können.

• Es wäre gut, wenn alle Modellanbieter einen Standardsatz an Dateien gemeinsam nutzen würden.
  Dann wäre der Wechsel zwischen Claude, Codex, Cursor und Opencode deutlich einfacher.

  • Allerdings hat die Kombination aus Modell und Harness großen Einfluss auf das Ergebnis.
    Selbst beim gleichen Prompt reagieren Modelle unterschiedlich, deshalb muss Prompt-Tuning modellabhängig sein.
  • Man kann eine agents.md erstellen, auf die Claude.md verweist, und sie zwischen Ordnern per Symlink (sync) verbinden.
    Perfekt ist das nicht, aber es funktioniert ziemlich gut.
  • Im Moment ist es wie in der frühen Browser-Ära. Gerade weil noch nichts standardisiert ist, konnten Innovationen wie AJAX entstehen.
    Deshalb ist die heutige Vielfalt eher etwas Positives.
  • Ich nutze vorübergehend dotagents by Sentry, um dieses Problem zu lösen.
  • Ich glaube nicht, dass Modellanbieter überhaupt einen Grund haben, den Wechsel absichtlich einfacher zu machen.

• Die Alternativdokumentation von Claude Fast ist sehr hilfreich.
  Ich sehe keinen Grund, die Definition des .claude-Ordners nicht zu mögen.
  Man kann den Hauptagenten die Dateien direkt schreiben lassen, sie iterativ aktualisieren und so ein selbstverbesserndes System aufbauen.
  Im Moment repliziert, bewertet und aktualisiert .claude sich selbst — ich programmiere also nicht Code, sondern programmiere .claude.

  • Kurz gesagt ist CLAUDE.md kein einfaches Dokument, sondern das Betriebssystem von Claude.
    Es definiert Verhalten, delegiert Wissen an Skills und schafft ein System, das sich mit der Zeit selbst verbessert.

• Eine Hürde, die viele nicht kennen: Selbst wenn man Claude Dateien ändern lässt, wird das nicht übernommen, wenn man nicht ausdrücklich sagt, dass es sie erneut lesen soll.
  Wenn man zum Beispiel CLAUDE.md neu geschrieben hat, muss man Claude dazu bringen, es zu reloaden, damit es die neuen Anweisungen erkennt.

• Im Ordner ~/.claude/plans werden Plan-Dateien gespeichert, die im plan mode erzeugt wurden.
  Ich öffne dieses Verzeichnis oft, um etwas zu sichern oder später nachzuschlagen.

• Ich habe mein Setup rund um globale MCP-Server und einen Composite Agent aufgebaut.
  Jeder MCP-Server definiert einen Satz von Tools, und der Agent arbeitet darin autonom.
  .agent.md ist lediglich ein Dokument, das die verfügbaren Tools beschreibt; komplexe Konfiguration ist unnötig.
  Skills oder wiederverwendbare Prompts haben aus meiner Sicht wenig Wert.
  Die Modelle sind schon intelligent genug; was man braucht, ist Orientierung.