Claude Code: Best Practice da Uso Reale in Produzione

[Lettura dell’operatore] Uso Claude Code ogni giorno lavorativo in due aziende — un marchio di consulenza e Pickleland, un centro pickleball a Pflugerville, in Texas — per tutto, dalla pipeline di pubblicazione di questo blog al code review sui Worker in produzione. Questo non è un’introduzione a cosa sia Claude Code. Sono le abitudini che ho mantenuto dopo mesi di uso reale, e quelle che ho abbandonato perché mi costavano più di quanto mi facessero risparmiare.

Indice dei contenuti

Apri Indice dei contenuti

• Scrivi il CLAUDE.md come regole, non come documentazione
• Cosa delego a un subagent e cosa tengo nel mio thread
• La gestione del contesto è la disciplina quotidiana, non una configurazione una tantum
• Cosa ho imparato a non lasciargli fare da solo
• Verifica prima di pubblicare — il “fatto” di Claude è un’affermazione, non un dato di fatto
• Il bilancio finale dell’operatore
• FAQ
  • Cosa dovrebbe davvero contenere un file CLAUDE.md?
  • Come decidi quando fidarti dell’output di Claude Code senza ricontrollarlo?
  • Lasci che Claude Code faccia commit e push da solo?
  • Qual è l’unica abitudine che ti ha fatto risparmiare più tempo?

Scrivi il CLAUDE.md come regole, non come documentazione

La prima versione di ogni CLAUDE.md che ho scritto era troppo lunga, e ognuna si è accorciata nel tempo, mai allungata. L’errore è trattarlo come una pagina wiki — contesto, filosofia, “perché facciamo così”. Claude legge il file intero a ogni sessione, che il compito attuale ne abbia bisogno o meno, quindi ogni paragrafo che non è un’istruzione compete per l’attenzione con i paragrafi che lo sono.

Ciò che sopravvive alla potatura è più stretto: regole rigide, idealmente quelle che un test fa rispettare così da non poter regredire in silenzio, più link a documenti più lunghi per i casi che davvero necessitano del dettaglio. “I titoli stanno sotto i 60 caratteri” merita una riga. La storia del perché quel limite esiste merita un link a un documento, non un paragrafo nel file che Claude rilegge a ogni sessione.

La seconda cosa che ho aggiunto, e quella che non mi aspettavo contasse così tanto: un breve elenco di fatti già risolti, scritti una volta, con l’istruzione esplicita di non reindagarli. All’inizio, Claude Code rifaceva la diagnosi dello stesso falso allarme ogni poche sessioni — un controllo instabile, una stranezza nota in un passaggio di build — bruciando contesto per riderivare una conclusione a cui ero già arrivato. Una riga che dichiara il fatto verificato e dice all’agente di andare avanti invece di riaprire l’indagine ha portato quel tempo morto quasi a zero. La regola che uso: se hai spiegato due volte lo stesso “in realtà è previsto”, appartiene al CLAUDE.md come fatto, non come qualcosa che riscrivi in chat una terza volta.

Cosa delego a un subagent e cosa tengo nel mio thread

Ho già scritto il framework decisionale completo su skill, slash command e subagent separatamente, quindi non lo rifaccio qui. Vale la pena aggiungere il filtro a livello operativo che applico davvero prima di generarne uno: riesco a dire in una frase cosa significa “fatto”, e leggerei davvero i passaggi intermedi se restassero nel mio thread principale?

Se la risposta a entrambe è no — il compito è delimitato e voglio solo il risultato — è un subagent. Tradurre questo articolo in 12 lingue è l’esempio più chiaro: ogni traduzione è verificabile in modo indipendente, questa distribuzione in parallelo è esattamente il motivo per cui la pipeline di contenuti fa girare un subagent per lingua, e non vorrei mai che 12 lingue di andirivieni intermedio intasassero il thread dove sto ancora decidendo se l’articolo in inglese è giusto.

Se il compito richiede che io veda il ragionamento mentre accade — una modifica di schema in cui la terza decisione dipende da ciò che ha rivelato la seconda — resta nel mio thread principale. La modalità di fallimento che ho davvero incontrato è generare comunque un subagent per quel tipo di compito, ricevere un riassunto pulito, e poi chiedere “aspetta, cosa hai trovato esattamente” tre volte perché il riassunto ha scartato l’unico dettaglio che contava. Quando succede due volte con lo stesso tipo di compito, smetto di delegarlo.

La gestione del contesto è la disciplina quotidiana, non una configurazione una tantum

Il CLAUDE.md è la parte che si scrive una volta e si dimentica. La finestra di contesto è la parte che gestisco a ogni sessione, ed è quella che determina davvero se il risultato è buono.

• Leggi prima di lasciarlo modificare. Claude Code proporrà volentieri una modifica contro un file di cui non ha visto lo stato attuale completo. Lo faccio sempre leggere prima il file, anche quando sono sicuro di sapere cosa contiene — mi sono sbagliato su quel “sicuro” abbastanza spesso da farlo non più opzionale.
• Non lasciare che una sessione faccia due lavori scollegati. Un thread che ha passato un’ora a debuggare un problema di deploy e poi vira su testi di marketing trascina quell’ora di output di strumenti irrilevanti in ogni risposta successiva. Avvio una nuova sessione invece di chiedere a Claude di “dimenticare il discorso deploy” — quell’istruzione non rimuove i token, chiede solo al modello di ignorarli, e lo fa in modo imperfetto.
• Pianifica prima di lasciarlo eseguire. Per qualsiasi cosa con più di due o tre passaggi, chiedo prima il piano e lo leggo prima di approvare l’esecuzione. Leggere un piano di cinque righe richiede quindici secondi. Scoprire che il passaggio tre era sbagliato dopo che il passaggio cinque è già partito costa il resto del pomeriggio.
• Incollare blocchi enormi è un costo, non una comodità. Buttare un intero file di log o una risposta API completa nella conversazione quando contano solo tre righe brucia contesto sul restante 97%. Faccio prima grep e incollo la corrispondenza.

