Claude Code im Team, wie ihr CLAUDE.md gemeinsam pflegt ohne dass es zur Muelltonne wird

Solo mit Claude Code läuft alles glatt. Du hast Deine CLAUDE.md, Du kennst jeden Hook, Du weißt warum die /deploy Slash-Command genau so aufgebaut ist. Dann kommt der erste Kollege ins Repo, klont, öffnet Claude Code, und auf einmal ist der Output anders. Die Antworten lesen sich anders, die Code-Style-Konventionen werden ignoriert, der /deploy Slash-Command erzeugt einen Branch der niemand erwartet hat.

Das ist nicht Claude Code kaputt. Das ist fehlende Team-Hygiene. CLAUDE.md, Hooks und Slash-Commands sind genau die Stellen wo Solo-Workflows kippen sobald mehr als eine Person dranhaengt. Dieses Playbook bringt 10 Schritte wie ihr das sauber teilt, ohne dass jeder seine privaten Notizen aus Versehen committed und ohne dass eine Person heimlich die geteilte Config verbiegt.

Ich gehe davon aus dass ihr Git nutzt und einen GitHub- oder GitLab-Workflow habt. Wer noch nicht mit Git für KI vertraut ist, schaut vorher ins Mini-Modul L1-08 bis L1-10.

Schritt 1, zwei CLAUDE.md trennen, geteilt und privat

Erste Regel. Es gibt zwei Plaetze für CLAUDE.md, und beide haben einen anderen Job. Das geteilte CLAUDE.md liegt im Repo-Root und wird committed. Das private CLAUDE.md liegt in ~/.claude/CLAUDE.md auf Deinem Rechner und wird nie committed.

Das geteilte File enthält alles was für das Team gilt. Tech-Stack, Code-Style, Branch-Konventionen, Test-Befehle, Deploy-Wege. Das private File enthält Deine persönlichen Vorlieben. Dass Du beim Pair-Coding gerne mehr Erklärungen hast, dass Du auf Deinem Rechner Pnpm statt Npm nutzt, dass Du den claude --print Modus nicht magst.

Wenn Du das mischst, kommt Chaos. Eine Person findet "schreibe immer Kommentare auf Englisch" im Repo-CLAUDE.md, eine andere hätte das nie so geschrieben. Trennen, sofort und konsequent.

Schritt 2, das Repo-CLAUDE.md kurz halten

Versuchung ist groß dass jeder seine Lieblings-Notiz reinkippt. Nach drei Wochen hat das File 800 Zeilen, niemand liest es, Claude Code lädt es trotzdem in jeden Context. Das ist Token-Verschwendung und Drift garantiert.

Halt das Repo-CLAUDE.md unter 200 Zeilen. Was nicht reinpasst landet in docs/claude/, also einer eigenen Doku-Struktur die Claude bei Bedarf liest. Das Repo-CLAUDE.md verweist dann auf diese Files mit Pfaden statt Inhalt zu duplizieren. Spart Tokens und macht die Quelle der Wahrheit klar.

Faustregel. Wenn Du nicht in 5 Minuten das Repo-CLAUDE.md von vorne bis hinten gelesen hast, ist es zu lang.

Schritt 3, Sektionen mit Verantwortlichkeiten

Strukturier das Repo-CLAUDE.md in Sektionen, und schreib hinter jede Sektion wer sie pflegt. Beispiel.

## Tech-Stack (Owner: alle)
- Next.js 16, Prisma 7, Postgres
- Pnpm für Package-Management
- Vitest für Tests

## Deploy-Workflow (Owner: Anna)
- main automatisch nach Vercel
- staging via `pnpm deploy:staging`

## Datenbank-Migrations (Owner: Tim)
- IMMER `prisma migrate dev --name <slug>` lokal
- NIEMALS `db push --force-reset` in CI

Wenn etwas im Repo-CLAUDE.md drinsteht ohne Owner, wird es nach drei Wochen niemand mehr aktualisieren. Mit Owner geht eine Person hin, prüft, und macht eine PR. Das gleiche Prinzip wie bei jeder Doku.

Schritt 4, .claude Verzeichnis ins Repo aufnehmen

Claude Code legt projektspezifische Skills, Slash-Commands und Hooks unter .claude/ im Repo ab. Das gehört in Git. Was nicht reingehoert sind die personalisierten Logs und Caches, also brauchst Du eine .gitignore Eintrag.

# .gitignore
.claude/cache/
.claude/sessions/
.claude/local-settings.json

Was committed wird sind .claude/skills/, .claude/commands/ und .claude/hooks/. Plus eine .claude/README.md die kurz erklärt was im Verzeichnis liegt und wer es pflegt.

Wenn Dein Team das nicht trennt, hat jeder andere Logs in Git und Pull-Requests werden zur Konflikt-Hoelle. Lieber jetzt sauber aufsetzen als nachher migrieren.

Schritt 5, eine Person ist Skill-Owner pro Projekt

Skills sind faehigkeits-ähnliche Add-Ons die Claude in einem Projekt benutzt. In einem Solo-Projekt schreibt jeder seine. Im Team-Projekt MUSS einer den Hut aufhaben. Sonst hat jeder eine eigene Variante von "Code-Review-Skill" und der Output ist nicht reproduzierbar.

Such Dir oder wählt eine Person als Skill-Owner. Diese Person merged neue Skills, prüft Konflikte und entfernt veraltete. Andere können vorschlagen, neue Skills entwerfen, aber das Mergen passiert über die eine Person. Klingt buerokratisch, ist aber genau das was Du nach drei Wochen Drift dankbar bist.

