Forschungsdokument
Ein systematischer Ansatz zur Erstellung von Bildungsdokumentationen durch gestufte Recherche.
Zweck
Erstellt tiefgehende erklärende Dokumente, die:
- Das Verständnis von den Grundlagen bis zu den Details aufbauen
- Progressive Wissensvermittlung nutzen, um den Leser zu führen
- Vollständige Quellenangaben für alle Informationen liefern
- Visuelle Zusammenfassungen und Tabellen für dichte Informationen verwenden
Wann verwenden
- Der Benutzer fragt nach umfassenden Erklärungen von Systemen oder Funktionen
- Es muss dokumentiert werden, wie Komponenten Ende-zu-Ende funktionieren
- Erstellung von Bildungsinhalten über Architektur oder Prozesse
- Fragen wie „Erkläre, wie X funktioniert“ oder „Was ist der Y-Prozess?“
Für schnelle Faktenabfragen stattdessen fact-find verwenden.
Forschungsmodell: Scout → Decompose → Research → Assemble → Verify
Die Recherche erfolgt in Stufen, nicht auf einmal. Alle Artefakte werden im Dateisystem abgelegt.
┌─────────────────────────────────────────────────────────────────┐
│ GESTUFTES FORSCHUNGSMODELL │
└─────────────────────────────────────────────────────────────────┘
STUFE 0: SCOUT STUFE 1: GEZIELTE RECHERCHE
───────────────── ────────────────────────
┌─────────────┐ ┌─────────────┐
│ Ursprüng- │ │ Unterfrage │──▶ Zitierte Antwort
│ liche Frage│ │ (fact-find) │ (kurz)
└──────┬──────┘ └─────────────┘
│ ┌─────────────┐
▼ │ Unterfrage │──▶ Zitierte Antwort
┌─────────────┐ Zerlegung │ (fact-find) │ (kurz)
│ Scout │────────────────▶ └─────────────┘
│ Suche │ ┌─────────────┐
└──────┬──────┘ │ Unterfrage │──▶ REKURSION
│ │ (research) │ (eigener Scout/Zerlegung)
▼ └─────────────┘
┌─────────────┐ │
│ Schreiben │ ▼
│ nach: │ ┌─────────────┐
│ planning/ │ │ Zusammenbau │──▶ Entwurfsdokument
│ <slug>/ │ │ aus Dateien │
│ 00-scout.md │ └──────┬──────┘
└─────────────┘ │
▼
┌─────────────┐
│ Überprüfung │──▶ Endgültiges Dokument
│ Zitate │
└─────────────┘
Warum das funktioniert:
- Agenten haben Schwierigkeiten, Unsicherheiten während der Aufgabe zuzugeben. Durch das Scouts werden Lücken zuerst identifiziert, bevor der Druck entsteht, Ergebnisse zu liefern.
- Das Schreiben ins Dateisystem ermöglicht die Zusammenarbeit zwischen Agenten (oder Kontextfenster-Resets für Einzelagentensysteme).
- Die Klassifizierung von Unterfragen verhindert, dass „zu große“ Fragen oberflächlich behandelt werden.
- Die Überprüfung fängt halluzinierte oder unbelegte Behauptungen ab, bevor sie finalisiert werden.
Einrichtung des Arbeitsbereichs
Alle Forschungsartefakte gehen nach ./planning/<fragen-slug>/:
./planning/
└── wie-twoliter-kits-baut/
├── 00-scout.md # Scout-Ergebnisse + Unterfragen
├── 01-kit-struktur.md # Antwort auf Unterfrage (fact-find)
├── 02-build-befehl.md # Antwort auf Unterfrage (fact-find)
├── 03-buildsys/ # Unterfrage, die Rekursion benötigte
│ ├── 00-scout.md
│ ├── 01-spezifikations-parsen.md
│ └── 02-docker-build.md
└── FINAL.md # Zusammengebautes Dokument
Slug-Format: Kleinbuchstaben, Bindestriche, beschreibend (z. B. wie-twoliter-kits-baut)
Für Mult-Agenten-Systeme
- Leitagent: Startet Scout, liest Scout-Ausgabe, zerlegt, baut zusammen, koordiniert Überprüfung
- Scout-Unteragent: Führt Phase 1 durch (sucht, überfliegt Ergebnisse, schreibt
00-scout.md) - Forschungs-Unteragenten: Jede Unterfrage wird zu einer Aufgabe; der Unteragent schreibt die Antwort in den Arbeitsbereich
- Prüfer: Leichte Agenten, die Zitate überprüfen (keine Werkzeuge nötig)
- Unteragenten können rekursiv starten, wenn ihre Frage zu groß ist (bis zu einer Tiefenbeschränkung)
Warum Scouts delegieren: Der Kontext des Leitagenten ist wertvoll. Rohe Suchergebnisse und Dateiinhalte aus dem Scout würden ihn verschmutzen. Der Scout schreibt strukturierte Ergebnisse in 00-scout.md; der Leitagent liest nur diese Datei.
Plan/Aufgabenliste-Disziplin
Wenn Sie eine Aufgabenlistenfunktionalität haben, nutzen Sie sie, um die Fertigstellung des Arbeitsablaufs zu erzwingen:
Vor jeder Phase die Arbeit in Ihrem Plan auflisten:
- Phase 2: Ein Eintrag pro Unterfrage aus dem Scout, mit Ziel-Dateinamen
- Schreibe 01-kit-struktur.md (Unterfrage 1)
- Schreibe 02-build-befehl.md (Unterfrage 2)
- ...
- Phase 4: Ein Eintrag pro zu überprüfendem Zitat
Das Muster: Auflisten → Ausführen → Übereinstimmung der Anzahl bestätigen
Dies verhindert, dass „einige“ statt „alle“ erledigt werden. Der Plan ist ein Vertrag – sobald Sie „Schreibe 01-kit-struktur.md“ geschrieben haben, sind Sie verpflichtet, diese Datei zu erstellen.
⛔ Anti-Pattern: Antworten während des Scouts sammeln und dann direkt zu FINAL.md springen. Selbst wenn Sie die Antworten „kennen“, schreiben Sie die einzelnen Dateien. Sie sind die durchsuchbaren Artefakte.
Für Einzelagentensysteme
Führen Sie die Stufen nacheinander aus und verwenden Sie das Dateisystem als Ihr „Gedächtnis“:
- Scouten und
00-scout.mdschreiben - Jede Unterfrage recherchieren und
01-*.md,02-*.mdusw. schreiben - Alle Dateien zurücklesen und
FINAL.mdzusammenbauen - Selbstüberprüfung der Zitate (weniger zuverlässig, aber immer noch wertvoll)
Dies ermöglicht Kontextfenster-Resets zwischen den Phasen, falls nötig.
Vorgehensweise
Phase 1: Scout (Die Form kennenlernen)
Ziel: Herausfinden, was existiert, und die richtigen Fragen formulieren. Ergebnisse in 00-scout.md schreiben.
⚠️ Scouts ist KEINE Recherche. Sie kartieren das Gebiet, nicht erkunden es.
mkdir -p ./planning/<fragen-slug>
# Breite Suche, um relevante Bereiche zu finden
crumbly search "systemname-übersicht"
crumbly search "systemname-architektur"
2-3 Top-Ergebnisse auf Struktur überfliegen, nicht auf Inhalt:
- Dateinamen und Abschnittsüberschriften notieren
- Schlüsselbegriffe und Komponentennamen identifizieren
- Finden, wo detaillierte Informationen zu finden sind
- KEINE Implementierungsdetails lesen oder versuchen zu verstehen, „wie es funktioniert“
Scout-Ausgabe sollte enthalten:
- Namen von Dingen (Dateien, Funktionen, Konzepte)
- Wo nach Antworten gesucht werden kann
- Zu stellende Fragen
Scout-Ausgabe sollte NICHT enthalten:
- Antworten auf die Fragen
- Implementierungsdetails
- Codeausschnitte oder tiefgehende Erklärungen
Wenn Sie das Scouts beenden und das Gefühl haben, „die Antwort zu kennen“, haben Sie zu tief gescoutet. Das Ziel ist informierte Ignoranz – zu wissen, was man nicht weiß und wo man es finden kann.
Erfassen in 00-scout.md:
# Scout: <Ursprüngliche Frage>
## Entdeckte Schlüsselkonzepte
- [Konzept 1]: [Kurzbeschreibung]
- [Konzept 2]: [Kurzbeschreibung]
## Gefundene relevante Dateien
- `pfad/zu/datei.md` - [Was sie abdeckt]
- `pfad/zu/code.rs` - [Was sie abdeckt]
## Terminologie
- [Begriff]: [Definition, wie in dieser Codebasis verwendet]
## Unterfragen
### 1. [Text der Unterfrage]
- **Typ:** fact-find | deep-research
- **Warum:** [Grund für diese Klassifizierung]
- **Schlüsseldateien:** [Dateien, die diese Frage wahrscheinlich beantworten]
### 2. [Text der Unterfrage]
...
Klassifizierung von Unterfragen:
| Wenn die Unterfrage... | Typ | Aktion |
|---|---|---|
| Eine konkrete, spezifische Antwort hat | fact-find | In 1-2 Absätzen antworten |
| Fragt „Was ist X“ oder „Wo ist Y“ | fact-find | In 1-2 Absätzen antworten |
| Fragt „Wie funktioniert X“ | deep-research | Rekursion (eigener Scout/Zerlegung) |
| Mehrere interagierende Komponenten umfasst | deep-research | Rekursion |
| 3+ Quelldateien zur Beantwortung benötigt würde | deep-research | Rekursion |
Rekursionsprüfung: Wenn mehr als 2 Unterfragen vom Typ deep-research sind, überlegen Sie, ob die ursprüngliche Frage zu breit ist.
Tiefenbeschränkung: Maximale Rekursionstiefe ist 2 Ebenen. Wenn eine Unter-Unterfrage eine eigene Rekursion benötigen würde, entweder:
- Zwingen Sie sie zu einer fact-find-Behandlung (akzeptieren Sie weniger Tiefe)
- Markieren Sie sie zur Überprüfung durch einen Menschen
- Teilen Sie die ursprüngliche Frage in mehrere Forschungsaufgaben auf
Phase 2: Unterfragen recherchieren
Für jede Unterfrage in NN-<slug>.md schreiben:
Für fact-find-Unterfragen:
# <Unterfrage>
<Direkte Antwort mit Inline-Zitaten>
Das Kit-Verzeichnis muss eine `Twoliter.toml`-Datei <sup>[1]</sup> und eine `Cargo.toml` enthalten,
die Pakete als Abhängigkeiten aufführt <sup>[2]</sup>.
## Quellen
<sup>[1]</sup> [`twoliter/README.md`](../twoliter/README.md) - Abschnitt zu Kit-Anforderungen
<sup>[2]</sup> [`kits/bottlerocket-core-kit/Cargo.toml`](../kits/bottlerocket-core-kit/Cargo.toml) - Beispiel-Kit-Manifest
Für deep-research-Unterfragen:
Ein Unterverzeichnis erstellen und rekursiv vorgehen:
./planning/wie-twoliter-kits-baut/03-buildsys/
├── 00-scout.md
├── 01-....md
└── FINAL.md
Die FINAL.md der Unterfrage wird zur Antwort.
Wenn Sie aus den Quellen nicht antworten können:
- Schreiben Sie „Konnte aus verfügbaren Quellen nicht ermittelt werden“
- Notieren Sie, wonach Sie gesucht haben
- Raten Sie NICHT
Phase 2 Abschlusstor (ERFORDERLICH)
⚠️ STOP: Fahren Sie erst mit Phase 3 fort, wenn dieses Tor passiert ist.
Vor dem Zusammenbau von FINAL.md MÜSSEN Sie:
-
Die Arbeitsbereichsdateien auflisten:
ls -la ./planning/<fragen-slug>/ -
Überprüfen, ob die Dateianzahl mit der Anzahl der Unterfragen übereinstimmt:
- Anzahl der Unterfragen in
00-scout.md: N - Anzahl der
NN-*.md-Dateien (ohne 00-scout.md): sollte N sein - Wenn die Anzahl nicht übereinstimmt, haben Sie Unterfragen übersprungen. Gehen Sie zurück.
- Anzahl der Unterfragen in
-
Zu Ihrem Plan/Ihrer Aufgabenliste hinzufügen:
- Bestätigen, dass N Unterfragen-Dateien geschrieben wurden
- Dateien auflisten: 01-X.md ✓, 02-Y.md ✓, ...
Warum das wichtig ist: Die Unterfragen-Dateien sind das primäre Arbeitsergebnis. FINAL.md ist nur eine Synthese. Ohne einzelne Q&A-Dateien:
- Die Recherche ist für zukünftige Abfragen nicht durchsuchbar
- Sie können nicht jede Antwort unabhängig überprüfen
- Der Dokumentenschreiber kann sie nicht als Quellmaterial verwenden
Häufiges Fehlermuster: Alle Informationen während des Scouts sammeln, dann direkt zu FINAL.md springen, weil „ich die Antworten bereits kenne“. Dies macht den Zweck zunichte – schreiben Sie die Dateien trotzdem.
Phase 3: Entwurfsdokument zusammenbauen
Alle Antworten auf Unterfragen aus dem Arbeitsbereich lesen. In FINAL.md kombinieren:
# [Systemname]
**Schlüsselwörter:** Schlüsselwort1, Schlüsselwort2, Schlüsselwort3
## Übersicht
[Visuelle Zusammenfassung - Diagramm oder Tabelle, die das gesamte System zeigt]
[1-2 Sätze Kontext]
## Wie [zugrunde liegendes Modell] funktioniert
[Synthese aus Antworten auf Unterfragen zu Grundlagen]
## [Hauptthema]
[Synthese aus Antworten auf Unterfragen zum Kernprozess]
### [Unterthema]
**Ziel:** [Ein Satz]
[Inhalt mit aus den Unterfragen übernommenen Zitaten]
## Anhang: [Detaillierte Referenz]
[Dichte Details, Tabellen, Konfigurationsoptionen]
## Konflikte und Lösungen
[Wenn Quellen uneins waren, dokumentieren Sie, wie Sie es gelöst haben]
- [Thema]: Quelle A sagte X, Quelle B sagte Y. Lösung: [Begründung]
(Schreiben Sie „Keine“, wenn keine Konflikte gefunden wurden)
## Quellen
[Konsolidierte, nummerierte Zitate aus allen Unterfragen]
Schreibrichtlinien
Abschnitt Übersicht:
- Mit einer Visualisierung beginnen (ASCII-Diagramm, Flussdiagramm oder Zusammenfassungstabelle)
- Maximum 2-3 Sätze Prosa nach der Visualisierung
- Der Leser sollte das gesamte System in 10 Sekunden erfassen
Tabellen vs. Prosa:
- Wenn 3+ ähnliche Elemente aufgelistet werden → eine Tabelle verwenden
- Prosa erklärt Beziehungen; Tabellen listen Fakten auf
Zitate:
<sup>[1]</sup>inline mit Fakten verwenden- Jede faktische Behauptung benötigt ein Zitat
- Quellen am Ende konsolidieren
- Beim Zusammenbau Zitate fortlaufend neu nummerieren
Lange Dokumente (Ausgabetoken-Limits):
Claude hat Ausgabelimits (~4K-8K Token pro Antwort). Für Dokumente länger als ~10 Seiten:
- Abschnitt für Abschnitt schreiben, an FINAL.md anhängen
- Oder: zuerst eine detaillierte Gliederung erstellen, dann jeden Abschnitt separat erweitern
- Versuchen Sie nicht, das gesamte Dokument in einer Antwort zu generieren
Phase 4: Überprüfen
Ziel: Bestätigen, dass Zitate ihre Behauptungen stützen. Unbelegte Aussagen erkennen.
Schritt 1: Zitate auflisten (ERFORDERLICH)
Bevor Sie Prüfer starten, MÜSSEN Sie alle Zitate in Ihrem Plan/Ihrer Aufgabenliste auflisten:
- Zitate in FINAL.md zählen (z. B. 12 Zitate)
- Ein Planelement pro Zitat hinzufügen:
- Überprüfe [1]: „Vorschau des Anspruchstexts...“
- Überprüfe [2]: „Vorschau des Anspruchstexts...“
- ... (alle 12)
- Letztes Element hinzufügen: „Bestätige 12/12 Prüfer abgeschlossen“
Fahren Sie NICHT mit dem Start fort, bis Ihr Plan N+1 Elemente hat (N Zitate + Bestätigung).
Dies verhindert das Fehlermuster, „einige repräsentative Zitate zu überprüfen“ anstatt alle.
Schritt 2: Prüfer starten
Für Multi-Agenten-Systeme:
Leichte Prüfer mit vorab geladenem Kontext starten. Jeder Prüfer benötigt KEINE Werkzeuge – nur Argumentation.
Zitierungspr�fer (einen pro Zitat starten):
Prompt:
Sie sind ein skeptischer Gutachter. Ihre Aufgabe ist es, Probleme zu finden, nicht die Richtigkeit zu bestätigen.
BEHAUPTUNG: „Der Build-Prozess beginnt mit dem Laden von Twoliter.toml“
ZITIERTE QUELLE: twoliter/twoliter/src/project/mod.rs
QUELLINHALT:
[Fügen Sie relevante Zeilen aus der Datei ein]
Unterstützt der Quellinhalt TATSÄCHLICH diese spezifische Behauptung?
Antworten Sie mit einem von:
- UNTERSTÜTZT: [kurze Erklärung, was in der Quelle dies bestätigt]
- NICHT UNTERSTÜTZT: [was fehlt oder falsch ist]
- TEILWEISE: [was bestätigt wurde vs. was nicht]
Seien Sie skeptisch. Wenn die Quelle tangential verwandt ist, aber die Behauptung
nicht direkt aussagt, ist das TEILWEISE oder NICHT UNTERSTÜTZT.
Detektor für unbelegte Behauptungen (einmal pro Dokumentabschnitt starten):
Prompt:
Sie sind ein skeptischer Gutachter. Ihre Aufgabe ist es, Probleme zu finden.
ABSCHNITT:
[Abschnittstext einfügen]
Finden Sie faktische Behauptungen, denen ein <sup>[N]</sup>-Zitat fehlt.
Faktische Behauptungen umfassen: Dateipfade, Verhaltensbeschreibungen,
Konfigurationswerte, Komponentennamen, Prozessschritte.
Meinungen, Übergänge und Zusammenfassungen benötigen keine Zitate.
Listen Sie jede von Ihnen gefundene unbelegte Behauptung auf. Sagen Sie NICHT
„sieht gut aus“ oder „keine gefunden“, es sei denn, Sie haben jeden Satz überprüft.
Wenn Sie nichts finden, erklären Sie, was Sie überprüft haben, um zu bestätigen,
dass es keine unbelegten Behauptungen gibt.
Diese bündeln: Verwenden Sie spawn_batch, um alle Zitierungsprüfer parallel auszuführen. Die Batch-Größe MUSS der Anzahl der Zitate entsprechen.
...
[truncated for translation]