CLAUDE.md erklärt:Die Datei, die KI-Fehler verhindert
CLAUDE.md erklärt: die eine Datei, die 90 % der KI-Coding-Fehler verhindert. Was sie ist, was genau hineingehört und wie du deine mit nur 5 Regeln startest.
CLAUDE.md erklärt: Es ist eine Klartextdatei im Stammverzeichnis deines Projekts, die dein KI-Coding-Tool vor jeder Antwort liest – und sie verhindert rund 90 % der Fehler, die KI in deiner Codebasis macht. Es ist kein Code. Es ist das Regelwerk: die Muster deines Projekts, deine Unverhandelbaren, die Fehler, die die KI nie wiederholen darf.
Die meisten, die mit KI bauen, wissen nicht, dass es sie gibt. Hier steht, was sie ist, warum sie alles verändert und was genau in deine gehört.
CLAUDE.md erklärt: die Analogie vom Mitarbeiterhandbuch
Stell dir vor, du stellst einen brillanten Auftragnehmer ein, der zwischen den Meetings komplett amnesisch ist. Jeden Morgen kommt er an und weiß nichts darüber, wie dein Unternehmen funktioniert – deine Standards, dein Ablagesystem, deine bisherigen Entscheidungen. Jeden Morgen erklärst du alles neu, und jeden Morgen macht er dieselben Fehler, bis du es tust.
Stell dir nun vor, du drückst ihm ein Mitarbeiterhandbuch in die Hand, das er zu Beginn jedes Meetings neu liest. Plötzlich erscheint er und kennt deine Regeln bereits.
Das ist CLAUDE.md. KI-Coding-Tools starten jede Unterhaltung bei null – sie erinnern sich nicht an die Korrekturen von gestern. CLAUDE.md ist das Handbuch, das sie automatisch lesen, bevor sie auf irgendetwas antworten. Sieh es als die Verfassung deiner Codebasis: die Regeln, denen die KI folgen muss, die Muster, die sie nutzen muss, die Fehler, die sie nie machen darf.
Warum die KI ohne sie immer dieselben Fehler macht
Das ist mir passiert. Ich baute ein System zur Prüfung von Bewerbungen für meine Plattform – komplexe Bewertungslogik, mehrstufige Workflows, Dutzende Datenbanktabellen. Ich sagte Claude: „Baue den Service für die Bewerbungsprüfung."
Claude erzeugte Code. Er funktionierte. Und er war auf fünf Arten falsch:
- Er ignorierte die Struktur, der jeder andere Teil meiner Codebasis folgt
- Er erfand Datendefinitionen, die nicht zu meiner tatsächlichen Datenbank passten
- Er fügte eine Fehlerbehandlung hinzu, die mit dem bestehenden System kollidierte
- Er nutzte schnelle, schmutzige Debug-Ausgaben statt meines Logging-Setups
- Er vergaß Multi-Tenancy – das Kundenlabel, das an jeder Abfrage hängen muss
Ich korrigierte alles von Hand. Und die nächste Datei, die ich anforderte? Dieselben Fehler. Schon wieder. Ich kämpfte bei jeder einzelnen Datei mit Claude – nicht weil Claude schlecht ist, sondern weil es die Regeln meines Projekts vergessen hatte. Ohne CLAUDE.md trainierst du deine KI in jeder Unterhaltung von vorn neu.
Das BuchThe Solopreneur RevolutionLuis Gonçalves darüber, wie du neben dem Job mit KI ein Solopreneur-Business aufbaust.Zum Buch →Was in eine CLAUDE.md-Datei gehört
Eine gute CLAUDE.md hat sieben Abschnitte. Keiner verlangt, dass du Code schreibst – sie verlangen, dass du Entscheidungen formulierst, und genau das ist die Aufgabe des Architekten:
| Abschnitt | Was er der KI sagt | Beispiel (in einfachem Deutsch) |
|---|---|---|
| Projektcharakter | Was dieses Produkt ist und wie groß es ist | „Ein mandantenfähiges SaaS für Projektmanagement" |
| Kritische Regeln | Die Unverhandelbaren, als IMMER-/NIEMALS-Aussagen | „Versieh IMMER jede Abfrage mit der Organisation des Kunden" |
| Architekturmuster | Wie der Code hier aufgebaut ist | „Jeder Datenbankzugriff läuft über die Service-Schicht" |
| Tech-Stack | Die exakt verwendeten Werkzeuge | „Supabase für die Datenbank, bereitgestellt auf Cloudflare" |
| Dateiorte | Wohin was gehört | „Services liegen in einem Ordner, Bildschirme in einem anderen" |
| Beispiele | Echter Code aus deinem Projekt, der es richtig macht | Ein funktionierendes Feature, das die KI nachahmen soll |
| Anti-Patterns | Was man NICHT tun soll, mit falschem und richtigem Weg | „Hole NIEMALS Daten ohne das Kundenlabel" |
Die wirkungsvollsten Abschnitte sind die letzten beiden. KI ist eine Mustererkennungsmaschine: Zeig ihr ein echtes Beispiel für richtig gemachten Code, und sie ahmt es überall nach. Zeig ihr genau den Fehler, den sie letzte Woche gemacht hat, beschriftet mit „niemals so machen", und der Fehler verschwindet.
Was sich änderte, nachdem ich meine geschrieben hatte
Dieselbe Anfrage – „Baue den Service für die Bewerbungsprüfung" – nach dem Hinzufügen von CLAUDE.md. Claude las zuerst die Regeln und erzeugte dann Code, der meiner Struktur folgte, exakt zu meiner Datenbank passte, jede Abfrage für Multi-Tenancy beschriftete, Fehler auf meine Art behandelte und jede Datei an den richtigen Ort legte. Beim ersten Versuch. Null Korrekturen.
Der Moment, in dem ich wusste, dass es Magie ist: Ich brauchte ein Mentor-Matching-Feature – komplexe Logik, mehrere Tabellen. Vor CLAUDE.md hieß das Stunden des Korrigierens von KI-Output. Danach sagte ich „baue das Mentor-Matching mit denselben Mustern wie die Bewerbungsprüfung". Claude las das Regelwerk, studierte das frühere Feature und baute das Ganze nach allen Mustern. Es dauerte 15 Minuten und funktionierte perfekt.
Ohne die Datei musst du bei jeder erzeugten Datei mit etwa 30 Minuten Korrekturen rechnen – falsche Muster, fehlende Absicherungen, falsch abgelegte Dateien. Multipliziere das mit Hunderten von Dateien, und CLAUDE.md ist der Unterschied zwischen Ausliefern und Untergehen.
So fängst du heute mit deiner an
Schreib kein Meisterwerk. Fang mit fünf Regeln an – den fünf Fehlern, die deine KI in deinem Projekt immer wieder macht – plus einer Zeile, die beschreibt, was du baust und welchen Tech-Stack du nutzt. Das war's.
Dann behandle sie als lebendes Dokument. Jedes Mal, wenn die KI einen neuen Fehler macht, füge eine Regel hinzu. Jedes Mal, wenn sie etwas Großartiges erzeugt, kopiere den Code in den Beispielabschnitt. Der Sweet Spot liegt bei 200–400 Zeilen: Unter 100 Zeilen gibt zu wenig Kontext, über 500 ertrinkt die KI darin.
Eine Grenze, die du kennen solltest: CLAUDE.md enthält deine globalen, immer gültigen Regeln. Für große, einmalige Features willst du zusätzlich ein aufgabenspezifisches Briefing mit den genauen Anforderungen und dem Kontext dieses Features – das ist ein anderes Werkzeug, die PRP-Methode, und beide wirken zusammen: die Verfassung für jeden Tag, der Bauplan für jeden Bau.
12 WochenDeine Konzernkarriere war nie der PlanBewirb dich beim Solopreneur Accelerator.Jetzt bewerben →Häufig gestellte Fragen
Was ist eine CLAUDE.md-Datei?
Eine Markdown-Datei (Klartext) im Stammverzeichnis deines Projekts, die Claude Code vor jeder Antwort liest. Sie enthält die Regeln, Muster, den Tech-Stack, echte Code-Beispiele und Anti-Patterns deines Projekts – damit die KI deinen Standards gleich beim ersten Versuch folgt, statt in jeder Unterhaltung neu trainiert zu werden.
Muss ich programmieren können, um eine zu schreiben?
Nein. Die Datei ist in einfachem Deutsch geschrieben: was das Produkt ist, welche Regeln immer gelten müssen, was nie passieren darf. Für den Beispielabschnitt fügst du Code ein, den die KI selbst erzeugt hat, sobald sie etwas richtig gemacht hat. Entscheidungen zu formulieren ist die Aufgabe des Gründers; sie umzusetzen die der KI.
Wie lang sollte eine CLAUDE.md-Datei sein?
Fang heute mit fünf Regeln an. Lass sie auf 200–400 Zeilen wachsen – lang genug, um deine Muster zu tragen, kurz genug, dass die KI sie wirklich ganz nutzt. Unter 100 Zeilen ist zu dünn; ab 500 kürzen. Überprüfe sie wöchentlich: neue Muster ergänzen, veraltete Regeln löschen.
Reicht CLAUDE.md allein, um Features zu bauen?
Sie deckt die globalen Regeln ab – die Fehler, die sich sonst bei jeder Datei wiederholen würden. Für ein komplexes Feature willst du zusätzlich eine aufgabenspezifische Spezifikation mit den genauen Anforderungen, Daten und Validierungsschritten dieses Features. Das ist die PRP-Methode; CLAUDE.md plus ein PRP ist, wie Features gleich im ersten Durchgang richtig gebaut werden.
Wie gefangen bist du wirklich?
Mach den Corporate Suffocation Index – die kostenlose Einschätzung, ob du bereit bist, Solopreneur zu werden.