ki-praxis/manuskript/kapitel-04-context-management-in-der-praxis.md

4. Context-Management in der Praxis

Kap. 3 hat begründet, warum Context die Qualität dominiert. Hier die vier Alltagsfragen: Wann neue Session? Wann Compact — und mit welchen Hints? Wie Handoff? Wie der Agent selbst mitträgt?

Kern: Context-Management ist keine Nebenbeschäftigung. Es ist der Steuerknüppel für Zuverlässigkeit, Kosten und Autonomie.

{width=90%}

Vorlagen zum Kopieren: templates/ / checklists/ (Buch-Repo; Begleit-Service) und Anhang A — Compaction-Hints, Handoff, Session-Start. Progress: templates/progress-template.md. Die Abschnitte erklären wann.

---

4.1 Frage 1: Wann neue Session starten?

Eine Session ist ein Context-Lebenszyklus: History, Tool-Spuren, implizite Annahmen. Neue Session heißt bewusstes Zurücksetzen — mit Handoff, nicht mit Amnesie.

Donnerstag, 11:40: Auth-Slice grün, Commit erledigt — und im selben Thread „noch schnell“ CSS-Polish. Zwanzig Minuten später sitzen Middleware-Nebenbedingungen in einem Spacing-Ticket. Die Trigger-Tabelle ist die Gegenprobe vor dem nächsten Prompt. Sessions als Trophäen („läuft seit drei Tagen“) sind der häufigste Fehler.

Neue Session, wenn die Arbeit eine natürliche Grenze hat oder der Context sie nicht mehr trägt:

Trigger	Begründung
Task-/Slice-Grenze erreicht	Sauberer Verify/Commit; nächster Slice braucht frischen Fokus
Themenwechsel	Auth-Bug → CSS-Polish vermischt Ziele und Dateien
Context-Rot spürbar	Symptome aus Kap. 3 trotz Compact
Hohe Auslastung + weiter wachsend	Kein sinnvoller Puffer mehr für Tool-Results
Fehlerspirale	>2–3 Fix-Zyklen ohne Annäherung an DoD. Erst Restore (4.2), sonst neue Session — nicht Compact über den Irrweg
Plan freigegeben, Execute soll „clean“ laufen	Explore-Rauschen nicht in den Implementierungs-Context
Personenwechsel / Pairing-Ende	Menschlicher Handoff = Agent-Handoff
Merge großer Fremdänderungen	HEAD hat sich unter dem alten Context weggedreht

Nicht jede Unsicherheit ist ein Reset-Grund. Ursache fast klar: fünf Zeilen Stand, dann Session oder Compact. Kurze Rückfrage? Im Thread. DoD in einem Befehl erreichbar? Verifizieren, committen, dann neu. Stand ohne Handoff nicht aus Repo rekonstruierbar: erst Handoff schreiben.

Ist das Ziel dasselbe und der Context noch „scharf“?
  ja → weiter (ggf. Compact)
  nein → Ist der Stand im Repo/Handoff rekonstruierbar?
            ja → neue Session
            nein → Handoff/Progress schreiben → neue Session

Anti-Patterns zu diesem Abschnitt: Kap. 19.5.

---

4.2 Frage 2: Wann Compact — und mit welchen Hints?

Explore fertig, drei Hypothesen widerlegt, als Nächstes Execute. Ohne Compact trägt der Implementierungs-Context den Irrweg mit — und der Agent „erinnert“ verworfene Pfade als Optionen. Compact vor Execute ist Hygiene, nicht Panik.

Compact (Summarize/Condense) verdichtet History verlustbehaftet: Details, Nuancen und oft die Spur von Irrwegen gehen verloren. Hygiene und Erste Hilfe — kein Freifahrtschein für Monatssessions.

UI-Name und Slash-Befehl variieren (/compact, Summarize, Condense o. Ä.) — der Job ist derselbe: History verdichten mit Erhaltungs-Hint. /compact … unten ist gängige Schreibweise, keine Produkt-Primärstellung.

Kern: Compact ist kein Zip. Es ist ein verlustbehafteter LLM-Summarizer-Pass: History raus, Summary rein. Der Hint steuert diesen Pass — nicht einen Harness-Algorithmus.

