Claude Code lavora con una finestra di contesto che arriva a un milione di token, ma il problema delle sessioni lunghe non è finire lo spazio: è il context rot. Man mano che la conversazione cresce, l'attenzione del modello si distribuisce su più token e il materiale vecchio e ormai irrilevante inizia a disturbare il lavoro in corso. La qualità cala prima che il contesto sia pieno.
Gli strumenti per gestirlo sono due, e vanno capiti insieme: /compact, che è un comando nativo, e l'handoff, che invece è una pratica — non un comando che esiste già.
/compact: cosa fa davvero
Il comando chiede al modello di riassumere la conversazione fino a quel punto e sostituisce la cronologia con quel riassunto. La sessione prosegue, il contesto si svuota, il lavoro continua.
/compactLa parte che spesso si ignora è che si può guidare, ed è quasi sempre una buona idea:
/compact concentrati sul refactoring dell'autenticazione,
lascia perdere il debug dei testSenza istruzioni il riassunto è generico e decide il modello cosa conta. Con una riga di indirizzo si tiene quello che serve al lavoro che continua.
Va detto chiaramente: /compact è un'operazione con perdita. Quello che resta è un riassunto, non la conversazione. Dettagli che sembravano marginali — il percorso esatto di un file, il motivo per cui una strada è stata scartata, il comando che ha funzionato al terzo tentativo — spariscono senza avvisare.
La compattazione automatica
Quando il contesto si avvicina al limite, Claude Code compatta da solo. È utile perché evita il blocco secco, ma arriva quando arriva: cioè spesso nel mezzo di un ragionamento, con criteri che non hai scelto tu. È il motivo principale per cui conviene compattare prima, quando si decide di farlo e si può dire cosa tenere.
Non è l'unico strumento
| Situazione | Strumento | Perché |
|---|---|---|
| Stesso compito, contesto ancora utile | Continuare | Non si rilegge quello che il modello ha già letto |
| L'approccio preso era sbagliato | /rewind (o doppio Esc) | Torna indietro e scarta il tentativo fallito, tenendo le letture dei file |
| Sessione gonfia, materiale ormai stantio | /compact | Riassunto a basso sforzo, la sessione prosegue |
| Compito nuovo | /clear + handoff scritto | Zero degrado: si riparte puliti e si decide cosa portarsi dietro |
| Sotto-attività che producono molto output | Subagent | Contesto isolato, alla sessione principale torna solo la conclusione |
Due comandi di supporto utili: /context per vedere com'è composto il contesto corrente e /usage per tenere d'occhio i consumi.
L'handoff: la parte che manca
Qui va fatta una precisazione, perché in giro se ne parla come se fosse un comando: in Claude Code non esiste un comando nativo /handoff. È un pattern nato nella community, che si realizza con una skill, uno slash command personalizzato o semplicemente chiedendolo a parole.
L'idea è banale e funziona: prima di compattare o di chiudere la sessione, si fa scrivere al modello un documento di passaggio di consegne. Non dopo — dopo la compattazione le informazioni non ci sono più.
La struttura che si è consolidata ha cinque sezioni:
- Cosa è successo — decisioni prese e obiettivi raggiunti
- Dove stanno le cose — percorsi dei file toccati
- Cosa è stato verificato — e soprattutto cosa non lo è stato
- Stato di git — branch, commit, cosa è stato pushato
- Punti aperti — i prossimi passi, numerati
Farsi il proprio comando /handoff
Bastano pochi minuti: si crea il file .claude/commands/handoff.md nel progetto (oppure in ~/.claude/commands/ per averlo ovunque) con dentro le istruzioni.
Scrivi il passaggio di consegne di questa sessione in
docs/handoff.md, sovrascrivendo il contenuto precedente.
Struttura:
## Cosa e stato fatto
Decisioni prese e perche, obiettivi raggiunti.
## File toccati
Percorsi completi, con una riga su cosa e cambiato in ciascuno.
## Verificato / non verificato
Cosa e stato testato davvero e cosa e rimasto da provare.
## Stato git
Branch, ultimo commit, cosa non e ancora committato.
## Prossimi passi
Elenco numerato, dal primo da fare.
Sii specifico: nomi di file, funzioni, comandi esatti.
Niente frasi generiche tipo "sistemare la logica".Da quel momento /handoff esiste — come comando tuo. Il flusso diventa: /handoff, poi /compact (o /clear), e alla ripresa basta far leggere docs/handoff.md.
Handoff e tasks.md sono la stessa idea
Chi tiene già un tasks.md nel repository ha metà del lavoro fatto: l'elenco dei task con le caselle spuntate è la parte "prossimi passi" del passaggio di consegne, e vive nel repository, versionata. L'handoff aggiunge il resto — il contesto delle decisioni, cosa è stato verificato, dove sono i file. Le due cose si tengono insieme: il file dei task racconta cosa manca, l'handoff racconta a che punto si era.
Il flusso che funziona
- Si lavora finché il contesto è sano e le risposte restano centrate
- Ai primi segnali di deriva — risposte che ignorano decisioni già prese, file riletti più volte — si ferma il lavoro
/handoff: il documento di passaggio viene scritto su disco/compactcon istruzioni mirate, oppure/clearse il prossimo compito è diverso- Alla ripresa: «leggi
docs/handoff.mde riparti dal punto 1 dei prossimi passi»
Errori tipici
- Compattare senza istruzioni — il riassunto tiene quello che sembra importante al modello, non a te
- Aspettare la compattazione automatica — arriva nel momento peggiore, e la qualità era già calata da un pezzo
- Scrivere l'handoff dopo aver compattato — è il singolo errore che vanifica tutto: il documento viene scritto su un riassunto, non sui fatti
- Handoff generico — «continuare il refactoring» non serve a nessuno; servono nomi di file, funzioni e comandi
- Tenere aperta una sessione infinita — il contesto non finisce, ma la lucidità sì
La regola pratica, alla fine, è una sola: il contesto è materiale di consumo, il documento di passaggio no. Quello che serve davvero deve finire su disco, dove sopravvive a qualsiasi compattazione.