CLAUDE.md schreiben: Anweisungen, die Claude Code wirklich befolgt.

Was CLAUDE.md ist

Jede Sitzung von Claude Code beginnt mit einem leeren Kontext. Das Programm kennt weder deine Firma noch deine Gewohnheiten noch das, was du gestern besprochen hast. CLAUDE.md ist eine einfache Textdatei im Markdown-Format, die Claude Code zu Beginn jeder Sitzung liest. Sie ist der Ort, an dem du aufschreibst, was du sonst immer wieder erklären würdest: Projektaufbau, Befehle, Regeln, Tonalität, Grenzen.

Neben dieser Datei gibt es das automatische Gedächtnis („Auto memory“): Notizen, die Claude Code selbst aus deinen Korrekturen anlegt. Beides wird zu Beginn jeder Sitzung geladen. Der Unterschied: CLAUDE.md schreibst du, das automatische Gedächtnis schreibt Claude. Für Regeln, auf die du dich verlassen willst, ist die Datei der richtige Ort, weil du sie lesen, prüfen und im Team teilen kannst.

Wichtig ist, wie die Datei wirkt: Claude Code behandelt sie als Kontext und nicht als technische Konfiguration. Das Modell berücksichtigt sie in aller Regel, aber sie ist keine Garantie. Je konkreter und kürzer die Anweisungen sind, desto zuverlässiger werden sie befolgt.

Wo die Datei liegt

Es gibt mehrere Orte mit unterschiedlicher Reichweite. Claude Code lädt sie von der breitesten zur engsten Ebene, sodass eine Projektanweisung nach der persönlichen im Kontext steht.

Claude Code lädt die Dateien aus dem aktuellen Ordner und allen Ordnern darüber beim Start. Dateien in Unterordnern werden erst geladen, wenn Claude eine Datei in diesem Unterordner liest oder ändert. Alles wird zusammengefügt, nichts überschreibt sich. Bei Widersprüchen kann das Modell eine Anweisung auswählen, ohne es zu sagen. Deshalb sind widerspruchsfreie Dateien wichtig.

Ob die Datei geladen wurde, siehst du in der Sitzung mit dem Befehl /context unter „Memory files“. Mit /init erzeugt Claude Code eine erste Fassung, indem es dein Projekt untersucht und Befehle und Konventionen aufschreibt. Das ist ein guter Anfang, aber noch nicht dein Ergebnis. Du kürzt, korrigierst und ergänzt.

Wenn dein Repository bereits eine AGENTS.md für andere Werkzeuge hat, kann Claude Code diese Datei anstelle einer CLAUDE.md lesen.

Was hineingehört und was nicht

Die Dokumentation formuliert eine einfache Faustregel: Schreibe auf, was du sonst erneut erklären würdest. Gute Gründe, etwas aufzunehmen:

• Claude Code macht denselben Fehler zum zweiten Mal.
• Eine Prüfung hat etwas bemängelt, das Claude über dein Projekt hätte wissen müssen.
• Du tippst dieselbe Korrektur wie in der letzten Sitzung.
• Eine neue Kollegin bräuchte dieselbe Information, um loszulegen.

Gehört hinein

• Befehle, die Claude nicht erraten kann: wie du die Seite baust, testest und veröffentlichst.
• Aufbau des Projekts: welche Ordner wofür da sind.
• Konventionen: Benennung, Schreibweise, Format von Dokumenten.
• Regeln und Grenzen: was Claude tun soll und was nie.
• Tonalität und Zielgruppe bei Texten.
• Verweise auf wichtige Dokumente.

Gehört nicht hinein

• Mehrstufige Abläufe, die nur manchmal gebraucht werden. Sie gehören in einen Skill, der bei Bedarf aufgerufen wird.
• Regeln, die nur für einen Teil des Projekts gelten. Dafür gibt es Regeldateien in .claude/rules/, die sich auf Dateitypen oder Ordner beschränken lassen.
• Passwörter, Schlüssel und Kundendaten. Niemals. Die Datei liegt im Projekt und wird oft geteilt.
• Selbstverständliches. Was Claude ohnehin richtig macht, kostet nur Platz.
• Überholtes. Alte Regeln widersprechen neuen und verwirren das Modell.

So schreibst du wirksame Regeln

1. Schreibe prüfbar

Eine Regel ist gut, wenn du an einem Ergebnis erkennen kannst, ob sie befolgt wurde. Die Dokumentation nennt drei Beispiele:

Für Texte gilt dasselbe: „Schreibe verständlich“ ist schwach. „Schreibe in ganzen Sätzen, höchstens 20 Wörter pro Satz, ohne Fachbegriffe ohne Erklärung“ ist stark.

