569a03dc08
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>
3.1 KiB
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.mdoder.claude/settings.jsonverlangt → 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.