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

Was gehört in den .claude-Ordner? Ordnerstruktur mit CLAUDE.md, commands, rules, skills und settings.json erklärt, plus Setup-Check fürs Team.

Veröffentlicht: 2026-04-01. Aktualisiert: 2026-09-22.

Warum der .claude/-Ordner entscheidend ist

Claude Code kann ein Repository selbst untersuchen. Ohne dokumentierte Projektregeln muss es Architekturentscheidungen und Teamkonventionen aber häufig neu erschließen.

Ein gemeinsames Setup macht Erwartungen und Prüfungen explizit. Es garantiert keine fehlerfreien Ergebnisse; Tests und menschliches Review bleiben Teil des Ablaufs.

Wie installiere und prüfe ich Claude Code?

Nutzen Sie den zu Ihrem Betriebssystem passenden Weg aus der offiziellen Installationsanleitung. Prüfen Sie vor der Installation Herkunft und Berechtigungen eines Installers; führen Sie ihn nicht mit pauschalen Administratorrechten aus. Verwenden Sie zunächst ein Test-Repository ohne produktive Zugangsdaten.

Nach der Installation:

claude --version
claude doctor
claude

Starten Sie Claude Code im Projektordner und melden Sie sich mit dem vorgesehenen Unternehmenskonto an. Die erste Aufgabe sollte nur lesen: „Erkläre die Projektstruktur und nenne die vorhandenen Testbefehle. Ändere nichts.“ Prüfen Sie danach, ob Claude die richtige Codebasis und Ihre Regeln berücksichtigt.

Die Struktur im Überblick

your-project/
├── CLAUDE.md                 # Team-Anweisungen (committet)
├── CLAUDE.local.md           # Persönliche Overrides (gitignored)
└── .claude/
    ├── settings.json         # Berechtigungen + Config (committet)
    ├── settings.local.json   # Persönliche Permissions (gitignored)
    ├── commands/             # Custom Slash Commands
    │   ├── team-review.md    → /team-review
    │   ├── fix-issue.md      → /fix-issue
    │   └── deploy.md         → /deploy
    ├── rules/                # Modulare Anweisungen
    │   ├── code-style.md
    │   ├── testing.md
    │   └── api-conventions.md
    ├── skills/               # Auto-invoked Workflows
    │   ├── security-review/
    │   │   └── SKILL.md
    │   └── deploy/
    │       └── SKILL.md
    └── agents/               # Subagent-Personas
        ├── code-reviewer.md
        └── security-auditor.md

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:

# 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: Das Team pflegt eine gemeinsame Quelle. Ändern sich Architektur oder Testbefehle, müssen auch die Anweisungen aktualisiert werden.

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 - /team-review:

# 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

Mit /team-review rufe ich dieselbe Prüfliste auf. Das vereinheitlicht den Prüfauftrag, ersetzt aber weder Tests noch eine unabhängige Kontrolle der Ergebnisse. Für neue Abläufe empfiehlt Anthropic inzwischen Skills statt des älteren Commands-Formats.

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

Eine Skill-Datei beschreibt einen wiederverwendbaren Ablauf. Name und Beschreibung helfen Claude Code, sie passend auszuwählen; ein direkter Aufruf macht den Einsatz überprüfbar.

Beispiel - .claude/skills/security-check/SKILL.md, aufrufbar mit /security-check:

---
name: security-check
description: Prüft einen Diff auf Sicherheitsrisiken bei Auth, Daten und Schnittstellen.
---
# 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.

Prüfen Sie die aktiven Regeln mit /permissions. Eine Anweisung in CLAUDE.md ist keine technische Zugriffssperre. Auch eine Bash-Deny-Regel deckt nicht automatisch jede alternative Schreibweise desselben Befehls ab. Für belastbare Grenzen brauchen Sie passende Sandbox-, Dateisystem- und Kontoberechtigungen. Testen Sie erlaubte und gesperrte Aktionen mit harmlosen Testdaten; halten Sie produktive Secrets aus dem Test-Repository heraus.

Vom Setup zum Team-Workflow

Ein gutes .claude/-Setup reduziert wiederholte Erklärungen und macht den Prüfablauf nachvollziehbar. Zur Abnahme gehören eine begrenzte Änderung, erfolgreiche Projekttests und ein Review des tatsächlichen Diffs.

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.

Wie wird daraus ein lauffähiges KI-System?

Claude Code unterstützt die Entwicklung; es ist nicht automatisch das fertige Produkt für Ihre Nutzer. Zur KI-Produktentwicklung gehören der konkrete Arbeitsablauf, Datenquellen, Schnittstellen, Rollen, Fehlerbehandlung, Tests und die Übergabe. Claude Code oder Codex können darin Entwicklungswerkzeuge sein. Ein dauerhaft laufender Hermes Agent hat andere Betriebsanforderungen.

Ein möglicher Anwendungsfall ist ein Unternehmens-PersonalOS: eine gemeinsame Kontextschicht mit nachvollziehbaren Entscheidungen und kontrolliertem Zugriff für mehrere Agenten. Ob das für Ihren Prozess sinnvoll ist, kläre ich vor der Umsetzung. Bei unklarem Umfang ist die Produkt-Discovery der Einstieg.

Kostenloses Erstgespräch buchen — oder das Vorhaben schriftlich schildern.

Quellen und Stand

Fachlich geprüft am 22. September 2026: Installation, Skills und Commands, Berechtigungen und Sandboxing. Installationswege und verfügbare Funktionen können sich mit neuen Versionen ändern.

Häufige Fragen

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.

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.

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.

Wie erstelle ich Custom Commands?

Für neue Abläufe empfiehlt Anthropic Skills: .claude/skills/team-review/SKILL.md wird über /team-review aufgerufen. Bestehende Markdown-Dateien unter .claude/commands/ funktionieren weiterhin. Plugin-Skills haben einen eigenen Namensraum.

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.

• KI-Produktentwicklung
• Codex
• Hermes Agent
• Unternehmens-PersonalOS
• Produkt-Discovery
• Zur Blog-Uebersicht
• Leistungen & Use Cases