2. Halte sie kurz

Als Zielgröße nennt die Dokumentation höchstens etwa 200 Zeilen pro Datei. Längere Dateien verbrauchen mehr Kontext und verschlechtern die Befolgung. Gehört mehr hinein, teile es: Regeln für Teilbereiche in Regeldateien, mehrstufige Abläufe in Skills.

3. Gliedere nach Themen

Überschriften und Aufzählungen sind für das Modell leichter zu befolgen als lange Fließtexte. Gruppiere nach Themen (Befehle, Aufbau, Regeln, Grenzen) und halte jede Regel in einem Satz.

4. Vermeide Widersprüche

Wenn zwei Anweisungen sich widersprechen, wählt Claude möglicherweise eine beliebige. Prüfe deshalb auch Dateien in Unterordnern und Regeldateien. Laut Dokumentation kann Claude Code deine Anweisungsdateien auf veraltete oder widersprüchliche Inhalte untersuchen (Befehl /doctor prompt-audit, verfügbar ab einer bestimmten Programmversion). Prüfe in der aktuellen Dokumentation, ob er bei dir verfügbar ist.

5. Sage, was du willst, und warum

„Verwende keine Abkürzungen“ wird zuverlässiger befolgt als ein reines Verbot, wenn der Grund dabei steht: „Die Leser:innen sind Einsteiger, deshalb schreiben wir Begriffe aus.“ Der Grund hilft dem Modell, in Grenzfällen richtig zu entscheiden.

6. Schreibe für Menschen mit

Die Datei wird auch von Kolleg:innen gelesen. Wenn du Notizen für Menschen hinterlassen willst, die Claude nicht sehen soll, setze sie als HTML-Kommentar (<!-- Hinweis -->). Solche Kommentare werden vor dem Laden entfernt und kosten keinen Kontext.

Struktur, Imports und Regeldateien

Imports mit @

Du kannst andere Dateien einbinden, indem du ihren Pfad mit einem @ davor in die Datei schreibst:

Projektüberblick: @README.md
Befehle: @package.json
Git-Ablauf: @docs/git-anleitung.md

Die eingebundenen Dateien werden beim Start mitgeladen. Relative Pfade beziehen sich auf die Datei, in der der Import steht. Imports dürfen sich verschachteln, bis zu vier Ebenen tief. Wichtig: Imports ordnen eine lange Datei, sparen aber keinen Kontext, weil die eingebundenen Dateien ebenfalls geladen werden. Wer einen Pfad im Text erwähnen will, ohne ihn zu importieren, setzt ihn in Backticks.

Persönliche Vorlieben

Alles, was nur dich betrifft (deine Testadressen, deine Arbeitsweise), gehört in CLAUDE.local.md, die du in .gitignore einträgst, oder in deine persönliche Datei unter ~/.claude/.

Regeldateien

Für große Projekte kannst du Anweisungen in einzelne Themendateien unter .claude/rules/ aufteilen und auf Dateitypen oder Ordner begrenzen. Die Regeln laden dann nur, wenn Claude mit passenden Dateien arbeitet. So bleibt die Hauptdatei kurz.

Skills statt langer Abläufe

Alles, was ein mehrstufiger Ablauf ist (zum Beispiel „Wochenbericht erstellen“ oder „Testseite veröffentlichen“), gehört in einen Skill. Der Skill wird bei Bedarf geladen und mit / aufgerufen. Er belastet den Kontext nicht in jeder Sitzung.

Vorlage 1: Gründer-Projekt (Testseite und Recherche)

Für dein erstes Projekt, etwa eine Testseite mit Recherche. Passe die Klammern an und streiche, was nicht passt.

# Projekt: [Name der Idee]

## Worum es geht
- Zielgruppe: [wer genau, in einem Satz]
- These: Bis [Datum] melden sich [Zahl] Menschen aus [Zielgruppe] für [Angebot] an.
- Wir bauen eine einfache Testseite und sammeln Gespräche. Kein fertiges Produkt.

## Aufbau
- Die Seite liegt in `site/index.html`, Bilder in `site/img/`.
- Recherche und Notizen liegen in `notes/`. Das Briefing liegt in `briefing.md`.

## Befehle
- Seite lokal öffnen: [Befehl oder Hinweis]
- Veröffentlichen: [Befehl oder Dienst]

## Regeln
- Nur statische Seiten mit HTML und CSS, keine Frameworks.
- Texte in einfachen Sätzen, Zielgruppe sind Einsteiger.
- Die Seite hat genau eine Handlung: die Anmeldung.
- Zahlen, Namen und Quellen nur aus belegten Quellen. Unbelegtes wird mit „offen“ markiert.
- Speichere nach jedem funktionierenden Schritt einen Stand in Git mit verständlicher Beschreibung.

