CLAUDE.md Best Practices – Projektgedächtnis & KI-Zusammenarbeit im Team

Was ist CLAUDE.md?

CLAUDE.md ist eine spezielle Datei im Stammverzeichnis Ihres Projekts, die Claude Code automatisch beim Start liest. Sie fungiert als „Projektbriefing“ für die KI — mit Tech-Stack, Code-Konventionen, Verzeichnisstruktur und den wichtigsten Befehlen, sodass Claude Ihren Kontext ohne wiederholte Erklärungen versteht.

Die offizielle Dokumentation beschreibt sie als den Ort, an dem man notiert, was man sonst immer wieder erklären müsste: Nur Fakten, die jede Session braucht, gehören hinein – Details zu einmaligen Aufgaben bleiben in der Konversation (geprüft 2026-09-21).

Eine einfache Textdatei

Es ist eine einfache Markdown-Datei im Repo: Sie schreiben, committen, lesen und diffen sie wie alles andere. Laut Dokumentation schreiben Sie sie und Claude Code liest sie zu Beginn jeder Session (geprüft 2026-09-21).

Beim Start geladen

CLAUDE.md im Arbeitsverzeichnis und auf jeder höheren Ebene wird beim Start geladen; Dateien in Unterordnern werden geladen, sobald Claude dort Dateien liest (geprüft 2026-09-21).

Kontext, nicht Konfiguration

Sie wird in jeder Session in das Kontextfenster geladen und verbraucht Tokens neben Ihrer Konversation, ohne Garantie auf strikte Befolgung – die Dokumentation bezeichnet sie als Kontext, nicht als erzwungene Konfiguration (geprüft 2026-09-21).

Warum CLAUDE.md?

Der Nutzen ist dreifach: kein Hintergrund-Eintippen mehr zu Beginn jeder Session, dieselbe Ausgabeform unabhängig davon, wer fragt, und ein Onboarding, das nicht auf mündlicher Überlieferung beruht.

Wiederholungen eliminieren

Kein Erklären mehr von „Wir verwenden TypeScript“ oder „Tests laufen mit Jest“ in jeder Sitzung — einmal schreiben, dauerhaft wirksam

Konsistente Ausgaben

Definieren Sie Coding-Stil, Namenskonventionen und Architekturvorgaben, damit Claudes Ausgaben stets den Projektstandards entsprechen

Team-Wissensaustausch

Wenn neue Mitglieder dazukommen, dient CLAUDE.md gleichzeitig als KI-Konfiguration und als für Menschen lesbarer Onboarding-Leitfaden

Empfohlene Vorlage

Eine gute CLAUDE.md enthält in der Regel folgende Abschnitte

CLAUDE.md

# Projektübersicht

- Order-Center-Backend, REST-API für Web und Mini-Programm
- Neueinsteiger lesen diese Datei, danach das Onboarding-Handbuch
- Vor einer API-Änderung prüfen, ob Clients synchronisiert werden müssen

## Tech-Stack

- Sprache TypeScript auf Node.js, pnpm für Pakete
- PostgreSQL für Daten, heiße Lesezugriffe über Redis
- Vitest für Tests, Abdeckungsgrad über CI überwacht

## Verzeichnisstruktur

- src/api: HTTP-Einstiegspunkt und Argumentprüfung, keine Geschäftslogik
- src/domain: Geschäftsregeln, keine Framework-Importe
- tests: spiegelt den src-Baum, Fehler schnell auffindbar

## Codierungskonventionen

- Zweizeichen-Einrückung, einfache Anführungszeichen, Semikolons beibehalten
- Namen vollständig ausschreiben, keine Abkürzungen
- Keine Framework-Typen in der Domain-Schicht, das ist ein Defekt

## Übliche Befehle

- npm run dev: lokal starten
- npm test: vollständige Unit-Suite, muss bestanden sein, bevor Sie die Arbeit beenden
- npm run lint: einmal vor dem Commit

## Wichtige Hinweise

- Keine Geheimnisse oder internen URLs hier, Umgebungsvariablen nutzen
- Datenbank-Migrationen zuerst auf einer Shadow-Datenbank ausführen
- Unklarer Sonderfall: nachfragen, keinen Standard erfinden

Erweiterte Tipps

Diese fünf Punkte entscheiden, ob die Datei befolgt oder zu Rauschen wird, das niemand erneut liest; jeder Punkt liefert einen Test für Ihre eigene Datei.

1

Nur wiederkehrende Fakten