Typischer Ablauf (UI driftet): Ein Extra-LLM-Call schreibt die Summary; der Hint steuert genau diesen Call. Der Harness ersetzt ältere Turns durch den Text und lädt den Startup-Context (AGENTS.md, System-Prompt) neu, statt ihn mit-zusummarisieren. Dateien, die nur im Chat standen, sind danach oft weg. Gleichrangig (Stand des Buchs): Claude Code, Codex und Copilot CLI, alle mit /compact. Compact setzt weder Gespräch noch Working Tree zurück — das ist Restore.

Compact proaktiv, nicht erst wenn nichts mehr geht: ab spürbarem Rauschen oder wenn DoD/Nebenbedingungen wegrücken (Kap. 3); nach Explore, vor Execute; nach großem Tool-Dump, sobald die Lehre klar ist; in langen Executes nach jedem grünen Teil-Verify; wenn der Agent sich wiederholt oder Anweisungen „vergisst“.

Zu spät ist Compact bei Panik und extrem hoher Füllung. Auto-Compact ist derselbe Job zum schlechteren Zeitpunkt — deshalb lieber selbst, mit Hint. Eine Summary aus verrottetem Material konserviert die frühe Annahme (Kap. 3.12) — sauberer Exit: Handoff plus neue Session, nicht „noch ein Compact“.

Was ein guter Hint tut

Ohne Hint rät das Modell, was wichtig war. Mit Hint steuerst du Erhaltungsprioritäten: Ziele, DoD, Entscheidungen, Dateipfade, Fehlerursache, nächste Schritte, Verbote. Explizit nicht: Höflichkeit, komplette Logs, gescheiterte Patch-Texte (außer die Lehre).

Kern-Hints: Anhang A; vollständige Liste unter templates/compaction-hints.md. Fünf Patterns:

Allrounder:

/compact Wichtige Architektur-Entscheidungen, aktuelle TODOs, offene Tasks und begründete Verwürfe behalten; Tool-Logs und Datei-Dumps verwerfen

Feature-Execute:

/compact Fokus auf aktuelle Feature-Implementierung: Ziel, DoD, geänderte Dateien, Teststatus und nächste Schritte der letzten Turns behalten

Debug:

/compact Debug-Fokus: Reproduktionsschritte, Fehlermeldungen, bereits ausgeschlossene Ursachen und aktuelle Hypothese behalten; fehlgeschlagene Experiment-Details knapper fassen

Nach Plan-Freigabe (Execute-Phase):

/compact Genehmigten Plan und DoD behalten; Explore-Diskussion und Alternativen nur als Kurzentscheidungen; Execute-Fortschritt und Diff-relevante Dateien priorisieren

Notfall:

/compact Nur Ziel, DoD, Branch, kritische Dateipfade und den nächsten Schritt behalten

Nach dem Compact

Smoke-Check: Kann der Agent Ziel und DoD noch nennen? Fehlt etwas Kritisches, in den nächsten User-Turn oder ins Handoff (Ränder!). Dann weiterarbeiten — nicht sofort zehn Dateien dumpen. Compact schafft Platz; es füllt ihn nicht von allein sinnvoll.

