# Token-Hygiene — User Guide (Tier 3: Cache-Disziplin)

Eine kurze Anleitung **für dich** (den Nutzer), wie du die Prompt-Cache-Mechanik
auf deiner Seite richtig bedienst. Claude liest diese Datei mit und **erinnert
dich aktiv**, wenn es eines der unten genannten Anti-Patterns beobachtet.

Hintergrund: Der stabile Anfang jeder Anfrage (System-Prompt + `CLAUDE.md`) wird
von Anthropic **gecacht**, mit einer **TTL von 5 Minuten**. Solange der Cache
warm ist, zahlst du diesen Teil nicht erneut. Ein Cache-Miss bedeutet: der ganze
Kontext wird uncached neu gelesen — langsamer und teurer.

---

## Die drei Regeln

### 1. Stabilen Präfix stabil halten
`CLAUDE.md` und Projekt-Config **nicht mitten in einer Arbeitssession editieren**.
Jede Änderung an der Datei bustet den Cache für **alle** folgenden Turns dieser
Session. Sammle Doku-/Config-Änderungen und mach sie in **einem eigenen
Durchgang** (so wie dieser hier), nicht verstreut zwischen Code-Arbeit.

> **Reminder-Trigger für Claude:** Wenn der Nutzer mitten in einer laufenden
> Code-/Debug-Aufgabe eine Änderung an `CLAUDE.md` oder `.claude/settings.json`
> verlangt → kurz darauf hinweisen, dass das den Cache bustet, und anbieten, es
> zu bündeln/ans Ende zu legen.

### 2. Keine Kette kurzer Wartepausen
Eine Pause **> 5 Minuten** kostet beim nächsten Turn einen Cache-Miss. Eine
*einzelne* lange Pause ist egal. Schlecht ist, viele kurze „warte mal kurz"-Turns
aneinanderzuhängen, bei denen jeder nach >5 Min den Kontext neu liest. Wenn du
auf etwas Externes wartest (CI, Deploy), lieber **einmal** lang warten als
mehrfach pollen.

> **Reminder-Trigger für Claude:** Wenn der Nutzer wiederholt kurze
> „warte/poll mal"-Anweisungen mit Lücken um die 5-Minuten-Grenze gibt → einen
> einzelnen längeren Wartezyklus (oder eine Hintergrund-/Monitor-Lösung)
> vorschlagen statt mehrfachem Pollen.

### 3. Eine Session pro Thema
Lange Multi-Themen-Sessions sind der größte versteckte Kostenfaktor (jeder Turn
schickt die ganze History neu). Nach einer abgeschlossenen Aufgabe: **neue
Session** (`/clear`) statt zum nächsten, unzusammenhängenden Thema im selben
Thread zu wechseln. Das ist eigentlich Tier 1, aber es interagiert direkt mit
dem Cache: ein frischer Thread = kleiner, vollständig gecachter Präfix.

> **Reminder-Trigger für Claude:** Wenn die Session erkennbar das Thema wechselt
> (z.B. von „Pages-Fix" zu „neues Feature implementieren") → vorschlagen, eine
> frische Session zu starten, und optional die wichtigsten Entscheidungen vorher
> in Memory/Decision-Records festhalten.

---

## Schnell-Check vor einer langen Session

- [ ] Ist das ein **einzelnes** Thema? Wenn nein → splitten.
- [ ] Stehen anstehende `CLAUDE.md`-Änderungen an? → **vorher** erledigen, dann stabil lassen.
- [ ] Erwarte ich lange Wartezeiten (CI/Build)? → Hintergrund-Job + **eine** lange Wartephase, kein Polling.

## Verwandte Hebel (nicht Cache, aber gleiche Wirkung)
Tier 1 (Session-Schnitt) und Tier 2 (Kommando-Disziplin: Output filtern, Pfad-
Scope, nicht zurücklesen) stehen als operative Regeln im Abschnitt
*„Agentic workflow patterns" → „Token hygiene"* in der `CLAUDE.md`.