## Grenzen
- Nichts veröffentlichen oder versenden, ohne dass ich es freigegeben habe.
- Keine Passwörter, Schlüssel oder echten Kundendaten in Dateien.
- Frage nach, bevor du Dateien löschst.

Vorlage 2: Team-Wissensarchiv

Für ein Team, das gemeinsam mit Claude Code arbeitet. Die Datei bleibt kurz und verweist auf Dokumente. Sie lebt im Projekt und wird über die Versionsverwaltung geteilt.

# [Unternehmen]: gemeinsames Wissensarchiv

## Was das ist
Wir arbeiten mit Menschen und KI-Assistenten nach denselben Regeln und derselben Wissensbasis.
Das Archiv besteht aus Textdateien in Git. Jede Seite hat einen Kopf mit
Bereich, Verantwortlichen, Datum, Quellen und Status.

## Aufbau
- `wissen/`: geprüftes Wissen, nur mit Freigabe der verantwortlichen Person
- `arbeit/[name]/`: Entwürfe und Protokolle, jeweils eine schreibende Person
- `vorlagen/`: Vorlagen für Seiten, Übergaben und Berichte
- Überblick über Bereiche und Zuständigkeiten: @wissen/zustaendigkeiten.md

## Fünf Regeln
1. Nichts erfinden. Bei Unsicherheit schreibst du „nicht belegt, Quelle nötig“ und hörst auf.
2. Nichts geht ohne Freigabe nach außen. Du entwirfst, Menschen senden.
3. Keine Zugangsdaten und keine echten Personendaten im Archiv. Verweise nur auf den
   Namen des Eintrags im Passwortmanager.
4. Änderungen an Regeln nur als Vorschlag, den eine zweite Person prüft.
5. Berichte ehrlich: Übersprungene Schritte nennst du, fehlgeschlagene Prüfungen zeigst du.

## Beim Start jeder Sitzung
- Aktuellen Stand holen, offene Übergaben und überfällige Aufgaben nennen.

## Schreibstil
- Ganze Sätze, einfache Sprache, keine Abkürzungen ohne Erklärung.
- Jede Zahl mit Quelle und Datum.

## Regeln für Dateien anderer
- Arbeitsordner anderer Personen werden nicht gelesen und nicht geändert.

Ein zusätzlicher Hinweis: Die fünf Regeln stammen aus unserer Praxis bei fainin. Wie sie dort zusammenspielen, beschreibe ich in „So arbeiten vier Personen mit zehn KI-Agenten“.

Vorlage 3: Rolle mit Grenzen (Unter-Agent)

Mit Unter-Agenten lassen sich Rollen mit eigenem Auftrag und eigenen Werkzeugen definieren. Sie liegen als Markdown-Dateien unter .claude/agents/, mit einem Kopf, in dem Name, Beschreibung und erlaubte Werkzeuge stehen. Die genauen Felder entwickeln sich weiter, prüfe sie in der aktuellen Dokumentation. Wichtig ist der Aufbau: Zweck, Arbeitsweise und eine ausdrückliche Liste dessen, was die Rolle nie tut.

---
name: recherche
description: Sammelt Fakten mit Quellen. Nutze sie, wenn Belege gebraucht werden.
tools: Read, Grep, Glob, WebSearch, WebFetch
---

Du bist die Recherche-Rolle.

## Auftrag
Du sammelst Fakten aus dem Archiv und aus öffentlichen Quellen und lieferst sie
in einer Tabelle: Aussage, Quelle (Link), Datum, Sicherheit (belegt oder unsicher).

## Arbeitsweise
- Beantworte nur, was gefragt ist.
- Jede Aussage braucht eine Quelle. Fehlt sie, schreibst du „nicht belegt“.
- Wenn Quellen sich widersprechen, nenne beide und sage, welche du für verlässlicher hältst und warum.

## Du tust nie
- Dateien ändern oder anlegen. Du darfst nur lesen.
- Etwas versenden, veröffentlichen oder in Namen anderer schreiben.
- Zahlen schätzen, ohne es zu kennzeichnen.

Die Begrenzung der Werkzeuge ist hier eine harte Grenze: Eine Rolle, der kein Schreibwerkzeug erlaubt ist, kann nichts schreiben, egal was im Text steht. Die Liste unter „Du tust nie“ ergänzt das als Anweisung für alles, was sich nicht über Werkzeuge regeln lässt.

Vorlage 4: Schreibstil

