CLAUDE.md: die einfache Datei für bessere Coding-Agenten

Eine gute CLAUDE.md macht das Modell nicht intelligenter. Sie macht die Aufgabe bei jedem Eintritt in dein Repository weniger mehrdeutig.

Dieser bescheidene Mechanismus erklärt, warum ein Repository basierend auf vier einfachen Coding-Regeln zu einem der sichtbarsten Agent-Projekte 2026 wurde. Die Anweisungen sagen dem Agent, Annahmen zu äußern, einfache Implementierungen zu bevorzugen, Änderungen chirurgisch zu halten und überprüfbaren Erfolg zu definieren. Nichts davon ist neuartig. Alle vier vor jeder Aufgabe in den Kontext einzuführen ist der nützliche Teil.

Die virale Schlagzeile sagte, eine Datei erreichte 91.000 GitHub-Sterne. Bis zum 2. August 2026 war das Repository von forrestchang zu multica-ai gewandert, in Plugins und Editor-Regeln erweitert worden und hatte laut GitHub-API 198.529 Sterne erreicht.^[1] Die Zahl wird sich weiter ändern. Die haltbare Lektion ist, wie kleine, beständige Anweisungen das Verhalten des Agenten verändern.

TL;DR

• CLAUDE.md ist eine Markdown-Datei mit bleibenden Anweisungen, die Claude Code als Kontext lädt.^[2]
• Das virale Repository verdichtete häufige Agent-Fehlschläge zu vier Regeln: Vor dem Coden denken, Einfachheit zuerst, chirurgische Änderungen und zielgesteuerte Ausführung.^[3]
• Die Datei funktioniert am besten, wenn sie Fakten und Regeln enthält, die in fast jeder Sitzung gebraucht werden: Befehle, Architektur, Konventionen, Grenzen und Verifikation.
• CLAUDE.md ist Kontext, keine Durchsetzung. Nutze Berechtigungen oder Hooks für Aktionen, die technisch blockiert sein müssen.^[2]
• Halte aufgabenspezifische Verfahren in Skills und dateigebundene Leitung in .claude/rules/; alles global zu laden verschwendet Kontext.
• Eine nützliche Datei ist kurz genug, um gewartet zu werden, spezifisch genug, um getestet zu werden, und wird überarbeitet, wenn der Agent einen Fehler wiederholt.

Was ist CLAUDE.md?

CLAUDE.md ist Claude Codes Projekt-Anweisungsdatei. Es ist gewöhnliches Markdown, üblicherweise im Repository-Root gepflegt, das dem Agent dauerhaften Kontext wie folgt bietet:

• wie man das Projekt installiert, testet, baut und formatiert;
• die Teile der Architektur, die aus Dateinamen nicht offensichtlich sind;
• Benennungs- und Code-Stil-Konventionen;
• welche generierten Dateien nicht manuell bearbeitet werden sollten;
• welche Prüfungen vor Aufgabenabschluss bestanden werden müssen;
• Repository-spezifische Sicherheitsgrenzen.

Claude Code liest die Datei am Anfang einer Sitzung. Anthropic beschreibt sie als einen von zwei Memory-Mechanismen: Menschen schreiben CLAUDE.md-Anweisungen, während Claudes Auto-Memory Muster speichert, die es aus Korrektionen lernt.^[2]

Das klingt nach Konfiguration, aber Anthropic trifft eine wichtige Unterscheidung. Diese Anweisungen gehen in den Modell-Kontext; sie sind keine harten Kontrollen. Wenn „nie in Produktion deployen" garantiert sein muss, sind PreToolUse-Hooks oder Berechtigungsgrenzen die richtige Schicht. Ein Satz in Markdown kann Verhalten anleiten. Er kann keine Sicherheitsgarantie geben.

Warum die Vier-Regel-Datei viral ging

