bf-infra/docs/handoff-20260922-claude-md-ausduennen.md

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.