Claude.md: die Datei, die Claude Code für dich arbeiten lässt

Dein Dev-Team erklärt Claude Code ständig dieselben Dinge. Wo die Auth-Logik liegt. In welchem Ordner die Stripe-Webhooks stecken. Warum niemand das alte Billing-Modul anfasst. Jede Sitzung beginnt bei null, und jede Sitzung kostet Zeit, für die du bezahlst.

CLAUDE.md löst das. Es ist eine reine Textdatei, die in deinem Projekt liegt und automatisch gelesen wird, bevor Claude mit der Arbeit beginnt. Stell es dir vor wie das Einarbeitungsdokument, das du einem neuen Mitarbeiter am ersten Tag geben würdest, nur dass dieses hier wirklich jedes Mal gelesen wird.

Die meisten Teams machen das auf eine von zwei Arten falsch. Entweder lassen sie die Datei weg und zahlen immer wieder für dieselben Korrekturen. Oder sie stopfen das gesamte Engineering-Handbuch hinein, und Claude ertrinkt in Details, die es gar nicht brauchte. Beides bringt dir nicht das, wofür du bezahlst.

Überlegst du noch, ob sich Claude Code überhaupt lohnt? Das solltest du zuerst lesen. Dieser Artikel geht davon aus, dass du diese Entscheidung bereits getroffen hast und das Setup jetzt richtig aufsetzen willst.

Das Wichtigste in Kürze

• CLAUDE.md ist eine Datei, die Claude Code automatisch liest, damit du nicht mehr dafür bezahlst, dass es dein Projekt jede Sitzung neu lernt
• Es funktioniert wie ein Einarbeitungsdokument für einen neuen Mitarbeiter, nicht wie eine technische Konfigurationsdatei
• Eine gute Datei ist kurz und spezifisch für die Eigenheiten deines Projekts, keine Liste generischer Regeln aus einer Vorlage
• Die besten CLAUDE.md-Dateien werden jedes Mal aktualisiert, wenn Claude einen Fehler wiederholt, genau wie du einen neuen Mitarbeiter korrigieren würdest
• Anthropic empfiehlt, die Datei auf etwa 200 Zeilen zu begrenzen, da aufgeblähte Dateien Kontext fressen und die Qualität der Ergebnisse verschlechtern
• Ein echtes Beispiel und eine kopierbare Vorlage folgen unten, keine Programmierkenntnisse nötig, um sie zu nutzen

Was ist claude.md?

CLAUDE.md ist eine Textdatei, die im Stammverzeichnis deines Projekts liegt. Wenn du eine Claude-Code-Sitzung startest, liest es diese Datei, bevor es irgendetwas anderes anfasst. Das ist der gesamte Mechanismus. Kein Plugin, kein Dashboard, kein Einrichtungsassistent.

Wo sie liegt

Die Datei liegt im Stammordner deines Projekts, neben deiner Package-Konfiguration und den obersten Quellordnern. Größere Codebases fügen manchmal eine zweite CLAUDE.md in einem bestimmten Unterordner hinzu, etwa einem API-Service oder einer mobilen App, sodass dieser Ordner zusätzlich zum projektweiten Kontext seinen eigenen lokalen Kontext bekommt.

Wann Claude sie liest

Claude prüft die Datei zu Beginn einer Sitzung, bevor es Änderungen vornimmt. Es liest sie nicht mitten im Gespräch erneut, es sei denn, du bearbeitest die Datei und startest neu. Deshalb muss die Datei die Anweisungen enthalten, die für das gesamte Projekt dauerhaft gelten, nicht eine Notiz darüber, woran du heute arbeitest.

Das Problem, das sie löst

Ohne CLAUDE.md tippst du jedes Mal denselben Kontext in den Chat: was das Produkt macht, welchen Mustern zu folgen ist, welche Dateien tabu sind. Mit ihr schreibst du das einmal auf, und Claude prüft es automatisch zu Beginn jeder Sitzung. Das bedeutet weniger Erklärungen, weniger wiederholte Fehler und weniger Zeit deines Entwicklers, die er damit verbringt, eine KI erneut zu briefen, statt zu bauen.

