Das .claude/-Verzeichnis ist keine Black Box – es ist dein Steuerstand

Es gibt einen Moment, den fast jeder kennt, der Claude Code ernsthaft zu nutzen beginnt: Man sieht irgendwann im Projekt-Root ein .claude/-Verzeichnis auftauchen. Man öffnet es kurz. Schaut rein. Schliesst es wieder. Und macht weiter wie bisher.

Das ist ein teurer Fehler – nicht in Geld, sondern in verschwendeter Kontrolle.

Akshay Pachaar hat letzte Woche eine exzellente Anatomy of the .claude/ folder veröffentlicht, die systematisch aufschlüsselt, was in diesem Verzeichnis lebt und warum es wichtig ist. Ich empfehle, das Original zu lesen. Was ich hier tun möchte, ist eine andere Frage zu stellen: Was verändert sich in der Art, wie wir mit KI-Tools arbeiten, wenn wir diesen Ordner ernst nehmen?

Claude verhält sich nicht zufällig — es reagiert auf Kontext

Die erste mentale Verschiebung, die notwendig ist: Claude Code ist kein deterministisches Tool wie ein Linter oder ein Compiler. Es ist ein kontextgesteuertes System. Das bedeutet: Wie es sich verhält, hängt direkt davon ab, was es über dein Projekt weiss.

Wer .claude/ ignoriert, überlässt diesen Kontext dem Zufall. Claude muss dann bei jeder Session von vorne schätzen, welche Konventionen gelten, welche Architekturentscheidungen getroffen wurden, was tabu ist. Das erklärt viele der frustrierenden Momente, die man aus der Arbeit mit LLM-Coding-Tools kennt: die Antwort war technisch korrekt, aber falsch für dieses Projekt.

CLAUDE.md löst genau das. Es ist kein Konfigurationsfile im technischen Sinne — es ist ein Briefing. Und wie jedes gute Briefing gilt: Je klarer und konziser, desto besser. Akshay empfiehlt unter 200 Zeilen. Ich würde noch weiter gehen: Wenn du mehr als 20 Minuten brauchst, um es zu schreiben, hast du noch nicht klar genug gedacht, was du eigentlich von Claude erwartest.

Der unterschätzte Vorteil: Teamwissen wird explizit

Es gibt einen zweiten, weniger offensichtlichen Grund, warum .claude/ wichtig ist — und der hat wenig mit KI zu tun.

Wenn du gezwungen bist aufzuschreiben, welche Architekturentscheidungen gelten, welche gotchas es gibt, welche Konventionen nicht verhandelbar sind — dann externalisierst du implizites Teamwissen. Du machst sichtbar, was sonst nur in den Köpfen einzelner Senior-Entwickler lebt.

Das rules/-Verzeichnis ist dafür besonders elegant konzipiert: Modulare Markdown-Files, die sich per Pfad-Scope aktivieren. api-conventions.md lädt nur, wenn Claude in src/api/ arbeitet. Das ist nicht nur effizient für das Kontextfenster — es ist auch eine vernünftige Ownership-Struktur fürs Team. Wer für API-Design zuständig ist, pflegt genau eine Datei.

Das klingt nach Dokumentation. Es ist Dokumentation — nur mit direkten Auswirkungen auf das Verhalten deines KI-Tools.

Commands und Skills: Der Unterschied zählt

Hier ist ein Detail, das im Alltag zu Verwirrung führt: Der Unterschied zwischen Commands und Skills.

Commands sind explizit. Du tippst /project:review, und ein vordefinierter Prompt wird ausgeführt — angereichert mit Live-Daten aus Shell-Befehlen. Das ist Automatisierung: schnell, vorhersehbar, kontrolliert.

Skills sind implizit. Claude entscheidet selbst, ob ein Skill zur aktuellen Situation passt, und aktiviert ihn ohne dass du etwas eingibst. Das ist ein anderes Paradigma: weniger Kontrolle, mehr Autonomie — und damit höhere Anforderungen an die Qualität der Beschreibung in SKILL.md.