Wenn Claude Texte für dich schreibt, sollen sie nach dir klingen. Der Trick: Schreibe deinen Stil als Regeln auf, nicht als Wunsch („schreibe locker“). Dieses Beispiel zeigt die Regeln, nach denen ich schreibe. Du ersetzt sie durch deine.

# Schreibstil

## Sprache
- Kurze Sätze, aktiv statt passiv.
- Leser:innen mit „du“ ansprechen. Bei Unternehmen mit „Sie“.
- Echte Umlaute (ä, ö, ü, ß), niemals ae, oe oder ue.
- Nomen großschreiben. Markennamen wie fainin schreibe ich klein.
- Kein Gedankenstrich als Satzzeichen. Nutze Punkt, Komma oder Doppelpunkt.
- Zahlenbereiche mit Bis-Strich: 15–25 €/h.

## Inhalt
- Zuerst das Ergebnis, dann die Details.
- Konkrete Zahlen, Zeiträume und Namen statt „viel“ oder „schnell“.
- Jede Aussage braucht einen Beleg. Was nicht belegt ist, kennzeichnest du als „nicht belegt“.
- Keine Marketingwörter wie „innovativ“, „revolutionär“, „disruptiv“. Beschreibe, was etwas tut.
- Erkläre nichts, was für die Zielgruppe offensichtlich ist.

## Ton
- Bodenständig und direkt, wie ein kluger Freund, der sagt, was funktioniert.
- Ehrlich: Wenn etwas Aufwand kostet, sag es.
- Kurz, prägnant, präzise. Lieber drei klare Sätze als zehn vage.

Wichtig sind die konkreten, prüfbaren Formulierungen („kein Gedankenstrich“, „echte Umlaute“). Mit „schreibe professionell“ kann Claude wenig anfangen. Die Datei bleibt trotzdem kurz: Stil gehört in eine eigene Datei oder in einen Skill für Texte, nicht in die Hauptdatei eines großen Projekts.

Wenn eine Bitte nicht reicht: harte Regeln

Eine Anweisung in CLAUDE.md ist eine Bitte. Sie wirkt in aller Regel, aber nicht immer. Anthropic weist in der Dokumentation selbst darauf hin: Um eine Aktion unabhängig von der Entscheidung des Modells zu verhindern, nutzt du einen Hook, der vor einer Aktion läuft (PreToolUse).

Beispiel: Dateien mit Zugangsdaten sperren

Das folgende Beispiel zeigt das Prinzip. Der Hook bekommt die geplante Aktion als Eingabe, prüft den Dateipfad und blockiert sie mit einer verständlichen Meldung. Prüfe Aufbau und Schreibweise gegen die aktuelle Dokumentation, bevor du es einsetzt.

Eintrag in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/sperre-zugangsdaten.sh" }
        ]
      }
    ]
  }
}

Das Skript .claude/hooks/sperre-zugangsdaten.sh:

#!/bin/bash
eingabe=$(cat)
pfad=$(echo "$eingabe" | jq -r '.tool_input.file_path // empty')

case "$pfad" in
  *.env|*/.env.*|*zugangsdaten*|*credentials*)
    echo "Gesperrt: Dateien mit Zugangsdaten werden nicht gelesen. Nutze den Passwortmanager." >&2
    exit 2
    ;;
esac
exit 0

Der Exit-Code 2 blockiert die Aktion, die Meldung wird Claude angezeigt und erklärt, was stattdessen möglich ist. Eine gute Sperre erklärt, warum sie greift, und nennt eine Alternative. Dann arbeitet das Modell damit, statt sie zu umgehen.

Pflege und Prüfung

Eine Anweisungsdatei ist nie fertig. Mit diesem Rhythmus bleibt sie nützlich:

1. Laufend ergänzen: Jede Korrektur, die du zweimal tippst, wird zu einer Regel.
2. Monatlich aufräumen: Überholtes streichen, Doppeltes zusammenführen, Widersprüche auflösen.
3. Kurz halten: Wird die Datei zu lang, verschiebe Teilbereiche in Regeldateien und Abläufe in Skills.
4. Wirkung prüfen: Starte eine neue Sitzung und stelle eine Aufgabe, bei der die Regel greifen müsste. Wird sie nicht befolgt, formuliere sie konkreter oder verkürze die Datei.
5. Im Team verantworten: Eine Person ist zuständig, Änderungen laufen als Vorschlag mit Zweitprüfung. Gerade bei Grundregeln wirkt ein einziger falscher Satz auf jede künftige Sitzung.

Wenn du die Datei im Rahmen einer Einführung für ein Team aufsetzt, hilft dir der Leitfaden zur Einführung im Unternehmen. Für den Einstieg in Claude Code selbst gibt es die Anleitung für Gründer:innen.