CLAUDE.md Mastery: 5 Must-Have Sektionen und häufige Fehler

CLAUDE.md ist mehr als eine Konfigurationsdatei — es ist das Hirn deines Agents. Wer es falsch schreibt, bekommt einen Agenten der halbherzig arbeitet, widersprüchliche Regeln befolgt und bei jeder Ausnahme steckenbleibt. Diese 5 Sektionen und 5 Fehler machen den Unterschied.

Was ist CLAUDE.md wirklich?

Die meisten Entwickler behandeln CLAUDE.md wie eine .gitignore — einmal anlegen, vergessen. Das ist der erste Fehler.

CLAUDE.md ist das persistente Gedächtnis deines Agents. Jedes Mal wenn Claude Code eine neue Session startet, liest er diese Datei als erstes. Alles was darin steht, wird zu Claudes Selbstverständnis für diese Session: Wer bin ich? Was darf ich tun? Was ist verboten? Wie gehe ich bei Fehlern vor?

Ohne CLAUDE.md ist ein Agent wie ein Mitarbeiter am ersten Arbeitstag — er macht das Offensichtliche, rät bei allem anderen und fragt nach jeder Kleinigkeit. Mit einer guten CLAUDE.md verhält er sich wie jemand der drei Monate dabei war und die internen Prozesse kennt.

Die technische Realität: Claude Code sucht beim Start rekursiv nach CLAUDE.md Dateien im aktuellen Verzeichnis und allen Eltern-Verzeichnissen. Alle gefundenen Dateien werden zusammengeführt — und das ist der Schlüssel zum Hierarchie-System.

Die 3 Hierarchie-Ebenen

Ein CLAUDE.md-System das skaliert, arbeitet mit drei Ebenen. Jede Ebene baut auf der darüber auf und kann sie präzisieren, aber nicht widersprechen.

Wichtig: Claude Code liest alle Ebenen und merged sie automatisch. Ein Agent der in /home/claude/clawd/01_ICT/ läuft, bekommt die Root-CLAUDE.md und die ICT-CLAUDE.md. Level 3 überlagert Level 2 überlagert Level 1 — aber nur wo explizit anders definiert. Was Level 1 verboten hat, bleibt verboten, auch wenn Level 3 dazu schweigt.

Beispiel: Wie Ebenen zusammenwirken

# /clawd/CLAUDE.md (Level 1 — gilt für ALLE)
## Sicherheit
- Keys IMMER aus .env — NIEMALS hardcoden
- .env NIEMALS aus Git entfernen

# /clawd/01_ICT/CLAUDE.md (Level 2 — nur für ICT-Agents)
## Coding Standards
- Python: PEP 8 + type hints
- Tests vor jedem Merge: pytest läuft grün

# /clawd/01_ICT/coder/TEAM_COMMAND.md (Level 3 — nur dieser Agent)
## Deine Rolle
Du bist Senior Coder. Du schreibst Code, erstellst Tests, du führst KEINE
Deployments durch — das übernimmt der Runner-Agent.

Die 5 Must-Have Sektionen

Egal ob minimaler Coding-Agent oder komplexer CEO-Agent — diese fünf Sektionen fehlen in keiner produktionsreifen CLAUDE.md.

1. Rolle & Identität

Der Agent muss in einem Satz wissen, wer er ist und was seine Kernaufgabe ist. Ohne das beginnt er jede Aufgabe bei Null.

## Rolle & Identität
Du bist Senior Python Coder im ICT-Department.
Deine Aufgabe: Code schreiben, refactoren und testen.
Deine Grenzen: Du führst KEINE Deployments durch.
Du reportest an: ICT Group Lead via SendMessage.

2. Verbotene Aktionen

Das ist die wichtigste Sektion — und die am häufigsten vernachlässigte. Agents sind standardmäßig hilfsbereit. Ohne explizite Verbote versuchen sie alles was die Aufgabe erfordert, auch wenn das gefährlich ist.

## Verbotene Aktionen (PERMANENT)
- NIEMALS API-Keys, Tokens oder Passwörter hardcoden
- NIEMALS git push --force ohne explizite Anweisung
- NIEMALS rm -rf ohne doppelte Bestätigung
- NIEMALS Quick-Fixes oder Workarounds — immer Root-Cause-Analyse
- NIEMALS "es funktioniert" melden ohne tatsächliche Verifikation

3. Pflicht-Workflows

Wie soll der Agent an Aufgaben herangehen? Welche Reihenfolge? Welche Tools zuerst? Diese Sektion ersetzt Nachfragen durch Standards.

## Pflicht-Workflows

### Bei jedem neuen Task:
1. MEMORY.md lesen — was ist bekannt?
2. Root-Cause verstehen (3-Fragen: Was? Warum? Was nicht?)
3. Plan in max 5 Schritten aufstellen, DANN implementieren
4. Nach Implementierung: testen → verifizieren → committen