Denselben Check härter, nach Compact und mittendrin, wenn der Thread weich wirkt: der Agent wiederholt Ziel, DoD und eine harte Invariante (Ausschluss, Pfadgrenze, „nicht anfassen“). Das ist Teach-back als Rot-Probe (Kap. 11) — nicht Alignment vor dem ersten Diff, sondern: überlebt die Spur die History? Fail: Compact hat sie verloren, oder Session-Müll überdeckt sie. Dann Hint nachlegen oder Handoff plus neue Session, nicht „noch ein Patch“. Ein Marker-String misst Rezitation. Ob die Invariante im Diff noch gilt, misst Session-Qualität: Der Agent sagt „legacy/** fasse ich nicht an“ — und der nächste Diff ändert genau dort eine Datei. Die Rezitation war grün, die Invariante tot. Gegenprobe: git diff --name-only gegen die Pfadgrenze im Hint.

Restore: zurückholen statt verdichten

Restore (Undo, Rewind, Checkpoint — UI driftet) setzt Gespräch und/oder Working Tree auf einen früheren Stand im selben Thread. Compact verdichtet vorwärts; Restore holt zurück. Die Git-History bleibt unberührt — das ist kein reset --hard (Kap. 7). Side Effects außerhalb der Dateien (Deploy, MCP-Write, DROP) kommen nicht mit (Kap. 18). Gleichrangig (Stand des Buchs): Claude Code /rewind; Cursor Checkpoints. Fehlt der Hebel, bleibt der portable Weg: dünner Slice, Commit, sonst Handoff und neue Session.

Die Wahl ist eine Weiche, keine Geschmacksfrage: Ziel und DoD gleich, aber der letzte Turn hat den Pfad verdorben → Restore. Steckt der Irrweg schon in Dateien und Commits → neue Session mit Handoff (4.3).

---

4.3 Frage 3: Handoff — essenzielle Informationen retten

Neue Session nach einem sauberen Compact — und der Agent rollt den Irrweg von gestern noch einmal auf. Der Stand lag nur im alten Thread. In der Praxis scheitert der Handoff selten an „keine Zeit“, sondern an „der Thread merkt sich das schon“.

Handoff ist die Brücke Session → Session (oder Mensch → Mensch). Er lebt als Datei im Repo, nicht nur im Chat — sonst ist er selbst Context-Risiko und nicht versionierbar.

Was rein muss:

Block	Zweck
Ziel / Outcome	Warum wir das tun
DoD (checkable)	Wann Schluss ist
Ausschlüsse / Verbote	Scope-Creep verhindern
Stand	Was bereits gilt (im Code!)
Commit-SHA (HEAD)	Frische prüfen: passt der Handoff zum Branch-Stand?
Entscheidungen + Begründung	Nicht erneut debattieren
Offene Punkte / Blocker	Ehrlich
Dateipfade + Befehle	Schneller Re-Entry
Nächste Schritte (nummeriert)	Sofort handlungsfähig
Kurzfazit	3–5 Sätze „Situationsbild“

Minimal, wenn Zeit brennt: Ziel · DoD-Commands · Stand · Commit-SHA · nächster Schritt · Nicht anfassen · Branch/Verify. Copy-Paste: Anhang A.1 · templates/handoff-template.md.

Progress (templates/progress-template.md) nach jedem Slice; das Handoff bei Task-Start anlegen und an der Session-Grenze finalisieren. Progress füttert das Handoff, ersetzt es nicht. Was überleben muss, gehört ins Repo — nicht in Turn 12.

Avoid	Besser
Roman ohne DoD	Eine Seite, harte Checks
Nur Chat-Summary ohne Dateipfade	Pfade + Befehle
Handoff erst am Session-Ende anlegen	Wenn Mehr-Session absehbar: bei Task-Start anlegen, an der Session-Grenze finalisieren
Handoff nach jedem Slice fortschreiben	Progress nach Slice; Handoff bleibt die Übergabe
Geheimnisse im Handoff	Referenz auf Secret-Store

Ohne Datei rettet Compact nur den laufenden Thread. Die nächste Session hat nichts, woran sie ansetzen kann.

Compact wechselt den UI-Namen, der Job bleibt (Kap. 4.2). Beim Wort Handoff ist es umgekehrt: derselbe Name, mehrere Jobs:

Was draußen oft „Handoff“ heißt	Mechanik	Im Buch
Stand retten, neue Session	wählen und in eine Datei schreiben	Handoff
History im laufenden Window kürzen	verlustbehaftet verdichten	Compact
Sub-Agent liefert an den Parent	kompakte Rückgabe im selben Task	Hand-back (Kap. 5.6)
Anderer Agent übernimmt das Gespräch	Routing / Delegation	Orchestrierung (Kap. 22) — nicht Handoff

Harnesses beschriften das uneinheitlich; Slash-Befehle driften. Gleichrangig (Stand des Buchs): Claude Code trennt /compact von der Datei plus neuer Session. Das OpenAI Agents SDK meint mit demselben Wort Agent-zu-Agent-Routing. Im Buch heißt nur die Datei Handoff.

Felder und Session-Start stehen hier. Warum das eine Memory-Übergabe ist: Kap. 6.5.

Session-Start mit Handoff

Nutze Anhang A · checklists/session-start-checkliste.md (Buch-Repo). Der erste Prompt braucht keine Novelle:

Lies HANDOFF.md und AGENTS.md. Prüfe HEAD gegen den Commit-SHA im Handoff.
Wiederhole kurz: Ziel, DoD, nächster Schritt.
Dann: kurzer Explore, Plan nur wenn nötig, dann Execute.

Wenn der Agent Ziel und DoD nicht sauber wiederholen kann, war der Handoff zu weich — oder die Session startet auf Sand. Weicht HEAD ab, klärt zuerst, was seit dem Handoff committet wurde; sonst arbeitet der Agent gegen einen Stand, den der Handoff nicht kennt (Kap. 6.5).

---

4.4 Frage 4: Wie der Agent selbst mittragen kann

Context-Management darf nicht nur „User-Disziplin“ sein. Regeln (AGENTS.md, Skills) sollen den Agenten zum Mitspieler machen — sonst fällt Hygiene unter Zeitdruck zuerst. Das ist weich: der Agent schlägt vor und liefert den Text; Slash-Befehle führt oft der Mensch aus. Was der Harness hart kann (Auto-Compact, Plan-Mode, Isolation), steht in Kap. 15 und Kap. 5.6.

Der Agent wählt eine Hauptaktion: Compact mit Hint, wenn Ziel und Context stabil sind; sonst Progress oder Handoff; an Task-, Themen- oder Rot-Grenze Handoff plus neue Session (4.1). Ein Handoff vor dem Verdichten ist Vorbereitung, keine zweite Aktion.

4.4.1 Proaktiv Compact vorschlagen

Compact wirkt nur im selben Thread. Vor dem Verdichten schreibt der Agent Progress oder Handoff, wenn der Stand die Session überleben muss (4.4.2, 4.4.3).

In AGENTS.md oder Skills verankern:

## Context-Management
- Trigger = Muster im Transkript (Kap. 3): Wiederhol-Reads ohne Fortschritt,
  Log-Wände, Scope-Drift, User-Korrektur. Füllgrad nur, wenn das Tool ihn anzeigt.
- Eine Hauptaktion, nicht alle drei: gleicher Task und Context noch scharf →
  Compact mit fertigem Hint (Ziel/DoD/Dateien/nächste Schritte behalten);
  Stand muss die Session überleben → Progress/Handoff; Themen-, Task- oder
  Rot-Grenze → Handoff und neue Session. Ein Handoff vor dem Verdichten ist
  Vorbereitung derselben Aktion, keine zweite.
- Nach Compact und vor dem nächsten großen Patch: Ziel, DoD und eine harte
  Invariante kurz wiederholen; bei Fail Hint nachlegen oder Handoff.

Der Agent rät den Füllgrad selten zuverlässig — den Balken nur, wenn der Harness ihn zeigt. Das Modell spürt keinen Matsch: es matcht, was im Schwanz steht; ob die DoD noch trägt, zeigt die Rezitation, nicht ein Gefühl.

Beispiel-Äußerung des Agents:

Die Test-Logs füllen das Fenster, der Slice ist derselbe. Vorschlag:
/compact Ziel, DoD, geänderte Dateien, nächste Schritte behalten
Soll ich das ausführen bzw. willst du compacten?

Das ist Professionalität — und spart den Moment, in dem Zone B schon da ist (Dumb Zone, Kap. 3). Pattern-Hints: 4.2. Denselben Check fährt der Agent von sich aus: Ziel und DoD in je einem Satz, die wenigen relevanten Dateien, der nächste Schritt. Unsicher → Hint nachlegen oder Handoff, nicht „noch ein Patch“.

4.4.2 Handoff anlegen und aktualisieren

Bei Task-Start: Progress anlegen. Wenn Mehr-Session absehbar, zusätzlich ein knappes Handoff (Ziel, DoD, nächster Schritt). Nach jedem Slice: Progress aktualisieren — das Handoff nicht zum laufenden Log machen. Bei Themenwechsel oder unfertigem Session-Ende: Handoff finalisieren (Stand, nächster Schritt, Commit-SHA) und neue Session empfehlen. Nie Secrets. Der Agent kann das Template befüllen — der Mensch prüft sechzig Sekunden.

4.4.3 Progress-Log pflegen

Kurze Einträge schlagen Chat-Abhängigkeit. Der Agent schreibt nach Verify:

### 2026-08-01 — rate-limit middleware
- Getan: Middleware + 3 Tests
- Verifiziert: go test ./internal/auth -count=1 → OK
- Als Nächstes: Redis-Backend Slice 2

Progress ist episodisches Gedächtnis im Repo und füttert das Handoff.

4.4.4 Session-Grenzen empfehlen

Der Agent soll sagen dürfen:

Slice 1 ist laut DoD grün. Empfehle Commit + neue Session für Slice 2 (Redis), damit der Explore-Context nicht mitzieht.

Wer solche Vorschläge „bestraft“, trainiert den Agenten, leise weiter im Matsch zu arbeiten.

---

4.5 Zusammenspiel: ein Tagesablauf

Die vier Fragen greifen ineinander. Ein typischer Tag:

Session-Start-Checkliste
  → Task-Prompt (Ziel, Nebenbedingungen, DoD)
  → Handoff anlegen, wenn Mehr-Session absehbar
  → Explore (Context noch klein halten)
  → optional Compact „Plan und DoD behalten“ (4.2)
  → Execute Slice → Verify DoD → Progress → Commit
      → fertig: Session-Ende (optional Compact)
      → unfertig / Themenwechsel: Handoff → neue Session

Der Unterschied liegt im Übergang, nicht im Repo. Gut: Slice „in-memory rate limit“ grün und committed, Progress und Handoff für Slice 2 Redis (DoD, nicht anfassen), neue Session nur mit Handoff und Code. Schlecht: 120 Turns Auth, Rate-Limit und JWT-Refactor in einem Thread; der Agent „fixt“ CSS im Login-Template, und alte JWT-Hypothesen wandern ins Redis-Design. Derselbe Mensch, dasselbe Repo — anderer Context-Lebenszyklus.

4.6 Team-Regeln und Einführungsfehler

Sechs Regeln als Startpaket:

1. Kein Feature ohne DoD-Checks im Prompt.
2. Kein unfertiges Session-Ende ohne Progress oder Handoff.
3. Compact-Hints kopierbar im Repo.
4. Eine Session ≈ ein Thema ≈ ein DoD. Ein Thema ist ein Ziel mit gemeinsamem DoD, kein Ordner und kein Sprint. Mehrere Slices laufen nur in derselben Session, solange dieses DoD gleich bleibt; sonst endet sie an der Slice-Grenze (Kap. 8.8).
5. Repo ist Wahrheit, Chat ist Arbeitsgedächtnis.
6. Der Agent darf Compact und Handoff vorschlagen.

Templates im Repo, Pflichten in AGENTS.md; nach Incidents zuerst Context/Slice/DoD — nicht das Modell.

Fehler	Besser
Templates anlegen, nie nutzen	Ein Pflicht-Task pro Woche mit Handoff
Alles in einer Meta-Session erklären	Richtlinie in AGENTS.md

Weitermachen „weil schon so viel Context drin steckt“ ist der teuerste Trugschluss. Kein Token-Dashboard ab Tag 1.

---

Key Takeaways

• Neue Session an Task-, Themen- und Rot-Grenzen — mit Handoff, nicht als Panik-Reset.
• Compact ist ein LLM-Summarizer-Pass (kein Zip) — proaktiv mit Erhaltungs-Hint; „kürzer“ ist kein Hint.
• Restore (Undo, Rewind, Checkpoint) holt Gespräch oder Working Tree im selben Thread zurück; Git-History und Side Effects außerhalb der Dateien bleiben unberührt.
• Handoff trägt Ziel, DoD, Stand, Commit-SHA, Dateien, nächste Schritte, Verbote — Datei, nicht Compact, nicht Agent-Routing (Vorlage: Anhang A).
• Der Agent trägt Compact, Handoff und Session-Grenzen mit — jeweils eine Hauptaktion, Vorbereitung zählt nicht als zweite; Team-Standard, kein privater Tick.

Praktische nächste Schritte

1. Handoff und Compaction-Hints aus Anhang A ins Team-Repo.
2. AGENTS.md um den Context-Block aus 4.4.1 ergänzen.
3. Eine Woche Session-Start-Checkliste (Anhang A); einmal bewusst: Slice → Handoff → neue Session.
4. Weiter: Kap. 5 — Lifecycle.