Chatanweisungen versus eine dauerhafte Datei

Der für Gründer relevante Unterschied ist einfach. Chatanweisungen sind ein Gespräch, das du immer wieder führen musst. CLAUDE.md ist eine Entscheidung, die du einmal triffst und die Claude respektiert, bis du sie änderst. Wenn eine Regel für jede zukünftige Sitzung gelten soll, gehört sie in die Datei, nicht in eine Nachricht.

Was gehört in claude.md?

Hier scheitern die meisten Dateien, entweder zu dünn, um etwas zu bewirken, oder zu aufgebläht, um lesbar zu sein. Das hier verdient tatsächlich einen Platz:

• Projektüberblick. Ein oder zwei Sätze darüber, was das Produkt macht. Die Art von Sache, die du einem neuen Mitarbeiter laut sagen würdest, kein Lastenheft.
• Architektur und Verzeichnisstruktur. Wie die Teile zusammenpassen, kurz gehalten. Das ist Orientierung, kein tiefer Einstieg.
• Coding-Konventionen und Befehle. Auch wenn du selbst nie einen Code-Editor öffnest, ist das für dich relevant: Konsistenz hier bedeutet weniger Bugs, die drei Wochen später auftauchen.
• Testanweisungen. Wie man prüft, dass nichts kaputtgegangen ist. Das ist der Abschnitt, der beantwortet, ob ein Release sicher ist.
• Abhängigkeiten. Worauf das Projekt basiert und warum.
• Dinge, die Claude niemals tun sollte. Gründer lesen diesen Abschnitt am schnellsten, weil er eine Leitplanke ist, kein Freibrief. Niemals direkt die Zahlungstabelle anfassen. Niemals Migrationsdateien löschen. Solche Dinge.
• Workflow und Definition von "fertig". Wie "fertig" in deinem Team aussieht, nicht Claudes Standardannahme von fertig.
• Bekannte Stolperfallen. Die kuriosen Dinge. Die API, die bei ihren Rate-Limits lügt. Die eine Komponente, die kaputtgeht, wenn man sie vor 9 Uhr morgens anfasst, bildlich gesprochen.

Jeder dieser Punkte sollte existieren, weil er verändert, was Claude tut. Wenn eine Zeile Claudes Verhalten nicht verändern würde, gehört sie nicht hinein.

Claude.md-Beispiel

So sieht das bei einem echten Stack aus: Next.js im Frontend, Supabase für Datenbank und Auth, Stripe fürs Billing. Kein Gedankenexperiment, sondern eine Projektform, die die meisten Gründer in dieser Position tatsächlich haben.

Beispieldatei

# CLAUDE.md

This file explains how Claude Code should work inside this repository.

Read it before making changes.

## Project

This is a web application for [briefly describe the users and product].

Current priority:
- Build: [current feature or phase]
- Deadline: [date, if relevant]
- Scope: [link or file containing requirements]

If requirements are unclear, ask before implementing.

## Tech stack

- Frontend: Next.js
- Language: TypeScript
- Database: PostgreSQL
- Hosting: Vercel
- Testing: [testing framework]

Do not introduce new frameworks or major dependencies without approval.

## Key project rules

- Follow the existing architecture and coding conventions.
- Keep changes limited to the requested task.
- Do not refactor unrelated code.
- Never modify an existing database migration. Create a new one.
- Add tests for new behaviour and bug fixes.
- Never expose secrets, API keys or environment variables.
- Ask before making architectural changes.

Add new rules here when important project decisions are made.

## Before coding

Before implementing a substantial change:

1. Read the relevant existing code.
2. Identify the files likely to change.
3. State any assumptions.
4. Explain the proposed approach.
5. Define how the result will be tested.

If something is ambiguous, stop and ask rather than guessing.

## Development guidelines

### Keep it simple

Write the minimum code required to solve the requested problem.