È lo stesso principio dietro il context engineering per agenti IA in generale — Claude Code rende solo il costo visibile prima, perché sei tu a vedere il contesto riempirsi in tempo reale invece di debuggarlo dopo in un log di un Worker.

Cosa ho imparato a non lasciargli fare da solo

Ogni azione irreversibile — commit, push, pubblicare, inviare, spendere — resta dietro un passaggio di approvazione esplicito che eseguo io stesso, mai uno che Claude Code decide di prendere perché ha giudicato il compito concluso. È lo stesso pattern human-in-the-loop che uso ovunque gli agenti tocchino conseguenze reali, e Claude Code non fa eccezione solo perché gira sulla mia macchina invece che nel cloud.

L’altra cosa che ho smesso di fare: concedere un permesso ampio e permanente per comandi distruttivi. rm -rf, force-push, saltare gli hook dei test — nessuno di questi riceve un sì generale. Ognuno viene chiesto, ogni volta, nel contesto, perché l’unica volta in cui ho pre-approvato qualcosa di ampio “per risparmiare tempo” è stata l’unica volta in cui il compito è slittato verso un ambito che non avevo davvero controllato. I cinque secondi che costa un prompt di permesso sono un’assicurazione economica contro l’alternativa.

Verifica prima di pubblicare — il “fatto” di Claude è un’affermazione, non un dato di fatto

Questa è l’abitudine che si è ripagata di più, ed è la meno appariscente: non mi fido di un report di completamento. Faccio girare il controllo vero.

Claude Code ti dirà che una build è passata, che una suite di test è verde, che un link funziona. A volte quel report è generato da un output reale. A volte è un riassunto sicuro di un comando che è partito solo a metà, o di un controllo tornato presto senza niente di utile dentro. I due sembrano identici nella trascrizione della chat. L’unico modo per distinguerli è guardare tu stesso l’output reale — la stessa disciplina dietro l’eval harness che uso per rilasciare agenti: un compito non è segnato come fatto perché lo dice l’agente, lo è quando il controllo definito passa davvero.

In pratica significa: fai girare il comando di build e leggi il suo output, non la parafrasi di Claude. Apri il file che dice di aver modificato. Clicca sul link che dice funzioni. Per i contenuti in particolare, rileggo la bozza in modo avversariale contro le regole che so essere imposte — limiti di lunghezza, pattern vietati, link interni rotti — invece di fidarmi che Claude le abbia applicate correttamente la prima volta, perché di solito lo fa e occasionalmente no, e il costo dell’errore occasionale che finisce su un sito live è più alto dei novanta secondi che richiede la rilettura.

Il bilancio finale dell’operatore

Niente di tutto questo riguarda il fidarsi meno di Claude Code col tempo — riguarda l’essere precisi su dove quella fiducia deve davvero guadagnarsela. CLAUDE.md brevi ed esigibili invece di documentazione lunga. Subagent per lavoro delimitato e verificabile, il tuo thread per tutto ciò in cui il ragionamento conta quanto il risultato. Contesto fresco invece di una sessione trascinata. Gate di approvazione su tutto ciò che non puoi disfare. E un controllo vero, letto da te stesso, prima che qualsiasi cosa delegata vada live. Questa è tutta la lista, ed è quella che seguo davvero.

FAQ

Cosa dovrebbe davvero contenere un file CLAUDE.md?

Regole che l’agente deve seguire a ogni sessione, formulate come istruzioni — non il contesto del perché il codice è arrivato a essere così. Se una regola è imposta da un test, dillo e lascia che il test sia la fonte di verità. Il contesto più lungo appartiene a un documento a cui il CLAUDE.md rimanda, letto solo quando il compito tocca davvero quell’area, non ricaricato di default a ogni sessione.

Come decidi quando fidarti dell’output di Claude Code senza ricontrollarlo?

Non decido di saltare il controllo — decido quanto costa. Far girare un comando di build è quasi gratis, quindi lo faccio sempre. Una rilettura avversariale completa di un documento lungo richiede più tempo, quindi la riservo a ciò che va davanti a un pubblico reale. L’unica cosa che non salto mai: qualsiasi cosa irreversibile — pubblicare, fare commit, spendere denaro.

Lasci che Claude Code faccia commit e push da solo?

No. Ogni commit e ogni push sono qualcosa che eseguo io stesso, dopo aver guardato il diff. Claude Code propone la modifica; io sono il gate di approvazione per tutto ciò che esce dallo stato di bozza, la stessa regola che applico a ogni altro agente che gestisco.

Qual è l’unica abitudine che ti ha fatto risparmiare più tempo?

Trattare un report di completamento come un’affermazione, non come un dato di fatto, e far girare io stesso il controllo vero. Sembra che rallenti tutto. In pratica è il contrario — beccare un “fatto” falso in trenta secondi è più veloce che scoprirlo in produzione tre giorni dopo.

---

Correlati: Claude: skill vs slash command vs subagent · Lo stack di agenti che uso per gestire 30+ agenti in produzione · Agenti IA human-in-the-loop: quando costruire un gate di approvazione · Come usare le attività pianificate di Claude

Vuoi far girare Claude Code così nella tua azienda? Il mio corso AI Agents for Beginners copre le basi di costruzione che questo manuale presuppone. Il programma cowork è dove insegno queste abitudini operative in un gruppo strutturato. Se preferisci farti costruire il setup, prenota una sessione di 30 minuti.