CLAUDE.md richtig schreiben: Praxistemplate für Claude Code

Zum dritten Mal kommt derselbe Kommentar im Pull Request zurück. Claude Code hat zwar die richtige Funktion geändert, aber den Testbefehl des Repositories übersehen, eine nicht beauftragte Migration angefasst oder die mobile Ansicht nicht geprüft. Ein noch längerer Prompt in jeder neuen Sitzung löst dieses Betriebsproblem nicht.

Eine brauchbare CLAUDE.md gibt Claude Code vor Arbeitsbeginn wenige, dauerhaft gültige Entscheidungen mit. Sie muss weder das ganze Unternehmen erklären noch die README kopieren. Dieser Leitfaden zeigt, was in die Datei gehört, welche Grenzen anderswo technisch durchgesetzt werden müssen und wie sich das Ergebnis mit einem lauffähigen Node.js-Prüfskript testen lässt.

Die kurze Antwort

In eine CLAUDE.md gehören Befehle, Bearbeitungsgrenzen und Prüfkriterien, die für die meisten Aufgaben in ihrem Geltungsbereich gelten. Fünf Regeln reichen für den Anfang:

CLAUDE.md ist eine dauerhafte Arbeitsanweisung für Claude Code, aber keine Zugriffskontrolle.
Gemeinsame Regeln liegen im Repository-Stamm, persönliche Notizen in CLAUDE.local.md und pfadbezogene Regeln in .claude/rules/.
Die Datei sollte ungefähr unter 200 Zeilen bleiben. Dateipfade, Befehle und eindeutige Erfolgskriterien sind wertvoller als lange Hintergrundtexte.
Sicherheitsgrenzen werden mit Berechtigungen und Hooks durchgesetzt, nicht nur mit einer schriftlichen Warnung.
Eine neue Regel wird zuerst an einer kleinen echten Aufgabe getestet, bevor sie als Teamstandard gilt.

Die erste Version muss nicht perfekt sein. Sammeln Sie die Hinweise aus den letzten drei Reviews und behalten Sie nur Entscheidungen, die voraussichtlich erneut gebraucht werden.

Was Claude Code übernehmen kann und was Menschen entscheiden müssen

Eine Anweisungsdatei und eine technische Berechtigungsgrenze lösen unterschiedliche Probleme. Claude Code kann bestehenden Code untersuchen, eine klar abgegrenzte Änderung umsetzen, benannte Prüfungen ausführen und den Diff zusammenfassen. Produktpolitik, Freigaben sowie Entscheidungen zu Kundendaten, Geld, Datenschutz oder Recht bleiben beim Menschen.

Entscheidung	An Claude Code delegieren	Beim Menschen belassen
Untersuchung	Zugehörige Dateien, Muster und Tests finden	Entscheiden, ob Kunden- oder Vertragsdaten untersucht werden dürfen
Umsetzung	Code und Tests im genannten Bereich ändern	Preise, Rechte, Rechtstexte und kundenwirksame Richtlinien freigeben
Prüfung	Linting, Typprüfung, Tests und Build ausführen	Akzeptanzkriterien bewerten und Veröffentlichung freigeben
Pflege	Geänderte Dateien und offene Risiken melden	Dauerhafte Repository-Regeln hinzufügen oder löschen

CLAUDE.md sagt sinngemäß: „Prüfe diese Punkte in dieser Reihenfolge.“ Sie garantiert nicht, dass ein destruktiver Befehl niemals läuft. Wenn git push --force, der Zugriff auf eine Produktionsdatenbank oder Dateien mit Geheimnissen wirklich blockiert werden müssen, verwenden Sie Deny-Regeln für Berechtigungen oder einen PreToolUse-Hook. Der Leitfaden zu Claude-Code-Berechtigungen behandelt diese technische Schutzschicht getrennt.

Vor dem Schreiben den richtigen Geltungsbereich wählen

Der Speicherort bestimmt, wo eine Anweisung gilt. Eine CLAUDE.md im Repository-Stamm eignet sich für gemeinsame Projektregeln. ~/.claude/CLAUDE.md gilt für die Projekte eines Benutzers. CLAUDE.local.md ist für private, rechnerbezogene Hinweise gedacht und sollte von Git ignoriert werden. Verschachtelte Dateien und pfadbezogene Regeln verhindern in großen Repositories, dass unpassende Informationen ständig geladen werden.

repo/
  CLAUDE.md                  # short rules shared by the team
  CLAUDE.local.md            # personal notes; add to .gitignore
  .claude/
    rules/
      api.md                 # rules needed only for API files
  packages/
    admin/
      CLAUDE.md              # added when Claude reads this subtree