Schritt 6, Slash-Commands versionieren wie Code

Slash-Commands sind kleine Shortcuts wie /deploy oder /review-pr. Wenn Tim heute morgen /deploy ändert weil er einen Edge-Case hat, und Du nachmittags deployst, kann das schief gehen. Slash-Commands sind Code, also behandelt sie wie Code.

Drei Regeln. Erstens, jede Änderung an einem Slash-Command geht über eine Pull-Request, nicht direkt in main. Zweitens, im Commit-Message steht WAS sich geaendert hat, nicht nur "update deploy". Drittens, im Repo-CLAUDE.md gibt es eine Sektion die kurz erklärt was jeder geteilte Slash-Command tut.

Wenn ein Slash-Command nur für eine Person Sinn macht, gehört er in das private ~/.claude/commands/ Verzeichnis, nicht ins Repo.

Schritt 7, Hooks die Geld kosten getrennt halten

Hooks können API-Calls machen, also auch Geld kosten. Wenn jemand einen Hook baut der bei jedem Tool-Use Claude Haiku anruft, und der läuft ungefragt bei allen 5 Team-Mitgliedern den ganzen Tag, kann das ein paar Hundert Euro im Monat sein.

Markiert in der .claude/hooks/README.md welche Hooks Geld kosten und welche nicht. Geld-kostende Hooks sollten optional sein, also nur wer sie aktiviert hat sie laufen lassen. Geld-kostende Hooks im Repo-Default zu aktivieren ist eine kleine Diktatur.

Faustregel. Pro neuem Hook eine Schaetzung "kostet pro 100 Aufrufe ungefähr X Cent" in den Kommentar. Spart später die unangenehme Frage "warum ist die Anthropic-Rechnung diesen Monat 400 Euro hoch".

Schritt 8, Pull-Requests zu CLAUDE.md brauchen ein Review

Klingt selbstverständlich, ist es nicht. Viele Teams committen direkt in main wenn sich nur "die Notiz für Claude" ändert. Das führt zu Drift weil niemand die Änderung sieht.

Setz die Regel. CLAUDE.md, .claude/skills/, .claude/commands/ und .claude/hooks/ brauchen alle ein Code-Review wie normaler Code. Im Review-Comment kurz erklären warum die Änderung notwendig war. Wenn der Reviewer nicht versteht warum eine Skill-Änderung kommt, ist das ein Zeichen dass die Änderung wahrscheinlich kein Team-Konsens ist.

Bonus. Bei Änderungen am CLAUDE.md kannst Du im Review zusätzlich prüfen ob das File noch unter 200 Zeilen bleibt (siehe Schritt 2). Sonst kommt der Trash-Effekt.

Schritt 9, vierteljaehrliches Team-Putzen

Alle drei Monate macht ihr eine Stunde "CLAUDE.md Putztag". Zusammen am Bildschirm, ein Zoom-Call, ihr scrollt durch alles was sich an Claude-Config angesammelt hat. Was wird noch genutzt, was ist veraltet, was kann weg.

Mein Rhythmus dafür ist Mitte Januar, Mitte April, Mitte Juli, Mitte Oktober. Klingt selten, reicht aber. Was zwischen den Putztagen entsteht, wird in der Pull-Request gefangen. Was zwischen Mai und Juli aus dem Sinn fällt, faengt der Putztag.

Konkretes Vorgehen. Drei Spalten auf einem Whiteboard. Behalten, Ändern, Loeschen. Pro Skill, pro Slash-Command, pro Hook eine Karte, jeder votet, am Ende verschiebt einer die Karten in die jeweiligen Stapel. Loescht in einer einzigen Pull-Request, nicht in fünf einzelnen.

Schritt 10, Onboarding-Doku für neue Team-Mitglieder

Wenn Lisa am Montag ins Team kommt, soll sie nicht erst durch 200 Zeilen CLAUDE.md kraulen. Schreibt eine 30-Minuten-Onboarding-Doku in docs/claude/onboarding.md. Was muss Lisa lokal installieren, welche Variante von Claude Code (Pro oder API), welche Hooks soll sie aktivieren, welche kostenpflichtigen lieber nicht, welche Skills sind Pflicht und welche optional.

Plus ein Smoke-Test. Lisa macht am Ende des Onboardings eine Aufgabe wie "Beschreibe was in src/lib/auth.ts passiert mit der Hilfe von Claude Code". Wenn der Output nach Team-Standard aussieht, ist sie eingerichtet. Wenn nicht, fehlt etwas in ihrer lokalen Config und ihr könnt es jetzt fixen statt in zwei Wochen wenn sie schon frustriert ist.

Wer das Onboarding nicht aufschreibt zwingt jeden neuen Kollegen denselben Pfad selbst rauszufinden, und jeder dieser Pfade hat eine andere Lösung. Das ist die Geburt des Drifts.

Was als nächstes

Wenn Du das hier durchhast, ist Dein Team-Setup robust. Nächster sinnvoller Schritt ist das Playbook "Eigene Slash-Commands für Claude Code", wo Du lernst wie Du den nächsten geteilten Slash-Command sauber baust. Wenn ihr noch keine Hooks committed habt, lohnt sich "Hooks gegen Halluzinationen" als zweiter Schritt. Und wenn Du gerade ueberlegst auf Claude Code 2.x zu updaten obwohl das Team noch auf 1.9 ist, schau ins Playbook "Claude Code Update-Strategie" bevor jemand am Montag morgen einen kaputten Workflow hat.