Meine CLAUDE.md hat 582 Zeilen. Sechs Schichten und der Fehler hinter jeder

Jeder neue Claude-Code-Chat beginnt bei null. Er kennt das Projekt nicht, erinnert sich nicht daran, was wir vor einer Stunde im nächsten Fenster besprochen haben, und hat keine Ahnung, dass ein Port auf einem Server niemals angerührt werden darf. Dieser Beitrag beschreibt die CLAUDE.md, die ich gebaut habe, um das in den Griff zu bekommen: sechs Schichten, der Vorfall hinter jeder davon, warum ein Hook funktioniert, wo eine geschriebene Regel scheitert, die eine Einstellung, die ein kompromittiertes npm-Paket von meinem Rechner fernhielt, und welche Teile ich für ein gewöhnliches Projekt behalten würde. Als die russische Originalfassung am 12. April 2026 erschien, umfasste die Konfiguration 582 Zeilen.

Eine CLAUDE.md soll zwei Probleme auf einmal lösen: Kontext zwischen Sitzungen tragen und verhindern, dass der Agent etwas Unumkehrbares tut. r/ClaudeAI hat jede Woche eine neue Horrorgeschichte. Ein Agent hat eine Produktionsdatenbank gelöscht. Ein Agent hat Secrets in ein öffentliches Repository gepusht. Ein Agent hat einen Abrechnungsdienst so lange „optimiert“, bis jeder Kunde eine Rechnung über null bekam. Eine typische CLAUDE.md mit fünf bis zehn Zeilen löst keins der beiden Probleme. Ich habe sie als Architekturaufgabe behandelt und nicht als Wunschliste, und jede Regel darin hat eine konkrete Geschichte hinter sich.

Drei Vorfälle hinter den ersten Regeln

Der Agent „reparierte“ ein funktionierendes System. Sonntagabend. Der Agent sieht 127.0.0.1 in der Konfiguration für einen externen Speicherdienst und entscheidet, eine frühere Sitzung habe dort einen Fehler hinterlassen. Er trägt die echte IP ein. Uploads schlagen fehl. Eine halbe Stunde Fehlersuche später stellt sich heraus, dass der Verkehr über einen SNI-Proxy durch einen lokalen Tunnel lief und 127.0.0.1 der richtige Wert war. Ohne Kontext war die offensichtliche Reparatur der Schaden.

Die Regel, die daraus folgte: Ändere eine Konfiguration erst, wenn du verstehst, warum die aktuellen Werte so sind. Wenn ein Wert merkwürdig aussieht, verstehe ihn zuerst und handle danach.

fail2ban hielt den Agenten für einen Brute-Forcer. Der Agent prüfte den Serverzustand und öffnete für jede Prüfung eine neue SSH-Verbindung. Ein Dutzend Verbindungen in einer Minute sah aus wie ein Angriff, und die IP wurde für eine halbe Stunde gesperrt. Auf dieser Kiste lief gerade ein Trainingslauf, und ich kam nicht mehr heran.

Regel: eine SSH-Brücke für alles, ein Client pro Sitzung, und keine separaten Skripte für Prüfung, Reparatur und Verifikation. Alles in einem Aufruf bündeln.

„Filtern“ bedeutete „löschen“. Ich bat darum, einen Datensatz zu filtern, gemeint war, die ungeeigneten Bilder herauszunehmen. Der Agent las es wörtlich und löschte die Dateien. Nicht verschoben, nicht markiert. Gelöscht.

Regel: Filtern heißt verschieben oder markieren, niemals löschen. Vor jeder Löschung prüfen, ob der Nutzer genau mit diesen Worten Löschen verlangt hat.

„Sei vorsichtig“ zu schreiben funktioniert nicht. Es braucht ein System.

Sechs Schichten, keine davon geplant

Jede Schicht kam nach einem konkreten Fehler dazu.

Regeln, 9 Dateien. Sie werden je nach Situation geladen. Wenn der Agent einen Artikel schreibt, braucht er die SSH-Regeln nicht; wenn er Code debuggt, braucht er die Regeln zur Prosa nicht. Claude Code kann die Regeldatei laden, die zur Aufgabe passt.

Memory, 78 Dateien. Sie entstand, als der Agent die Konfiguration eines Servers zum dritten Mal vergessen hatte. Zwischen Sitzungen behält er jetzt Infrastruktureinstellungen, Projektentscheidungen, meine Vorlieben und frühere Fehler. Die Dateien verlinken sich gegenseitig als [[filename]], insgesamt 178 Querverweise, sodass einfaches Markdown zu einem Wissensgraphen wird. Ein Teil wird immer geladen, der Rest nach Thema.

Handoffs. Sie entstanden, als ein neuer Chat geradewegs in die Sackgasse des vorherigen Chats lief. Wenn eine Sitzung endet, schreibt der Agent eine Zusammenfassung: was getan wurde, was NICHT funktioniert hat (der wertvolle Teil) und eine nächste Aktion. Ein echtes Beispiel, aus dem Russischen übersetzt:

## Session goal
Colour checker: CNN sweep + diffusion, first visual results.