Meine Einschätzung: Für die meisten Teams sind Commands der bessere Einstieg. Sie sind transparent, nachvollziehbar und einfach zu debuggen. Skills machen Sinn, wenn du Workflows hast, die wirklich situativ-kontextuell sind — etwa ein Security-Review, der immer dann greifen soll, wenn jemand Authentifizierungslogik anfasst. Aber für ein /pr-review-Kommando, das du ohnehin bewusst auslösen willst, brauchst du keine Magie.

Agents: Isolation als Feature

Der Abschnitt über .claude/agents/ ist der, den ich am meisten unterschätzt hatte.

Die Idee ist nicht neu — Subagents, die spezialisierte Aufgaben in isolierten Kontexten übernehmen, gibt es als Konzept schon länger. Aber die Implementierung über einfache Markdown-Files mit YAML-Frontmatter ist bemerkenswert pragmatisch. Du definierst einen security-auditor-Agent, gibst ihm nur Read, Grep und Glob-Berechtigungen, wählst ein günstigeres Modell für die Exploration — und der Hauptkontext bleibt sauber.

Das Tool-Restriktionsfeld (tools: Read, Grep, Glob) ist dabei mehr als ein Sicherheitsfeature. Es ist auch eine Denkdisziplin: Was braucht dieser Agent wirklich? Ein Agent, der nur liest, kann nichts kaputt machen. Das ist eine Form von Software-Design, angewendet auf KI-Workflows.

settings.json: Security als explizite Entscheidung

Der allow/deny-Mechanismus in settings.json ist das Feld, das für Unternehmen und Teams am stärksten unterschätzt wird.

Die Standardeinstellung — “frag nach, wenn unklar” — ist ein vernünftiger Ausgangspunkt. Aber sobald Claude in CI/CD-Pipelines, automatisierten Workflows oder an kritischer Infrastruktur arbeitet, ist “frag nach” keine Option. Da muss explizit definiert sein, was erlaubt ist und was nicht.

"deny": [
  "Bash(rm -rf *)",
  "Bash(curl *)",
  "Read(./.env)",
  "Read(./.env.*)"
]

Das ist keine Paranoia. Das ist vernünftiges Boundary-Setting — das gleiche, das du für jeden anderen automatisierten Prozess in deiner Infrastruktur auch vornehmen würdest.

Was mich an diesem System überzeugt

Ich habe in den letzten Monaten verschiedene Wege beobachtet, wie Teams KI-Coding-Tools in ihre Workflows integrieren. Die häufigsten Muster:

1. Ad-hoc-Nutzung: Jeder prompt nach eigenem Gutdünken. Inkonsistente Ergebnisse, viel Frustration.
2. Prompt-Bibliotheken: Geteilte Prompts in Notion oder Confluence. Nicht kontextuell, schwer zu pflegen.
3. Code-Generator-Denken: Claude als Autocomplete auf Steroiden. Sinnvoll für repetitive Tasks, aber verschenkt das Potenzial.

Das .claude/-System ist etwas anderes: Es verschiebt die Konfiguration von Claude direkt ins Repository. Versioniert, reviewbar, dokumentierend. Das hat eine Qualität, die die anderen Ansätze nicht haben: es skaliert mit dem Projekt.

Ein Team, das sein .claude/-Verzeichnis gut pflegt, gibt jedem neuen Entwickler — ob menschlich oder KI — vom ersten Tag an denselben Kontext. Das ist der eigentliche Wert.

Wo anfangen?

Wenn du Claude Code nutzt und .claude/ bisher ignoriert hast:

Fang mit /init an. Claude analysiert dein Projekt und generiert einen Starter-CLAUDE.md. Dann: kürzen, schärfen, committen.

Dann settings.json mit einem vernünftigen deny-Block für sensible Dateien und destruktive Befehle.

Dann — erst wenn du merkst, dass du dieselben Prompts immer wieder tippst — ein paar Commands in .claude/commands/.

Der Rest ergibt sich. Aber diese drei Schritte alleine werden die Qualität deiner Claude-Code-Sessions spürbar verändern.

Dieser Beitrag ist inspiriert von Akshay Pachaars Thread Anatomy of the .claude/ folder vom 21. März 2026 – sehr empfehlenswert als tiefergehende technische Referenz.