Das Übergabedokument: Agent-Gedächtnis über Sitzungen hinweg
Am 21. März 2026 lieferte meine Produktionssite 14-Sekunden-Ladezeiten aus, nachdem eine Cache-Leerung einen Leistungsengpass offenlegte. Ich untersuchte die Grundursache über zwei Sitzungen hinweg, identifizierte den langsamen Code-Pfad, entwarf einen Fix-Plan und hielt alles in einem Übergabedokument fest.
Ein Übergabedokument trägt eine Diagnose über Sitzungsgrenzen hinweg, damit der umsetzende Agent ein korrigiertes Verständnis erbt, statt dieselben falschen Schlussfolgerungen erneut abzuleiten. Anders als Tickets, die sagen, was zu tun ist, halten Übergaben fest, was versucht wurde, was falsch war und warum frühere Ansätze scheiterten. Die Übergabe für die Market-Seite überstand drei Korrekturen über vier Tage und führte zu einer Implementierung, die die Ladezeit von 14 Sekunden auf 108 Millisekunden reduzierte.
Der erste Entwurf dieser Übergabe war falsch. Er zielte auf den falschen Code-Pfad. Eine Code-Review stellte fest, dass die gemessenen langsamen Seiten von market_hub() ausgeliefert wurden, nicht von _fetch_market_data(), wie die Übergabe annahm. Die Übergabe wurde überarbeitet.
Der zweite Entwurf schlug unnötige HTMX-Partials für Apple Maps und Tier-Zählungen vor. Eine Review stellte fest, dass Apple Maps URLs lokal signiert (keine ausgehende Anfrage zum Verzögern) und dass Tier-Zählungen aus einer einzigen Aggregationsabfrage kommen sollten. Die Übergabe wurde erneut überarbeitet.
Der dritte Entwurf schlug vor, den Wetter-Endpoint async zu machen, spezifizierte aber nicht, dass der bestehende synchrone HTTP-Client den Event-Loop auch hinter HTMX weiterhin blockieren würde. Die Übergabe wurde ein drittes Mal überarbeitet.
Vier Tage später las eine andere Sitzung die dreimal überarbeitete Übergabe und implementierte den Fix. Austin ging von 14.290ms auf 108ms. Die Implementierung zielte auf den korrekten Code-Pfad, verwendete den korrekten Abfrageansatz und sparte die unnötigen HTMX-Partials aus. Jede Korrektur aus den drei Reviews war bereits eingearbeitet.
Das Übergabedokument trug eine Diagnose über vier Tage und mehrere Sitzungen hinweg. Ohne es hätte die umsetzende Sitzung von Grund auf begonnen, dieselben falschen Annahmen getroffen, dieselben unnötigen Optimierungen vorgeschlagen und dieselben Korrekturen benötigt. Die Übergabe komprimierte vier Tage Untersuchung in ein Dokument, das der umsetzende Agent in Sekunden las. Dies ist Kontextfenster-Management angewendet auf ein spezifisches Problem: wie man eine Diagnose über Sitzungsgrenzen hinweg überträgt, ohne die Korrekturen zu verlieren, die sie präzise machen.
Was eine Übergabe enthält
Ein Übergabedokument ist kein Ticket. Ein Ticket sagt, was zu tun ist. Eine Übergabe sagt, was versucht wurde, was gelernt wurde, was falsch war und was als Nächstes zu tun ist. Der Unterschied ist institutionelles Gedächtnis.
Die Übergabe für die Market-Seite enthielt:
Die Diagnose. Cold-Render-TTFB-Messungen für sechs Market-Seiten, von 381ms (Tokio, kleiner Markt) bis 14.290ms (Austin, 500+ Unternehmen). Die Messungen bewiesen, dass das Problem mit der Unternehmensanzahl skaliert, was auf die Abfrageform als Engpass hindeutete.
Die Grundursachen, priorisiert. Vier Grundursachen nach Auswirkung geordnet: Abfrageform (primär), blockierendes Wetter API (sekundär), Full-Table-Scan auf einem anderen Code-Pfad (tertiär) und fehlende Cache-Header (bereits teilweise adressiert). Jede Grundursache enthielt Dateipfade, Zeilennummern und das spezifische Code-Muster, das die Verlangsamung verursachte.
Die falschen Abzweigungen. Der erste Entwurf zielte auf _fetch_market_data() statt auf market_hub(). Die Übergabe hielt diesen Fehler und die Korrektur fest, damit die umsetzende Sitzung nicht dieselbe falsche Schlussfolgerung erneut ableitet. Sie hielt auch die verworfenen HTMX-Partials fest und warum sie verworfen wurden: Apple Maps hat keine ausgehende Anfrage, Tier-Zählungen gehören in die Aggregationsabfrage.
Der Implementierungsplan. Fünf Schritte mit SQL-Beispielen, Akzeptanzkriterien und Verifizierungsanweisungen. Schritt 1: Python-seitige Paginierung durch eine Datenbankabfrage ersetzen. Schritt 2: HTMX-Wetter-Partial mit asynchronem Client hinzufügen. Schritt 3: den sekundären Code-Pfad cachen. Schritt 4: Edge-Cache-Header hinzufügen. Schritt 5: dieselben sechs URLs erneut messen.
Der Beitrag Kontextfenster-Management erklärt, warum dieser Detailgrad wichtig ist: Jede Mehrdeutigkeit in der Übergabe ist eine Entscheidung, die der umsetzende Agent neu ableiten muss, was Kontextbudget verbraucht und dieselbe falsche Schlussfolgerung riskiert.
Die Kontext-Landminen. Der gemeinsame Template-Kontext enthält eine authentifizierte Coin-Balance-Abfrage auf jeder Seite, einschließlich Seiten, die sie nie rendern. Die Übergabe vermerkte dies als Cache-Korrektheitsbedenken: s-maxage ohne korrekte Vary-Header könnte veraltete Auth-Daten an anonyme Benutzer ausliefern.
Warum Tickets scheitern
Ein Ticket für dieselbe Arbeit würde sagen: „Market-Seiten sind langsam. Optimieren Sie die Market-Hub-Abfrage.” Die umsetzende Sitzung müsste:
- Herausfinden, welcher Code-Pfad Market-Seiten ausliefert (nicht offensichtlich ohne den Router zu lesen)
- Den Code-Pfad profilieren, um den Engpass zu finden
- Verschiedene Optimierungsansätze erwägen
- Einen implementieren
- Feststellen, dass der Ansatz eine Nebenwirkung hat (Cache-Korrektheit mit Auth-Daten)
- Den Ansatz überarbeiten
Schritte 1-3 wurden bereits in den Untersuchungssitzungen erledigt. Die Übergabe trägt diese Arbeit weiter. Ein Ticket verwirft sie.
Der Fehlermodus ist nicht Faulheit. Der Fehlermodus ist Kontextverlust über Sitzungsgrenzen hinweg. Eine KI-Agent-Sitzung beginnt mit einem sauberen Kontextfenster. Sie erinnert sich nicht daran, was die vorherige Sitzung entdeckt hat. Dies ist dasselbe Problem, das Kontext ist Architektur auf Systemebene adressiert: Was Sie in das Kontextfenster einfügen, bestimmt die Qualität der Ausgabe. Ein Ticket liefert ein Ziel. Eine Übergabe liefert ein Ziel plus das angesammelte Verständnis, das nötig ist, um es korrekt zu erreichen.
Die Überarbeitungshistorie zählt
Die Überarbeitungshistorie der Übergabe ist genauso wertvoll wie ihr aktueller Inhalt. Die Übergabe für die Market-Seite hielt drei Überarbeitungen mit Zeitstempeln und Gründen fest:
- Erfasst: 2026-03-21T17:24 (ursprüngliche Untersuchung)
- Überarbeitet: 2026-03-21T18:20 (Code-Review-Korrekturen: falscher Code-Pfad, unnötiges HTMX)
- Überarbeitet: 2026-03-25T06:30 (Implementierung abgeschlossen, Abfrage-Fix deployed)
Die Überarbeitungshistorie sagt der umsetzenden Sitzung: „Diese Diagnose wurde angefochten und korrigiert. Die aktuelle Version enthält diese Korrekturen.” Eine Übergabe ohne Überarbeitungen könnte falsch sein. Eine Übergabe mit drei Überarbeitungen wurde stressgetestet.
Die falschen Abzweigungen sind Teil des Werts. Eine Übergabe, die sagt „wir haben /_map HTMX erwogen und abgelehnt, weil Apple Maps URLs lokal signiert”, erspart der umsetzenden Sitzung, dieselbe Optimierung vorzuschlagen, sie prüfen zu lassen und sie abgelehnt zu bekommen. Die Übergabe stellt die Ablehnung an den Anfang.
Wann man eine Übergabe schreibt
Nicht jede Aufgabe braucht eine Übergabe. Ein Bugfix, der eine Sitzung dauert, benötigt keine sitzungsübergreifende Persistenz. Eine Übergabe ist wertvoll, wenn:
Die Untersuchung aufwendig ist. Das Profilieren eines Leistungsengpasses, das Nachverfolgen einer Sicherheitslücke, das Debuggen einer Multi-System-Interaktion. Wenn die Untersuchung erheblichen Aufwand erforderte, bewahrt die Übergabe diesen Aufwand.
Die Implementierung in einer anderen Sitzung stattfinden wird. Wenn Sie die Untersuchung heute abschließen, aber morgen implementieren werden, überbrückt die Übergabe die Lücke. Ohne sie beginnt die morgige Sitzung bei null.
Die Diagnose nicht offensichtlich ist. Wenn der korrekte Fix voraussetzt, zu verstehen, warum drei scheinbar vernünftige Alternativen falsch sind, erfasst die Übergabe dieses Verständnis. Das System Compound Context erklärt, wie Übergaben in die breitere Akkumulation von Projektwissen passen. Ein Ticket, das sagt „Abfrage fixen”, erklärt nicht, warum die Abfrage einen spezifischen Fix benötigt.
Mehrere Personen (oder Agenten) daran arbeiten könnten. Die Übergabe ist ein gemeinsames Verständnisdokument. Jede Sitzung, die sie liest, erbt den vollständigen Untersuchungskontext.
Übergaben als Compound Context
Eine Übergabe ist eine Einzahlung in das System Compound Context. Jede Übergabe erfasst Diagnosezeit und wandelt sie in ein wiederverwendbares Artefakt um. Die umsetzende Sitzung hebt die Diagnose zu nahezu null Kosten ab.
Im Laufe der Zeit akkumulieren sich Übergaben zu einer Untersuchungshistorie. Die Übergabe für die Market-Seite verweist auf den Cache-Purge-Vorfall, die Nightcheck-Messungen, den destruktiven API-Guard und das Code-Review-System. Jedes davon ist selbst ein Produkt vorheriger Sitzungen. Die Übergabe verbindet sie zu einer Erzählung, der eine neue Sitzung folgen kann.
Die Übergabe ersetzt nicht das Verständnis. Die umsetzende Sitzung muss immer noch den Code lesen, den Fix schreiben und das Ergebnis verifizieren. Die Übergabe ersetzt die Wiederentdeckung. Die Sitzung muss nicht entdecken, was bereits bekannt ist. Die Ralph-Agent-Architektur verwendet Übergaben als primären sitzungsübergreifenden Persistenzmechanismus für ihre nächtliche Ausführungsschleife. Der AI Engineering Hub dokumentiert, wie Übergaben in die breitere Infrastruktur von Hooks, Skills und Gedächtnissystemen passen, die agentengestützte Entwicklung im Laufe der Zeit kompoundieren lassen.
FAQ
Wie lang sollte eine Übergabe sein?
Lang genug, um die Diagnose, die falschen Abzweigungen und den Implementierungsplan zu erfassen. Kurz genug, dass ein Agent sie in einem Kontextladevorgang lesen kann. Die Übergabe für die Market-Seite war 103 Zeilen lang. Die meisten Übergaben umfassen 50-150 Zeilen.
Wo speichern Sie Übergaben?
Im Memory-Verzeichnis des Projekts: ~/.claude/projects/{project}/memory/handoff-{topic}.md. Das Memory-System lädt relevante Dateien basierend auf Frontmatter-Beschreibungen, sodass Übergaben für zukünftige Sitzungen ohne expliziten Verweis auffindbar sind.
Ersetzen Übergaben die Dokumentation?
Nein. Dokumentation beschreibt, wie das System funktioniert. Eine Übergabe beschreibt, was über ein spezifisches Problem gelernt wurde und was dagegen zu tun ist. Dokumentation ist dauerhaft. Eine Übergabe wird von der umsetzenden Sitzung konsumiert und wird dann zu historischem Kontext.
Was, wenn die Übergabe veraltet?
Das Status-Feld der Übergabe verfolgt dies. Aktive Übergaben sind als PLANNED oder IN PROGRESS markiert. Abgeschlossene Übergaben sind als RESOLVED mit dem Implementierungs-Commit-Hash markiert. Veraltete Übergaben sind als historischer Kontext sichtbar, aber nicht handlungsrelevant.
Quellen
Dieser Artikel stützt sich auf die Performance-Übergabe für die Market-Seite (handoff-market-page-perf.md), die den am 25. März 2026 deployten Abfrageform-Fix leitete. Die Übergabe überstand drei Überarbeitungszyklen über vier Tage und führte zu einer Implementierung, die eine 132-fache Leistungsverbesserung erzielte. Referenziert in Compound Context.