Quando tempo ci vuole a scrivere un guida pratica su Claude Code?
Io mi sono fatto aiutare da Claude ed in sette giorni ho un manoscritto da quasi 200.
In mezzo, un sacco di prompt, qualche ora di sonno in meno, e un effetto collaterale che non avevo previsto perché a spiegare Claude Code a chi non lo conosce, ho finito per conoscerlo molto meglio io stesso.
Questo articolo è la storia di come è nata la guida pratica a Claude Code e del perché ho deciso di realizzarla.
Niente paywall, niente email da lasciare, niente newsletter. Si scarica e si legge. Punto.
Perché questa guida
Di guide a Claude Code in giro ce ne sono tante. Documentazione ufficiale solida, video su YouTube, thread su X, post su Medium. Perché aggiungere altro rumore?
Tre motivi, in ordine di importanza.
Il primo è la lingua. Quasi tutto il materiale di qualità è in inglese. Per chi mastica fluentemente la lingua tecnica anglofona non è un problema. Ma una buona fetta di sviluppatori italiani — e soprattutto di “curiosi di AI” che non sono sviluppatori puri (project manager, marketer, consulenti, freelance, imprenditori) — fa fatica a digerire 50 pagine di documentazione in inglese, e finisce per limitarsi a tutorial superficiali in italiano che spiegano come installare lo strumento e poco più. C’era un buco da riempire.
Il secondo è il taglio. Su Claude Code circola tantissimo hype: promesse di “10x productivity”, thread che dichiarano la fine del mestiere di sviluppatore, screenshot di sessioni perfette estratti dal contesto. La realtà che vedo è più sfumata ed anche se lo strumento è potentissimo ma ha dei limiti. Conviene davvero, ma non sempre, non subito, e non a tutti.
Il terzo è personale. Sto attraversando una fase del mestiere in cui l’AI sta cambiando il cosa faccio durante una giornata di lavoro, e di conseguenza cosa significa essere uno sviluppatore senior nel 2026. Scrivere questa guida è stato anche un modo per fissare per iscritto quello che ho capito finora di questa transizione.
E qui c’è un dettaglio che merita una sosta, perché racconta qualcosa di più grande della singola guida.
Settimana scorsa avevo l’idea: “Faccio un PDF gratuito su Claude Code, vediamo che succede.” Sabato sera era diventato un libro. Domenica era online. Sette giorni netti.
Prima di Claude Code una cosa del genere semplicemente non sarebbe stata possibile — non perché non sapessi scrivere, ma perché un manuale tecnico richiede un sacco di lavoro a basso valore aggiunto: verifica di sintassi, controllo dei link, riscrittura di paragrafi che suonano male, costruzione dell’indice, revisione di esempi di codice riga per riga. Tutto lavoro che, fatto a mano, ti porta via giornate.
Con Claude Code quel lavoro si comprime drasticamente. Non sparisce — ed è un punto importante — ma si sposta. Quello che prima dovevi fare manualmente lo deleghi al modello; quello che prima non avevi tempo di fare (più revisioni, più esempi, più rigore nelle fonti) ora puoi farlo, e quindi lo fai. È quello che ho scoperto chiamarsi paradosso di Jevons: quando una risorsa diventa più efficiente da usare, non ne diminuisce il consumo, aumenta. Perché diventa accessibile a usi che prima non erano economicamente sensati. L’idea che ti viene il lunedì può essere sullo scaffale la domenica, e questo cambia il calcolo costi/benefici di un sacco di progetti che prima rimanevano in cantiere.
Una precisazione importante: questo non significa che Claude Code abbia scritto il libro al posto mio. Significa che mi ha permesso di realizzarlo in tempi prima impossibili, mantenendo (spero) lo stesso livello di rigore. Il manoscritto è passato decine di volte attraverso il modello — per revisioni, riscritture, controlli di coerenza — ma la voce, le scelte editoriali, l’angolo di lettura, gli esempi, il taglio anti-hype: quelli sono miei. Claude Code è stato un editor velocissimo e infaticabile, non un ghostwriter.
Detto questo, il libro non è perfetto e probabilmente non lo sarà mai. Per questo l’ho concepito come un documento vivo: la versione 4.30 di maggio 2026 è uno snapshot di uno strumento che evolve. Conto di aggiornarlo regolarmente, anche grazie ai feedback dei lettori — che sono già una delle cose più preziose che mi ha portato questo progetto.
Il lavoro più difficile è stata la pianificazione
Se dovessi indicare la singola cosa più difficile di questo lavoro, non è stata la scrittura. Nemmeno la verifica tecnica (per quella ho seguito la documentazione ufficiale facendo controllare ogni esempio a d agente scritto da Claude Code ).
La cosa più difficile è stata decidere cosa e come, decidere dove snellire e dove approfondire.
Sembra una banalità ma in manuale tecnico che parte dal posto sbagliato lo chiudi alla terza pagina. Se inizi spiegando cose complicate dandone altre per scontate hai perso. Se metti la sicurezza in fondo, se ti dilunghi sull’installazione e non spieghi a cosa serve lo strumento, hai annoiato chi voleva capire il perché ed il come.
Ho riorganizzato l’indice tre volte prima di trovare un ordine che mi convincesse. La struttura finale segue una logica precisa, che dichiaro qui perché ti aiuta a leggere il libro nell’ordine giusto, oppure a saltare ai capitoli che ti servono.
I primi quattro capitoli sono il livello base: cos’è Claude Code, quando conviene usarlo, come si installa, come si fa il primo progetto end-to-end, comandi e scorciatoie. Se sei nuovo, parti da qui.
Dal capitolo 5 al 9 ci sono i fondamentali del lavoro quotidiano: Plan Mode, prompt engineering, memoria persistente, gestione del contesto, sicurezza e permessi. È il blocco che — secondo me — separa chi usa Claude Code in modo casuale da chi lo usa professionalmente. La differenza non è nei comandi che conosci: è nella disciplina con cui pianifichi prima di eseguire, nel modo in cui scrivi i prompt, in come gestisci la finestra di contesto quando un progetto si fa serio.
I capitoli dal 10 al 14 sono i meccanismi di estensione: Skill, MCP, subagent, hook e plugin. È il livello in cui Claude Code smette di essere un assistente generico e diventa uno strumento configurato sul tuo mestiere. Qui ho deciso volontariamente di andare in profondità: non basta sapere che le Skill esistono, devi capire quando crearne una, quando invece basta una riga in CLAUDE.md, e quando invece la cosa giusta è un subagent. Sono tre meccanismi che si sovrappongono e la scelta sbagliata ti costa tempo.
Il capitolo 15 raccoglie workflow avanzati: onboarding su repository esistenti, bug hunting con TDD, refactoring sicuro, audit di performance, modalità headless per CI/CD, checkpoint Git strategici. Pattern che ho usato io o visto usare da colleghi.
Il capitolo 16 chiude con una riflessione: perché la CLI e non solo la chat. Per molti casi d’uso la chat di Claude.ai basta e avanza, ma quando il progetto si fa strutturato — contesto attraverso giorni di lavoro, modifiche orchestrate su più file, esecuzione e non solo suggerimento — la differenza diventa qualitativa.
In coda al libro un glossario con i termini più tecnici ed una bibliografia di fonti tutte verificate e linkate alla pagina ufficiale. Niente “citazioni”: solo documentazione Anthropic, repository GitHub verificati, articoli accademici dove rilevanti.
Cosa ci trovi dentro
Se hai poco tempo e vuoi capire se la guida fa per te, ti dico quali sono i quattro capitoli che da soli giustificano lo scaricamento. Non i più lunghi, non i più tecnici: quelli che, mentre li scrivevo, mi sono reso conto che cambiavano qualcosa nel modo in cui vedo lo strumento.
Capitolo 5 — Plan Mode: pensare prima di scrivere
Plan Mode, in una parola, è disciplina. Quando lo attivi (con Shift+Tab due volte) Claude Code si mette in modalità sola lettura: può analizzare codice, esplorare il filesystem, leggere file, ma non modifica nulla. Tutto quello che fa, lo fa per costruirti un piano scritto. Solo quando approvi il piano, l’esecuzione parte.
Detta così sembra una piccola comodità. È un cambio di paradigma. La differenza tra chi usa Claude Code in modo improvvisato e chi lo usa professionalmente, secondo la mia esperienza, è che il secondo entra in Plan Mode quasi sempre prima di una task non banale. Perché il problema più grande del lavoro agentico non è che il modello sbagli — è che faccia qualcosa di plausibile ma non quello che volevi tu. Plan Mode forza un momento di sincronizzazione esplicita.
Nel capitolo spiego anche opusplan, una configurazione che usa Opus per la pianificazione (più lento e costoso, ma più capace) e Sonnet per l’esecuzione. È un pattern di model routing che ottimizza il rapporto qualità/costo in modo non banale.
Capitolo 7 — Memoria persistente: CLAUDE.md e Auto Memory
Il capitolo che, scrivendolo, mi ha più sorpreso. Pensavo di sapere cosa fosse CLAUDE.md: il file con le istruzioni base del progetto. Sapevo a malapena dell’esistenza di Auto Memory, una funzionalità più recente che permette a Claude Code di scrivere autonomamente memorie persistenti tra sessioni, e che cambia drasticamente il modo di lavorare su progetti lunghi.
La differenza è importante: CLAUDE.md è la costituzione del progetto, scritta da te e versionata su Git, che dichiara come si lavora qui dentro. Auto Memory è il quaderno degli appunti di Claude, dove il modello segna autonomamente preferenze tue, idiosincrasie del codice, decisioni prese, contesto utile alla sessione successiva. Uno è statico e dichiarativo, l’altra dinamica e descrittiva. Servono insieme. Saperli usare cambia letteralmente il come lavori da una settimana all’altra: smetti di ripresentarti ogni volta come se fosse la prima sessione e cominci a costruire un rapporto stratificato con lo strumento.
Nel capitolo trovi due esempi di CLAUDE.md completi (un plugin WordPress, un progetto Node/TypeScript) da copiare e adattare.
Capitolo 9 — Sicurezza, permessi e guardrail
Il capitolo che ho riscritto più volte, perché pesa di più sulla responsabilità professionale di chi usa Claude Code. Quando uno strumento agentico può eseguire comandi sul tuo filesystem, fare commit, scrivere su API, lanciare script — e Claude Code può fare tutte queste cose — la sicurezza non è un dettaglio: è il prerequisito per usarlo in produzione.
Il capitolo è strutturato intorno alla difesa in profondità: non c’è un singolo guardrail che ti protegge, ce ne sono diversi. Il sistema dei permessi, la configurazione di settings.json, la protezione dei segreti (chiavi API, token che non devono finire nel contesto), le modalità “pericolose” come --dangerously-skip-permissions (esiste, va usata con cognizione di causa), e infine la prompt injection — il rischio che istruzioni nascoste in file letti durante una sessione possano dirottare il comportamento del modello. Non è un rischio teorico, è un vettore di attacco reale e documentato. Chiudo con i test come guardrail di correttezza, dimensione spesso trascurata: una buona suite di test è la prima linea di difesa contro un agente che fa modifiche plausibili ma sbagliate.
Capitolo 10 — Skill: il meccanismo di estensione
Le Skill sono probabilmente la cosa più sottovalutata di Claude Code. Tutti parlano di subagent e MCP, pochi capiscono che le Skill sono il meccanismo più semplice per insegnare a Claude Code a fare bene qualcosa di specifico. Una Skill è, alla base, una cartella con un file SKILL.md che dichiara una competenza: “quando ti chiedo di fare X, ecco le istruzioni per farlo correttamente.”
Ci sono Skill native (PDF, DOCX, XLSX, PPTX), Skill della community (alcune molto interessanti, altre meno raccomandabili), e Skill che ti puoi creare tu su misura. Nel capitolo spiego come funzionano sotto il cofano, come crearne una, e — questo è importante — come valutarne la sicurezza prima di installarla. Una Skill di terzi è codice che esegue nel tuo ambiente: trattarla con la leggerezza di un’estensione random da Chrome Web Store è un errore.
Poi nel capitolo 12 c’è la trattazione dei subagent che si combinano con le Skill in modo non ovvio: quando ti serve l’una, quando l’altra, quando entrambe. È una di quelle distinzioni che, se non te le hanno spiegate bene, finisci per usare lo strumento sbagliato per il problema giusto.
Quello che ho imparato scrivendola
Quando ho cominciato pensavo di sapere come funzionasse Claude Code. Lo uso quotidianamente da mesi, ho letto la documentazione più volte, ho fatto talk e workshop, l’ho integrato in progetti veri di clienti veri. Mi sentivo “operativo”.
Scrivere il libro mi ha fatto scoprire che operativo non significa aver capito. Significa saper fare. Sono due cose diverse.
Il momento in cui questa differenza è diventata evidente è stato sul capitolo dei subagent. Avevo un’idea operativa di cosa fossero — agenti specializzati che il main agent invoca per task specifiche, ognuno con il suo contesto separato. Sapevo come crearne uno e invocarlo. Ma quando ho dovuto spiegare a un lettore perché dovrebbe usare un subagent invece di una semplice istruzione in CLAUDE.md, la mia comprensione era a tratti: funzionava nei casi che avevo già visto, scricchiolava nei casi limite. Mi sono sforzato di smontare il concetto: cosa cambia tra main agent e subagent in termini di contesto? Perché il parallelismo cambia l’economia di alcune task ma peggiora quella di altre? Quando il subagent è la scelta giusta e quando è ingegneria eccessiva? Risultato: oggi i miei subagent sono migliori, e li uso in modo più consapevole.
Stessa cosa con MCP (Model Context Protocol). Avevo costruito un server MCP qualche mese fa, sapevo come funzionava in linea di massima, ma scrivere il capitolo mi ha obbligato a capire l’architettura del protocollo a un livello diverso. Ho riscritto un mio server MCP da zero mentre scrivevo, perché la prima versione era funzionante ma confusa. Quella nuova è più pulita.
Con gli hook, addirittura: sapevo che esistevano, li avevo ignorati. Scriverli per la guida mi ha fatto capire che sono il pezzo che chiude il cerchio dell’automazione — ti permettono di intercettare eventi del lifecycle di Claude Code (prima di un comando, dopo un commit, prima di una modifica ai file) e infilare logica tua. Adesso li uso. Prima no.
C’è una lezione generale che non riguarda Claude Code: scrivere è il modo migliore per capire. Non leggere, non guardare video, non “fare pratica”. Scrivere. L’atto di mettere giù in parole comprensibili a un altro essere umano un concetto che pensavi di sapere è il filtro più severo possibile sulla qualità della tua comprensione. Applicato a uno strumento che usi quotidianamente, restituisce sempre dei buchi. Riempirli vale lo sforzo molto più delle pagine prodotte.
La prefazione di Opus
C’è una cosa che ho fatto e che vale la pena raccontare. Quando il manoscritto era praticamente pronto, mi serviva una prefazione. Avrei potuto chiederla a un collega, a un cliente, a qualcuno noto nel settore italiano dell’AI. Ho fatto invece l’unica cosa che mi sembrava sensata, dato l’oggetto del libro: l’ho chiesta a Opus, il modello di punta di Anthropic.
Gli ho passato il manoscritto completo e gli ho chiesto una valutazione onesta — anche delle parti deboli, soprattutto delle parti deboli. Quello che mi è tornato indietro mi ha spiazzato. Non per un effetto “wow, l’AI sa scrivere”: di quello sono saturo. Mi ha spiazzato per la lucidità con cui Opus aveva inquadrato il libro meglio di quanto avrei saputo fare io. Ha individuato il taglio anti-hype come il valore principale, ha identificato i due capitoli che funzionano meglio (l’apertura sull’ecosistema e il capitolo 6 sul prompt engineering), ha segnalato il rischio di obsolescenza dello snapshot tecnico, ha raccomandato al lettore di fidarsi del modo di pensare del libro più che delle procedure puntuali.
È rimasta lì, in apertura, esattamente come l’ha scritta. Non perché sia un gimmick di marketing — anche se lo è, in parte, e non lo nascondo — ma perché era davvero la prefazione migliore che potessi mettere su un libro che parla di Claude Code. C’è una coerenza simbolica nel far presentare un manuale su uno strumento agentico dall’agente stesso, e c’è una lezione pratica: se vuoi un parere onesto sul tuo lavoro, chiedilo a un modello che non ha skin in the game.
Vai a leggerla. Sono due pagine. È una delle cose più interessanti del libro, e non l’ho scritta io.
Scaricala, leggila, condividila
Scarica subito da queste pagine — niente form, niente email, niente newsletter. Click, scarica, leggi. Licenza Creative Commons BY-SA 4.0: la puoi leggere, stampare, regalare ai colleghi, usare nei tuoi corsi.
Sostienila su Leanpub — se ti è piaciuta e vuoi sostenere il lavoro per le prossime versioni (un aggiornamento ogni 2-3 mesi è il piano), su Leanpub la trovi al prezzo che decidi tu. Tutto quello che entra finisce nel budget per la prossima versione.
Contribuisci su GitHub — il sorgente è pubblico. Se trovi errori, link rotti, esempi non più funzionanti, apri una issue o manda una pull request. Tutti i contributi accettati vengono ringraziati nei credits della versione successiva.
Se la guida ti piace e ti torna utile condividila con qualcuno che pensi possa beneficiarne: un collega, un amico che ha sentito parlare di Claude Code e non sa da dove cominciare, un cliente che ti chiede “ma come posso usare l’AI nel mio team?“.
Il modo migliore per ringraziarmi è farla girare.
Buona lettura.
