ClaudeDo/docs/usage-optimization.md

Usage-Optimierung — Befunde und Messmethodik

Stand: 2026-08-05. Ausgangsfrage: Wie lassen sich autonome ClaudeDo-Agents token-effizient betreiben? Abrechnung läuft über Abo-Session-Limits, nicht über die API — relevant ist roher Token-Verbrauch gegen 5h-/7d-Fenster, nicht Geld.

Dieses Dokument ist bewusst kompakt gehalten. Was eine Session früh in den Prefix lädt, wird mit jeder weiteren Nachricht multipliziert (siehe Befund 5) — ein 30k-Handover-Dokument würde das Problem reproduzieren, das es beschreibt.

---

1. Verbrauchsstruktur

Gemessen über alle Transcripts unter C:\Users\mika.kuns\.claude\projects.

Posten	Roh-Token	Anteil
Cache-Read	3.118.025.644	95,6 %
Cache-Write	140.783.227	4,3 %
Output	22.466.702	0,7 %
Input frisch	141.496	0,0 %

Kontext-Resend = 99,3 % des Rohverbrauchs. Auch unter API-Preisgewichtung (read 0,1× / write 1,25× / out 5×) bleibt es bei 81,3 %. Die Rangfolge ist gegen jede plausible Gewichtung robust.

Verstärkung: ~3,6 Mio einzigartiger Inhalt → 1,59 Mrd abgerechnete Prompt-Token in ClaudeDo-Sessions. Jeder Kontext-Token wird im Schnitt ~425× erneut abgerechnet.

2. Scope-Split — wer verbraucht

Scope	Roh-Token	Anteil
INTERAKTIV (Mikas eigene Sessions)	2.690.028.785	81,6 %
AGENT (ClaudeDo-Runs)	606.222.055	18,4 %

Interaktiv nach Modell: opus-4-8 33,0 % · opus-5 28,5 % · sonnet-5 14,0 % · fable-5 5,2 %. Agent-Runs fahren überwiegend sonnet-5 — der Default greift, die Modelldisziplin auf Agent-Seite ist in Ordnung.

Konsequenz: ClaudeDo-Optimierung adressiert maximal 18 % des Limits. Der größere Block sind die eigenen Opus-Sessions.

3. Session-Länge ist der Treiber

Verbrauch ≈ Nachrichten × Ø-Kontext, und der Kontext wächst mit den Nachrichten → quadratisch. Eine Session in k Teile schneiden bringt grob 1/k.

Interaktiv: Top 20 von 255 Sessions = 55,9 % des Verbrauchs.

Roh-Token	Msgs	Ø Kontext	Modell
199.516.097	716	278.653	opus-4-8
138.020.247	440	313.682	opus-5
123.586.522	463	266.925	opus-4-8

4. Was den Kontext füllt

Tool	Anteil (Agent)	Anteil (interaktiv)
Read	59,8 %	68,2 %
Bash	16,3 %	15,4 %
Grep	8,3 %	5,2 %

Read ohne offset/limit: 57 % (Agent) / 62 % (interaktiv). Re-Reads derselben Datei in derselben Session: 18 % der Read-Calls. Subagent-Nutzung: nur 40 Calls bei 1.325 Reads (Agent-Seite) — die Kontext-Firewall ist praktisch ungenutzt. Interaktiv sind Subagent-Sessions dagegen 20 % des Verbrauchs.

Teuerste Read-Ziele sind God-Files: TasksIslandViewModel.cs (1121 Z.), ExternalMcpService.cs (1002 Z.), WorkerHub.cs (979 Z.).

5. Prefix-Größe × Nachrichtenzahl schlägt alles

Fallstudie an der Analyse-Session selbst (136 Msgs, 43.492.835 Roh-Token):

msg  1 :     39.914
msg  3 :    273.822   (+233.908)  <-- claude-api-Skill geladen
msg 136:    380.327

Der Skill in Nachricht 3 wurde danach 136× mitgelesen: 31,8 Mio Token = 73 % der Session. Zum Vergleich: alle tool_results zusammen = 21.600 Token (0,05 %).

Discovery ist praktisch gratis, wenn man aggregiert statt Dateien dumpt. Teuer ist ausschließlich, was früh und groß in den Prefix wandert. Derselbe Block in Nachricht 120 geladen hätte ein Zwanzigstel gekostet.

6. Amortisation von Planungssessions

Posten	Token
Analyse-Session gesamt	43,5 Mio
davon vermeidbarer Prefix-Ballast	−31,8 Mio
echte Planungsleistung	≈ 11,7 Mio

Gegenrechnung: 10 von 37 Tasks brauchten einen Retry (27 %), 13 von 54 Runs sind Wiederholungen. Ein Agent-Run liegt im Schnitt bei ~11 Mio Roh-Token — ein vermiedener Retry spart also grob eine ganze Planungssession. Dazu ersparte Rediscovery: ein Fund von ~8k Token, den ein Agent in Turn 10 eines 60-Turn-Runs selbst machen müsste, wird danach ~50× mitgelesen = ~400k pro Fund.