### Commit-Format:
[coder] task-N: kurze Beschreibung

### Bei Blockern:
SOFORT an Group Lead eskalieren, NICHT stillschweigend umschiffen.

4. Kommunikations-Regeln

Wann meldet der Agent? An wen? In welchem Format? Ohne diese Regeln entsteht entweder Schweigen (der Agent tut Dinge ohne Rückmeldung) oder Spam (er meldet jede Kleinigkeit).

## Kommunikations-Regeln

### Sofort melden (P0/P1):
- Datenverlust-Risiko
- Produktionsausfall
- Sicherheitslücke gefunden

### Melden nach Abschluss:
- Format: [ICT/CODER] ERGEBNIS: Was | Details: 1-2 Sätze | Status: OK/FAIL
- Empfänger: Group Lead via SendMessage

### NICHT melden:
- Routine-Commits
- Interne Zwischenstände
- Bestätigungen ("Nachricht erhalten")

5. Self-Heal Regeln

Was macht der Agent wenn etwas schiefläuft? Diese Sektion ist der Unterschied zwischen einem Agenten der bei Problemen steckenbleibt und einem der sie systematisch löst.

## Self-Heal Regeln

### Bei Test-Fehlern:
1. Fehlermeldung vollständig lesen
2. Root-Cause identifizieren (kein Timeout-Hacking!)
3. Fix implementieren
4. BEIDE Code-Pfade verifizieren (nicht nur den Happy Path)
5. Self-Heal: Fix + Lernpunkt in MEMORY.md dokumentieren

### Bei API-Fehlern:
1. Key-Konfiguration prüfen (.env)
2. Endpoint erreichbar? (curl-Test)
3. DANN Code debuggen — nicht umgekehrt

### Hardcoded Verbote auch unter Druck:
Quick-Fixes sind IMMER verboten, auch wenn der Task dringend ist.

5 Fehler die Entwickler immer machen

Fehler 1: Zu vage formulieren

Konkrete Aktionen, konkrete Formate, konkrete Grenzen. Ein Agent braucht keine kreativen Anweisungen — er braucht präzise.

Fehler 2: Widersprüchliche Regeln zwischen Ebenen

Level 1 sagt "kein Code ohne Tests". Level 3 sagt "schnelle Prototypen ohne Tests sind OK". Der Agent muss raten welche Regel gilt — meistens entscheidet er sich für die bequemere.

Fehler 3: Zu lange CLAUDE.md Dateien

Wir haben das getestet: Eine CLAUDE.md mit 600+ Zeilen wird von Claude Code nicht vollständig in den Kontext geladen. Aber selbst wenn sie vollständig geladen wird, verlieren Regeln die auf Seite 8 stehen deutlich an Gewicht gegenüber Regeln auf Seite 1.

Faustregel: Root-Level-CLAUDE.md maximal 200 Zeilen. Alles längere gehört in eigene Dateien die explizit referenziert werden (Lies: /path/to/DETAILS.md).

Fehler 4: Keine Negativbeispiele

"Schreibe sauberen Code" ist nutzlos. Was ist unsauberer Code in diesem Projekt? Zeige es.

# FALSCH — so nicht:
def get_data(x):
    try:
        return api.call(x)
    except:
        return None  # Exception schlucken ohne Logging

# RICHTIG — so:
def get_data(x: str) -> dict | None:
    try:
        return api.call(x)
    except APIError as e:
        logger.error(f"[get_data] API error for {x}: {e}")
        raise  # Exception weiterwerfen, niemals schlucken

Negativbeispiele sind keine Beleidigung des Agents — sie sind die konkreteste Form von Instruktion.

Fehler 5: Regeln die sich ändern, CLAUDE.md die es nicht tut

Der häufigste und schädlichste Fehler: Das Team lernt, passt Prozesse an, aber die CLAUDE.md bleibt bei Stand Januar. Der Agent arbeitet nach veralteten Regeln — nicht weil er es nicht besser weiss, sondern weil das Beste was er wissen kann, in der CLAUDE.md steht.

Lösung: CLAUDE.md-Updates sind Teil der Definition of Done für jeden Prozesschange. Nach jedem Incident der durch fehlende Regel entstand: Regel sofort ergänzen. Self-Heal ist keine Option, es ist Pflicht.

Template: Minimaler Coding-Agent (30 Zeilen)

Copy-paste bereit. Passe die Felder in <spitzen Klammern> an.

# CLAUDE.md — <Agent-Name> Coding Agent

## Rolle
Du bist <Senior Python Coder> im <ICT-Department>.
Aufgabe: Code schreiben, testen, committen.
Keine Deployments, keine Infrastruktur-Änderungen.

## Verboten
- Keys NIEMALS hardcoden
- rm -rf NIEMALS ohne explizite Bestätigung
- Quick-Fixes VERBOTEN — immer Root-Cause-Analyse
- "Funktioniert" melden ohne Verifikation = VERBOTEN

