CLAUDE.md-Dateien verwenden: Anpassung von Claude Code für Ihre Codebasis

Wenn Sie KI-Programmieragenten verwenden, stehen Sie vor einer wiederkehrenden Herausforderung: Wie geben Sie ihnen genug Kontext, um Ihre Architektur, Konventionen und Workflows zu verstehen, ohne sich ständig zu wiederholen?

Das Problem verschärft sich, wenn Ihre Codebasis wächst. Komplexe Modulbeziehungen, branchenspezifische Muster und Teamkonventionen lassen sich nicht ohne weiteres umsetzen. Am Ende erklärt man zu Beginn jedes Gesprächs dieselben Architekturentscheidungen, Testanforderungen und Programmierstilpräferenzen.

CLAUDE.md-Dateien lösen dieses Problem, indem sie Claude einen dauerhaften Kontext zu Ihrem Projekt geben. Es ist quasi eine Konfigurationsdatei, die Claude automatisch in jedes Gespräch integriert, um sicherzustellen, dass es immer Ihre Projektstruktur, Programmierstandards und bevorzugte Workflows kennt.

In diesem Artikel erklären wir, wie Sie Ihre CLAUDE.md strukturieren. Wir stellen Best Practices vor und geben Tipps, wie Sie sie verwenden, um Claude Code optimal zu nutzen. 

Was ist eine CLAUDE.md-Datei?

CLAUDE.md ist eine spezielle Konfigurationsdatei, die in Ihrem Repository gespeichert wird und Claude den projektspezifischen Kontext zur Verfügung stellt. Sie können sie in Ihrem Stamm-Repository speichern, um sie mit Ihrem Team zu teilen, in übergeordneten Verzeichnissen für Monorepo-Setups oder in Ihrem Home-Ordner zur universellen Verwendung in allen Projekten.

Hier ist ein Beispiel für CLAUDE.md, das Sie in Ihrem Repository haben:

Eine gut konfigurierte CLAUDE.md ändert die Arbeitsweise von Claude für Ihr Projekt. Die Datei dient mehreren Zwecken: zur Bereitstellung des architektonischen Kontexts, zur Einrichtung von Workflows und zur Verknüpfung von Claude mit Ihren Entwicklungstools. Jede Ergänzung sollte ein reales Problem lösen, nicht theoretische Fragen darüber, was Claude benötigt.

Diese Datei kann gängige Bash-Befehle, Kerndienstprogramme, Code-Stilrichtlinien, Testanweisungen, Repository-Konventionen, die Einrichtung der Entwicklerumgebung und projektspezifische Warnungen dokumentieren. Es gibt kein erforderliches Format. Die Empfehlung ist, diese Datei prägnant und lesbar zu halten und sie wie eine Dokumentation zu behandeln, die sowohl ein Mensch als auch Claude schnell verstehen muss.

Ihre Datei CLAUDE.md wird Teil des Systemprompts von Claude. Jedes Gespräch beginnt mit diesem Kontext, sodass grundlegende Projektinformationen nicht immer wieder erklärt werden müssen.

Erste Schritte mit /init

Eine CLAUDE.md zu erstellen, kann überwältigend erscheinen, insbesondere in einer unbekannten Codebasis. 

Der Befehl /init automatisiert diesen Prozess, indem er Ihr Projekt analysiert und eine Startkonfiguration generiert.

/init in einer Claude-Code-Sitzung ausführen:

Claude analysiert Ihre Codebasis – liest die Paketdateien, die vorhandenen Dokumentationen, Konfigurationsdateien und die Codestruktur – und generiert dann eine CLAUDE.md, die auf Ihr Projekt zugeschnitten ist. Die generierte Datei enthält normalerweise Build-Befehle, Testanweisungen, Schlüsselverzeichnisse und erkannte Programmierkonventionen.

Stellen Sie sich /init als Ausgangspunkt vor, nicht als fertiges Produkt. Die generierte CLAUDE.md erfasst offensichtliche Muster, übersieht jedoch möglicherweise die spezifischen Nuancen Ihres Workflows. Überprüfen Sie, was Claude produziert, und passen Sie es an die tatsächlichen Praktiken Ihres Teams an.

