Vitalij Bojatschkin

Der .claude/-Ordner erklärt: So wird Claude Code zum Teamwerkzeug

Q: Was ist der .claude/-Ordner?

Der .claude/-Ordner ist das Konfigurationsverzeichnis für Claude Code in einem Projekt. Er enthält Projektanweisungen (CLAUDE.md), Berechtigungen (settings.json), wiederverwendbare Workflows (Commands, Rules, Skills) und persönliche Overrides. Er wird ins Git-Repository committet und ist damit für das gesamte Team verfügbar.

Q: Was gehört in die CLAUDE.md?

In die CLAUDE.md gehören: Architekturentscheidungen, Coding-Konventionen, wichtige Befehle (Build, Test, Deploy), Review-Erwartungen, Projektstruktur und bekannte Fallstricke. Alles, was ein neuer Entwickler — oder ein KI-Tool — über das Projekt wissen muss.

Q: Was ist der Unterschied zwischen CLAUDE.md und CLAUDE.local.md?

CLAUDE.md wird committet und gilt für das gesamte Team. CLAUDE.local.md ist gitignored und enthält persönliche Präferenzen wie bevorzugten Editor-Style, Sprache für Commit-Messages oder individuelle Shortcuts. So bleiben Team-Standards sauber, ohne persönliche Vorlieben zu blockieren.

Q: Wie erstelle ich Custom Commands?

Custom Commands liegen als Markdown-Dateien im Ordner .claude/commands/. Jede Datei wird als Slash-Command verfügbar — z.B. wird review.md zu /project:review. Der Inhalt der Datei ist der Prompt, den Claude Code bei Aufruf ausführt.

Q: Muss ich den .claude/-Ordner ins Git committen?

Ja, der .claude/-Ordner sollte committet werden — mit Ausnahme der .local-Dateien (CLAUDE.local.md, settings.local.json), die per .gitignore ausgeschlossen werden. So hat jeder im Team denselben Projektkontext.

CLAUDE.md, Commands, Rules, Skills und Permissions — wie der .claude/-Ordner Claude Code von einem Chat-Tool zum reproduzierbaren Entwicklungswerkzeug macht.

import BlogFAQ from '../../src/components/BlogFAQ'; import KeyTakeaways from '../../src/components/KeyTakeaways';

<KeyTakeaways items= /

<p data speakable Der .claude/ Ordner ist der Grund, warum Claude Code bei manchen Teams hervorragend funktioniert und bei anderen nach zwei Wochen wieder vergessen wird. Er verwandelt Claude Code von einem generischen Chat Tool in ein projektspezifisches Entwicklungswerkzeug. In diesem Guide zeige ich die vollständige Struktur, erkläre jede Komponente und gebe konkrete Beispiele aus meinen Cloud und KI Projekten. </p

Warum der .claude/ Ordner entscheidend ist

Wer Claude Code ohne Konfiguration nutzt, bekommt generische Antworten. Das Tool kennt weder die Architektur noch die Konventionen eines Projekts. Jeder Prompt startet bei null.

Mit einem sauberen .claude/ Setup ändert sich das grundlegend: Claude Code kennt den Tech Stack, weiß welche Befehle es gibt, hält sich an Coding Standards und führt wiederkehrende Aufgaben über vordefinierte Workflows aus. Das Ergebnis sind reproduzierbare, konsistente Ergebnisse — unabhängig davon, wer im Team Claude Code nutzt.

Die Struktur im Überblick

CLAUDE.md — das Herzstück

Die CLAUDE.md ist die wichtigste Datei im gesamten Setup. Sie ist das Erste, was Claude Code beim Start eines Projekts liest. Alles, was hier steht, wird als Projektkontext behandelt.

Was hineingehört:

Architekturentscheidungen und Tech Stack, Coding Konventionen (Namensgebung, Dateistruktur, Test Patterns), wichtige Befehle (Build, Test, Lint, Deploy), Review Erwartungen und Qualitätsstandards, bekannte Fallstricke und Anti Patterns sowie Projektstruktur mit Erklärung der wichtigsten Verzeichnisse.

Praxisbeispiel aus einem meiner AWS Projekte:

```markdown CLAUDE.md

Tech Stack React 19 + TypeScript 5.8 + Vite 7 Tailwind CSS 3 + shadcn/ui Vitest für Unit Tests

Befehle npm run check Lint + Type Check + Tests (vor jedem Push) npm run build Production Build

Konventionen PascalCase für Komponenten Tests in tests / neben der Quelldatei Alle Texte auf Deutsch (lang="de") "KI" statt "AI" in allen Texten ```

Der entscheidende Punkt: Diese Informationen schreibt man einmal auf und erklärt sie nie wieder. Jeder im Team — und Claude Code — arbeitet mit demselben Kontext.

Lokale Dateien: Team Standards und persönliche Präferenzen trennen

CLAUDE.local.md und settings.local.json werden nicht committet. Hier leben persönliche Vorlieben: bevorzugte Sprache für Commit Messages, individuelle Editor Shortcuts, zusätzliche Berechtigungen für lokale Experimente.

Das klingt nach einem Detail, löst aber ein echtes Problem: Ohne diese Trennung landen persönliche Präferenzen in der Team Konfiguration — oder Team Standards werden durch individuelle Overrides verwässert.

Commands: Wiederholtes Prompting eliminieren

Jede Aufgabe, die ich mehr als zweimal beschreibe, wird zum Command. Ein Command ist eine Markdown Datei im .claude/commands/ Ordner, die als Slash Command verfügbar wird.

Beispiel — /project:review:

```markdown Code Review

Führe ein Review des aktuellen Diffs durch:

1. Prüfe TypeScript Typen und Null Safety 2. Prüfe Naming Konventionen (PascalCase Komponenten, camelCase Hooks) 3. Prüfe Test Abdeckung für neue Funktionen 4. Prüfe Accessibility (alt Texte, semantische HTML Elemente) 5. Fasse Findings als priorisierte Liste zusammen ```

Statt jedes Mal den gleichen Prompt zu schreiben, tippe ich /project:review und bekomme ein konsistentes Review — unabhängig davon, ob ich müde bin, in Eile oder an einem anderen Projekt gearbeitet habe.

Rules: Modulare Regeln für verschiedene Kontexte

Rules sind Anweisungsdateien, die Claude Code automatisch berücksichtigt. Im Gegensatz zur CLAUDE.md sind sie modular organisiert — eine Datei pro Thema.

Typische Rules in meinen Projekten:

code style.md definiert Formatierung, Import Reihenfolge und Naming Patterns. testing.md legt fest, welche Tests erwartet werden (Unit, Integration, E2E) und welche Patterns zu verwenden sind. api conventions.md beschreibt REST Konventionen, Error Handling und Response Formate.

Skills: Automatisierte Workflows

Skills sind der leistungsfähigste Teil des .claude/ Systems. Eine Skill Datei beschreibt einen kompletten Workflow, den Claude Code automatisch erkennt und ausführt.

Beispiel — Security Review Skill:

```markdown Security Review

Trigger: Wenn Code sicherheitsrelevante Änderungen enthält (Auth, IAM, Secrets, API Endpunkte)

Workflow: 1. Prüfe auf hardcodierte Secrets oder Credentials 2. Validiere IAM Policies nach Least Privilege 3. Prüfe Input Validierung an allen Endpunkten 4. Erstelle Security Findings als priorisierte Liste ```

Settings und Permissions: Vertrauen durch Klarheit

settings.json definiert, was Claude Code darf und was nicht. Das ist kein Nebenschauplatz — es ist die Grundlage dafür, dass Claude Code zuverlässig arbeitet, statt unkontrolliert Dateien zu ändern.

Klare Berechtigungen schaffen Vertrauen im Team. Wenn jeder weiß, dass Claude Code nur in src/ schreiben darf und niemals .env Dateien anfasst, sinkt die Hemmschwelle für den produktiven Einsatz erheblich.

Vom Setup zum Team Workflow

Ein gutes .claude/ Setup löst drei Probleme gleichzeitig: Es eliminiert wiederholtes Prompting, es macht KI Ergebnisse reproduzierbar, und es ermöglicht einheitliche Qualität im gesamten Team.

In meiner Arbeit als Cloud Engineer ist das .claude/ Setup inzwischen Teil des Projekt Onboardings. Jedes neue Projekt bekommt eine CLAUDE.md, bevor die erste Zeile Code geschrieben wird.

Wer Unterstützung beim Aufbau eines produktiven Claude Code Setups für sein Team sucht, findet mehr Details auf meiner Service Seite für Claude Code Onboarding.

<BlogFAQ faq= /