docs(findings): spec the .claudedo findings store
This commit is contained in:
mika kuns
@@ -0,0 +1,262 @@
|
||||
# Findings-Store — Design
|
||||
|
||||
Stand: 2026-08-10.
|
||||
|
||||
Persistenter, projektgebundener Speicher für **Fallen und Invarianten**, den Agents im
|
||||
Moment des Schmerzes selbst befüllen und in späteren Sessions vor dem Erkunden lesen.
|
||||
Ziel ist Token-Ersparnis durch verhinderte Fehlläufe.
|
||||
|
||||
---
|
||||
|
||||
## 1. Ausgangslage
|
||||
|
||||
Auslöser war die Frage, ob ein Code-Knowledge-Graph (Graphify-Bauart) das
|
||||
Wiedererkunden in jeder Session einspart. Die Messung sagt: nein, nicht in dieser Form.
|
||||
|
||||
### Die Zahlen (aus `docs/usage-optimization.md`, 2026-08-05)
|
||||
|
||||
- Kontext-Resend = **99,3 %** des Rohverbrauchs. Jeder Kontext-Token wird im Schnitt
|
||||
**~425× nachberechnet**. Das gilt symmetrisch: für gespartes *und* für geladenes Wissen.
|
||||
- **Explore-note ersetzt Exploration:** Note 4,6k tok in Turn 5 eines 60-Turn-Runs
|
||||
→ 4,6k × 55 ≈ **250k**. Ersparte Exploration (~8k tok Findings ab Turn 10) ≈ **400k**.
|
||||
Netto ~150k, Faktor 1,6. Wird die Note geladen, ohne gebraucht zu werden: **−250k**.
|
||||
- **Ein verhinderter Retry:** ~11 Mio Token. **27 % der Tasks brauchten einen Retry.**
|
||||
|
||||
Faktor 27 zwischen den beiden Klassen. Deshalb ist der Inhalt dieses Stores **nicht**
|
||||
„Architektur-Map, damit ich nicht neu erkunden muss" (400k-Klasse), sondern „Agent läuft
|
||||
in die bekannte Falle und der Run ist Müll" (11-Mio-Klasse).
|
||||
|
||||
### Was heute schon da ist
|
||||
|
||||
| Ebene | Größe | Ladeverhalten |
|
||||
|---|---:|---|
|
||||
| `CLAUDE.md` (root) | 6,4 KB ≈ 1,6k tok | immer |
|
||||
| `src/*/CLAUDE.md` (6×) | 1,5–14 KB | beim Arbeiten im Verzeichnis |
|
||||
| `docs/explore-notes/` (6 Notes) | 11–18 KB, 92 KB gesamt | on demand, **ganze Datei** |
|
||||
| Auto-Memory (`~/.claude/projects/.../memory/`) | 55 Dateien, 397 KB | Index immer (nur interaktiv) |
|
||||
|
||||
Die Sektionen der Notes sind bereits 12–36 Zeilen (~150–450 tok) — also schon
|
||||
knotengroß. Und `conpty-sessions.md` markiert Fallen bereits konventionell als
|
||||
`## ⚠️ Gotcha: …` (5 Stück). Die anderen Notes tragen dieselbe Art Wissen unmarkiert im
|
||||
Fließtext. **Das Wissen ist zu großen Teilen schon geschrieben, nur nicht einsammelbar.**
|
||||
|
||||
---
|
||||
|
||||
## 2. Verworfene Alternativen
|
||||
|
||||
- **Code-Knowledge-Graph (Graphify o. ä.).** Ein tree-sitter-Graph liefert Call-Kanten —
|
||||
genau die Klasse, die Grep exakt und billig liefert (Grep = 5–8 % des Kontexts; Read =
|
||||
60–68 %, das Problem ist zu viel *lesen*, nicht Finden). Der wertvolle Inhalt ist
|
||||
semantisch und nicht ableitbar („Approve = merge the whole unit", „no directory arg may
|
||||
end in a separator"). Dazu: Build-/Staleness-Pipeline über N parallele Worktrees und
|
||||
Merge-Konflikte auf einem Graph-Artefakt im Repo. AXAML wird ohnehin nicht geparst.
|
||||
- **DB-Tabelle + UI-Editor.** Kuration passiert in VSCode, damit entfällt der einzige
|
||||
Vorteil. Agent-Zugriff bräuchte ein Lese-Tool statt `Read`; Agents könnten veraltete
|
||||
Einträge nicht selbst korrigieren.
|
||||
- **Hook-Injektion der Findings in den System-Prompt.** Früh und groß in den Prefix ist
|
||||
das teuerste Muster überhaupt (Befund 5), auch wenn nichts davon gebraucht wird.
|
||||
- **Post-Merge-Trigger.** Ursprünglicher Entwurf. Hinfällig, weil der Aufrufer des Tools
|
||||
den Kontext bereits hat — siehe §4.
|
||||
- **Retro-Distill aus alten Transkripten.** Zurückgestellt, siehe §8.
|
||||
|
||||
---
|
||||
|
||||
## 3. Speicher
|
||||
|
||||
```
|
||||
<working-dir>/.claudedo/
|
||||
INDEX.md # eine Zeile je Finding — die einzige Datei, die immer gelesen wird
|
||||
traps/<slug>.md # ein Finding je Datei, ~150–300 tok
|
||||
```
|
||||
|
||||
`maps/` ist reserviert, aber **nicht Teil von v1**.
|
||||
|
||||
Ordner liegt im Repo-Root, das er beschreibt — maximale Erkennbarkeit, reist bei
|
||||
Bedarf mit. `.claudedo` ist als Name frei; die Worktrees liegen unter dem *Geschwister*-Pfad
|
||||
`.claudedo-worktrees`, und `TranscriptUsageReader` prüft auf das exakte Segment, also kein
|
||||
Fehlalarm bei der Scope-Erkennung.
|
||||
|
||||
### Finding-Format
|
||||
|
||||
```markdown
|
||||
---
|
||||
slug: conpty-arg-quoting
|
||||
scope: src/ClaudeDo.Worker/Planning
|
||||
source-task: 5d627df8
|
||||
verified-against: e10634b
|
||||
---
|
||||
|
||||
# Ein Verzeichnis-Argument, das auf `\` endet, frisst alle folgenden Argumente
|
||||
|
||||
<2–6 Sätze: was passiert, warum es nicht danach aussieht, was man stattdessen tut.>
|
||||
```
|
||||
|
||||
### INDEX.md
|
||||
|
||||
```markdown
|
||||
# Findings
|
||||
|
||||
- [conpty-arg-quoting](traps/conpty-arg-quoting.md) — Dir-Arg auf `\` escapet sein eigenes Quote
|
||||
- [shared-worktree-partial-commit](traps/shared-worktree-partial-commit.md) — nie blank committen
|
||||
```
|
||||
|
||||
Reine Routing-Ebene: Titel + einzeiliger Aufhänger + Pfad. Ablauf im Agenten:
|
||||
Index lesen (~700 tok) → ein bis zwei Findings lesen (~400 tok), statt 4 600 für eine
|
||||
ganze Note.
|
||||
|
||||
### Einchecken oder nicht — Toggle je Liste
|
||||
|
||||
Beim Anlegen einer Liste: **„`.claudedo` einchecken"**, Default **aus**.
|
||||
|
||||
- **Aus** → `/.claudedo/` wird nach `.git/info/exclude` geschrieben (per-Clone,
|
||||
unsichtbar fürs Repo, **keine getrackte Datei angefasst**). Mechanik existiert bereits in
|
||||
`SessionSkillSeeder.AppendExcludeLineAsync` (auflösen über
|
||||
`git rev-parse --git-path info/exclude`) — wiederverwenden, nicht neu bauen.
|
||||
- **An** → nichts tun, der Nutzer commitet den Ordner selbst.
|
||||
|
||||
### Worktree-Regeln (hart)
|
||||
|
||||
- **Geschrieben wird ausschließlich im Haupt-Checkout, nie in einem Worktree.** Sonst
|
||||
entstehen `INDEX.md`-Merge-Konflikte über parallele Tasks — exakt das Problem, das oben
|
||||
gegen den Graph-Ansatz spricht.
|
||||
- **Gelesen wird über den absoluten Pfad auf den Haupt-Checkout.** Eine Regel für beide
|
||||
Toggle-Stellungen; in „aus" existiert der Ordner im Worktree ohnehin nicht.
|
||||
- Falls der Store getrackt ist und der Distiller committet: pfad-skopiert
|
||||
(`git commit -- .claudedo`), nie blank — der Haupt-Checkout wird von parallelen
|
||||
Sessions geteilt.
|
||||
- Ein Finding je Datei heißt: parallele Schreiber kollidieren nicht. Umkämpft ist nur
|
||||
`INDEX.md`; das Tool serialisiert dessen Rewrite prozessintern.
|
||||
|
||||
---
|
||||
|
||||
## 4. Schreibweg — ein MCP-Tool
|
||||
|
||||
`save_finding(slug, title, body, scope = "", list = "")` am bestehenden `claudedo`-MCP-Server.
|
||||
|
||||
Signatur folgt den zwei test-erzwungenen Konventionen des Servers: jeder optionale
|
||||
Parameter hat einen C#-Defaultwert, und das Tool gibt kein blankes `Task` und keine
|
||||
nullable Payload zurück (→ `docs/explore-notes/external-mcp.md`). Beschreibungsstil nach
|
||||
`External/McpToolDocs.cs`.
|
||||
|
||||
### Welcher Store wird beschrieben?
|
||||
|
||||
Der MCP-Server ist global, der Store projektgebunden — die Zuordnung muss explizit sein:
|
||||
|
||||
1. **Autonomer Run:** aus dem Aufrufkontext (`TaskRunMcpContext`) → Task → Liste →
|
||||
`working_dir`. Der `list`-Parameter wird ignoriert.
|
||||
2. **Interaktive Session ohne Task-Kontext:** `list` (Name oder Id) entscheidet. Fehlt er
|
||||
und es existiert **genau eine** Liste, wird diese genommen; bei mehreren gibt das Tool
|
||||
einen Fehler zurück, der die verfügbaren Listen nennt. Nie raten.
|
||||
|
||||
Geschrieben wird immer in `<list.working_dir>/.claudedo/` — also den Haupt-Checkout,
|
||||
auch wenn der Aufrufer in einem Worktree läuft.
|
||||
|
||||
Bewusst ein **dummes Schreib-Tool**, kein „generiere mir Findings"-Tool: der Aufrufer hat
|
||||
den Kontext bereits. Ein zweiter Claude-Lauf (RefineRunner-Bauart) würde ihn aus
|
||||
Transkripten rekonstruieren — teurer und schlechter.
|
||||
|
||||
**Genau ein Tool.** Gelesen wird mit `Read` auf die Dateien; das kostet nichts und braucht
|
||||
kein Tool. Der Server exponiert bereits ~60 Tools, eines mehr ist im Prefix Rauschen —
|
||||
fünf wären es nicht.
|
||||
|
||||
**Verhalten:**
|
||||
- Gleicher `slug` → **überschreiben**, nicht anlegen. Dedupe gehört ins Tool, nicht in die
|
||||
Prompt-Disziplin.
|
||||
- Schreibt `traps/<slug>.md` **und** aktualisiert die Zeile in `INDEX.md` atomar.
|
||||
- `verified-against` wird vom Tool aus dem aktuellen HEAD des Haupt-Checkouts gesetzt,
|
||||
nicht vom Aufrufer.
|
||||
- `source-task` wird aus dem Aufrufkontext gesetzt, wenn vorhanden (autonome Runs),
|
||||
sonst leer (interaktive Sessions).
|
||||
|
||||
### Aufrufwege
|
||||
|
||||
1. **Im Run.** Ein Task-Agent tritt in eine Falle und hält sie fest. Höchste Qualität —
|
||||
er hat gerade Turns dafür verbrannt. Billigster Weg, kein zusätzlicher Prozess.
|
||||
2. **Merge-Helper-Abschlussphase.** Der List-Handler sweept am Ende nach, was ihm über den
|
||||
Batch hinweg auffiel. Er sieht Diffs, nicht das Straucheln — daher Ergänzung zu (1),
|
||||
kein Ersatz.
|
||||
3. **Interaktive Sessions.** Der `claudedo`-MCP ist global registriert, das Tool steht
|
||||
dort ohne Weiteres zur Verfügung.
|
||||
4. **VSCode.** Nutzer korrigiert und löscht direkt in den Dateien.
|
||||
|
||||
### Aufnahmehürde
|
||||
|
||||
Ein Finding ist nur, was **dauerhaft**, **nicht offensichtlich** und **verhaltensändernd**
|
||||
ist: „X sieht aus wie Y, ist aber Z — mach stattdessen W". Ein gefixter Bug ist **kein**
|
||||
Finding, das ist Git-Historie.
|
||||
|
||||
Diese Hürde steht in der Tool-Beschreibung. Sie ist kein Stilhinweis, sondern die
|
||||
Betriebsbedingung: `INDEX.md` wird immer gelesen; bei ~15 tok je Zeile sind 50 Findings
|
||||
≈ 750 tok, 300 Findings ≈ 4 500 tok — ab da kostet der Index so viel wie früher eine ganze
|
||||
Note und die Ersparnis ist weg. Deshalb zusätzlich eine **Warnschwelle bei 80 Einträgen**,
|
||||
die das Tool im Ergebnis zurückmeldet.
|
||||
|
||||
---
|
||||
|
||||
## 5. Leseweg
|
||||
|
||||
ClaudeDo hängt einen Satz an den System-Prompt seiner eigenen Runs
|
||||
(`--append-system-prompt`, wie heute schon für andere Zwecke genutzt):
|
||||
|
||||
> Findings-Index für dieses Projekt: `<abs>/.claudedo/INDEX.md`. Lies ihn, bevor du den
|
||||
> Code erkundest, und öffne nur die Findings, die zu deiner Aufgabe passen.
|
||||
|
||||
~30 Token, komplett in ClaudeDo gekapselt, **keine CLAUDE.md wird angefasst** — weder die
|
||||
des Projekts noch die globale.
|
||||
|
||||
Interaktive Sessions bekommen diesen Zeiger nicht (ClaudeDo startet sie nicht). Sie können
|
||||
schreiben, aber nicht automatisch lesen. Wer das will, setzt selbst eine Zeile in seine
|
||||
globale CLAUDE.md — außerhalb des Scopes dieses Features.
|
||||
|
||||
---
|
||||
|
||||
## 6. UI
|
||||
|
||||
Ein Button an der Liste: **„Findings öffnen"** → öffnet `<working-dir>/.claudedo/` im
|
||||
Datei-Explorer bzw. der Standardanwendung. **Kein In-App-Editor** — Kuration passiert in
|
||||
VSCode.
|
||||
|
||||
Dazu der Toggle aus §3 im Dialog „Liste anlegen" und in den Listen-Einstellungen.
|
||||
|
||||
---
|
||||
|
||||
## 7. Scope-Grenze (bewusst akzeptiert)
|
||||
|
||||
Die Kapselung in ClaudeDo deckelt den Lese-Nutzen auf den Agent-Anteil: laut Messung
|
||||
**18,4 %** des Verbrauchs (interaktiv = 81,6 %). Das ist kein Argument gegen das Feature —
|
||||
Retries passieren ausschließlich auf der Agent-Seite, und dort sitzt der 11-Mio-Hebel.
|
||||
Aber „Token-Ersparnis" heißt hier: Ersparnis in den 18 %, nicht auf dem Konto insgesamt.
|
||||
|
||||
---
|
||||
|
||||
## 8. Nicht in v1
|
||||
|
||||
- **`maps/`** — Subsystem-Maps. Ordner reserviert, Inhalt später. Die bestehenden
|
||||
`docs/explore-notes/` bleiben unangetastet.
|
||||
- **Retro-Distill aus Transkripten.** Erst interessant, wenn belegt ist, dass Findings
|
||||
überhaupt wirken. Rohmaterial bleibt verfügbar: vollständiges NDJSON je Run unter
|
||||
`~/.todo-app/logs/{taskId}_run{N}.ndjson`, `ResultMarkdown` in `task_runs`,
|
||||
`WorktreeEntity.BaseCommit/HeadCommit/MergeCommit` für den nachträglichen Diff.
|
||||
- **Ernte der bestehenden `⚠️ Gotcha:`-Sektionen** aus `docs/explore-notes/` in den Store.
|
||||
Naheliegender erster Füllstand, aber eine eigene, manuelle Aktion.
|
||||
- **Wirkungsmessung** (welches Finding wurde je gelesen, hat es einen Retry verhindert).
|
||||
Braucht ein eigenes Konzept; Dateien tragen keinen Zähler.
|
||||
- **Automatischer Staleness-Check** gegen `verified-against`. Frontmatter trägt den Commit,
|
||||
ausgewertet wird er in v1 nur vom Menschen.
|
||||
|
||||
---
|
||||
|
||||
## 9. Testbarkeit
|
||||
|
||||
- `save_finding`: Neuanlage, Überschreiben bei gleichem Slug, Index-Update, Slug-Validierung
|
||||
(kein Pfad-Escape), Warnschwelle bei 80 Einträgen, paralleler Index-Rewrite.
|
||||
- Store-Auflösung: Task-Kontext schlägt `list`; genau eine Liste ohne `list` → Treffer;
|
||||
mehrere Listen ohne `list` → Fehler statt Raten; Schreibziel ist der Haupt-Checkout,
|
||||
auch wenn der Aufrufer in einem Worktree sitzt.
|
||||
- Die beiden `external-mcp`-Konventionen (Default je optionalem Parameter, kein blankes
|
||||
`Task`/nullable Payload) sind test-erzwungen — die bestehenden Tests greifen automatisch.
|
||||
- Toggle: `.git/info/exclude`-Zeile wird genau einmal geschrieben (Idempotenz) — die
|
||||
bestehenden Tests zu `SessionSkillSeeder` sind die Vorlage.
|
||||
- Kein Test darf die echte `claude`-CLI starten.
|
||||
- `IWorkerClient` / `WorkerHub` / ViewModel-Konstruktoren ändern → handgeschriebene Fakes in
|
||||
**beiden** Testprojekten mitziehen.
|
||||
Reference in New Issue
Block a user