Avoid:
- unnecessary abstractions
- speculative features
- new dependencies without a clear reason
- changes unrelated to the task

### Make surgical changes

Every changed line should have a reason connected to the task.

Match the existing project's conventions instead of rewriting surrounding code to match your preferences.

### Verify your work

For a bug:

1. Reproduce the problem.
2. Add or identify a test that catches it.
3. Fix the problem.
4. Run the relevant tests.

For a feature:

1. Define the expected behaviour.
2. Implement it.
3. Test the main path and important edge cases.
4. Run the relevant test suite.

Do not describe work as complete until the relevant checks pass.

## Git workflow

Never work directly on `main`.

For each task:

1. Pull the latest `main`.
2. Create a dedicated branch.
3. Make focused commits.
4. Run tests before opening a pull request.
5. Review the final diff for unrelated changes.

## Communication

Keep explanations short and clear.

When finishing a task, report:

- what changed
- which files were affected
- what was tested
- anything that still needs human review

If you are uncertain about a requirement, say so instead of silently choosing an interpretation.

Warum diese Version funktioniert

Nichts in dieser Datei erklärt, was Next.js ist oder was ein Webhook allgemein macht. Sie sagt nur, was für dieses Projekt zutrifft. Genau darum geht es. Ein Gründer, der sie liest, kann trotzdem der Struktur folgen: was existiert, was tabu ist und was als fertig gilt, ohne auch nur eine einzige Zeile der tatsächlichen Codebase lesen zu müssen.

Claude.md-Vorlage

Entfernt man die Details, bleibt das hier übrig. Kopiere das, gib es deinem Entwickler und lass die Klammern ausfüllen.

Kopierbare Struktur

# Projektüberblick
[Was das Produkt macht, in ein oder zwei Sätzen]

# Architektur
[Wichtigste Ordner und was jeweils drin liegt]

# Konventionen
[Muster, denen zu folgen ist, Muster, die zu vermeiden sind]

# Befehle
[Dev-Server, Tests, Build, Lint, was auch immer du tatsächlich ausführst]

# Niemals tun
[Konkrete Aktionen, die etwas kaputt machen oder eine Geschäftsregel verletzen würden]

# Definition von "fertig"
[Was "fertig" bedeutet, bevor etwas released wird]

# Bekannte Stolperfallen
[Das Nicht-Offensichtliche, worüber dein Team schon einmal gestolpert ist]

Sieben Abschnitte. Wenn deine Datei länger als anderthalb Seiten ist, erklärt darin wahrscheinlich etwas, das der Code schon von selbst erklärt.

Claude.md Best Practices

Anthropics eigene Empfehlung nennt eine konkrete Zahl: Diese Dateien unter etwa 200 Zeilen halten. Danach beginnt die Datei, Kontext zu fressen, den Claude für die eigentliche Arbeit braucht, und das Befolgen von Anweisungen wird schlechter, nicht besser. Mehr ist hier nicht nützlicher. Es ist das Gegenteil.

Dokumentiere nicht, was Claude bereits lesen kann

Wenn eine Funktion calculateInvoiceTotal heißt, brauchst du keine Zeile, die erklärt, was sie berechnet. Claude liest Code. Nutze die Datei für das, was der Code nicht von selbst erzählen kann.

Priorisiere, was einzigartig für dein Projekt ist

„Schreib sauberen Code" sagt Claude nichts. „Umgehe niemals die RLS-Richtlinie in der Rechnungstabelle" sagt ihm etwas, das es unmöglich hätte erraten können. Generische Ratschläge gibt es überall gratis. Die spezifischen Regeln deines Projekts sind das Einzige, was diese Datei bieten kann, das ein allgemeiner KI-Coding-Guide nicht kann.

Nutze Befehle, keine Beschreibungen

npm run test auszuführen ist besser als eine vage Erinnerung, sicherzustellen, dass es getestet ist. Eine Anweisung, die Claude direkt ausführen kann, ist mehr wert als eine Beschreibung, die es interpretieren muss.

