Il metodo dell'orchestratore in Claude Code: una sessione che coordina tutte le altre

In breve: lavoro con una sessione di Claude Code che fa da orchestratore, e io parlo solo con lei. Lei apre le sessioni di lavoro, una per ogni area del progetto, e gli scrive compiti e priorità. Ogni sessione divide il suo lavoro in pezzi e lo affida ad agenti in parallelo. Quando un'ondata di lavoro finisce, passa tre controlli sempre nello stesso ordine: /simplify, /code-review high e tutte le prove automatiche.

Questa è la pagina che ti ho promesso nel video, con il metodo spiegato in breve. Il file con il metodo per chiudere ogni ondata di lavoro lo scarichi in fondo alla pagina.

Cosa serve

• Claude Code dalla versione 2.1.224 in poi, su macOS o Linux: è la versione in cui le sessioni hanno iniziato a scriversi tra loro. Come funziona la funzione lo spiego nell'articolo su come far parlare più sessioni di Claude Code.
• Un progetto con git, perché ogni pezzo finito diventa un commit, cioè un salvataggio con nome nella storia del progetto.
• I compiti già organizzati, per esempio su Linear, un issue per ogni compito. Se i compiti sono confusi, l'orchestratore distribuisce confusione.
• Un piano che regga il consumo: questo metodo usa molti token.

I tre livelli

1. L'orchestratore. È la sessione con cui parlo. Assegna a ogni sessione di lavoro la sua area, manda le priorità, legge i rapporti e controlla i commit. Non scrive codice e non si chiude mai, perché perderebbe il filo di tutto.
2. Le sessioni di lavoro. Una per area, ognuna con il suo nome e i suoi file: per esempio una sull'interfaccia, una sul nucleo del software, una sulle prove. Le aree non si sovrappongono, così due sessioni non toccano mai lo stesso file.
3. Gli agenti. Dentro ogni sessione la chat principale non fa il lavoro da sé. Lo divide in pezzi e lo affida a 6-8 agenti in parallelo, su file distinti, con Sonnet o Haiku e il modello sempre scritto in modo esplicito. Poi controlla quello che consegnano e fa i commit: gli agenti non committano.

Il terzo livello è quello che fa durare le sessioni. La chat principale non legge file grandi e non scrive codice, quindi il suo contesto resta leggero.

Come si parlano le sessioni

Ogni sessione si apre con un nome, per esempio:

claude -n lavoro-interfaccia

L'orchestratore vede le sessioni aperte con ListAgents e gli scrive con SendMessage. Le sessioni rispondono allo stesso modo: appena partono dicono da dove riprendono, e a ogni pezzo chiuso mandano una riga con quello che hanno fatto.

Le decisioni importanti però non stanno solo nei messaggi. Ogni sessione ha un file di passaggio con compito, stato, file suoi, prossimi passi e regole. Quando l'orchestratore manda una priorità nuova, la scrive anche lì, così resta valida se la sessione viene sostituita.

Aprire e sostituire le sessioni in automatico

Le sessioni le può aprire l'orchestratore da solo. Sul Mac basta un piccolo script che apre una nuova scheda del Terminale, dà alla sessione il suo nome e la fa partire con questo messaggio di avvio:

Sei [nome], una sessione nuova del progetto.
Prima di tutto leggi per intero il file di passaggio [percorso]: compito, stato, file tuoi, regole e coordinatore.
Poi controlla il git status dei tuoi file e riprendi dal punto indicato nel file.
Tu, chat principale, orchestri e non fai il lavoro da te: dividi in pezzi e affidali ad agenti in parallelo (solo sonnet o haiku, modello esplicito, fino a 6-8 alla volta, su file distinti). Tu verifichi, committi e scrivi al coordinatore.
Appena sei partita manda una riga al coordinatore con SendMessage, dicendo che hai letto il passaggio e da dove riparti.

Se non vuoi lo script, le sessioni le apri a mano in schede diverse, ognuna col suo nome: il resto del metodo non cambia.

Quando una sessione di lavoro supera una soglia di contesto, per esempio 500 mila token, l'orchestratore la fa ruotare. La sessione chiude il pezzo in corso, committa, scrive il file di passaggio e si ferma. L'orchestratore apre la sessione nuova, aspetta che parta, e solo dopo chiude la vecchia. Oltre quella soglia ogni passo consuma molto più limite e la sessione è meno lucida.

Come si chiude ogni ondata di lavoro

Gli agenti scrivono tanto e in fretta. Prima di dire "fatto", ogni sessione passa tre controlli, sempre in questo ordine.

1. /simplify. Rilegge solo il codice appena cambiato e cerca quattro cose: pezzi che esistono già e vanno riusati, parti scritte in modo troppo complicato, lavoro inutile per la macchina, codice messo nel posto sbagliato. Non cerca bug, cerca peso in più. Due regole: al massimo due passate, e accetto solo le correzioni che tolgono o uniscono codice. Se una correzione aggiunge, la scarto.
2. /code-review high. Adesso si cercano i bug: cose che si rompono, casi dimenticati, regressioni, cioè cose che prima funzionavano e ora no. "high" è il livello di impegno: va a fondo senza riempirti di dubbi. Ogni rilievo si corregge oppure si scarta con il motivo scritto.
3. Le prove automatiche. Si lanciano tutte, non solo quelle del pezzo toccato. Se una è rossa, l'ondata non è chiusa.

Le correzioni di /simplify e quelle della review vanno ognuna in un commit a parte.

L'ordine conta. Prima si semplifica, così la review legge meno codice e guarda solo quello che conta. La review viene dopo perché controlla anche le modifiche della semplificazione: se /simplify ha rotto qualcosa, la review lo prende. Le prove sono l'ultima parola e non si fidano di nessuno dei due.

La regola dei tagli

Si toglie qualcosa solo con una prova, e le prove valide sono tre: la stessa logica scritta in due posti (se ne tiene uno), codice che nessuno chiama mai, una funzione che nessuno ha chiesto. Se c'è un dubbio non si taglia, si annota. E quando si toglie un test, si scrive quale altro test controlla la stessa cosa.

Se qualcosa non va

• La review trova troppi rilievi: l'ondata era troppo grande, la prossima volta spezzala.
• /simplify propone di aggiungere codice: scarta, non è il suo compito.
• Le prove sono rosse dopo le correzioni: torna all'ultimo commit verde e rifai un pezzo alla volta.

Scarica il metodo

Il metodo per chiudere ogni ondata di lavoro, in un file di testo da tenere accanto al progetto o da dare a Claude Code come istruzione.

Scarica il metodo (TXT) ↓

Come si porta questo modo di lavorare in un team, dalla richiesta al rilascio, lo racconto nella pagina sull'industrializzazione della produzione di software. Per partire dalle basi trovi anche i 10 comandi più importanti di Claude Code.