Gedächtnisverwaltung
Wie man in Claude Codes automatisches Gedächtnis und die CLAUDE.md schreibt, damit die Bibliothek mit dem Projektwachstum durchsuchbar bleibt.
Kurzreferenz
| Benutzer sagt... | Tue dies |
|---|---|
| "Erinnere mich" (vage, mehrere Kandidaten)/"Rückblick"/"Nach der Entwicklung sehen, was es zu merken gibt" | → Modus 1: Kandidatenbewertung (Mehrfachauswahl) |
| "Erinnere mich an dieses X-Problem von heute" (konkret, einzelner Eintrag)/ Nach größerem Bugfix / Nach Sicherheitsvorfall / Einmalige Entscheidung mit nicht offensichtlichem Ergebnis | → Modus 2: Neues Memory anlegen (direkt durchführen) |
| "Aktualisiere dieses Memory / Korrigiere die Schlussfolgerung zu X" | → Modus 3: Vorhandenes Memory aktualisieren (Vorrang vor Neuanlage) |
| Hinzuzufügender Abschnitt > 100 Zeilen oder Datei bereits > 4 H2-Themen | → Regel 6: Aufteilen statt aktualisieren |
| "Schema ändern / Neuen Typ hinzufügen / Speicherstruktur ändern" | → Modus 4: Strukturelle Änderung (vorher Fallstrickliste lesen) |
| "Neues Projekt ohne Erinnerungen starten" / "Wie fange ich an" | → Modus 5: Bootstrap ohne Memory |
| "Memory-System sieht unordentlich aus / Audit durchführen" | → Wenn im Projektstamm scripts/audit-memory.sh existiert, ausführen; sonst aus templates/audit-memory.template.sh selbst erstellen |
Wichtige Regeln
Regel 1: Fakten ins Memory, Methoden in den Skill
Die Memory-Datei enthält „X-Fallstrick erlebt“, „Y-Daten aus der Branche“, „Z-Projektstatus“; dieser Skill enthält „Wie entscheide ich, was aufgeschrieben wird / Wie schreibe ich / Wie organisiere ich“. Schreibe Schema-Regeln nicht in Memory-Dateien (Kategoriefehler).
Regel 2: Zuerst prüfen, ob es sich zu merken lohnt, dann entscheiden, wo es gespeichert wird
Nicht jede Entdeckung sollte gespeichert werden. Entscheidungsbaum:
| Signal | Sollte es gespeichert werden? |
|---|---|
| Gleicher Fallstrick zum zweiten Mal erlebt | ✅ Unbedingt |
| Bei Gegenprüfung nicht offensichtliche Erkenntnis | ✅ Grund der Entscheidung speichern („Why“) |
| Branchenvergleich / gemessene Zahlen (wiederverwendbare Basis) | ✅ Speichern |
| Einmaliger Debug, bereits behoben, kein bleibender Wert | ❌ Nicht speichern (Commit-Nachricht reicht) |
| Temporärer Zustand, der sich ändert | ⚠️ Auf Beständigkeit prüfen, nur bei Langfristigkeit speichern |
| Selten, aber kritisch (seit 6 Monaten nicht gelesen, aber immer noch einzige Wahrheit) | ✅ Behalten – 30 Tage nicht aufgerufen ≠ veraltet; Löschung basiert auf „Thema verschwunden/ersetzt“, nicht auf „wie lange nicht gelesen“ |
Entscheiden, wo es gespeichert wird – Vierstufige Lokalitätsroute:
Stelle zunächst eine orthogonale Frage: „Wird diese Tatsache in Zukunft benötigt, während man auf eine bestimmte Codezeile starrt, oder bei einer dateiübergreifenden Entscheidung / Fehlersuche zu einem bestimmten Fehlertyp?“
| Auslöser | Ziel | Mechanismus |
|---|---|---|
| Fokussiert auf eine bestimmte Zeile/einen Block, Grund in einem Satz erklärbar | Inline-Kommentar (direkt über der Zeile) | Bei Dateiänderung zu 100 % sichtbar, 0 Indexkosten |
| Mehrere Verträge / Checklisten für eine bestimmte Gruppe von Dateien | .claude/rules/<x>.md + paths: Frontmatter | Bei Treffer des Pfades automatisch Kontext einfügen |
| Auslöser ist ein Szenario/Fehler/eine bestimmte Problemart oder mehrere Dateien betreffend oder nicht zu einer einzelnen Repository-Datei gehörig (Plattform-/SDK-Fallstricke) | Memory (dieses System) | Beschreibung wird getroffen |
| Regeln, die in jeder Sitzung gelten (Befehle, Tech-Stack, Kollaborationspräferenzen) | CLAUDE.md | Dauerhaft |
An eine Datei gebundenes Feedback standardmäßig AUFTEILEN: Dateilokaler Kern → Inline-Kommentar (vor dem Schreiben den Codebereich greppen, oft existiert bereits ein äquivalenter Kommentar); Memory behält nur „dateiübergreifend wiederverwendbares Prinzip + Zeiger auf die Datei“.
Drei Barrieren gegen übermäßige Migration (Standard: Memory, lieber weniger migrieren):
- Nach Entfernen des Dateibezugs bleibt eine allgemeine Lektion übrig → Im Memory belassen (z. B. „Optionale Felder nicht für kritische Pfadentscheidungen verwenden“ – die Datei ist nur ein Beispiel, das Prinzip ist übertragbar)
- Plattform-/SDK-Verhalten tritt dateiübergreifend auf → Im Memory belassen, auch wenn es Code-Implikationen gibt
- Grabstein (X ist veraltet → siehe Y) / Untersuchungs-SOP / geschäftliche ökonomische Überlegungen → Im Memory belassen (Auslöser auf Architektur-/Szenarioebene)
Empirischer Beleg (Vollaudit einer Produktionsdatenbank mit 175 Dateien): Nur ~15 % der Einträge sind an eine einzelne Datei gebunden, und der Kern der meisten dieser Dateien ist bereits in Code-Kommentaren – „Migration“ bedeutet meist das Löschen redundanter Memory-Kopien, nicht tatsächliches Verschieben.
.claude/rules/*.md-Schreibweise (im Projekt .claude/rules/, in Git → geräte-/worktree-übergreifend nutzbar):
---
description: Ein Satz, was diese Regel betrifft
paths:
- src/components/SomeDialog.tsx
- src/lib/providers/*.ts # glob unterstützt
---
Bei Treffern der obigen Pfade automatisch eingefügte Verträge / Checkliste (Mehrfach-Gotchas).
⚠️ Bekannte Grenzen der nativen Rules-Einbindung (Stand Juli 2026, anthropics/claude-code issues): paths:-Regeln werden nur beim Lesen von Dateien eingefügt, nicht beim Schreiben/Neuanlegen (#23478); paths: in der benutzerspezifischen ~/.claude/rules/ werden ignoriert, nur projektspezifische wirken (#21858). Verträge, die „muss auch beim Erstellen neuer Dateien gelten“ erfordern, müssen in der CLAUDE.md stehen, nicht nur in rules.
Regel 3: Vorhandenes Memory vorrangig aktualisieren, nicht neu anlegen
Zu einem Thema existiert bereits eine Datei → diese Datei aktualisieren (Abschnitt oder Changelog-Abschnitt hinzufügen). Nur bei vollständig orthogonalem Thema neu anlegen. Neuanlage führt zu thematischer Fragmentierung → erschwertes Auffinden → Gedächtnisverlust.
Regel 4: Memory wird nicht automatisch geladen, die Beschreibung bestimmt den Treffer
Themendateien (memory/*.md) werden beim Sitzungsstart nicht geladen. Claude entscheidet anhand der Beschreibung im MEMORY.md-Index, ob er sie liest. Die Beschreibung muss eine Mischung aus Szenario-Schlüsselwörtern und Kernschlussfolgerung sein, sonst entscheidet Claude nach Gefühl, welche Datei gelesen wird.
Nachweis des nativen Mechanismus (Stand Juli 2026, offizielle Dok. en/memory): Es gibt kein vektorbasiertes/semantisches automatisches Abrufen – die Entdeckung erfolgt ausschließlich über die „MEMORY.md-Indexzeile + Dateiname“. Claude liest bei Bedarf mit Read; beim Lesen fügt das Harness einen Hinweis „Dieses Memory ist N Tage alt“ ein. Die Qualität des Indexzeilen-Hooks = die gesamte Trefferquote – das ist natives Verhalten, keine Konvention dieses Skills.
Regel 5: Der Skill selbst muss den vom Skill gelehrten Regeln entsprechen
Wenn dieser Skill den Benutzer auffordert, Abschnitte wie ## Why zu schreiben, sollte der Skill auch sein eigenes Why hinter jeder Regel erklären (hier alle inline in dieser Datei).
Beachte den Geltungsbereich: Regel 5 bezieht sich auf „Methoden/Schreibweise/Kurzreferenz-Form etc.“, Schema-Regeln gelten nicht rekursiv für den Skill. Schema (Benennung/Frontmatter/Why-Abschnitte) ist für Memory-Dateien, nicht für den Skill selbst. Der Skill ist keine Memory-Datei.
Regel 6: Wann aufteilen statt aktualisieren (Überlastung einzelner Dateien/Gruppen verhindern)
Regel 3 bevorzugt Aktualisieren, aber es gibt Schwellenwerte. Signale zum Auslösen einer Aufteilung (auf Dateiebene):
| Signal | Aktion |
|---|---|
| Bestehende Datei > 100 Zeilen, und neuer Inhalt ohne Bezug zum ursprünglichen Thema | Neue Datei ausgliedern, nicht einfügen |
| Bestehende Datei hat bereits ≥ 4 H2-Abschnitte auf oberster Ebene, und neuer Inhalt gehört zu einem 5. unabhängigen Thema | Neue Datei ausgliedern |
| Nach Hinzufügen des Abschnitts Gesamtlänge > 150 Zeilen | Prüfen, ob Aufteilung sinnvoll (abhängig von thematischer Unabhängigkeit) |
| Neuer Inhalt passt nicht zum Titel/description der Originaldatei | Neue Datei ausgliedern (Originaldatei sollte sich auf ihr angegebenes Thema konzentrieren) |
Überlastung einer Gruppe (auf Indexebene):
| Signal | Aktion |
|---|---|
| Anzahl Einträge in einer großen Gruppe im MEMORY.md ≥ 15 | Erwägen, einen Hub-Memory (Abschnittsindex) als Ersatz für flache Liste zu erstellen; neue Einträge an den Hub anhängen |
| Summe der Beschreibungen einer Gruppe übersteigt 25 Zeilen | Wie oben |
MEMORY.md > 23.000 Zeichen (wc -m) oder > 190 Zeilen | 🔴 Natives hartes Limit: erste 200 Zeilen oder 25k Zeichen, je nachdem, was zuerst erreicht wird (Offizielle Doku spricht von „25KB“, tatsächlich wird nach Zeichenlänge gemessen: Ein Index mit 27.972 Zeichen/37,9KB wird genau an der 25.000-Zeichen-Grenze abgeschnitten; nach Bytes würde ~35 % mehr erwartet). Der überstehende Teil wird stillschweigend nicht geladen. ⚠️ Nicht mit wc -c (Bytes) schätzen: Chinesische UTF-8-Zeichen haben 3 Byte pro Zeichen, was zu einer Überschätzung der Reserve um ~35 % führt. Bei Annäherung an das Limit gibt das Harness eine Warnung aus; „Only part of it was loaded“ = Index geht bereits verloren |
| Einzelne Indexzeile > ~160 Zeichen | Zu viele Details in der Beschreibung → in die Themendatei oder in Code-Kommentare verschieben, im Index nur „Szenario-Schlüsselwörter + Kernschlussfolgerung“ belassen |
Warum auch Gruppenüberlastung wichtig ist: Claude scannt die MEMORY.md-Indexbeschreibungen auf Treffer; bei 20+ Beschreibungen in einer Gruppe besteht aufgrund eines einzigen Scans eine Übersehensquote. Nach Erstellung eines Hubs zeigt die Gruppenindexzeile nur auf den Hub, und der Hub enthält eine thematische Karte.
Warum die Indexebene insgesamt am gefährlichsten ist: Einzelne Datei-/Gruppenüberlastung senkt nur die Trefferquote; aber wenn der Index insgesamt abgeschnitten wird = ganze Einträge am Ende nicht geladen = Trefferquote Null, und das geschieht stillschweigend ohne Fehlermeldung. Daher sollten ⭐⭐⭐-Kroneinträge nahe dem Anfang des MEMORY.md platziert werden (Absicherung gegen Abschneiden).
Priorität beim Entschlacken bei Überschreitung/Überlastung (Beschreibungen zu kürzen ist der schlechteste erste Schritt, da es die Trefferquote schädigt):
- Zuerst verschieben: Dateilokale Einträge → Inline-Kommentare /
.claude/rules(Index wird kleiner und Trefferquote steigt, siehe Regel 2 vierstufige Route) - Dann löschen: Echte Grabsteine (Thema verschwunden/ersetzt und kein Wert für Wiederbelebung)
- Dann neu anordnen: ⭐⭐⭐ nach oben im MEMORY.md verschieben
- Dann abstufen: Indexzeilen nach Wichtigkeit budgetieren – Kroneinträge ≤160 Zeichen, normale ≤110, Long-Tail-Niedrigfrequenz-Einträge zu einer Zeile mit mehreren Links zusammenfassen (
Unterthema → [a](f1.md) · [b](f2.md), eine Zeile fasst 5-10 Dateien). Zudem: Link-Label mit kurzem Namen ohne Typ-Präfix ([foo-bar](feedback_foo_bar.md)) verwenden, nicht den vollständigen Dateinamen wiederholen, spart 12-45 Zeichen pro Zeile - Zuletzt den Informationsgehalt einzelner Beschreibungen kürzen
Historische Fallstrickbeispiele (Referenz, kein Teil der Regeln)
- Einzeldatei-Überlastung: Eine Referenzdatei auf 130+ Zeilen angewachsen, mit 7-8 unabhängigen Unterthemen (Infrastruktur, Cron-Liste, Fehlerhandbuch etc.), MEMORY.md-Indexbeschreibung unvollständig, Claude konnte bestimmte Unterthemen nicht treffen. Nach Aufteilung in 5 separate Memory-Dateien jedes Thema präzise getroffen.
- Gruppenüberlastung: Eine Gruppe auf 20+ Einträge angewachsen, Claude übersah beim Scannen des Index einige, wiederholte Arbeit. Hub-Memory erstellt, das relevante Einträge bündelt → gelöst.
- Gesamtindex-Überlastung: MEMORY.md auf 43KB (≈31k Zeichen, über 25k-Zeichen-Limit) angewachsen, 93 Beschreibungen mit je 400-900 Zeichen, beim Start stillschweigend abgeschnitten, ⭐⭐⭐-Einträge am Ende nicht gelesen → bei einer Untersuchung wurde ein absichtlich so funktionierender Mechanismus fälschlich als Bug eingestuft. Lehre: Beschreibungen sind nicht umso besser, je detaillierter sie sind; zu viele Details überlasten den Index und schaden der Trefferquote.
- Falschkalibrierung Byte/Zeichen: Bei der Entschlackung wurde die Warnschwelle nach Bytes (
wc -c) auf 32KB gesetzt, während das Harness nach Zeichen misst (Chinesisch 3 Byte/Zeichen) → Die Byte-Schwelle ließ fälschlich Reserve vermuten, der Index wurde erneut abgeschnitten. Lehre: Mit dem Harness muss in denselben Einheiten abgeglichen werden, Überwachung mitwc -m.
Arbeitsmodi
Modus 1: Kandidatenbewertung (Mehrere Kandidaten, Auswahl erforderlich)
Auslöseszenarien (mehrere Kandidaten → Modus 1 erforderlich):
- Nach Feature-Entwicklung / nach langem Debug / nach Gegenprüfung
- Nach Anti-Missbrauchsbehandlung (möglicherweise mehrere Entscheidungspunkte + Lehren)
- Nach Sicherheitsvorfall / nach Fehlerlokalisierung
- Benutzer sagt: „Erinnere mich“ (vage, nicht auf einen bestimmten Fallstrick bezogen)
Einzelner konkreter Inhalt direkt an Modus 2: Benutzer sagt: „Erinnere mich an diesen Wildcard-Bug von heute“ / „Erinnere mich an das Fehlerhandbuch zur Verbindungsleckage“ → bereits konkreter Einzelfall → Modus 2, nicht Modus 1.
Schritte:
- Wichtige Knotenpunkte dieser Sitzung rekapitulieren (Benutzerkorrekturen, Gegenprüfung-Erkenntnisse, unerwartete Bugs, Branchenvergleichsabfragen, nicht offensichtliche Schlussfolgerungen einmaliger Entscheidungen)
- Jeden einzelnen mit dem Entscheidungsbaum aus Regel 2 prüfen, relevante herausfiltern
- Für jeden Kandidaten prüfen:
- Existiert bereits eine Memory-Datei, die das abdeckt? (grep MEMORY.md-Index) → Ja: Modus 3 aktualisieren, Nein: Modus 2 neu anlegen
- Übersteigt der hinzuzufügende Inhalt die Aufteilungsschwelle von Regel 6? → Neue Datei ausgliedern
- Sollte es in die CLAUDE.md statt ins Memory? (siehe Tabelle unten)
- Mit Benutzer abstimmen: Liste der „vorgeschlagenen neuen / vorgeschlagenen Aktualisierungen / vorgeschlagenen Aufteilungen“ präsentieren, auf Bestätigung warten
Grenze Memory vs. CLAUDE.md:
| Inhaltstyp | Wohin |
|---|---|
| Konkrete Fallstricke (SDK-Bug, Plattformbeschränkung, Branchendaten) | Memory feedback_* |
| Tiefgehende thematische Referenz / Standardmethode / Prozessdokumentation | Memory reference_* |
| Zustandsbezogene Fakten (laufende Arbeit, temporäre Konfiguration, aktuelle Architektur-Snapshot) | Memory project_* |
| In jeder Sitzung zu befolgende Regeln (Befehle, Tech-Stack, Kollaborationspräferenzen) | CLAUDE.md |
| Nur bei bestimmten Dateioperationen benötigte Regeln | .claude/rules/*.md mit paths: Frontmatter |
Modus 2: Neues Memory anlegen (Standardablauf)
Schritt 0: Zuerst die Lokalitätsprüfung durchführen (Regel 2 vierstufige Route)
Vor dem Schreiben bestätigen, dass es wirklich ins Memory gehört: Einzelne Datei → Inline-Kommentar; Verträge zu einer Dateigruppe → .claude/rules + paths; Szenario/dateiübergreifend/Plattform-Fallstricke → erst dann ins Memory. An eine Datei gebundenes Feedback standardmäßig AUFTEILEN (Kern in Kommentar, Memory nur dateiübergreifendes Prinzip + Zeiger). Siehe Regel 2.
Schritt 1: Typ bestimmen
| Typ | Wann verwenden | Pflichtinformationen |
|---|---|---|
| feedback | Gelernte Fallstricke (SDK-Bug / Plattformbeschränkung / Benutzerpräferenz) | Grund (warum diese Schlussfolgerung) + Wann wiederverwenden (Auslöseszenario) |
| reference | Tiefgehende thematische Referenz / Standardmethode / Branchenvergleich / wiederverwendbare Pipeline | Kein zwingender Grund-Abschnitt (beschreibend) |
| project | Zustandsbezogene Fakten (Architektur-Snapshot, laufende Arbeit, ökonomische Analyse) | Kein zwingender Grund-Abschnitt (zustandsbezogen) |
Darstellungsform der Pflichtinformationen bei feedback (eine davon):
- Eigenständiger Abschnitt:
## Whyoder gleichbedeutend auf Chinesisch## 根因/## 原因/## 教训/## 为什么(Audit akzeptiert alle) - Fettgedruckt inline:
**Why**:/**根因**:(auch bei kurzer Schlussfolgerung) - Inline in der description oder in der ##-Überschrift (wenn die Schlussfolgerung bereits Grund + Wiederverwendungszeitpunkt impliziert, z. B. Vergleichstabelle ❌/✅)
Information zur Wiederverwendung: Kann ein separater Abschnitt ## How to apply sein, oder die description enthält Szenario-Schlüsselwörter (z. B. Tab-Wechsel / Mutation impliziert bereits das Auslöseszenario).
Schritt 2: Dateiname
<type>_<topic>[_<modifier>].md komplett klein mit Unterstrichen:
- ✅
feedback_supabase_from_deadlock.md - ✅
reference_supabase_egress_favorites_refactor.md - ❌
feedback-supabase-deadlock.md(Bindestriche verwendet) - ❌
FeedbackSupabaseDeadlock.md(CamelCase) - ❌
_schema.md(Unterstrich am Anfang wird als versteckte Datei behandelt, Claude liest nicht aktiv)
Schritt 3: Frontmatter schreiben
---
name: kebab-case-slug
description: Szenario-Schlüsselwörter + Kernschlussfolgerung
type: feedback | reference | project # flach (empfohlen)
# oder:
# metadata:
# type: feedback | reference | project # verschachtelt (kompatible Schreibweise)
---
Position des type-Feldes: type: flach (empfohlen) oder metadata.type: verschachtelt werden beide akzeptiert. Das Audit-Skript erkennt beide. Bei neuen Dateien flache Schreibweise bevorzugen, um mit der Mehrheit bestehender Dateien konsistent zu sein.
Stilbeurteilung der description:
| ✅ Gute description | ❌ Schlechte description |
|---|---|
supabase.from()-mutation im Browser führt nach Tab-Wechsel zu Deadlock, fetch() mit REST API verwenden | Supabase-bezogene Probleme |
CF Image Transformations schlagen fehl: 7-Tage-Cache / cf-resized err= / FavoriteCard-Retry-Muster | Bilder werden manchmal nicht angezeigt |
RLS-Richtlinien müssen mit (SELECT auth.uid()) umschlossen werden, sonst wird jeder Zeilenausdruck erneut ausgewertet | RLS-Leistungsoptimierung |
Bewertungskriterium: Kann Claude beim Lesen der description sofort erkennen, „dies ist die Schlussfolgerung Y, die in Szenario X nachgeschlagen werden muss“?
Schritt 4: Haupttext schreiben
feedback-Klasse (muss Grund + Wiederverwendungszeitpunkt enthalten):
# Titel (Was – ein Satz)
[Kernschlussfolgerung + 1-2 Absätze Hintergrund]
## Why (oder gleichbedeutend: ## 根因 / ## 原因 / ## 教训 / ## 为什么)
[Warum diese Schlussfolgerung – konkret erlebte Fallstricke, Gegenprüfung-Erkenntnisse, Benutzerpräferenzen]
**Warum Pflicht**: Ohne Grund-Abschnitt wird dieselbe Entscheidung beim nächsten Mal oft zur gleichen falschen Schlussfolgerung führen.
## How to apply (kann weggelassen werden, wenn description bereits Szenario-Schlüsselwörter enthält)
[Wann diese Regel wiederverwendet wird – Auslöseszenario, Checkliste, Schritte zur Vermeidung von Fallstricken]
reference / project-Klasse: Keine zwingende Abschnittsstruktur, nach Thema natürlich organisieren.
Schritt 5: Zum MEMORY.md-Index hinzufügen
- Bestehende große Gruppe wählen, keine neue Gruppe anlegen
- Beschreibung innerhalb der Gruppe an passender Stelle einfügen (hohe Wichtigkeit mit ⭐⭐ / ⭐⭐⭐ fett markieren)
- Thematikübergreifend: Am Ende der description
(siehe auch [[other-file]])hinzufügen
Modus 3: Vorhandenes Memory aktualisieren (Vorrang vor Neuanlage)
Schritt 1: Zugehörigkeit zu bestehenden Themen mit grep bestätigen
grep -l "<Schlüsselwort>" memory/*.md
Schritt 2: Aktualisierungsmethode wählen
| Situation | Wie aktualisieren |
|---|---|
| Neue Daten / neuer Fall ergänzen bestehende Schlussfolgerung | Abschnitt oder Changelog-Abschnitt im Haupttext hinzufügen |
| Bestehende Schlussfolgerung widerlegt | Am Anfang der alten Datei ⚠️ Superseded by [[new-file-slug]] hinzufügen, in der neuen Datei schreiben, was sie von der alten ersetzt |
| Nur die Beschreibung ist unklar | MEMORY.md-Index ändern, nicht die Datei selbst (es sei denn, auch Inhalt wird hinzugefügt) |
Schritt 3: MEMORY.md synchronisieren
Wenn die description geändert wurde, muss auch die entsprechende Zeile im MEMORY.md aktualisiert werden.
Modus 4: Strukturelle Änderung (Schema ändern / neuen Typ hinzufügen / Gruppen umorganisieren)
Vorher die Liste bereits erlebter Fallstricke lesen:
- Nicht versuchen, die Glob-Syntax
if: "Write(memory/*.md)"zu hooken –if:ist eine Permission-Regel, kein Datei-Glob, als ungültig bestätigt - Nicht
exit 2verwenden, um Hooks zu blockieren – als schädlich für Pre-Deployment-Batch-Abläufe bestätigt (Claude hat keinen automatischen Wiederholungsmechanismus) - Die Schema-Autoritätsquelle nicht in einer Datei mit führendem Unterstrich wie
_schema.mdablegen – Claude liest Themendateien nicht aktiv - Keine Hooks in
.claude/settings.jsondes Projekts konfigurieren – dieses Verzeichnis ist normalerweise in.gitignore, nicht in Git und nicht worktree-übergreifend - Bei neuen Pflichtfeldern an 3 Stellen synchronisieren: (a) Abschnitt „Modus 2 → Schritt 3“ in diesem Skill, (b) Kurzreferenz-Abschnitt oben im MEMORY.md, (c) Feldliste im audit-memory.sh-Skript
- Vor dem Ändern von Hooks / Hinzufügen von Beschränkungen
bash scripts/audit-memory.shausführen, um aktuelle Compliance-Rate zu sehen – nur bei <95 % harte Maßnahmen ergreifen, bei ≥95 % weiche Warnung belassen - MEMORY.md-Größenüberwachung muss auf Zeichen (
wc -m) basieren, nicht auf Bytes (wc -c) – nativ obere Grenze 200 Zeilen/25k Zeichen nach Zeichen; Chinesisch 3 Byte/Zeichen, Kalibrierung nach Bytes führt zu stillschweigendem Abschneiden (siehe Regel 6 historische Fallstricke)
Ablauf einer Schemaänderung:
- Audit laufen lassen, um aktuelle Basislinie zu erhalten
- Änderung entwerfen (diesen Skill + Projekt-Hub ändern)
- Prüfen, ob bestehende Memorys massiv gegen die neue Regel verstoßen (>10 % → zurückstellen, zuerst nach neuer Regel migrieren)
- MEMORY.md-Kurzreferenz-Abschnitt aktualisieren
- Feldliste im Audit-Skript ändern
- Erneut Audit laufen lassen, um neue Compliance-Rate zu prüfen
Modus 5: Bootstrap ohne Memory (Neues Projekt)
Wenn der Benutzer in einem Projekt ohne Memory-System sagt: „Fang an, Erinnerungen aufzubauen“:
Schritt 1: Pfad zum Auto-Memory-Verzeichnis bestätigen
Claude Code erstellt automatisch ~/.claude/projects/<project-slug>/memory/, wobei <project-slug> = absoluter Projektpfad mit / durch - ersetzt. Beispiel:
- Projekt
/Users/alice/Project/myapp→ slug-Users-alice-Project-myapp
Wenn Claude Code bereits automatisch Auto-Memory für dieses Projekt erstellt hat, existiert das Verzeichnis. Prüfen: ls ~/.claude/projects/ | grep <Projektname>.
Schritt 2: MEMORY.md-Index erstellen
Vorlage für den oberen Teil (auf ~25 Zeilen komprimierbar):
# <Projektname> Projekt-Memory
## ⭐⭐⭐ Kurzreferenz Memory schreiben (harte Regeln)
- Dateiname: `<type>_<topic>.md` komplett klein mit Unterstrichen; type ∈ {feedback, reference, project}
- Pflicht-Frontmatter: name / description / type
- feedback muss einen ## Why-Abschnitt enthalten (oder gleichbedeutend chinesisch ## 根因 / ## 教训 / ## 原因)
- description-Stil: Szenario-Schlüsselwörter + Kernschlussfolgerung (einzelne Zeile ≤160 Zeichen)
- Bei bereits vorhandener Datei zum selben Thema → aktualisieren, nicht neu anlegen (bei Überschreitung der Schwelle von Regel 6 aufteilen)
- Hartes Limit dieses Index: erste 200 Zeilen oder 25k Zeichen (je nachdem, was zuerst erreicht wird); Überstehendes wird stillschweigend nicht geladen
- Ausführliche Methode: memory-management-Skill
## ⭐ Projekt-Themenliste
(Noch keine – später nach Thema Gruppen hinzufügen)
Schritt 3: Schwellenwert für Gruppenentwicklung (Struktur nach Dateianzahl)
| Anzahl Memory-Dateien | Empfohlene Struktur |
|---|---|
| < 15 | Flache Liste, keine Gruppen (eine Liste reicht, Gruppen würden fragmentieren) |
| 15-25 | 3-5 große Gruppen einführen (nach Thema gruppieren) |
| > 25 | Gruppen ausgereift, Gruppen einfrieren, keine neuen Gruppen anlegen; neue Einträge in bestehende Gruppen einhängen (themaübergreifend mit (siehe auch X)) |
Schritt 4: Memory-Protokoll oben in der CLAUDE.md hinzufügen (3-5 Zeilen)
## Memory-Verwaltung
Bei Memory-Schreib-/Update-/Schema-Anpassungen → `memory-management`-Skill verwenden.
- Kurzreferenz-Regeln: MEMORY.md oben ⭐⭐⭐-Abschnitt
- Compliance-Rate prüfen: `bash scripts/audit-memory.sh` (optional, siehe Skill-Vorlagen/)
Schritt 5: Allgemeine Methoden dieses Skills wiederverwenden
Skill-Inhalt nicht in das Projekt kopieren. Der Skill befindet sich auf Benutzerebene, alle Projekte teilen sich eine Methodik. Im Projekt nur projektspezifische Zustände ablegen (Gruppenliste / Todos / projektspezifische Fallstricke).
Schema-Spezifikation (Autoritätsquelle)
Dateibenennung
<type>_<topic>[_<modifier>].md komplett klein mit Unterstrichen, type ∈ {feedback, reference, project}
Pflicht-Frontmatter
---
name: kebab-case-slug
description: Szenario-Schlüsselwörter + Kernschlussfolgerung
type: feedback | reference | project # flach (empfohlen)
# oder:
# metadata:
# type: feedback | reference | project # verschachtelt (kompatible)
---
Das Audit-Skript erkennt beide. Bei neuen Dateien flache Schreibweise bevorzugen.
Pflichtinformationen bei feedback
Grund-Abschnitt (einer davon):
## Whyoder gleichbedeutend auf Chinesisch## 根因/## 教训/## 原因/## 为什么/## Root cause(mit englischem:oder chinesischem:)- Fettgedruckt inline
**Why**:/**根因**:etc.
Wiederverwendungszeitpunkt (einer davon):
- Separater Abschnitt
## How to apply - description enthält Szenario-Schlüsselwörter (impliziert Auslöseszenario)
description-Stil
Gemisch (Szenario-Schlüsselwörter + Kernschlussfolgerung), damit Claude anhand der description erkennt: „In Szenario X nach Schlussfolgerung Y suchen“. Einzelne Zeile ≤ ~160 Zeichen – Details in Themendatei oder Code-Kommentare verschieben (Index-Hartlimit = 200 Zeilen/25.000 Zeichen, je nachdem zuerst erreicht; überstehende werden stillschweigend nicht geladen)
Indexzeilenformat
- [Kurztitel](vollständiger_dateiname.md) — hook. Kurztitel = Name mit Bindestrichen ohne Typ-Präfix (z. B. [supabase-from-deadlock](feedback_supabase_from_deadlock.md)); Long-Tail-Niedrigfrequenz-Einträge mit Sammelzeile (Unterthema → [a](f1.md) · [b](f2.md))
Gruppen eingefroren
Aus bestehenden großen Gruppen wählen, keine neuen Gruppen anlegen. Bei unklarer Zuordnung mit (siehe auch hub-X) querverweisen.
Häufige Fehler
| Falsch | Richtig |
|---|---|
| Aus dem Gedächtnis description schreiben: „Supabase-Problem“ | Szenario-Schlüsselwörter + Schlussfolgerung schreiben: „supabase.from() Tab-Wechsel Deadlock, fetch verwenden“ |
| Bei feedback nur „Was es ist“ schreiben | feedback muss ## Why enthalten, um künftige Hinterfragung zu verhindern |
| Bei gleichem Thema eine zweite Datei neu anlegen | Vorhandene Datei aktualisieren, Neuanlage fragmentiert |
| Neue Gruppe „Netzwerkproblem“ mit einem Eintrag anlegen | Bestehende Gruppe verwenden, themaübergreifend mit (siehe auch X) |
| Schema-Regeln in Memory-Datei schreiben | Schema in diesem Skill, Memory enthält Fakten |
Hook mit exit 2 zum Blockieren verwenden | Weiche Warnung (stderr + exit 0) oder nachträgliches Audit verwenden |
Selbstprüfung (nach dem Schreiben)
- Typ korrekt (feedback/reference/project)?
- Dateiname entspricht
<type>_<topic>.mdkomplett klein mit Unterstrichen? - Frontmatter 3 Felder vollständig (name / description / type)?
- feedback-Klasse hat Grund-Abschnitt (
## Whyoder gleichbedeutend chinesisch / fettgedruckt inline)? - description enthält Szenario-Schlüsselwörter + Kernschlussfolgerung?
- Bereits im MEMORY.md-Index unter der richtigen großen Gruppe hinzugefügt?
- Keine neue Gruppe angelegt? (Wenn doch, rückgängig machen und in bestehende Gruppe einfügen)
- Regel 6-Prüfung: Neue Datei < 100 Zeilen + < 5 H2-Abschnitte? (Wenn Aktualisieren einer bestehenden Datei diese Schwelle überschreiten würde, stattdessen neue Datei ausgliedern)
- Lokalitätsprüfung (Regel 2): Bezieht sich dieser Eintrag auf eine bestimmte Datei? Falls ja, ist der dateilokale Grund bereits/angemessen in Code-Kommentaren und das Memory enthält nur dateiübergreifende Prinzipien?
- Indexebenen-Prüfung: Nach Hinzufügen/Ändern der description ist MEMORY.md < 23.000 Zeichen (
wc -m, nicht Bytes!) und < 190 Zeilen + einzelne Zeile ≤ ~160 Zeichen? - Trefferkraft-Prüfung: Drei mögliche Szenario-Schlüsselwörter für künftige Anfragen notieren; simulieren: „Würde Claude anhand der description dieses Memory lesen?“ (Wenn kein Szenario vorstellbar, ist die description unzureichend)
Tool-Integration
Das Audit-Skript ist ein optionales Projektwerkzeug.
scripts/audit-memory.sh im Projektstamm vorhanden → ausführen:
bash scripts/audit-memory.sh # Compliance-Rate anzeigen / Verstöße auflisten / 30 Tage nicht aufgerufene auflisten
Ausgabe: Gesamtanzahl Dateien / fehlendes Frontmatter / fehlendes Why / MEMORY.md-zerbrochene Links / 30 Tage nicht aufgerufene / MEMORY.md-Größe (Zeichen+Zeilen, verglichen mit nativem Limit 200 Zeilen/25k Zeichen) / Compliance-Rate in %. Ziel-Compliance-Rate ≥ 95 %.
Kein Audit-Skript vorhanden → aus Vorlage selbst erstellen:
# Universelle Vorlage im benutzerspezifischen Skill-Verzeichnis
cp ~/.claude/skills/memory-management/templates/audit-memory.template.sh \
<Ihr Projekt>/scripts/audit-memory.sh
# MEMORY_DIR auf das Auto-Memory-Verzeichnis Ihres Projekts anpassen
chmod +x <Ihr Projekt>/scripts/audit-memory.sh
bash <Ihr Projekt>/scripts/audit-memory.sh
Referenz Standard-Auto-Memory-Pfad: ~/.claude/projects/<project-slug>/memory/, siehe Modus 5 Schritt 1.