Die Prüfung ist nüchtern: Ist diese Zeile in der nächsten Session noch nützlich? Build-Befehle, Namensregeln und frühere Fallstricke gehören hinein; Verzeichnislisten und Abhängigkeitslisten nicht – Claude leitet diese aus dem Code ab (geprüft 2026-09-21).

2

Unter 200 Zeilen bleiben

Die Referenzgröße in der Dokumentation liegt unter 200 Zeilen pro Datei; darüber verbraucht sie mehr Kontext und wird seltener befolgt (geprüft 2026-09-21). Falls der Platz nicht ausreicht, auf pfadbezogene Regeln aufteilen, die nur geladen werden, wenn Claude passende Dateien berührt.

3

Nachvollziehbar formulieren

„Code schön formatieren“ trägt keine Information; „Zweizeichen-Einrückung, einfache Anführungszeichen, npm test vor dem Commit ausführen“ lässt sich befolgen. Zeilen unter Zwischenüberschriften und Aufzählungspunkten gruppieren – Claude scannt die Struktur wie ein Leser (geprüft 2026-09-21).

4

Generieren, dann kürzen

Nicht bei null anfangen: /init analysiert die Codebasis und entwirft Build-Befehle, Test-Setup und gefundene Konventionen; dann den Füllstoff wie bei /doctor kürzen und Fallstricke sowie Begründungen behalten; mit /context abschließen, um zu bestätigen, dass die Datei geladen wurde (geprüft 2026-09-21).

5

Keine Geheimnisse darin

Diese Datei landet in Git und wird von allen in jeder Session gelesen. Geheimnisse, interne URLs und Testkonten gehören in Umgebungsvariablen; persönliche Präferenzen in CLAUDE.local.md schreiben und in die .gitignore aufnehmen, damit die Team-Kopie sauber bleibt (geprüft 2026-09-21).

Standards für die Teamzusammenarbeit

Best Practices für die Pflege von CLAUDE.md in Mehrpersonenprojekten

Wie Code prüfen

Die Projekt-Kopie ist ein Team-Asset, keine privaten Notizen: Ändern Sie sie im selben PR wie den Code, begründen Sie die Änderung und lassen Sie sie vom Verantwortlichen des jeweiligen Verzeichnisses prüfen. Die Dokumentation: Projektanweisungen werden über die Versionskontrolle geteilt (geprüft 2026-09-21).

Reihenfolge und Konflikte

Dateien in höheren Verzeichnissen werden zuerst in den Kontext geladen, Unterordner-Dateien bei Bedarf – der Inhalt wird zusammengeführt, nichts überschreibt etwas anderes. Wenn zwei Dateien dasselbe Verhalten unterschiedlich formulieren, kann Claude beliebig eine wählen – daher die Formulierungen vereinheitlichen oder eine Datei löschen (geprüft 2026-09-21).

Nach Modulen aufteilen

In einem großen Repo die Root-Datei nicht überladen: Modulspezifische Notizen gehören in eine CLAUDE.md im Unterordner oder eine pfadbezogene Regel, die nur dann in den Kontext gelangt, wenn Claude dort arbeitet – kostengünstiger und präziser als eine einzige riesige Root-Datei (geprüft 2026-09-21).

Prüfung automatisieren

Zwei Abläufe als Routine etablieren: Die CI prüft, dass die Root-CLAUDE.md existiert und innerhalb der vereinbarten Größe bleibt, und jeder Architektur-PR geht die bestehenden Einträge erneut durch. Die Dokumentation empfiehlt zudem, veraltete und widersprüchliche Anweisungen regelmäßig zu entfernen (geprüft 2026-09-21).

Häufige Fehler

Alle vier verwandeln die Datei vom Hebel in Rauschen, und keiner dieser Punkte erfordert eine Neuformulierung zur Behebung.

Aufgabennotizen statt Regeln

Die Reproduktionsschritte eines einzelnen Bugs oder Zwischennotizen eines Refactorings einzufügen bedeutet, dass sie in der nächsten Sitzung noch Kontext belegen, ohne dass eine allgemeine Regel formuliert wurde. Das gehört in ein Issue oder die PR-Beschreibung (geprüft am 2026-09-21).

Sie wächst nur

Die Dokumentation setzt die Grenze bei 200 Zeilen: darüber kostet die Datei mehr Kontext und wird weniger befolgt (geprüft am 2026-09-21). Aufgeblähte Inhalte lassen sich nicht durch eine weitere Regel beheben — verschieben Sie, was nur für bestimmte Verzeichnisse gilt, heraus.

