569a03dc08
All checks were successful
C++ Tests / test-fast (pull_request) Successful in 2m2s
API Docs / doc-build (pull_request) Successful in 1m8s
Markdown link check / check (pull_request) Successful in 52s
C++ Tests / test-cgal (pull_request) Has been skipped
C++ Tests / quality-gates (pull_request) Successful in 1m59s
Refresh CLAUDE.md for v0.10.0 (3 CI jobs incl. disabled test-cgal,
compile-time option matrix, reviewer/pages docs, agentic + token-hygiene
workflow patterns) and condense the historical Phase-8/audit logs to
pointers.
Add the documentation-pass process so the single-source-of-truth rules
stay enforced:
* scripts/quality/check-doc-freshness.sh — string-only drift gate
(version/date across CITATION/CHANGELOG/CLAUDE, doc-map count), <1 s,
registered in run-all.sh + quality README.
* doc/release-policy.md — "Documentation passes" subsection (triggers +
docs:sync rule); fix stale Phase-milestone mapping (v0.10.0 was
reviewer-ready, 9c→v0.11.0) and the test-cgal CI mention.
Add shared Claude config (un-ignore the two files only):
* .claude/settings.json — permission allowlist for safe repo commands.
* .claude/token-hygiene.md — Tier-3 cache-discipline user guide that
CLAUDE.md instructs Claude to remind the user about.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
63 lines
3.1 KiB
Markdown
63 lines
3.1 KiB
Markdown
# 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`.
|