Sie können /init auch in bestehenden Projekten verwenden, die bereits eine CLAUDE.md haben. Claude überprüft die aktuelle Datei und schlägt Verbesserungen vor, die auf den Erkenntnissen der Analyse Ihrer Codebasis basieren.

Nach dem Ausführen von /init sollten Sie die folgenden Schritte durchführen:

• Überprüfen Sie die generierten Inhalte auf Richtigkeit
• Fügen Sie Workflow-Anweisungen hinzu, die Claude nicht ableiten konnte (Namenskonventionen für Niederlassungen, Bereitstellungsprozesse, Anforderungen an die Codeüberprüfung)
• Entfernen Sie allgemeine Richtlinien, die für Ihr Projekt nicht relevant sind
• Übergeben Sie die Datein an die Versionskontrolle, damit Ihr Team davon profitiert

Der Befehl /init funktioniert gut, um sich schnell zu orientieren, aber der wahre Nutzen kommt von der Iteration der generierten Datei im Laufe der Zeit. Wenn Sie mit Claude Code arbeiten, verwenden Sie den #-Schlüssel, um Anweisungen hinzuzufügen, die Sie häufig nutzen. Diese Ergänzungen werden in einer CLAUDE.md zusammengeführt, die die Arbeitsweise Ihres Teams widerspiegelt.

So strukturieren Sie Ihre CLAUDE.md

In den folgenden Abschnitten wird erläutert, wie Inhalte so strukturiert werden, dass sie maximale Wirkung erzielen: komplexe Architekturen steuern, den Fortschritt bei mehrstufigen Aufgaben verfolgen, benutzerdefinierte Tools integrieren und Nacharbeiten durch konsistente Workflows vermeiden.

Geben Sie Claude eine Anleitung

Die Projektarchitektur, Schlüsselbibliotheken und Programmierstile zu erklären wird mühsam, wenn man dies für jede Aufgabe erneut tun muss. Sie benötigen Claude, um einen konsistenten Kontext über Ihre Codebasis ohne manuelle Verstärkung zu erstellen.

Fügen Sie Ihrer CLAUDE.md. eine Projektzusammenfassung und die übergeordnete Verzeichnisstruktur hinzu. Dies gibt Claude eine sofortige Orientierung beim Navigieren in der Codebasis.

Eine einfache Baumausgabe mit den Schlüsselverzeichnissen hilft Claude zu verstehen, wo die verschiedenen Komponenten gespeichert sind:

Geben Sie Informationen über Ihre wichtigsten Abhängigkeiten, Architekturmuster und alle unternehmensinternen Entscheidungen an, die vom Standard abweichen. Wenn Sie domänenorientiertes Design, Mikroservices oder bestimmte Frameworks verwenden, dokumentieren Sie dies. Claude verwendet diese Übersicht, um bessere Entscheidungen darüber zu treffen, wo er Code finden und Änderungen vornehmen soll.

Verbinden Sie Claude mit Ihren Tools

Claude übernimmt Ihre gesamte Umgebung, benötigt jedoch Leitlinien bei der Auswahl der Tools und Skripte, die verwendet werden sollen. Ihr Team hat wahrscheinlich spezialisierte Dienstprogramme für die Bereitstellung, das Testen oder die Codegenerierung entwickelt, die Claude kennen sollte.

Dokumentieren Sie Ihre benutzerdefinierten Tools in CLAUDE.md mit Anwendungsbeispielen. Geben Sie Tool-Namen, grundlegende Nutzungsmuster und wann sie verwendet werden, an. Wenn Ihr Tool Hilfedokumentation über ein --help-Flag bereitstellt, geben Sie dies an, damit Claude es überprüfen kann. Fügen Sie bei komplexen Tools Beispiele für häufige Anwendungen hinzu, die Ihr Team regelmäßig verwendet.

Claude fungiert als MCP-Client (Model Context Protocol) und verbindet sich mit MCP-Servern zur Erweiterung seiner Funktionen. Konfigurieren Sie diese über Projekteinstellungen, globale Konfiguration oder eingecheckte .mcp.json-Dateien. Das Flag --mcp-debug hilft bei der Behebung von Verbindungsproblemen, wenn Tools nicht wie erwartet angezeigt werden.