Beim Start liest Claude Code die anwendbaren Dateien im aktuellen Verzeichnis und in dessen übergeordneten Verzeichnissen. Eine verschachtelte CLAUDE.md wird geladen, sobald Claude Dateien in diesem Teilbaum liest. Deshalb gehören Paketregeln in die Nähe des Pakets, statt jede Anweisung in die Stammdatei zu schreiben.

Ein Import wie @docs/project-map.md kann Anweisungen übersichtlicher gliedern, spart aber keinen Kontext. Importierte Inhalte werden ebenfalls beim Start geladen. Behalten Sie die ständig nötige Entscheidung in CLAUDE.md und verweisen Sie für Details auf Material, das nur bei Bedarf gelesen wird. Unter Windows liest Claude Code CLAUDE.md und nicht AGENTS.md; ein ausdrücklicher Import mit @AGENTS.md ist deshalb zuverlässiger als ein Symlink.

Mit diesem CLAUDE.md-Template beginnen

Befehle und Änderungsregeln sollten auf einen Bildschirm passen. Die folgende Vorlage vermeidet unprüfbare Sätze wie „Schreibe sauberen Code“. Stattdessen nennt sie Pfade, Prüfungen, ausgeschlossene Bereiche und den erwarteten Abschlussbericht.

# Project Instructions