Das jetzt multica-ai/andrej-karpathy-skills genannte Repository sagt, seine Richtlinien seien von Andrej Karpathys öffentlichen Beobachtungen über Coding-Modell-Fehlschläge abgeleitet.^[3] Seine Popularität ist leicht zu verkomplizieren. Jede Regel ordnet eine bekannte Frustration einem Verhalten zu, das der Agent ausführen kann.

Diese Regeln lehren nicht TypeScript, Datenbankdesign oder Debugging. Sie formen, wie das Modell mit Unsicherheit und Umfang umgeht. Das macht sie über Repositories hinweg wiederverwendbar.

Die Einfachheit ist auch sozial. Ein Team kann vier Grundsätze in zwei Minuten lesen, mit einem nicht einverstanden sein, ihn bearbeiten und die Änderung in Git überprüfen. Es gibt keine versteckte Prompt-Plattform zu verwalten.

Die vier Grundsätze übersetzt in Projekt-Verhalten

1. Vor dem Coden denken

Die ursprüngliche Richtlinie verlangt vom Agent, Annahmen zu äußern, mehrere Interpretationen bei Bedarf darzustellen, auf unnötige Komplexität einzulenken und zu stoppen, wenn wirklich verwirrt.^[3]

Projektspezifisches Wording macht es stärker:

Vor dem Ändern eines API-Vertrags alle In-Repo-Consumer identifizieren und
festhalten, ob die Änderung rückwärts kompatibel ist. Wenn Produktverhalten
mehrdeutig ist, stoppen und fragen; wähle Verhalten nicht still.

Der generische Grundsatz setzt Haltung. Die konkrete Ergänzung sagt dem Agent, wo falsche Annahmen teuer sind.

2. Einfachheit zuerst

„Nicht über-engineeren" ist richtungsweiend aber schwer zu verifizieren. Füge die lokale Definition von einfach hinzu:

Bevorzuge ein bestehendes Utility über eine neue Abstraktion. Führe keinen
Service, keine Factory oder kein Konfigurationsfeature für einen Aufrufplatz
ein. Implementiere nur das geforderte Verhalten; liste optionale Folgearbeiten
statt diese zu bauen.

Das reduziert eine vorhersehbare Modell-Neigung: eine hypothetische Zukunftsproblem-Familie lösen statt die aktuelle.

3. Chirurgische Änderungen

Agenten sehen Cleanup-Gelegenheiten in der Nähe, weil sie breit lesen. Das bedeutet nicht, dass eine Aufgabe jedes Cleanup autorisiert.

Jede geänderte Zeile muss zur Anfrage rückverfolgbar sein. Erhalt umliegende
Formatierung und Namensgebung. Entferne Imports, die deine Bearbeitung
ungenutzt machte, aber berichte unverbundenen toten Code statt ihn zu löschen.

Kleine Diffs sind einfacher zu überprüfen, zu testen, zurückzusetzen und zuzuweisen. Sie reduzieren auch die Chance, dass ein Agent etwas bricht, dessen Zweck er nicht verstand.

4. Zielgesteuerte Ausführung

Eine Anweisung wie „mach es funktionieren" lässt den Endzustand undefiniert. Übersetze die Aufgabe in ein Ergebnis, das der Agent prüfen kann:

Für Bug-Fixes das Fehlschlagen mit einem Test reproduzieren vor dem Ändern von
Produktionscode. Die engsten relevanten Prüfungen bei Iteration und die
erforderlichen Projekt-Prüfungen vor Abschluss laufen. Befehle und Ergebnisse
berichten.

Hier wird Autonomie brauchbar. Wenn Erfolg beobachtbar ist, kann der Agent an Fehlschlägen iterieren statt nach der ersten plausiblen Bearbeitung zu stoppen.

Was gehört in CLAUDE.md

Anthropic empfiehlt, Fakten in CLAUDE.md zu halten, die Claude in jeder Sitzung halten sollte, und mehrstufige oder enge Verfahren zu gezielteren Mechanismen zu verschieben.^[2] Ein nützlicher Test ist: „Würde ich das bei fast jeder Aufgabe beim Onboarding wiederholen?"

