# 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`.

```python
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.