Wenn Sie beispielsweise einen Slack-MCP-Server für Ihr Unternehmen konfiguriert haben und Claude benötigen, um zu verstehen, wie er verwendet wird, fügen Sie etwas wie Folgendes in CLAUDE.md ein:

Erfahren Sie mehr über MCP-Grundlagen und Best Practices.

Weitere Informationen zum Festlegen von Berechtigungen für Claude Code finden Sie in der settings.json-Dokumentation unter code.claude.com.

Definition von Standard-Workflows

Wenn Claude ohne Planung direkt mit Codeänderungen anfängt, müssen Dinge überarbeitet werden. Claude implementiert möglicherweise eine Lösung, die die Anforderungen verfehlt, den falschen Architekturansatz wählt oder Änderungen vornimmt, die die vorhandene Funktionalität beeinträchtigen.

Claude muss denken, bevor er handelt. Definieren Sie Standard-Workflows in Ihrer CLAUDE.md, die Claude für verschiedene Arten von Aufgaben verwenden soll. Ein solider Standardworkflow beantwortet vier Fragen, bevor Änderungen vorgenommen werden:

1. Ist das eine Frage zum aktuellen Stand, die zuerst untersucht werden muss?
2. Benötigt man einen detaillierten Plan vor der Implementierung?
3. Welche zusätzlichen Informationen fehlen?
4. Wie wird die Effektivität getestet?

Spezielle Workflows können Explore-Plan-Code-Commit für Funktionen, die testgetriebene Entwicklung für algorithmische Arbeit oder die visuelle Iteration für UI-Änderungen umfassen. Dokumentieren Sie Ihre Testanforderungen, das Nachrichtenformat und alle Genehmigungsschritte. Wenn Claude Ihren Workflow im Voraus kennt, strukturiert er die Arbeit so, dass sie den tatsächlichen Prozessen Ihres Teams entspricht, anstatt sie zu erraten.

Eine Beispiel-Workflow-Anweisung könnte lauten: 

‍Zusätzliche Tipps für die Arbeit mit Claude Code 

Neben der Konfiguration Ihrer CLAUDE.md-Datei verbessern drei zusätzliche Techniken die Arbeit mit Claude Code.

Kontext aktualisieren

Bei der Arbeit mit Claude Code sammelt sich im Laufe der Zeit irrelevanter Kontext an. Dateiinhalte früherer Aufgaben, Befehlsausgaben, die nicht mehr relevant sind, und tangentielle Gespräche füllen das Kontextfenster von Claude. Da das Signal-Rausch-Verhältnis sinkt, hat Claude Schwierigkeiten, sich auf die aktuelle Aufgabe zu konzentrieren.

Verwenden Sie /clear zwischen den Aufgaben, um das Kontextfenster zurückzusetzen. Dadurch wird der akkumulierte Verlauf entfernt, während Ihre CLAUDE.md-Konfiguration erhalten bleibt, und Claude kann neue Probleme in einem neuen Kontext lösen. Stellen Sie sich das als das Ende einer Arbeitssitzung und das Eröffnen einer neuen vor.

Wenn Sie das Debugging der Authentifizierung abgeschlossen haben und zur Implementierung eines neuen API-Endpunkts wechseln, müssen Sie den Kontext bereinigen. Die Authentifizierungsdetails spielen keine Rolle mehr und lenken von der neuen Arbeit ab.

Subagenten für verschiedene Phasen verwenden

Bei langen Gesprächen sammelt sich Kontext an, der neue Aufgaben beeinträchtigt. Sie haben einen komplexen Authentifizierungsprozess debuggt und benötigen jetzt eine Sicherheitsüberprüfung desselben Codes. Das Debugging führt dazu, dass Claude Probleme übersieht oder sich auf bereits gelöste Probleme konzentriert.

Claude soll einen Subagenten für verschiedene Arbeitsphasen verwenden. Subagenten halten den isolierten Kontext bei, um zu verhindern, dass Informationen aus früheren Aufgaben die neue Analyse beeinträchtigen. Nach der Implementierung eines Zahlungsprozesses sollten Sie Claude anweisen, „einen Subagenten zu verwenden, um eine Sicherheitsüberprüfung des Codes durchzuführen“, anstatt dasselbe Gespräch fortzusetzen.