Setze diese in die Stammdatei

• Absatz-Projekt und Architektur-Beschreibung;
• Package-Manager und kanonische Install-, Dev-, Test-, Type-Check- und Build-Befehle;
• Verzeichnis-Eigentümerschaft und generierte-Datei-Grenzen;
• Regeln, die über Sprachen oder Pakete gelten;
• Definition von Erledigung;
• hochfrequente Fehler und deren Korrektur;
• wo tiefere Anweisungen zu finden sind.

Setze diese anderswo hin

Ein knappes CLAUDE.md-Template

Kopiere das als Startpunkt, ersetze dann jedes Bracketed-Item. Lösche Abschnitte, die dein Projekt nicht einschränken.

# Projekt-Anweisungen

## Projekt

[Ein Absatz: was dieses Repository liefert, seine Haupt-Laufzeit und die
wichtigste architektonische Grenze.]

## Befehle

- Installieren: `[Befehl]`
- Entwicklung: `[Befehl]`
- Fokussierter Test: `[Befehl mit Datei oder Muster]`
- Vollständiger Test: `[Befehl]`
- Type-Check: `[Befehl]`
- Build: `[Befehl]`

## Vor Bearbeitung

- Lese die nächste bestehende Implementierung und Tests vor Vorschlag einer Änderung.
- Äußere Annahmen, die öffentliches Verhalten, Daten, Sicherheit oder Kompatibilität
  beeinflussen.
- Wenn die Anfrage mehrere materiell verschiedene Interpretationen hat, frag.

## Umfang

- Implementiere nur das geforderte Verhalten.
- Bevorzuge bestehende Muster und Utilities über neue Abstraktionen.
- Halte Diffs chirurgisch; refaktoriere benachbarten Code nicht ohne Anforderung.
- Entferne nur toten Code, den deine Änderung schuf.

## Projekt-Grenzen

- `[Pfad]` wird generiert; ändere statt `[Quellpfad oder Befehl]`.
- `[Paket]` besitzt `[Verantwortung]`; dupliziere sie nicht in `[anderem Paket]`.
- Expose niemals `[Geheimnis oder private Daten-Kategorie]` in Logs oder Fixtures.

## Stil

- [Zwei bis fünf Regeln, die sich von Formatter-Defaults unterscheiden oder leicht
  zu verpassen sind.]
- Gleiche die umliegende Datei an, wenn keine explizite Regel gilt.

## Verifikation

- Für einen Bug-Fix ein Test hinzufügen oder aktualisieren, der vor dem Fix
  fehlschlägt.
- Bei Iteration die engste relevante Prüfung laufen.
- Vor Abschluss: `[erforderliche Befehle]`.
- Geänderte Dateien, Befehle-Lauf, Ergebnisse und nicht-verifizierten Risiken
  berichten.

## Tiefere Anweisungen

- API-Arbeit: `.claude/rules/api.md`
- Datenbankänderungen: `[Skill- oder Dokumentations-Pfad]`
- Releases: `[Skill- oder Dokumentations-Pfad]`

Das Template ist absichtlich einfach. Eine CLAUDE.md sollte nicht wie ein Motivations-Manifest lesen. Sie sollte Entscheidungen reduzieren, die der Agent sonst raten müsste.

Wie Claude Code mehrere Anweisungs-Dateien lädt

Claude Code läuft den Verzeichnisbaum vom aktuellen Arbeitsverzeichnis hinauf und lädt CLAUDE.md und CLAUDE.local.md-Dateien, die es findet. Anweisungen näher zum Start-Verzeichnis erscheinen später in Kontext. Verschachtelte Dateien unter dem Arbeitsverzeichnis werden geladen, wenn Claude Dateien in jenen Unterverzeichnissen liest.^[2]

Für ein Monorepo erlaubt das eine nützliche Hierarchie:

repo/
├── CLAUDE.md                 # Organisations-breite Projekt-Fakten
├── .claude/
│   └── rules/
│       ├── testing.md        # Ungebundene gemeinsame Regel
│       └── api.md            # paths: packages/api/**
├── packages/
│   ├── web/
│   │   └── CLAUDE.md         # Web-spezifische Architektur und Prüfungen
│   └── worker/
│       └── CLAUDE.md         # Worker Laufzeit-Beschränkungen
└── CLAUDE.local.md           # Developer-Only lokale Notizen

Dateien werden als Kontext verkettet statt sich zu verhalten wie strikte Konfiguration-Überschreibung. Widersprüchliche Regeln können daher inkonsistentes Verhalten erzeugen. Überprüfe die Hierarchie periodisch und entferne veraltete Anweisungen.

Wie die Datei aus echten Fehlschlägen verbessert wird

Versuche nicht, an Tag eins jeden möglichen Fehler vorauszusagen. Beginne klein und nutze wiederholte Reibung als Backlog.

1. Rekordiere den Fehlschlag. Was tat der Agent und was hast du erwartet?
2. Finde die richtige Schicht. Ist das eine universelle Anweisung, eine pfad-spezifische Regel, ein Aufgaben-Verfahren oder eine harte Sicherheits- kontrolle?
3. Schreibe eine beobachtbare Regel. Ersetze „sei vorsichtig" mit der Aktion und Bedingung.
4. Teste sie auf ähnlicher Aufgabe. Bestätige, dass sich Verhalten verbessert ohne triviale Arbeit zu blockieren.
5. Lösche veraltete Regeln. Kontext hat Kosten; eine obsolete Anweisung kann schlechter sein als keine.

Anthropic's praktischer Auslöser ist merkwürdig: füge etwas hinzu, wenn Claude denselben Fehler zweimal macht, wenn Code-Überprüfung Wissen entdeckt, das der Agent haben sollte, oder wenn du dieselbe Korrektur über Sitzungen wiederholst.^[2]

Fünf CLAUDE.md-Fehler zu vermeiden

Aspirationen statt Anweisungen schreiben

„Schreibe exzellenten, robusten Code" gibt keine neuen Informationen. „Laufe pnpm test --filter api nach Änderungen unter packages/api" kann gefolgt und geprüft werden.

Ein riesiges generisches Regelwerk kopieren

Ein öffentliches Template kann Ideen geben, aber jede unbedingte Zeile verbraucht Kontext und kann mit dem Projekt konfligieren. Behalte die vier breiten Verhaltens-Grundsätze wenn sie helfen; ersetze generische Technologie-Ratschläge mit lokalen Fakten.

Fakten kodieren, die der Agent billig entdecken kann

Du brauchst selten jedes Verzeichnis aufzulisten. Erkläre Grenzen, die Dateinamen nicht offenbaren, wie welches Paket Autorisierung besitzt oder welche Quelle einen eingecheckten Client generiert.

Anweisungen als Sicherheits-Kontrollen behandeln

Verlasse dich niemals auf „lese keine Geheimnisse" oder „deploye nicht" als einzigen Schutz. Nutze gebundete Anmeldedaten, Berechtigungen, Sandboxing und Hooks für harte Grenzen.

Die Datei nie überprüfen

Befehle ändern sich, Pakete bewegen sich und alte Ausnahmen werden Standard- verhalten. Weise Eigentümerschaft zu und überprüfe CLAUDE.md wie Code.

Wie du weißt, ob es funktioniert

Vermeide Wertung der Datei, ob eine Demo beeindruckend aussieht. Messe bereits überprüfte Arbeit des Teams:

• mittlere geänderte Zeilen pro abgeschlossener Aufgabe;
• unverbundene berührte Dateien;
• Überprüfungs-Kommentare verursacht durch Repository-Konventions-Verletzungen;
• Erst-Pass-Test-Erfolg;
• nach behauptetem Abschluss erneut geöffnete Aufgaben;
• wiederholte Klarstellungen, die zum permanenten Kontext werden sollten.