## Project map
- App: Next.js 15 + TypeScript
- API: src/app/api/**
- Database schema: prisma/schema.prisma
- Tests: Vitest for units, Playwright for checkout

## Commands
- Install: npm ci
- Type check: npm run typecheck
- Unit tests: npm test
- Lint: npm run lint
- Build: npm run build

## Change rules
- Follow nearby code before adding a new abstraction.
- Do not change auth, billing, or migrations unless the task names them.
- When an API handler changes, update validation and tests together.
- Never place secrets in code, fixtures, logs, or screenshots.

## Review checklist
- Run the checks related to the changed files.
- Test an error path as well as the happy path.
- Report changed files, commands run, and skipped checks.

Die Datei darf in der Sprache des Teams geschrieben sein. Genauigkeit ist wichtiger als die Sprache. Ersetzen Sie „angemessen testen“ durch npm test. Aus „die bestehende Architektur beachten“ wird zum Beispiel „API-Antworten verwenden src/lib/api-response.ts“. Ein Reviewer muss ohne Raten feststellen können, ob die Regel eingehalten wurde.

Drei praktische Anwendungsfälle

Die folgenden Abläufe trennen Eingabe, Ausgabe und menschliche Kontrolle. Bevor eine Erkenntnis dauerhaft in CLAUDE.md landet, sollte eine kleine Aufgabe zeigen, ob die Regel das beobachtbare Ergebnis wirklich verbessert.

Anwendungsfall 1: Wiederholte Review-Kommentare einer Agentur reduzieren

Eine Webagentur verwendet je nach Kundenprojekt andere CSS-Konventionen, Bildgrößen und Browserziele. Das komplette Agenturhandbuch in jedes Repository zu kopieren macht die wichtigen Regeln schwer auffindbar. Besser sind drei bis fünf Prüfungen, die genau für diesen Kunden und diese Codebasis gelten.

Eingabe: Die letzten drei Review-Verläufe, die Dateien im Arbeitsumfang sowie vorhandene Lint- und Build-Befehle.

Ausgabe: Ein Diff-Bericht mit wiederverwendeten Komponenten, geänderten Seiten, ausgeführten Befehlen und noch ungeprüften Browserbedingungen.

Menschliche Kontrolle: Gestaltungsabsicht, Bildrechte, CTA-Text und die endgültige mobile Darstellung. Vergleichen Sie bei jeweils zehn Aufgaben vor und nach der Änderung, wie oft ein Review zurückgeht. Diese Kennzahl ist aussagekräftiger als die Länge der CLAUDE.md.

Anwendungsfall 2: Ein SaaS-Kontaktformular sicher ändern

Ein Formular kann richtig aussehen, obwohl serverseitige Validierung, Benachrichtigungsmail oder Fehlerbehandlung defekt bleiben. Die Projektanweisung sollte Dateien und Prüfungen nennen, die bei jeder Formularänderung gemeinsam angepasst werden.

Eingabe: Formularkomponente, Validierungsschema, API-Handler, E-Mail-Template und bestehende Tests.

Ausgabe: Tests für Erfolgsfall und ungültige Eingaben, verständliche Fehlermeldungen und eine Liste geänderter Einstellungen. Der Abschlussbericht bestätigt außerdem, dass keine personenbezogenen Daten in Logs geschrieben wurden.

Menschliche Kontrolle: Erhobene Datenfelder, Aufbewahrungsdauer, Empfänger der Benachrichtigung und Produktionsfreigabe. Neben der Conversion-Rate sollten fehlgeschlagene Übermittlungen und Bearbeitungszeit gemessen werden.

Anwendungsfall 3: Unvollständige Content-Veröffentlichungen verhindern

Eine MDX-Seite kann fachlich richtig sein und trotzdem ohne Description, internen Link, Titelbild oder brauchbaren mobilen Codeblock erscheinen. Eine kurze Veröffentlichungsliste gibt Claude Code ein sichtbar erreichbares Ziel.

Eingabe: MDX-Datei, Frontmatter-Schema, Ziele interner Links, Build-Befehl und Produktions-URL.

Ausgabe: Länge der Description, Ergebnis der Linkprüfung, Kontrolle der Codeblöcke, Build-Status und im Browser geprüfte URLs.

Menschliche Kontrolle: Fachliche Richtigkeit, Suchintention, Anzeigenplatzierung, Lesbarkeit und Veröffentlichung. Bewerten Sie wöchentlich Suchklicks, engagierte Lesezeit und CTA-Klicks, statt nur Seitenaufrufe zu betrachten.

CLAUDE.md mit einem lauffähigen Skript prüfen

Das folgende Node.js-Skript prüft die Zeilenzahl, erforderliche Überschriften und einige besonders aussagekräftige Muster für Geheimnisse. Speichern Sie es als check-claude-md.mjs und führen Sie es mit Node.js 20 oder neuer aus.

import { readFile } from "node:fs/promises";

const filePath = process.argv[2] ?? "CLAUDE.md";
const text = await readFile(filePath, "utf8");
const lines = text.split(/\r?\n/);
const lineCount = text.endsWith("\n") ? lines.length - 1 : lines.length;

// Pass localized H2 names as the third argument, separated by "|".
const requiredHeadings = (
  process.argv[3] ?? "Commands|Change rules|Review checklist"
)
  .split("|")
  .map((heading) => heading.trim())
  .filter(Boolean);
const h2Headings = new Set();
let fenceMarker = null;

for (const line of lines) {
  const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
  if (fenceMatch) {
    const marker = fenceMatch[1];
    if (fenceMarker === null) fenceMarker = marker;
    else if (marker[0] === fenceMarker[0] && marker.length >= fenceMarker.length) fenceMarker = null;
    continue;
  }
  if (fenceMarker !== null) continue;

  const heading = line.match(/^##\s+(.+?)\s*$/)?.[1];
  if (heading) h2Headings.add(heading);
}

const secretPatterns = [
  ["AWS access key", /AKIA[0-9A-Z]{16}/],
  ["GitHub token", /gh[pousr]_[A-Za-z0-9]{20,}/],
  ["assigned secret", /\b(api[_-]?key|password|token)\s*[:=]\s*["'][^"'\n]{8,}["']/i],
];

const failures = [];
if (lineCount > 200) failures.push(`too many lines: ${lineCount} (max 200)`);
if (requiredHeadings.length === 0) failures.push("required heading list is empty");

for (const heading of requiredHeadings) {
  if (!h2Headings.has(heading)) failures.push(`missing h2: ${heading}`);
}

for (const [label, pattern] of secretPatterns) {
  if (pattern.test(text)) failures.push(`possible secret: ${label}`);
}

if (failures.length > 0) {
  console.table(failures.map((problem) => ({ problem })));
  process.exitCode = 1;
} else {
  console.log(`CLAUDE.md check passed: ${lineCount} lines`);
}

Der Aufruf ist bewusst einfach und kann lokal wie in der CI verwendet werden:

node check-claude-md.mjs CLAUDE.md
# Bei deutschen H2-Überschriften
node check-claude-md.mjs CLAUDE.md "Befehle|Änderungsregeln|Prüfliste"

Dieses Skript ersetzt keinen vollständigen Secret-Scanner. Kombinieren Sie es mit GitHub Secret Scanning oder einem spezialisierten Werkzeug. Wird ein Zugangswert gefunden, muss er gegebenenfalls aus der Historie entfernt und widerrufen werden; nur die sichtbare Zeile zu löschen reicht nicht.

Fallstricke mit Ursache und Korrektur

Fallstrick 1: Die Datei wächst nach jedem Review. Ursache ist, dass jeder Kommentar sofort zur dauerhaften Regel wird, ohne seine Wiederholungswahrscheinlichkeit zu prüfen. Nehmen Sie nur wiederkehrende Entscheidungen auf, löschen Sie zuerst veraltete Befehle und verschieben Sie paketbezogene Details näher an das Paket.

Fallstrick 2: Anweisungen lassen sich nicht prüfen. „Hohe Qualität sichern“ und „dem bestehenden Design folgen“ definieren kein Erfolgskriterium. Nennen Sie stattdessen Zielpfad, Befehl, erwarteten Exit-Code, Browserbreite oder konkreten Test. Ein neues Teammitglied sollte zum gleichen Urteil kommen wie der Verfasser.

Fallstrick 3: Sicherheit hängt von Prosa ab. Der Satz „Niemals die Produktion anfassen“ baut keine Barriere. Gefährliche Befehlsmuster gehören in Deny-Regeln; ein PreToolUse-Hook stoppt Vorgänge, die deterministisch blockiert werden müssen. CLAUDE.md enthält nur den Grund und den erlaubten Ersatzweg.

Fallstrick 4: Imports werden zum versteckten Wissenslager. Ursache ist die Annahme, importierte Dateien kosteten keinen Kontext. Sie werden beim Start geladen. Halten Sie die Entscheidungsregel in der Stammdatei kurz und nennen Sie für aufgabenspezifische Details einen Pfad oder eine URL.

Pflege ohne veraltete Dokumentation

Behandeln Sie eine Änderung an CLAUDE.md wie eine Codeänderung: Diff lesen, Prüfer ausführen und eine repräsentative Aufgabe testen. Löschen Sie eine Regel, sobald Befehl, Pfad oder Architektur nicht mehr existiert.

Für eine kurze monatliche Prüfung genügen vier Fragen:

Welcher Review-Kommentar kam mehr als einmal vor?
Welche Anweisung wurde ignoriert oder unterschiedlich ausgelegt?
Welcher Befehl oder Pfad ist veraltet?
Welche Warnung sollte durch Berechtigungen oder einen Hook durchgesetzt werden?

Entscheidend sind nicht Tokenzahl oder Dokumentlänge. Messen Sie zurückgewiesene Reviews, vor dem Merge erkannte Prüffehler und die Zeit, die für wiederholte Projekterklärungen anfällt. Verbessern sich diese Werte nicht, wird die Regel umgeschrieben oder gelöscht.

Häufig gestellte Fragen

Wie lang sollte eine CLAUDE.md sein?

Es gibt keine starre Inhaltsgrenze, doch die offizielle Empfehlung nennt weniger als 200 Zeilen als Ziel. Mit ungefähr 100 Zeilen bleibt Platz für Projektübersicht, Befehle, Grenzen und Prüfkriterien. Nur für ein Paket relevante Inhalte wandern in verschachtelte Dateien oder .claude/rules/.

Bleibt die Datei nach /compact erhalten?

Die CLAUDE.md im Stamm wird nach der Komprimierung erneut in den Kontext eingefügt. Verschachtelte und pfadbezogene Anweisungen werden wieder geladen, sobald Claude passende Dateien liest. Dauerhafte Entscheidungen gehören deshalb in Dateien und nicht nur in eine Unterhaltung, die komprimiert werden kann.

Worin unterscheidet sich Auto Memory?

CLAUDE.md enthält von Menschen verfasste und gepflegte Anweisungen. Auto Memory enthält lokale Notizen, die Claude aus der Arbeit speichert, etwa Erkenntnisse aus der Fehlersuche und Präferenzen. Gemeinsame Befehle und Grenzen gehören in CLAUDE.md; lokale Entdeckungen bleiben in Auto Memory, bis ein Mensch sie bewusst zur Teamregel macht.

Was gehört in die erste Version?

Beginnen Sie mit Installations-, Test- und Build-Befehl, einer Liste geschützter Bereiche und den Pflichtangaben des Abschlussberichts. Führen Sie eine echte Aufgabe aus und ergänzen Sie danach nur die fehlende Entscheidung, die nachweisbar zu Nacharbeit geführt hat.

Eine eigene Projektvorlage mit den Lernmaterialien erstellen

CLAUDE.md ist nur ein Baustein eines verlässlichen Ablaufs. Berechtigungen, Tests, Übergabe und Review müssen dazu passen. Im ClaudeCodeLab-Produktkatalog finden Sie wiederverwendbare Checklisten und Übungen, aus denen sich eine projektspezifische Arbeitsvorlage erstellen lässt.

Was tatsächlich getestet wurde

Am 22. Juli 2026 wurde der in diesem Artikel gezeigte Code aus check-claude-md.mjs mit zwei temporären Testdateien ausgeführt. Ein gültiges Beispiel mit 10 Zeilen lieferte Exit-Code 0 und die Erfolgsmeldung. Ein negatives Beispiel mit einer fehlenden Überschrift und einem Test-Token lieferte Exit-Code 1 und genau drei Befunde: die fehlende Überschrift sowie zwei passende Secret-Muster.

Bei der Artikelprüfung wurden außerdem JavaScript-Syntax, offizielle Quell-URLs, interne Links, Frontmatter, der abschließende Ergebnisabschnitt und genau ein primärer kommerzieller CTA kontrolliert. Führen Sie zuerst den Prüfer für Ihre eigene CLAUDE.md aus und beheben Sie den ersten gemeldeten Punkt. Das beschriebene Produktverhalten wurde mit der offiziellen Claude-Code-Dokumentation zu Memory, Kontextfenstern, Settings und Hooks abgeglichen.