Subagenten eignen sich am besten für mehrstufige Workflows, bei denen jede Phase andere Perspektiven erfordert. Die Implementierung erfordert einen architektonischen Kontext und Funktionen; die Sicherheitsüberprüfung erfordert einen neuen Fokus, der sich ausschließlich auf Schwachstellen konzentriert. Die Kontexttrennung gewährleistet die Genauigkeit beider Analysen.

Benutzerdefinierte Befehle erstellen

Wiederholung führt zu Zeitverschwendung. Sie geben immer wieder ein: „Diesen Code auf Sicherheitsprobleme überprüfen“ oder „Diesen Code auf Performance-Probleme analysieren“. Jedes Mal müssen Sie sich die genaue Formulierung merken, die gute Ergebnisse liefert.

Benutzerdefinierte Slash-Befehle speichern diese als Markdown-Dateien in Ihrem Verzeichnis .claude/commands/. Erstellen Sie eine Datei mit dem Namen performance-optimization.mm mit Ihrem bevorzugten Prompt zur Performance-Optimierung, und es steht als /performance-optimization in jeder Konversation zur Verfügung. Befehle unterstützen Argumente durch $ARGUMENTE oder nummerierte Platzhalter wie $1 und $2, wobei Sie bestimmte Dateien oder Parameter übergeben können.

Performance-optimierung.md könnte beispielsweise wie folgt aussehen:

Sie müssen keine benutzerdefinierten Befehlsdateien manuell schreiben. Bitten Sie Claude, sie für Sie zu erstellen:

Claude schreibt die Markdown-Datei in .claude/commands/performance-optimization.md, und der Befehl steht sofort zur Verfügung.

Einfach anfangen, bewusst erweitern

Es ist verlockend, sofort ein umfassendes CLAUDE.md zu erstellen. Widerstehen Sie diesem Drang.

CLAUDE.md wird jedes Mal dem Kontext von Claude Code hinzugefügt, damit es aus Sicht des Kontext- und Prompt-Engineering kompakt bleibt. Eine Möglichkeit: Die Informationen in separate Markdown-Dateien aufzuteilen und in der CLAUDE.md-Datei zu verweisen.

Geben Sie keine vertraulichen Informationen, API-Schlüssel, Anmeldedaten, Datenbankverbindungszeichenfolgen oder detaillierte Informationen zu Sicherheitsschwachstellen an – insbesondere wenn Sie die Versionskontrolle verwenden. Da CLAUDE.md Teil des Systemprompts von Claude wird, behandeln Sie sie wie eine Dokumentation, die öffentlich geteilt werden kann.

Lassen Sie CLAUDE.md für sich arbeiten

CLAUDE.md-Dateien wandeln Claude Code von einem allgemeingültigen Assistenten in ein speziell für Ihre Codebasis konfiguriertes Tool um. Starten Sie einfach mit der grundlegenden Projektstruktur und erstellen Sie eine Dokumentation, die Sie dann je nach tatsächlichen Problemen in Ihrem Workflow erweitern können.

Die effektivsten CLAUDE.md-Dateien lösen reale Probleme: Sie dokumentieren die Befehle, die wiederholt eingegeben werden, erfassen den architektonischen Kontext, dessen Erklärung zehn Minuten dauert, und erstellen Workflows, die eine Nacharbeit vermeiden. Ihre Datei sollte widerspiegeln, wie Ihr Team tatsächlich Software entwickelt – nicht theoretische Best Practices, die gut klingen, aber nicht der Realität entsprechen.

Behandeln Sie die Anpassung als fortlaufende Praxis und nicht als einmalige Einrichtung. Projekte ändern sich, Teams lernen bessere Muster kennen und neue Tools fließen in Ihren Workflow ein. Eine gut gewartete CLAUDE.md entwickelt sich mit Ihrer Codebasis weiter und reduziert so den Reibungsaufwand bei der Arbeit mit KI-Unterstützung an komplexer Software.

Erste Schritte mit Claude Code.