## Done
- CNN baseline: median 1.99 deg (11M params, 21 MB)
- Sweep on 5 GPUs: crop128 (3.17), bs16 (2.04), lr3e-4 (NaN)
- Diffusion training started: epoch 5/50, loss 0.827

## Did NOT work
- EfficientNet-B0: hash mismatch in the Docker image
- lr=3e-4: NaN after epoch 10-13, no gradient clipping
- CNN, visually: three numbers give stray colour casts

## Next step
Inference script for diffusion + visual sheets with 24 patches

Der nächste Chat liest etwa 1.500 Token, statt das Projekt von Grund auf zu analysieren. In vier Tagen sammelten sich 27 Handoffs an, und keine Sackgasse wurde wiederholt. Es funktioniert auch über Konten hinweg: Ich habe drei Abos, zwei für die Arbeit und eins privat, und ein Handoff lässt mich in einem anderen weiterarbeiten, ohne alles noch einmal zu erklären. Wie daraus ein Werkzeug für mehrere Leute wurde, die gleichzeitig arbeiten, steht in Mehrere Claudes auf einem Repo.

Chroniken. Sie entstanden, als nach zwanzig Handoffs nicht mehr klar war, wie das Projekt in seinen jetzigen Zustand gekommen war. Ein Handoff beantwortet „was als Nächstes“, eine Chronik beantwortet „wie sind wir hierher gekommen“. Wichtige Entscheidungen, Wendungen und Sackgassen, drei bis sieben Zeilen pro Meilenstein.

Hooks. Sie entstanden, als die Regel „Links in der CLAUDE.md prüfen“ zwanzig Minuten nach Sitzungsbeginn nicht mehr befolgt wurde. Um Hooks geht es im nächsten Abschnitt.

Skills, 16. Verpacktes Wissen für bestimmte Aufgaben. Die Beschreibung ist als Auslöser für das Modell formuliert, „use when: GPU hung, server health check needed“, nicht als „hilft bei Servern“.

Eine Regel ist ein Wunsch, ein Hook ist eine Garantie

Das war die am wenigsten offensichtliche Erkenntnis dieses Monats. Eine Regel in der CLAUDE.md ist eine Anweisung in einem Prompt. Das Modell kann sie vergessen, neu interpretieren oder spät in einer langen Sitzung fallen lassen, wenn der Kontext voll ist mit anderen Dingen. Meine Regel „Links vor der Arbeit prüfen“ hielt etwa zehn Minuten, dann war der Agent in der Aufgabe versunken.

Ein Hook ist ein Python-Skript, das Claude Code bei einem Ereignis ausführt: SessionStart, Stop, PreToolUse. Er vergisst nichts und interpretiert nichts neu. Er läuft jedes Mal. Hier ist der, der vor dem Schließen einer langen Sitzung einen Handoff verlangt:

# remind_handoff.py  (Stop hook, simplified)
age = session_age_minutes()
if age < 15:
    return                      # short session, nothing to hand off

if fresh_handoff_exists():
    return                      # already written

print(json.dumps({              # block the close, ask for the handoff
    "decision": "block",
    "reason": f"Session ran {int(age)} min with no handoff. "
              f"Write one into .claude/handoffs/ before exiting."
}))

Das Modell merkt meist von selbst, wann es Zeit ist, etwa wenn eine Aufgabe fertig ist oder der Kontext sich füllt. Der Hook deckt die Fälle ab, in denen es das vergisst.

Wenn etwas jedes Mal passieren muss, ist es ein Hook, keine Regel.

Eine Konfigurationszeile gegen einen Supply-Chain-Angriff

Am 31. März 2026 wurde das offizielle npm-Paket axios, rund 100 Millionen Downloads pro Woche, über das Konto eines Maintainers kompromittiert (Elastic Security Labs). Eine bösartige Version 1.14.1 ging um 00:21 UTC raus, und die bösartigen Versionen blieben bis 03:15 UTC auf npm, also etwa drei Stunden (das Post-Mortem zu axios). Microsoft führt den Angriff auf Sapphire Sleet zurück, einen nordkoreanischen staatlichen Akteur (Microsoft Security Blog).

In meiner .npmrc stand eine einzige Zeile:

min-release-age=7

Pakete, die vor weniger als sieben Tagen veröffentlicht wurden, werden nicht installiert. Die meisten bösartigen Pakete fallen innerhalb von ein bis drei Tagen auf, sieben Tage sind also ein komfortabler Puffer. Ich war nicht betroffen, und es hat eine Zeile gekostet. Das Python-Gegenstück gehört in uv.toml:

exclude-newer = "7 days"

Die Forschung dahinter: 37 Paper

Ein guter Teil der Regeln stammt nicht aus meinen eigenen Fehlern, sondern aus akademischer Arbeit: 37 arXiv-Paper, umgearbeitet zu Prinzipien. Vier davon haben meinen Arbeitsablauf am stärksten verändert.