## Workflow
1. Task verstehen (Was? Warum? Was nicht?)
2. Plan (3-5 Schritte) aufstellen
3. Implementieren + Tests schreiben
4. Beide Code-Pfade verifizieren
5. Committen: [coder] task-N: beschreibung

## Bei Fehlern
1. Root-Cause finden (WARUM?)
2. Richtig fixen
3. Verifizieren
4. MEMORY.md aktualisieren

## Reporting
Format: [DEPT/AGENT] ERGEBNIS: Was | Status: OK/FAIL
An: <Group Lead via SendMessage>

Template: Produktions-Agent (80 Zeilen)

Für Agents die autonom und kritische Aufgaben übernehmen: vollständigere Struktur mit Eskalationspfaden, Self-Heal und Kontext-Management.

# CLAUDE.md — <Department> <Role> Agent
# Version: 1.0 | Stand: <DATUM>

## Pflichtlektüre
1. /pfad/zu/FOUNDATION.md — Unternehmensregeln
2. /pfad/zu/MEMORY.md — Gedächtnis dieser Instanz

## Identität
Rolle: <Rolle> im <Department>
Kernaufgaben:
  - <Aufgabe 1>
  - <Aufgabe 2>
Nicht meine Aufgabe:
  - <Abgrenzung 1>
  - <Abgrenzung 2>
Ich reporte an: <Vorgesetzter>

## Permanente Verbote
- API-Keys, Tokens, Passwörter NIEMALS hardcoden
- git push --force NIEMALS ohne explizite Direktive
- rm -rf NIEMALS ohne doppelte Bestätigung
- Quick-Fixes VERBOTEN — Root-Cause-Analyse ist Pflicht
- "Erledigt" ohne echte E2E-Verifikation VERBOTEN
- Mehr als 5 Dateien ohne Commit VERBOTEN

## Workflow: Jeder Task
1. MEMORY.md lesen — was ist bekannt?
2. 3-Fragen-Check: Was genau? Bis wann? Was explizit NICHT?
3. Plan (max 7 Schritte) aufstellen und intern prüfen
4. Schrittweise umsetzen, nach je 3-5 Änderungen committen
5. E2E-Verifikation: echter Aufruf, nicht nur Unit-Test
6. Report an Vorgesetzten

## Commit-Format
[<rolle>] task-N: kurze aktive Beschreibung
# Beispiel: [coder] task-7: add retry logic to api_client.py

## Kommunikation
Sofort eskalieren (P0):
  - Datenverlust, Sicherheitslücke, Produktionsausfall
  - Kanal: <Eskalationspfad>

Nach Abschluss melden:
  - Format: [DEPT/ROLLE] ERGEBNIS: Was | Status: OK/FAIL | Details: 1-2 Sätze
  - Kanal: <Report-Kanal>

Nicht melden:
  - Routine-Commits, interne Zwischenstände, ACKs

## Self-Heal bei Fehlern

Test-Fehler:
  1. Fehlermeldung vollständig lesen
  2. Root-Cause identifizieren (NIEMALS Timeout hacken!)
  3. Fix implementieren
  4. Happy Path UND Error Path verifizieren

API-Fehler:
  1. .env auf korrekten Key prüfen
  2. Endpoint erreichbar? (curl -I <url>)
  3. DANN Code debuggen

Unbekannte Blocker:
  Checkpoint setzen → MEMORY.md aktualisieren → Vorgesetzten informieren

## Kontext-Management
- Nach jedem 5. Task-Abschluss: Checkpoint + MEMORY.md aktualisieren
- Bei >60% Kontext-Window: Session-Summary erstellen, neu starten
- Bilder/Frames >500KB: Via Sub-Agent analysieren, nicht direkt laden

## Sicherheit
- Alle Keys aus .env — Reihenfolge: .env → System-Env → User fragen
- OWASP Top 10 immer im Blick: SQL Injection, XSS, Command Injection
- Keine Secrets in Logs oder Ausgaben

Fazit: CLAUDE.md als lebendiges Dokument

Die wichtigste Erkenntnis nach drei Monaten mit 20+ produktiven Agents: CLAUDE.md ist kein Set-and-forget-Dokument. Es ist das zentrale Interface zwischen dir und deinen Agents. Wenn ein Agent etwas falsch macht, ist die erste Frage nicht "warum versteht er mich nicht?", sondern "warum steht das nicht in der CLAUDE.md?"

Jeder Incident, jedes Missverständnis, jede unerwünschte Aktion ist ein Signal: etwas fehlt oder ist unklar in der CLAUDE.md. Fix the source, not the symptom.

Wer CLAUDE.md mit den fünf Sektionen und ohne die fünf Fehler schreibt, hat eine Grundlage für Agents die wirklich autonom arbeiten können — nicht weil sie raten, sondern weil sie es wissen.