Regeln widersprechen sich

Das Stammverzeichnis sagt pnpm, ein Unterverzeichnis sagt npm — Claude folgt möglicherweise derjenigen Vorgabe, auf die es sich festgelegt hat (geprüft am 2026-09-21). Halten Sie pro Thema eine maßgebliche Aussage fest und verweisen Sie von anderen Stellen darauf, statt eine zweite Version zu kopieren.

Niemand pflegt es

Der Tech-Stack hat sich geändert, das Layout wurde refaktoriert, doch die Befehle in der Datei sind noch die alten. Die Dokumentation empfiehlt eine regelmäßige Überprüfung auf jeder Ebene und das Entfernen veralteter sowie widersprüchlicher Einträge (geprüft 2026-09-21) – am einfachsten über den Architektur-PR anzustoßen.

FAQ

CLAUDE.md in jeder Sitzung bereitstellen?

Nein. Eine CLAUDE.md im Arbeitsverzeichnis oder einem Verzeichnis darüber wird automatisch beim Sitzungsstart geladen; Dateien in Unterverzeichnissen kommen hinzu, wenn Claude dort Code liest. Führen Sie /context aus und prüfen Sie die Memory-Dateienliste, um zu sehen, was tatsächlich geladen wurde (geprüft am 2026-09-21).

Wie groß ist zu groß?

Die dokumentierte Referenz liegt bei unter 200 Zeilen pro Datei; darüber steigen die Kontextkosten und die Befolgung sinkt (geprüft am 2026-09-21). Verschieben Sie modulbezogenen Inhalt in pfadbezogene Regel-Dateien, damit er nur geladen wird, wenn Claude die passenden Dateien bearbeitet.

Was ist mit AGENTS.md?

Standardmäßig gilt Entweder-oder: Jede CLAUDE.md im Arbeitsverzeichnis oder darüber verhindert, dass AGENTS.md geladen wird. Um beide zu nutzen, setzen Sie im /config-Panel die Projektanweisungen auf „beide laden“, oder importieren Sie die Datei in CLAUDE.md mit @AGENTS.md (geprüft am 2026-09-21).

Wer pflegt sie?

Gleicher Workflow wie Code: Die Projektversion liegt in der Versionskontrolle und wird zusammen mit der Änderung geprüft, die sie ausgelöst hat; wer die Architektur anfasst, aktualisiert sie. Persönliche Präferenzen gehören in eine separate lokale Datei unter gitignore, und die Dokumentation empfiehlt eine regelmäßige Bereinigung veralteter Einträge (geprüft am 2026-09-21).

Team-Praxis mit QCode.cc

Ein QCode.cc API-Key + einheitliche CLAUDE.md = konsistentes und effizientes KI-Coding für Ihr gesamtes Team

Ein API-Key pro Team

Das Team teilt sich einen QCode.cc API-Key, und die Nutzung wird unter einem einzigen Konto erfasst, anstatt einen Key pro Person zu verwenden (geprüft 2026-09-21).

Modelle wechseln, Datei behalten

CLAUDE.md wird vom Client im Projekt gelesen und hängt nicht davon ab, welches Modell antwortet – ein Modellwechsel erfordert daher keine Neuformulierung.

Ein gemeinsamer Ausgangspunkt

Alle gehen vom selben Punkt aus: Neueinsteiger und Senior-Engineer fragen mit denselben Projektvoraussetzungen im Kontext – die Ausgabe hängt nicht mehr davon ab, wer sie eingegeben hat.

Drei Projektformen

Dieselbe Vorlage sollte nicht dieselbe Datei erzeugen. Diese drei Repository-Formen brauchen unterschiedliche Klarstellungen; streichen Sie, was übrig bleibt.

Team-Backend

Fassen Sie Build- und Migrationsbefehle, strikte API-Kompatibilitätsregeln und gesperrte Verzeichnisse klar zusammen; hier ist das Teure das, was alle wiederholen.

Open-Source-Bibliothek

Beitragsworkflow, Testanforderungen, was als Breaking Change gilt: Externe Beitragende und Maintainer arbeiten mit demselben Text, daher muss jede Zeile überprüfbar sein.

Solo-Tooling

Überspringen Sie die vollständige Abschnitte-Liste. Behalten Sie nur die Startanleitung, die Versionsrichtlinie für Abhängigkeiten und harte Vorgaben wie „die gesamte Datei nicht neu formatieren“ — mehr nicht.