Das virale Repository deutet denselben Outcome-Level-Test: weniger unnötige Diff-Änderungen, weniger Umschreibungen verursacht durch Überkomplexität und Klarstellung vor Implementierung statt nach Fehlern.^[3]

FAQ

Wo sollte CLAUDE.md hingehen?

Für team-geteilte Projekt-Anweisungen, platziere es bei ./CLAUDE.md oder ./.claude/CLAUDE.md und committe es. Nutze ~/.claude/CLAUDE.md für persönliche Anweisungen über Projekte und CLAUDE.local.md für persönliche Notizen in einem.^[2]

Funktioniert CLAUDE.md mit Cursor oder anderen Coding-Agenten?

CLAUDE.md ist eine Claude-Code-Konvention. Das virale Repository liefert auch Cursor-Regeln und ein Plugin, während andere Agenten Dateien wie AGENTS.md oder produkt-spezifische Regel-Verzeichnisse nutzen können. Halte eine kanonische Quelle und adaptiere sie absichtlich statt zu vermuten, jedes Tool lädt dieselbe Datei.

Wie lang sollte CLAUDE.md sein?

Es gibt keine universelle Zeilenzahl. Sie sollte nur Information enthalten, die wertvoll in fast jeder Sitzung ist. Wenn ein Abschnitt nur ein Verzeichnis oder einen Workflow anwendet, verschiebe ihn zu einer pfad-gebundenen Regel oder Skill.

Kann CLAUDE.md destruktive Befehle stoppen?

Sie kann Claude instruieren, sie nicht zu laufen, aber Anthropic beschreibt die Datei explizit als Kontext statt durchgesetzte Konfiguration. Nutze Berechtigungen oder Hooks für zuverlässige Verhinderung.^[2]

Wie erstelle ich die erste Datei?

Führe /init in Claude Code aus, um einen Start CLAUDE.md zu generieren, oder erstelle die Markdown-Datei manuell. Dann laufe /context, um zu bestätigen, dass es geladen wurde, und /memory, um Memory-Dateien zu inspizieren oder zu bearbeiten.^[4]

Die Datei ist einfach, weil das Problem repetitiv ist

Coding-Agenten brauchen keine 500-Zeilen-Verfassung bevor sie einen Bug beherrschbar machen. Sie brauchen ein paar Projekt-Fakten, die sie nicht inferieren können, eine klare Grenze um die geforderte Änderung und eine Prüfung, die Abschluss von Vertrauen unterscheidet.

Das ist, warum vier gewöhnliche Regeln so weit fuhren. Sie beheben Fehler, die Entwickler täglich sehen, leben in einem Format, das das ganze Team bearbeiten kann, und werden geladen bevor der Agent Entscheidungen trifft. Beginne dort. Füge Projekt-Wissen nur hinzu, wenn es einen echten Fehlschlag verhindert, und erzwinge kritische Grenzen außerhalb des Prompts.

Wenn du das Werkzeug selbst neu bist, beginne mit dem breiteren Leitfaden zum Nutzen von Claude Code. Nutze diesen Artikel wenn die Installation fertig ist und die nächste Frage ist, was dein Agent jedes Mal bei Eintritt ins Repo wissen sollte.

References

1. GitHub REST API. multica-ai/andrej-karpathy-skills repository metadata. Retrieved August 2, 2026. api.github.com
2. Anthropic. How Claude remembers your project. Claude Code Docs. Retrieved August 2026. code.claude.com
3. multica-ai. Karpathy-Inspired Claude Code Guidelines. GitHub. Retrieved August 2026. github.com
4. Anthropic. Claude Code commands. Retrieved August 2026. code.claude.com
5. Sumit Pandey. A Single CLAUDE.md File Went Viral. The Reason Is Embarrassingly Simple. Towards Deep Learning, May 2026. towardsdeeplearning.com

Further reading

• reAPI. How to use Claude Code. reapi.ai/blog/how-to-use-claude-code
• reAPI. How to get a Claude API key. reapi.ai/blog/how-to-get-claude-api-key
• reAPI. Claude model catalog. reapi.ai/models