• Beweisschleife. Der Agent sagt, die Tests laufen durch; du prüfst, und sie laufen nicht durch. Die Beweisschleife verbietet dem Agenten, die eigene Arbeit abzunicken. Sie verlangt Belege: Testausgaben und ein Urteil eines Verifikators in einer frischen Sitzung, die die Arbeit nie gesehen hat. Quelle: arXiv 2603.10165.
• Strukturiertes Reasoning (or 'strukturiertes Denken'), used the same way in every occurrence. Statt eines freien „vielleicht so, vielleicht so“: was wir aus Code und Logs sicher wissen, ein Schritt-für-Schritt-Ablauf, was daraus folgt, und welche Hypothesen geprüft und verworfen wurden. In den Experimenten von Ugare und Chandra hob diese Art halbformalen Schließens die Genauigkeit bei der Patch-Äquivalenz von 78 % auf 88 % bei kuratierten Beispielen und auf 93 % bei echten, vom Agenten erzeugten Patches (arXiv 2603.01896).
• Deterministische Orchestrierung. Alles Deterministische, etwa Tests, Linter und Formatierung, läuft über ein Shell-Skript. Ein Modell verliert in Schleifen den Überblick und verwechselt Verzweigungsbedingungen. Ein Skript tut das nicht.
• Rote Linien. Gewöhnliche Regeln werden kreativ ausgelegt. Rote Linien sind absolute Verbote ohne Ausnahmen, jede an einen Vorfall gebunden: nicht ohne Bestätigung löschen, Produktionskonfigurationen nicht ändern, ohne sie zu verstehen. Das Muster stammt aus chinesischen Ingenieurteams, 红线, wörtlich „rote Linie“.

Der Rest, von Generator-Evaluator und Autoresearch bis zu Multi-Agent-Zerlegung, kodifiziertem Kontext, Agentensicherheit und Dokumentationsintegrität, ist im Repository beschrieben.

Zahlen und die Stelle, an der es scheiterte

78 Memory-Dateien. 178 Querverweise. 27 Handoffs in vier Tagen. Eine KV-Cache-Trefferquote von 96,9 % über 83 Sitzungen in einer Woche. Die Konfiguration pflegt sich selbst: Nach jeder Änderung prüft der Agent, ob Links veraltet sind, und ein SessionStart-Hook validiert sie automatisch.

Funktioniert es perfekt? Nein. Eine Prüfung ergab, dass vier Memory-Dateien aus dem Index herausgefallen waren. Dokumentationsdrift, innerhalb des Systems, das Dokumentationsdrift verhindern soll. Ohne das System wäre es schlimmer gewesen.

Was ich nicht sicher weiß

Ich bin nicht überzeugt, dass jeder all das braucht. Für die meisten Projekte würden wahrscheinlich fünf Prinzipien reichen: deterministische Orchestrierung, strukturiertes Schließen, Supply-Chain-Schutz, kodifizierter Kontext und Handoffs.

Ich bin auch nicht überzeugt, dass sechs Schichten das Minimum sind. Vielleicht habe ich es überdimensioniert. Aber in diesem Monat ging kein Kontext verloren, und keine Sackgasse kehrte zurück.

Eines der Prinzipien, das Testen von Annahmen, sagt es deutlich. Jeder Bestandteil des Aufbaus kodiert eine Annahme darüber, was das Modell nicht allein kann, und Modelle werden besser. Entferne Bestandteile und miss. Eine Schicht hier ist wahrscheinlich schon überflüssig.

Was sich seit April geändert hat

Update, September 2026. Das Repository wurde von claude-code-config in codex-claude-code-config umbenannt, weil dieselben Prinzipien, Hooks und Skills jetzt auch Codex und gemischte Claude- und Codex-Sitzungen steuern und der alte Name das nicht mehr beschrieb. Die alte URL leitet weiter. Am 23. September 2026 enthielt es 30 Prinzipien, 58 Skills, 35 Regeldateien und 73 Skripte in hooks/, auf GitHub mit 150 Sternen und 24 Forks.

Die Zahlen in den Abschnitten oben (9 Regeldateien, 78 Memory-Dateien, 16 Skills, 37 Paper, 582 Zeilen) beschreiben meinen Aufbau am 12. April. Sie waren an diesem Tag richtig, und ich habe sie so belassen.

Wo man anfängt

Füge das in einen Claude-Code-Chat ein:

https://github.com/AnastasiyaW/codex-claude-code-config - study it, pick what fits my work and set up my Claude Code

Fang klein an: Supply-Chain-Schutz (eine Zeile in .npmrc), deterministische Orchestrierung (Tests über Skripte) und strukturiertes Schließen (ein Format fürs Debuggen). Das Übrige kommt hinzu, wenn ein Fehler es verlangt. Alles steht unter der MIT-Lizenz.

Die Projektseite auf dieser Website ist codex-claude-code-config. Die Referenzbibliothek, die daneben gewachsen ist, beschreibt 785 Artikel für Agenten, nicht für Menschen, und warum ich Handoffs mehr vertraue als dem eigenen Sitzungsverlauf der Desktop-App, steht in 45 MB Claude-Code-Sitzungen, die du nie ansiehst.