Später habe ich ein Plugin erstellt, das automatisch die folgenden Inhalte einbinden und die kompakte Funktion transparent verbessern kann.
https://x.com/u1/status/2073742408555343968
Wie Claude Codes Compact tatsächlich funktioniert
Als Grundvoraussetzung durchläuft Claude Codes Compact zwei Pfade:
- Manuelles Compact (/compact): Wird explizit vom Benutzer ausgelöst. Kann zu jedem beliebigen Zeitpunkt ausgeführt werden.
- Automatisches Compact: Wird automatisch ausgeführt, wenn die Sitzungskontextnutzung nahe an das Limit herankommt (in der Praxis etwa 90-95 %). Es wird nicht genau in dem Moment ausgeführt, den der Benutzer beabsichtigt, sondern an Übergängen, an denen man plötzlich merkt, dass komprimiert wurde.
In beiden Pfaden ist der Inhalt derselbe: Der vorherige Gesprächsverlauf wird an das LLM gesendet, um eine Zusammenfassung in natürlicher Sprache zu erstellen, und die Zusammenfassung + die letzten Schritte + der System-Prompt werden als neuer Kontext rekonstruiert. Die Zusammenfassung wird zu einer erzählungsbasierten Beschreibung von "was getan wurde", und als Ergebnis wird die Entscheidungsstruktur – wie "warum diese Wahl getroffen wurde", "welche Pläne verworfen wurden" und "in welcher Phase wir uns gerade befinden" – geschwächt. Darüber hinaus ist die Komprimierung, sobald sie ausgeführt wurde, ein irreversibler Vorgang; man kann nicht zu den Rohdaten vor der Komprimierung zurückkehren.
Aus Sicht der Hooks kann die Komprimierung durch das PostCompact-Ereignis abgefangen werden. Der PostCompact-Hook kann jedoch kein additionalContext zurückgeben, sodass es keinen Pfad gibt, um direkt nach der Komprimierung Anweisungen in den Agenten einzuschleusen. Um Anweisungen einzufügen, muss man den nachfolgenden UserPromptSubmit-Ereignis durchlaufen. Diese Einschränkung bestimmt das Hook-Design in diesem Artikel.
Was ist falsch am Standard-Compact
Claude Codes /compact fasst den Gesprächsverlauf zusammen und platziert das Ergebnis als Anfangskontext für eine neue Sitzung. Obwohl die Zusammenfassung an sich vernünftig ist, ist sie ein "Arbeitsprotokoll der Vergangenheit" und keine "Anweisung für das, was als nächstes zu tun ist". Folglich neigt der Agent nach der Komprimierung zu folgenden Fehlannahmen:
- Verlust der Grenze zwischen "Arbeitsanweisungen" und "Arbeitsprotokollen". Wenn die Zusammenfassung sagt "Plan A wurde in Betracht gezogen", könnte der Agent damit beginnen, Plan A zu implementieren, anstatt des tatsächlich angenommenen Plans B.
- Verwechslung der Verifikationsphase mit der Implementierungsphase. Die Prämisse "vor dem Deployment auf der echten Maschine verifizieren" fällt aus der Zusammenfassung heraus, und der Agent könnte im nächsten Schritt zu destruktiven Deployment-Operationen übergehen.
- Erneutes Vorschlagen von falschen Ansätzen, die bereits verworfen wurden. Die Zusammenfassung könnte festhalten, dass ein Ansatz "ausprobiert" wurde, aber nicht den "Grund, warum er abgelehnt wurde".
- Verlust des "Sitzungszustands" wie Plan-Modus, Worker-Delegierung oder Aufgabenbäume. Der Agent könnte außerhalb des Plan-Modus weiterarbeiten oder die Existenz von Workern in tmux vergessen und die Arbeit selbst erledigen.
Welche Arten von Unfällen tatsächlich aufgetreten sind
Wenn ich auf meine Sitzungen der letzten Woche zurückblicke, habe ich mindestens vier Muster unmittelbar nach einem Compact beobachtet. Alle scheinen auf das Versagen zurückzuführen zu sein, "Arbeitsanweisungen" von "Arbeitsprotokollen" zu trennen:
- Deployment vor Verifikation: Obwohl vereinbart wurde, "das Verhalten auf der Maschine zu verifizieren, bevor Dateien platziert werden", sah der Agent nach der Komprimierung nur das Fertigstellungsbild in der Zusammenfassung, übersprang die Verifikation und überschrieb das Ziel.
- Erneutes Ausführen von abgelehnten Abkürzungen: Da die Zusammenfassung einen fehlgeschlagenen Abkürzungsansatz als "ausprobiertes Verfahren" aufzeichnete, führte der Agent ihn erneut aus und geriet in denselben Fehler.
- Vergessen von Designprinzipien: Während der Sitzung aufgestellte Prinzipien wie "das Quell-Repository bearbeiten, nicht das Ziel" fielen aus der Zusammenfassung heraus, was den Agenten dazu veranlasste, direkte Änderungen vorzunehmen, die kurzfristig funktionieren, aber nicht reproduzierbar sind.
- Missverständnis der Aufgabenziele: Der spezifische Zweck eines vor der Komprimierung festgelegten Tests ging verloren, was den Agenten dazu brachte, in periphere Untersuchungen abzuschweifen und an einer völlig anderen Linie zu arbeiten.
Diese traten innerhalb derselben Sitzung mehrfach auf, wobei nach jedem Compact unterschiedliche Arten von Fehlannahmen auftraten. Ich betrachte dies als strukturelle Fehler der Standard-Compact-Spezifikation und nicht als isolierte Unfälle.
Was ich gebaut habe
(1) compact-prep Skill
Ein Skill, der als Slash-Befehl implementiert ist und den der Benutzer explizit vor der Eingabe von /compact ausführt. Er extrahiert die "Entscheidungsstruktur" und den "Sitzungszustand", die wahrscheinlich nicht in eine Zusammenfassung passen, und speichert sie in einer Zustandsdatei unter einem festen Pfad (${TMPDIR}/claude-compact-state/<session_id>.md) in einem bestimmten Format.
Gespeicherte Elemente umfassen solche, die in Zusammenfassungen schwer zu erfassen sind:
- Aktiver Plan (Plandateipfad und aktuelle Phase)
- TaskList-Zusammenfassung (laufende Aufgaben und Ergänzungen)
- Sitzungsentscheidungen (angenommene Pläne / abgelehnte Pläne / Ablehnungsgründe)
- Einschränkungen und Blocker
- Worker-Topologie (tmux-bridge Panes / Rollen / Zuweisungen)
- Bearbeitete Dateien (Notizen zu ungespeicherten oder unverifizierten Änderungen)
- Wiederherstellungsnotizen (ein Brief an das Selbst nach der Komprimierung)
Das entscheidende Designmerkmal ist "mechanische Durchsetzung". Es verwendet eine harte Sperre, um die Dateierstellung zu verhindern, wenn keine session_id gefunden wird, eine Zwangsfunktion mit festen Überschriften, um Auslassungen zu erkennen, und eingeschränkte erlaubte Tools, um Zustandsbeschädigungen zu verhindern.
(2) Zweistufiger Hook: PostCompact + UserPromptSubmit
Selbst wenn (1) eine Zustandsdatei schreibt, ist es bedeutungslos, wenn der Agent nach der Komprimierung sie nicht liest. Da PostCompact kein additionalContext zurückgeben kann, habe ich eine zweistufige Konfiguration verwendet:
- Der PostCompact-Hook schreibt eine Markierungsdatei mit der session_id (keine Anweisungen, nur die Aufzeichnung, dass eine Komprimierung stattgefunden hat).
- Wenn der nächste UserPromptSubmit-Hook die Markierung erkennt, injiziert er Anweisungen über additionalContext: "Lies die Plandatei / Lies die Zustandsdatei / Überprüfe die TaskList / Behandle die nächsten Schritte der Zusammenfassung als Hypothesen / Bestätige den Wiedereinstieg, wenn der Plan-Modus deaktiviert wurde", und löscht dann die Markierung.
Da Claude Code keinen gemeinsamen Zustandsmechanismus zwischen Hooks hat, ist eine Markierung im Dateisystem der einzige Kommunikationsweg. Dies hält jeden Hook schlank mit einer einzigen Verantwortung. In normalen Schritten beträgt der Overhead nur eine test -f-Prüfung.
(3) 60 %-Benachrichtigung (Um automatisches Compact zu vermeiden)
Die vorherigen Tools setzen voraus, dass der Benutzer manuell /compact-prep → /compact ausführt. Das automatische Compact läuft jedoch ohne Vorwarnung und umgeht diesen Ablauf. Wenn das automatische Compact zuerst zuschlägt, wird die Zustandsdatei nicht gespeichert, und die Rohdaten werden zu einer Zusammenfassung zerdrückt, wodurch Wiederherstellungsmaterial verloren geht.
Die Lösung besteht darin, einen Zustand zu schaffen, in dem der Benutzer die Vorbereitung manuell ausführen kann, bevor das automatische Compact ausgelöst wird. Dies ist der Zweck der 60 %-Benachrichtigung.
Warum 60 %?
- Ausreichende Vorlaufzeit: Das automatische Compact wird bei etwa 90-95 % ausgelöst. 60 % bieten eine Marge von 30 %, sodass der Benutzer die Warnung sieht, bevor der nächste Schritt ein automatisches Compact auslöst.
- Spielraum, um zu einem Haltepunkt zu gelangen: Bei 60 % sind noch 30 % Kapazität vorhanden, um eine Unteraufgabe abzuschließen, bevor der Zustand gespeichert wird.
- Mechanischer Auslöser: Es fungiert als Zwangsfunktion, wenn man zu konzentriert ist, um den Kontextverbrauch zu bemerken.
- 1M-Kontextannahme: Bei einem 200K-Kontext sind 60 % zu wenig. Ich verwende den 1M-Kontext (Opus 4.7), bei dem 60 % etwa 600K Tokens übrig lassen – reichlich Spielraum, um die Arbeit zu beenden und die Vorbereitung auszuführen.
Die Implementierung umfasst einen Statusline-Hook, der eine Warnmarkierung an der Schwelle schreibt, und einen UserPromptSubmit-Hook, der sie erkennt, um die Ausführung von /compact-prep vorzuschlagen.
Ergebnisse
Sitzungen sind jetzt selbst nach etwa 10 Komprimierungen ohne logischen Zusammenbruch stabil!
- Arbeitsverlust durch Komprimierung ist nahezu null.
- Erneute Vorschläge von abgelehnten Ideen sind verschwunden.
- Der Plan-Modus wird beibehalten.
- Kein Vergessen der Topologie mehr beim Ausführen mehrerer Worker in tmux.
Referenz: Implementierungscode
Nachfolgend sind die tatsächlichen Skill- und Hook-Codes. Sie funktionieren, indem sie in das Standard-Claude-Code-Verzeichnis (~/.claude/) kopiert werden.
A: compact-prep Skill-Body
Platziert in ~/.claude/skills/compact-prep/SKILL.md.
1---2name: compact-prep3description: |4 Vor der Ausführung von /compact in Claude Code den aktuellen Sitzungszustand in einer temporären Zustandsdatei speichern.5 ZWINGENDE AUSLÖSER: /compact-prep, compact-prep, Komprimierungsvorbereitung.6 NICHT AUSLÖSEN: Wiederherstellung nach Compact, normale Fortschrittsberichte, Planerstellung.7strict_procedure: true8argument-hint: "[Wiederherstellungsnotizen]"9allowed-tools: Read Write Bash(~/.claude/scripts/get-session-id.sh *) Bash(mkdir *) Bash(date *) Bash(pwd)10---1112# compact-prep1314Speichert den Sitzungszustand, der in Komprimierungszusammenfassungen schwer zu halten ist, in15`${TMPDIR}/claude-compact-state/${SESSION_ID}.md` vor `/compact`.1617## Profil des strengen Verfahrens1819- Strenge: strenges Verfahren.20- Harte Sperren: Stoppen, wenn session_id nicht abgerufen werden kann.21- Zwangsfunktion: Fester Pfad und obligatorische Überschriftenprüfung nach dem Speichern.22- Abschlussbeleg: Dateipfad, gespeicherte Elemente und Anleitung zur Ausführung von `/compact` melden.2324## Verfahren25261. session_id über `~/.claude/scripts/get-session-id.sh` abrufen.272. Pfad auf `${TMPDIR:-/tmp}/claude-compact-state/${SESSION_ID}.md` setzen.283. TaskList, aktiven Plan, tmux-bridge und bearbeitete Dateien überprüfen.294. Überschriften in der Reihenfolge speichern: # Compact Prep State, ## Active Plan, ## Current Phase, ## TaskList Summary, ## Session Decisions, ## Constraints and Blockers, ## Worker Topology, ## Editing Files, ## Recovery Notes.305. Überprüfen, ob alle Überschriften vorhanden sind.316. Dem Benutzer mitteilen: "Vorbereitung abgeschlossen. Bitte führen Sie `/compact` aus."
B: Wiederherstellungs-Hooks (2 Stufen)
B-1: PostCompact-Hook
~/.claude/hooks/compaction-recovery.sh
B-2: UserPromptSubmit-Hook (Injektion)
~/.claude/hooks/userpromptsubmit-compaction-recovery.sh
C: 60 %-Benachrichtigung
C-1: Statusline-Hook-Schwellenwert-Zweig
Hinzugefügt zu ~/.claude/hooks/statusline.sh.
C-2: UserPromptSubmit-Hook (Erinnerung)
~/.claude/hooks/userpromptsubmit-compact-prep-reminder.sh
D: settings.json-Registrierung
Fügen Sie die Hooks zu ~/.claude/settings.json hinzu.