Fazit: gründliche Planung rechnet sich — aber nur bei schlankem Prefix.

---

Was NICHT hilft (geprüft und verworfen)

• --effort senken. Thinking ist 12.536 Token über alle interaktiven Sessions = 0,00 % des Verbrauchs. Effort zu senken spart nichts und kostet Qualität. Endgültig erledigt.
• Skill-Trigger entschärfen. Der claude-api-Skill kostete in einer Session 73 % — feuerte aber nur 2× in 3 Wochen (2026-07-14, 2026-08-05). Erwarteter Nutzen vernachlässigbar, Risiko (Antworten aus veraltetem Prior) real. Er hat sich in dieser Session sogar bezahlt gemacht: der Hinweis, dass input_tokens nur der uncached Rest ist, hat den Accounting-Bug aufgedeckt.
• God-Files splitten. Eigenes Risiko; Read-Disziplin entschärft das Symptom billiger.

Offene Hebel — noch nicht untersucht

• Interaktive Session-Hygiene: ab wann lohnt /clear, messbar an Ø-Kontext?
• Modellrouting interaktiv (opus-4-8 + opus-5 = 61,5 % des Accounts).
• Subagent-Ökonomie: Firewall-Nutzen gegen Eigenverbrauch (20 % interaktiv).
• MCP-Tool-Definitionen im Prefix: Umfang bei ~200 deferred Tools nicht gemessen.
• Kalibrierung der tatsächlichen Limit-Gewichtung gegen die Rohtoken-Zahlen (braucht /usage-Ausgabe; der OAuth-Endpoint ist für Claude nicht zugänglich, weil ~/.claude/.credentials.json hart blockiert ist).

---

Messmethodik (reproduzierbar)

Datenquelle: C:\Users\mika.kuns\.claude\projects\**\*.jsonl, ein Record je Message, Verbrauch in message.usage.

raw = (u.get('input_tokens',0) + u.get('output_tokens',0)
       + u.get('cache_read_input_tokens',0) + u.get('cache_creation_input_tokens',0))

Kontextgröße einer Message = input_tokens + cache_read + cache_write (ohne Output). Der Verlauf über die Session zeigt Prefix-Sprünge.

Fallstricke

1. Scope-Filter. NICHT nach Pfadname claudedo filtern — das zieht interaktive Sessions im ClaudeDo-Repo mit rein und verfälscht den Split massiv (53 % statt korrekt 18,4 %). Agent-Runs erkennt man an claudedo-worktrees oder sandbox im Projektordner, so wie es TranscriptUsageReader macht.
2. <synthetic>-Messages überspringen — keine echten API-Calls.
3. task_runs.tokens_in ist unbrauchbar — liest nur input_tokens, also den uncached Rest. Lag bei einer 79-Mio-Token-Session bei 200 (Faktor ~400.000). tokens_out zusätzlich 3,8× zu niedrig. Siehe Task 38394081.
4. In Bash absolute Pfade verwenden — $HOME/~ zeigt auf dieser Maschine auf das P:-Laufwerk, nicht auf C:\Users\mika.kuns.
5. DB nie direkt lesen während die App läuft — Kopie ziehen (todo.db + todo.db-wal).
6. Grundrate prüfen, bevor ein Hebel empfohlen wird. Ein teurer Einzelfall ist kein Muster (siehe Skill-Trigger oben).

---

Abgeleitete Tasks (Liste „Claude do")

Empfohlene Reihenfolge:

#	ID	Titel
1	1b599d67	Prompt-Dateien frieren Default ein — SuggestImprovement/AskUser tot
2	38394081	Limit-Verbrauch pro Run sichtbar machen (Cache-Token in task_runs)
3	0d0aa8b0	Read-Disziplin + Explorer-Subagent im System-Prompt
4	2de2f008	max_turns deckeln (Ceiling, Defaults, UI-Warnung)
5	87105f5e	UsageGate: Parallelität stufenweise drosseln

(1) zuerst, weil es ein echter Funktionsbug ist und Voraussetzung dafür, dass (3) den Nutzer überhaupt erreicht. (2) als Nächstes, weil ohne korrektes Accounting nichts messbar ist.

Ist-Zustand zum Zeitpunkt der Analyse

• app_settings: default_model = sonnet, default_max_turns = 100, max_parallel_executions = 3, model_presets = null (fällt auf Defaults zurück: haiku 20 / sonnet 30 / opus 40 / fable 25 — greifen faktisch nie).
• 15 Tasks überschreiben max_turns nach oben: 10× auf 100, 5× auf 200.
• UsageGate existiert bereits: 5h @ 80 %, 7d @ 90 % (Migration 20260805074906_AddUsageGateAndRunModel, dieselbe Migration hat auch die model-Spalte auf task_runs gebracht).
• ~/.todo-app/prompts/system.md stammt vom 2026-06-04 und weicht vom SystemDefault in PromptFiles.cs ab; agent.md und planning.md dort sind verwaiste Reste eines alten Namensschemas.