Ecco la traduzione in italiano del testo fornito, seguendo tutte le linee guida specificate.
Successivamente, ho creato un plugin che può includere automaticamente il seguente contenuto e potenziare in modo trasparente la funzionalità compatta.
https://x.com/u1/status/2073742408555343968
Come funziona realmente la funzione Compact di Claude Code
Come premessa, la funzione Compact di Claude Code opera attraverso due percorsi:
- Compact manuale (/compact): Attivato esplicitamente dall'utente. Può essere eseguito in qualsiasi momento.
- Compact automatico: Viene eseguito automaticamente quando l'utilizzo del contesto della sessione si avvicina al limite (in pratica, circa il 90-95%). Non viene eseguito nel momento esatto in cui l'utente lo desidera, ma piuttosto ai confini dei turni, quando ci si accorge improvvisamente che è stato compresso.
In entrambi i percorsi, il contenuto è lo stesso: la cronologia della conversazione precedente viene inviata all'LLM per creare un riepilogo in linguaggio naturale, e il riepilogo, insieme ai turni recenti e al prompt di sistema, viene ricostruito come un nuovo contesto. Il riepilogo diventa una descrizione narrativa di "cosa è stato fatto" e, di conseguenza, la struttura decisionale, come "perché è stata presa quella scelta", "quali piani sono stati rifiutati" e "in quale fase ci troviamo attualmente", viene indebolita. Inoltre, una volta eseguita la compressione, si tratta di un'operazione irreversibile; non è possibile tornare ai log grezzi precedenti alla compressione.
Dal punto di vista degli hook, la compressione può essere intercettata dall'evento PostCompact. Tuttavia, l'hook PostCompact non può restituire additionalContext, quindi non esiste un percorso per iniettare direttamente istruzioni nell'agente immediatamente dopo la compressione. Per inserire istruzioni, è necessario passare attraverso il successivo evento UserPromptSubmit. Questo vincolo determina la progettazione degli hook descritta in questo articolo.
Cosa non va nel Compact standard
Il comando /compact di Claude Code riassume la cronologia della conversazione, inserendo il risultato come contesto iniziale per una nuova sessione. Sebbene il riepilogo in sé sia ragionevole, si tratta di un "registro di lavoro del passato" piuttosto che di una "istruzione su cosa fare dopo". Di conseguenza, l'agente post-compressione diventa incline ai seguenti fraintendimenti:
- Perdita del confine tra "istruzioni di lavoro" e "registri di lavoro". Se il riepilogo dice "Il Piano A è stato preso in considerazione", l'agente potrebbe iniziare a implementare il Piano A invece del Piano B effettivamente adottato.
- Confusione tra la fase di verifica e quella di implementazione. La premessa di "verificare sulla macchina reale prima di distribuire" scompare dal riepilogo e l'agente potrebbe passare a operazioni di distribuzione distruttive nel turno successivo.
- Riproposizione di approcci errati già scartati. Il riepilogo potrebbe registrare che un approccio è stato "provato" ma non il "motivo per cui è stato rifiutato".
- Perdita dello "stato della sessione" come la modalità piano, la delega dei worker o gli alberi delle attività. L'agente potrebbe continuare a lavorare senza essere in modalità piano o dimenticare l'esistenza di worker in esecuzione in tmux e iniziare a fare il lavoro da solo.
Quali tipi di incidenti si sono verificati effettivamente
Ripensando alle mie sessioni dell'ultima settimana, ho osservato almeno quattro modelli subito dopo un compact. Tutti sembrano radicati nell'incapacità di separare le "istruzioni di lavoro" dai "registri di lavoro":
- Distribuzione prima della verifica: Nonostante l'accordo di "verificare il comportamento sulla macchina prima di posizionare i file", l'agente ha visto solo l'immagine di completamento nel riepilogo dopo la compressione, ha saltato la verifica e ha sovrascritto la destinazione.
- Riesecuzione di scorciatoie rifiutate: Poiché il riepilogo registrava un approccio di scorciatoia fallito come "procedura provata", l'agente lo ha rieseguito e si è imbattuto nello stesso fallimento.
- Dimenticanza dei principi di progettazione: Principi stabiliti durante la sessione, come "modificare il repository sorgente invece della destinazione", sono scomparsi dal riepilogo, portando l'agente a fare modifiche dirette che funzionano a breve termine ma non sono riproducibili.
- Incomprensione degli obiettivi dell'attività: Lo scopo specifico di un test fissato prima della compressione è andato perso, portando l'agente a deviare verso indagini periferiche e iniziare a lavorare su una linea completamente diversa.
Questi si sono verificati più volte all'interno della stessa sessione, con diversi tipi di fraintendimenti dopo ogni compact. Considero questi fallimenti strutturali della specifica standard del compact, piuttosto che incidenti isolati.
Cosa ho costruito
(1) Skill compact-prep
Una skill implementata come comando slash che l'utente attiva esplicitamente prima di digitare /compact. Estrae la "struttura decisionale" e lo "stato della sessione" che probabilmente non troveranno posto in un riepilogo e li salva in un file di stato in un percorso fisso (${TMPDIR}/claude-compact-state/<session_id>.md) in un formato specifico.
Gli elementi salvati includono quelli difficili da catturare nei riepiloghi:
- Piano Attivo (percorso del file del piano e fase corrente)
- Riepilogo TaskList (attività in corso e integrazioni)
- Decisioni della Sessione (piani adottati / piani rifiutati / motivi del rifiuto)
- Vincoli e Blocchi
- Topologia dei Worker (pannelli tmux-bridge / ruoli / assegnazioni)
- File in Modifica (note su modifiche non salvate o non verificate)
- Note di Recupero (una lettera al sé post-compressione)
Il punto chiave del design è l'"imposizione meccanica". Utilizza un gate rigido per impedire la creazione del file se non viene trovato un session_id, una funzione di forzatura con intestazioni fisse per rilevare omissioni e strumenti consentiti limitati per prevenire il danneggiamento dello stato.
(2) Hook a due stadi: PostCompact + UserPromptSubmit
Anche se (1) scrive un file di stato, è inutile se l'agente post-compressione non lo legge. Poiché PostCompact non può restituire additionalContext, ho utilizzato una configurazione a due stadi:
- L'hook
PostCompactscrive un file marker con il session_id (nessuna istruzione, solo la registrazione che la compressione è avvenuta). - Quando il successivo hook
UserPromptSubmitrileva il marker, inietta istruzioni tramiteadditionalContext: "Leggi il file del piano / Leggi il file di stato / Controlla la TaskList / Considera i passaggi successivi del riepilogo come ipotesi / Conferma il rientro se la modalità piano è stata disattivata", quindi elimina il marker.
Poiché Claude Code manca di un meccanismo di stato condiviso tra gli hook, un marker sul filesystem è l'unico percorso di comunicazione. Questo mantiene ogni hook snello con una singola responsabilità. Nei turni normali, il sovraccarico è solo un controllo test -f.
(3) Notifica al 60% (Per evitare il compact automatico)
Gli strumenti precedenti presuppongono che l'utente esegua manualmente /compact-prep → /compact. Tuttavia, il compact automatico viene eseguito senza preavviso, bypassando questo flusso. Se il compact automatico scatta per primo, il file di stato non viene salvato e i log grezzi vengono compressi in un riepilogo, perdendo il materiale di recupero.
La soluzione è creare uno stato in cui l'utente possa eseguire manualmente la preparazione prima che scatti il compact automatico. Questo è lo scopo della notifica al 60%.
Perché il 60%?
- Tempo di anticipo sufficiente: Il compact automatico scatta intorno al 90-95%. Il 60% fornisce un margine del 30%, assicurando che l'utente veda l'avviso prima che il turno successivo attivi un auto-compact.
- Spazio per raggiungere un punto di arresto: Al 60%, c'è ancora il 30% di capacità rimanente per completare un sotto-compito prima di salvare lo stato.
- Trigger meccanico: Funge da funzione di forzatura quando si è troppo concentrati per notare il consumo del contesto.
- Assunzione di contesto 1M: Con un contesto di 200K, il 60% è troppo piccolo. Io uso il contesto 1M (Opus 4.7), dove il 60% lascia circa 600K token, spazio più che sufficiente per finire il lavoro ed eseguire la preparazione.
L'implementazione prevede un hook statusline che scrive un marker di avviso alla soglia e un hook UserPromptSubmit che lo rileva per suggerire di eseguire /compact-prep.
Risultati
Le sessioni sono ora stabili anche dopo circa 10 compattazioni senza rotture logiche!
- La perdita di lavoro dovuta alla compressione è quasi zero.
- Le riproposizioni di idee rifiutate sono scomparse.
- La modalità piano viene mantenuta.
- Non si dimentica più la topologia quando si eseguono più worker in tmux.
Riferimento: Codice di implementazione
Di seguito sono riportati i codici effettivi della skill e degli hook. Funzionano copiandoli nella directory standard di Claude Code (~/.claude/).
A: Corpo della skill compact-prep
Posizionare in ~/.claude/skills/compact-prep/SKILL.md.
1---2name: compact-prep3description: |4 Prima di eseguire /compact in Claude Code, salva lo stato corrente della sessione in un file di stato temporaneo.5 ATTIVAZIONI OBBLIGATORIE: /compact-prep, compact-prep, preparazione alla compressione.6 NON ATTIVARE: recupero dopo compact, rapporti di avanzamento normali, creazione di piani.7strict_procedure: true8argument-hint: "[note di recupero]"9allowed-tools: Read Write Bash(~/.claude/scripts/get-session-id.sh *) Bash(mkdir *) Bash(date *) Bash(pwd)10---1112# compact-prep1314Salva lo stato della sessione che è difficile mantenere nei riepiloghi di compressione in15`${TMPDIR}/claude-compact-state/${SESSION_ID}.md` prima di `/compact`.1617## Profilo della procedura rigorosa1819- Rigore: procedura rigorosa.20- Gate rigidi: Interrompi se l'ID sessione non può essere recuperato.21- Funzione di forzatura: Controllo obbligatorio del percorso fisso e dell'intestazione dopo il salvataggio.22- Ricevuta di completamento: Segnala il percorso del file, gli elementi salvati e le indicazioni per eseguire `/compact`.2324## Procedura25261. Ottieni l'ID sessione tramite `~/.claude/scripts/get-session-id.sh`.272. Imposta il percorso su `${TMPDIR:-/tmp}/claude-compact-state/${SESSION_ID}.md`.283. Controlla TaskList, piano attivo, tmux-bridge e file in modifica.294. Salva le intestazioni in ordine: # Compact Prep State, ## Active Plan, ## Current Phase, ## TaskList Summary, ## Session Decisions, ## Constraints and Blockers, ## Worker Topology, ## Editing Files, ## Recovery Notes.305. Verifica che tutte le intestazioni esistano.316. Comunica all'utente: "Preparazione completata. Eseguire `/compact`."
B: Hook di recupero (2 stadi)
B-1: Hook PostCompact
~/.claude/hooks/compaction-recovery.sh
B-2: Hook UserPromptSubmit (Iniezione)
~/.claude/hooks/userpromptsubmit-compaction-recovery.sh
C: Notifica al 60%
C-1: Ramo di soglia dell'hook statusline
Aggiunto a ~/.claude/hooks/statusline.sh.
C-2: Hook UserPromptSubmit (Promemoria)
~/.claude/hooks/userpromptsubmit-compact-prep-reminder.sh
D: Registrazione in settings.json
Aggiungere gli hook a ~/.claude/settings.json.
