diff --git a/docs/handoff-20260922-claude-md-ausduennen.md b/docs/handoff-20260922-claude-md-ausduennen.md new file mode 100644 index 0000000..65c8830 --- /dev/null +++ b/docs/handoff-20260922-claude-md-ausduennen.md @@ -0,0 +1,75 @@ +# Handoff 2026-09-22 — CLAUDE.md ausdünnen (strukturelle Hygiene, kein Bug) + +**Anlass:** Christoph stellt fest, dass CLAUDE.md „eh schon so groß" ist. Das ist kein kosmetischer +Punkt — es ist eine strukturelle Drift, die jede künftige Session belastet. Dieser Handoff beschreibt +das Problem aus der Innenperspektive einer Session (die CLAUDE.md bei jedem Start komplett lädt) und +gibt einen Scope für eine eigene Cleanup-Session. + +## Das Problem, aus Sicht der Session + +Jede Session lädt CLAUDE.md **vollständig** in den Kontext. Was dabei konkret wehtut: + +1. **Reine Kontext-Kosten.** Die Datei ist >58 KB. Ein großer Teil davon ist nicht „Kontext für die + anstehende Arbeit", sondern Historie und abgeschlossene TPs. Der Token-Preis wird bei jeder Session + fällig, egal worum es geht. + +2. **Signal-to-noise im Gotcha-Block.** Der „Kritische Gotchas"-Abschnitt mischt **aktive Fallen** mit + **erledigten/gegenstandslosen** Einträgen. Beispiele direkt aus dem Bestand: `~~ALLNET~~` und + `~~Omada~~` sind mehrfach als „gegenstandslos/historisch" markiert, stehen aber weiterhin voll im + Text. Mehrere Einträge tragen „korrigiert am X" — die **korrigierte** Fassung steht neben der + **falschen**, die damit weiter mitgelesen wird. Beim Suchen nach *einer* relevanten Falle scannt + die Session dutzende Zeilen, von denen ein guter Teil totes Gewicht ist. + +3. **Redundanz über drei Orte.** Dieselbe Information (z. B. die AP-Positionen, der FT-Verlauf) steht + in CLAUDE.md **und** in `teilprojekte.md` **und** teils in Handoffs. Eine Korrektur an einer Stelle + lässt die anderen stumm veralten — genau die Drift, vor der die eigene CLAUDE.md warnt + („Manuell gepflegte Doku verliert gegen die Realität, wenn sie lang wird"). + +4. **Der gefährlichste Effekt: die Bloat untergräbt „live prüfen".** Die Projektregel lautet „nicht + raten, live prüfen oder fragen". Eine Riesen-CLAUDE.md mit eingestreuten Stale-Angaben verleitet + genau dazu, sich auf die Datei zu verlassen statt nachzusehen — die Datei ist Teil des Problems, + das sie zu lösen vorgibt. + +## Was wohin gehört (SSoT-Dreiteilung, TP36) + +| Inhalt | Soll-Ort | +|---|---| +| VLAN-Modell, Hardware-Tabelle (aktuell), Tooling-Pointer | CLAUDE.md (bleibt) | +| **Aktive, querschnittliche** Fallen (Firewall deny-by-default, sshpass-Regel, cap-wifiN-Karte …) | CLAUDE.md (bleibt, komprimiert) | +| TP-spezifische Gotchas & Detail-Verläufe | `teilprojekte.md` `### TPnn` | +| Erledigte/historische Geräte & Entscheidungen | `teilprojekte-archiv.md` | +| „korrigiert am X"-Notizen | Original-Eintrag bereinigen (Stale-Wert raus), Korrektur **ersetzt** den Irrtum, statt neben ihm zu stehen | + +## Konkrete Kandidaten zum Ausdünnen (Startpunkte, nicht abschließend) + +- **„Kritische Gotchas":** alle `~~durchgestrichenen~~`/„gegenstandslos"-Einträge (ALLNET, Omada, + sw1, ES208G, „ALLNET VLAN-DB") → Archiv oder löschen. +- **„korrigiert"-Notizen:** die falsche Angabe entfernen, nur die korrigierte behalten (z. B. + Nautobot-IP, „2×/Tag war nie real", „`ft=no` war NICHT uniform"). +- **„Pflichtlektüre":** ist von „1–7" auf effektiv „0–7" angewachsen; die ✅-GESCHLOSSEN-Punkte + (TP16.3 §5, Fund E) sind abgeschlossene Historie → aus dem Pflichtteil in einen Verweis. +- **„Lessons for Sessions":** mehrere Meta-Lektionen überlappen sich (Maskierungs-Muster kommt 3×, + „erst das Werkzeug verdächtigen" 2×) → auf je eine Fassung verdichten. +- **Hardware-Tabelle:** ausgemusterte Geräte (Omada, ALLNET) sind noch als Zeilen da, teils nur mit + ❌ — prüfen, ob sie ganz raus können (Archiv) statt als Toten in der aktuellen Tabelle zu stehen. + +## Vorgehen für die Cleanup-Session + +1. **Bestandsaufnahme zuerst:** CLAUDE.md abschnittsweise sichten und je Eintrag klassifizieren + (aktiv-querschnittlich / TP-spezifisch / historisch / redundant). Drift-Tabelle vorlegen, **fragen** + was wohin soll — nicht stillschweigend umsortieren. +2. **Nichts löschen ohne Zielort:** TP-spezifisches wandert nach `teilprojekte.md`, Historisches nach + `teilprojekte-archiv.md`. Erst wenn der Zielort steht, aus CLAUDE.md entfernen. +3. **Zielbild:** CLAUDE.md zurück auf einen **schlanken Index** (VLAN-Modell, Hardware, Tooling, die + ~10 wirklich querschnittlichen aktiven Fallen). Detail gehört nach `teilprojekte.md`. +4. **Abnahme:** CLAUDE.md-Wortzahl/Zeilen vorher/nachher notieren; sicherstellen, dass kein + noch-aktiver Gotcha (Firewall, sshpass, cap-wifiN, slaves-datapath, WLAN-Logs-Topic) verloren geht. + +## Übergabeprompt (nächste Session) + +> CLAUDE.md ausdünnen: die Datei ist >58 KB und mischt aktive Fallen mit erledigter Historie +> (durchgestrichene „gegenstandslos"-Einträge, „korrigiert"-Notizen neben der falschen Angabe, +> Redundanz mit teilprojekte.md). Aufgabe: Bestandsaufnahme + Drift-Tabelle, dann TP-spezifisches +> nach teilprojekte.md, Historisches ins Archiv, CLAUDE.md zurück auf einen schlanken Index +> (~10 querschnittliche aktive Gotchas behalten). Nicht stillschweigend umsortieren — erst klassifizieren +> und fragen. Siehe [[handoff-20260922-claude-md-ausduennen]].