Dokumentiere die Grenzen

Sei konkret darüber, was Claude nicht anfassen sollte: welche Tabellen, welche Dateien, welche Ordner tabu sind und warum. Das ist der Abschnitt, der die teuren Fehler verhindert, die einen Gründer echtes Geld kosten, um sie rückgängig zu machen.

Sag Claude, wie es seine eigene Arbeit überprüfen kann

Wenn es eine Testsuite oder einen Typecheck-Befehl gibt, schreib das direkt in die Datei. Ein Modell, das weiß, wie es seine eigene Ausgabe prüft, fängt mehr Probleme ab, bevor sie dich erreichen.

Mach daraus kein Engineering-Handbuch

Ein vollständiges Einarbeitungshandbuch, ein Styleguide oder ein Architekturentscheidungsprotokoll können woanders liegen. CLAUDE.md ist für das da, was Claudes Verhalten in dieser spezifischen Codebase tatsächlich verändert, nicht mehr.

Lass sie aus Claudes Fehlern wachsen

Das ist die Praxis, die am meisten zählt, und sie taucht in generischen Guides selten auf. Wenn Claude denselben projektspezifischen Fehler zweimal macht, ist das keine einmalige Korrektur mehr. Das ist eine Zeile, die in die Datei gehört, genauso wie du Einarbeitungsmaterial aktualisieren würdest, nachdem ein neuer Mitarbeiter zweimal über dieselbe Sache gestolpert ist. Behandle jeden wiederholten Fehler als Anlass, die Datei zu aktualisieren, nicht nur den Code.

Wie wir claude.md bei KI-gestützter Entwicklung nutzen

Wir schreiben das nicht vom Whiteboard aus. Jedes Projekt, das wir mit Claude Code bauen, beginnt mit einer CLAUDE.md-Datei, die mit der Codebase mitwächst, statt einmal geschrieben und dann sich selbst überlassen zu werden. Wägst du Claude Code gegen andere Coding-Agents für dein Team ab? Unser Vergleich von Gemini CLI und Claude Code zeigt, wo jeder der beiden punktet.

Weniger wiederholte Erklärungen

Die Zeit, die für erneute Kontexterklärungen von Sitzung zu Sitzung draufgeht, sinkt nahezu auf null, weil die Datei ihn bereits enthält. Das bringt bei jedem Projekt Stunden zurück, nicht nur in der ersten Woche.

Mehr Konsistenz in der Codebase

Eine Codebase, die über Wochen entsteht, bleibt konsistent, wenn dieselben Regeln automatisch in jeder Sitzung gelten. Das zählt, wenn ein Gründer darauf vertraut, dass KI-gestützte Arbeit auch im echten Einsatz hält, nicht nur in einer Demo.

Weniger unsichtbare Architekturänderungen

In der Datei dokumentierte Grenzen verhindern, dass Claude Änderungen vornimmt, die ein nicht-technischer Gründer unmöglich hätte bemerken können, bis etwas in der Produktion kaputtgeht.

Zuverlässigere Tests und Prüfungen

Tests und Prüfungen laufen tatsächlich so, wie sie sollen, weil die Datei Claude sagt, wie es seine eigene Arbeit verifiziert, statt diesen Schritt optional zu lassen.

Bessere Kontinuität zwischen Sitzungen

Diese Kontinuität ist es, die KI-gestützte Entwicklung in dem Tempo hält, das Gründer tatsächlich brauchen, nicht nur in einer Demo, sondern über die Monate hinweg, die es braucht, um etwas Echtes zu bauen.

Bereit, dein Projekt mit einem Team zu bauen, das claude.md als Teil des Liefergegenstands behandelt?

Wir richten solche Kontextdateien bei jedem KI-gestützten Build ein, den wir durchführen, damit deine Codebase auch lange nach dem ersten Sprint konsistent bleibt. Vereinbare ein Gespräch, und wir zeigen dir, wie das für dein Projekt aussieht.

Start dein Projekt, ruf Tom an.

‍