Quando ho iniziato a usare Claude Code, lo trattavo come una chat.
Chiedevo qualcosa, rispondeva, e basta.
Funzionava, ma col tempo ho iniziato a notare che non ne stavo sfruttando appieno il potenziale.
Ripetevo gli stessi prompt. Eseguivo gli stessi comandi. Non avevo chiaro come sfruttarlo al massimo.
Quindi mi sono fermato e mi sono fatto una domanda:
Come funziona realmente Claude Code al suo interno?
Ho iniziato a leggere la documentazione, a fare esperimenti e a testare.
E ho scoperto questo:
Non fa magia. È costruito su componenti concrete, ognuna con un ruolo preciso. E quando le capisci, tutto il resto inizia ad avere senso.
→ Se ripeti sempre le stesse istruzioni, le trasformi in una Skill.
→ Se perde il filo in un'attività lunga, deleghi a un SubAgent.
→ Se ci sono passaggi manuali che ripeti, li automatizzi con gli Hook.
Capire le basi è ciò che ti permette di sapere cosa usare, quando e perché.
Oggi ho più di 100 Skill, processi automatizzati che prima mi richiedevano ore e agenti per fare code review e studiare argomenti che mi interessano.
Ho scritto questo articolo per condividere tutto ciò che ho imparato con te.
Iniziamo.
Agent Loop: Il Cuore di Claude Code
Claude Code è un agente.
Un sistema a cui dai un obiettivo e che lavora finché non lo raggiunge.
È diverso da una chat. In una chat, chiedi "Come aggiungo l'autenticazione alla mia app?" e ti spiega i passaggi.
Ma devi andare tu sul progetto, modificare il codice e testare se funziona.
Il lavoro lo fai tu.
Con Claude Code, gli dici "Aggiungi l'autenticazione alla mia app" e ci pensa lui.
Legge il codice, sceglie la libreria, scrive le modifiche e ti avvisa quando ha finito.
Ha un obiettivo: aggiungere l'autenticazione.
E lavora finché non lo raggiunge.
Ma come fa a sapere cosa fare dopo ogni passaggio? Come fa a sapere se qualcosa ha funzionato? Ha bisogno di qualcosa che coordini queste decisioni.
Questo è il loop.
Un ciclo che si ripete.
Claude Code esegue un'azione, osserva il risultato, decide cosa fare dopo e ricomincia. Non si ferma finché l'obiettivo non è raggiunto.
Se qualcosa fallisce, torna indietro, corregge e continua.
Il loop ha 3 fasi:
Raccogli contesto → Capisce cosa deve fare. Legge file, analizza codice, esplora la struttura del progetto.
Agisci → Esegue modifiche. Modifica file, esegue comandi, installa dipendenze.
Verifica i risultati → Controlla che ciò che ha fatto funzioni. Esegue test, rivede errori, corregge se qualcosa fallisce.
Il loop si adatta a ciò che chiedi.
Una domanda semplice potrebbe richiedere solo la raccolta del contesto. Risolvere un bug potrebbe attraversare tutte e tre le fasi più volte.
Claude Code decide cosa richiede ogni passaggio in base a ciò che ha imparato dal precedente. E anche tu fai parte di quel loop.
Puoi interrompere in qualsiasi momento per reindirizzarlo, aggiungere contesto o chiedergli di provare un altro approccio.
Questo è il cuore di Claude Code.
Tutto ciò che segue esiste per rendere questo loop più potente.
Strumenti: Come Claude Code Agisce nel Mondo
Un LLM, per progettazione, elabora solo testo.
Riceve testo e genera testo. Non ha accesso al tuo file system, non può eseguire comandi, non sa cosa c'è nel tuo progetto.
È isolato.
Quindi, come fa Claude Code ad aprire un file o modificarlo?
Usa gli strumenti (tools).
Gli strumenti sono funzioni che Claude Code può invocare per interagire con il mondo reale.
Pensala come alle app per cellulari. Il telefono da solo non fa nulla: sono le app che gli danno capacità specifiche: scattare foto, inviare messaggi, navigare.
Gli strumenti sono la stessa cosa per Claude Code.
Ogni volta che usa uno strumento, invia una richiesta al sistema con ciò di cui ha bisogno. Il sistema lo esegue e restituisce il risultato.
Claude Code usa quel risultato per decidere cosa fare dopo.
1La tua richiesta2 ↓3Claude Code decide quale strumento usare4 ↓5┌─────────────────────────────────┐6│ Leggi · Modifica · Scrivi · Bash │7│ Grep · Glob · WebFetch · WebSearch │8└─────────────────────────────────┘9 ↓10Il sistema esegue lo strumento11 ↓12Il risultato torna a Claude Code13 ↓14Finito? → No → usa un altro strumento15 Sì → rispondi
Claude Code viene fornito con strumenti nativi per le operazioni più comuni:
Leggi / Modifica / Scrivi → Legge, modifica e crea file. I più usati. Ogni volta che Claude Code "capisce il tuo codice" o "fa una modifica", sta usando questi tre.
Bash → Accesso completo al terminale. Se puoi farlo da riga di comando, Claude Code può farlo: installare dipendenze, eseguire test, fare commit.
Grep e Glob → Cerca all'interno del progetto. Glob trova file per nome o pattern. Grep cerca contenuti specifici all'interno dei file.
WebFetch e WebSearch → Accesso a Internet. Consulta documentazione, legge un'API, investiga un errore che non ha mai visto prima.
Tornando all'esempio del bug nel pulsante di login.
Quando Claude Code lavora su quello, usa diversi strumenti insieme:
→ Usa Glob per trovare il file del componente
→ Usa Leggi per leggere il codice e capire cosa sta succedendo
→ Usa Modifica per correggere l'errore
→ Usa Bash per eseguire i test e verificare che funzioni
Tutto senza che tu intervenga. Questa è la differenza tra una chat e un agente.
Contesto e Memoria: Cosa Ricorda Claude Code
Claude Code lavora, esegue azioni, ottiene risultati e decide cosa fare dopo.
Ma come fa a sapere cosa ha fatto mentre procede?
Tutto grazie al contesto.
Il contesto è l'informazione che Claude Code ha a disposizione in quel momento. Ogni volta che esegue un'azione, il risultato si accumula lì.
Non solo il tuo prompt iniziale, ma tutto ciò che trova: file che ha aperto, cosa ha scoperto nel codice, le azioni che ha eseguito e i loro risultati.
Ecco perché può concatenare passaggi, correggersi e completare l'attività da solo.
Questo contesto ha 2 problemi.
1. Ha capacità limitata. Se la sessione è molto lunga, il contesto si riempie e Claude Code inizia a dimenticare cosa è successo prima. Più avanti vedrai come i SubAgent risolvono questo problema.
2. Viene svuotato ogni volta che apri una nuova conversazione. Claude Code non sa in quale progetto ti trovi, come lavora il tuo team o quali decisioni sono già state prese. Se non glielo dici, lo deduce o te lo chiede.
La memoria risolve il secondo problema.
È un sistema di file in markdown in cui salvi tutto ciò che Claude Code deve sapere: il tuo stack, le convenzioni del team, come sono strutturati i progetti.
Claude Code li legge all'inizio di ogni sessione e inietta quelle informazioni nel contesto prima che tu scriva la prima riga.
Senza Memoria: Gli dici "aggiungi un endpoint per creare utenti" e Claude Code ti chiede: "Che framework usi? Hai un database configurato? Come sono strutturate le route?"
Con Memoria: Gli dici la stessa cosa e sa già che usi Express con Prisma, che le route vanno in /src/routes e che gli errori sono gestiti con un middleware centralizzato. Inizia a lavorare senza chiedere.
Claude Code ha 2 sistemi di memoria:
→ CLAUDE.md - File Markdown che scrivi con tutto ciò che Claude Code deve sapere. Possono trovarsi a diversi livelli:
→ ~/.claude/CLAUDE.md - Si applica a tutti i tuoi progetti. Qui vanno le tue preferenze personali: come vuoi che scriva il codice, le convenzioni che usi sempre. Le istruzioni devono essere specifiche: "usa 2 spazi di indentazione" è più chiaro di "formatta bene il codice."
→ /tuo-progetto/CLAUDE.md - Specifico per il repository. Qui vanno architettura, convenzioni del team e comandi importanti. Quando inizi un nuovo progetto, esegui /init e Claude Code lo genera automaticamente. Mantienilo sotto le 200 righe: se cresce troppo, Claude Code inizia a ignorare le istruzioni. E se lo commiti nel repo, tutto il team condivide lo stesso contesto.
→ .claude/rules/ - Regole modulari che si attivano in base al tipo di file. Utile quando il progetto cresce e non vuoi mettere tutto in un unico file.
Auto Memoria - La memoria che Claude Code costruisce da solo. Mentre lavori, prende appunti autonomamente: pattern che rileva, correzioni che fai, decisioni prese insieme. Viene salvata in
~/.claude/projects/<progetto>/memory/ e viene caricata all'inizio di ogni sessione.
Revisionala spesso: Claude Code potrebbe aver salvato cattive pratiche senza che tu te ne accorga.
Consiglio: Puoi vedere e modificare tutto ciò che Claude Code ricorda eseguendo /memory.
Hook e Skill: Prendi il Controllo
1. Hook
Claude Code lavora in modo autonomo.
Esegue azioni, prende decisioni, va avanti.
Ma questa autonomia ha un aspetto di cui non si parla tanto: Claude Code fa ciò che ritiene corretto in ogni passaggio.
Se qualcosa va storto, o fa qualcosa che non volevi, è già fatto.
Come lo controlli? Con gli Hook.
Un Hook è un comando che viene eseguito automaticamente in punti specifici del ciclo. Prima che Claude Code usi uno strumento, dopo che lo ha usato, quando la sessione termina.
Tu definisci cosa succede in ogni momento.
Il punto cruciale è che gli Hook sono deterministici.
Non dipendono dal fatto che Claude Code "si ricordi" di fare qualcosa. Vengono sempre eseguiti, senza eccezioni.
I quattro Hook principali sono:
PreToolUse - Viene eseguito prima che Claude Code usi uno strumento. È l'unico Hook che può bloccare un'azione. Esempio: Blocca qualsiasi comando che tenti di modificare i file .env.
PostToolUse - Viene eseguito dopo che Claude Code ha usato uno strumento. Esempio: Esegui Prettier automaticamente ogni volta che Claude Code modifica un file.
Notifica - Viene eseguito quando Claude Code ha bisogno della tua attenzione. Esempio: Ricevi una notifica sul Mac quando Claude Code ha finito un'attività lunga.
Stop - Viene eseguito quando Claude Code finisce di rispondere. Esempio: Fai push automatico in staging quando l'agente finisce.
Si configurano in .claude/settings.json:
1{2 "hooks": {3 "PostToolUse": [4 {5 "matcher": "Edit|Write",6 "hooks": [7 {8 "type": "command",9 "command": "npx prettier --write $file_path"10 }11 ]12 }13 ]14 }15}
Questo Hook esegue Prettier automaticamente ogni volta che Claude Code modifica o crea un file.
Senza che tu glielo chieda. Senza che Claude Code debba ricordarselo.
Senza Hook: Claude Code modifica un file, il codice rimane non formattato e te ne accorgi al prossimo commit.
Con Hook: Claude Code modifica un file, PostToolUse si attiva automaticamente, Prettier formatta il file e il codice è sempre pulito.
Gli Hook ti permettono di aggiungere comportamenti garantiti al ciclo dell'agente. Non suggerimenti, non istruzioni che il modello può ignorare. Regole che vengono sempre eseguite.
2. Skill
C'è un altro problema: la coerenza.
Chiedi la stessa attività due volte e ottieni risultati diversi. Ogni volta che apri una nuova conversazione, Claude Code ricomincia senza sapere come hai fatto l'ultima volta.
Come lo risolvi? Con le Skill.
Una Skill è un file Markdown in cui spieghi il processo esatto per un'attività a Claude Code: cosa rivedere, in quale ordine, che formato usare, cosa ignorare.
Ogni volta che quell'attività si presenta, Claude Code segue quelle istruzioni.
Senza Skill: Gli chiedi di documentare un'API e genera qualcosa, ma ogni volta con un formato diverso. A volte con esempi, altre senza.
Con Skill: Gli chiedi di documentare un'API e segue il processo esatto che hai definito. Sempre con gli stessi passaggi, lo stesso formato, gli stessi criteri. Ogni volta uguale.
Per creare una Skill, definisci una cartella con questa struttura:
1my-skill/2├── SKILL.md # Istruzioni principali (obbligatorio)3├── template.md # Template che Claude completa4├── examples/5│ └── sample.md # Esempio di output atteso6└── scripts/7 └── validate.sh # Script che Claude può eseguire
L'unico file obbligatorio è SKILL.md. Il resto è opzionale e lo aggiungi in base a ciò di cui l'attività ha bisogno.
SKILL.md ha 2 parti:
Il frontmatter - Un blocco YAML con nome e descrizione. Il nome è il comando per invocarla manualmente. La descrizione è ciò che Claude Code legge per decidere quando attivarla automaticamente.
Il corpo - Le istruzioni in Markdown. Il flusso di lavoro, i criteri, il formato dell'output.
1---2name: api-docs3description: Documenta gli endpoint API. Usalo quando l'utente4 chiede di documentare un'API o menziona "swagger" o "endpoint"5---67## Processo81. Identifica tutti gli endpoint92. Per ognuno: metodo, percorso, parametri, risposta attesa103. Includi un esempio di richiesta e risposta114. Concludi con una tabella riassuntiva
Una volta creata, puoi invocarla in due modi.
Scrivendo /api-docs direttamente nella chat, o semplicemente chiedendo a Claude Code in linguaggio naturale.
Se la descrizione corrisponde a ciò che stai chiedendo, si attiva da sola.
Puoi crearle per qualsiasi attività che ripeti con un processo chiaro alle spalle: documentazione API, changelog, riunioni di riepilogo, migrazioni di codice.
SubAgents: Delega Quando il Problema Cresce
Abbiamo già visto che il contesto ha capacità limitata.
Più lunga è la sessione, più si riempie. E quando si riempie, Claude Code inizia a perdere informazioni su ciò che è successo prima.
Immagina di chiedergli di revisionare l'intero progetto per problemi di sicurezza. Legge dozzine di file, analizza il codice, genera un report dettagliato.
Tutto questo riempie rapidamente il contesto.
E mentre lo fa, la tua conversazione principale è bloccata.
Come lo risolvi? Con i SubAgenti.
Un SubAgent è un'istanza separata di Claude Code che opera con il proprio contesto.
L'agente principale delega un'attività a lui, il SubAgent la esegue in modo indipendente e, quando finisce, invia un riepilogo con i risultati.
Il contesto dell'agente principale non si riempie con l'intero processo, ma solo con la conclusione.
1Agente Principale2 ↓3"revisiona il progetto per problemi di sicurezza"4 ↓5┌─────────────────────────────┐6│ SubAgent: security-reviewer │7│ │8│ Legge i file del progetto │9│ Analizza il codice │10│ Rileva vulnerabilità │11│ Genera un report │12└─────────────────────────────┘13 ↓14Restituisce il riepilogo all'agente principale15 ↓16L'agente principale continua con il loop
E non solo.
I SubAgenti possono essere eseguiti in parallelo.
Invece di analizzare tre parti del codice in sequenza, Claude Code può delegarle tutte e tre contemporaneamente.
Quello che prima richiedeva minuti, ora può richiedere secondi.
1Agente Principale2 ↓3Divide il lavoro in attività indipendenti4 ↓5┌──────────────┐ ┌──────────────┐ ┌──────────────┐6│ SubAgent 1 │ │ SubAgent 2 │ │ SubAgent 3 │7│ │ │ │ │ │8│ Revisiona │ │ Revisiona DB │ │ Revisiona │9│ autenticaz. │ │ │ │ API esterne │10└──────────────┘ └──────────────┘ └──────────────┘11 ↓ ↓ ↓12 L'agente principale riceve i tre riepiloghi13 ↓14 Continua con il loop
Claude Code ha 3 SubAgenti nativi che usa automaticamente:
→ Explore - Un agente veloce e di sola lettura specializzato nella ricerca e nell'analisi del progetto. I risultati rimangono nel contesto del SubAgent, non nel tuo.
→ Plan - Si attiva in modalità plan. Prima di presentarti un piano, Claude Code delega l'esplorazione del progetto a questo agente.
→ Scopo generale - Per attività complesse che richiedono sia esplorazione che modifiche.
Puoi anche crearne di tuoi.
I SubAgenti vengono definiti in file Markdown con frontmatter YAML e salvati in .claude/agents/.
1---2name: security-reviewer3description: Revisiona il codice per vulnerabilità di sicurezza.4 Usalo quando l'utente chiede una revisione della sicurezza.5tools: Read, Grep, Glob6---78Sei un esperto di sicurezza. Analizza il codice per:9- SQL Injection10- Esposizione di dati sensibili11- Vulnerabilità di autenticazione1213Concludi con un riepilogo dei risultati ordinati per gravità.
Nota che nel frontmatter limitiamo gli strumenti a Read, Grep e Glob.
Questo agente può analizzare ma non modificare mai nulla.
Quando hai bisogno di un controllo preciso su ciò che ogni agente può fare, questa restrizione sugli strumenti è fondamentale.
Una volta creato, Claude Code lo rileva automaticamente tramite la descrizione e lo invoca quando l'attività corrisponde. Oppure puoi chiamarlo esplicitamente: "usa l'agente security-reviewer per revisionare questa PR."
Quando usare i SubAgenti e quando no?
Ha senso quando l'attività è lunga e genererà molto output, quando puoi dividere il lavoro in parti indipendenti che possono essere eseguite in parallelo, o quando hai bisogno di un agente specializzato con strumenti limitati.
Non vale la pena per attività brevi che non riempiono il contesto. Coordinare i SubAgenti aggiunge complessità che non ha senso se l'agente principale può risolvere l'attività in due minuti.
MCP: Collegare l'Agente con il Mondo Esterno
Gli strumenti danno a Claude Code la capacità di agire sulla tua macchina.
Ma c'è un limite: tutto ciò che accade, accade lì.
Non può aprire una PR su GitHub, interrogare un database di produzione o creare un ticket in Jira. Per farlo, prima dovevi lasciare l'agente e farlo manualmente.
Come lo risolvi? Con MCP.
MCP (Model Context Protocol) è un protocollo aperto che definisce come Claude Code si collega ai servizi esterni.
Funziona con un'architettura client-server: Claude Code è il client, e ogni servizio esterno ha il proprio server MCP che espone ciò che può fare.
Quando connetti un server MCP, Claude Code riceve un elenco di strumenti disponibili con il loro nome e descrizione.
Da lì, li usa esattamente come gli strumenti nativi. L'unica differenza è che l'azione avviene nel servizio esterno, non sulla tua macchina.
1Claude Code2 ↓3Decide di usare uno strumento dal server MCP di GitHub4 ↓5┌─────────────────────────────┐6│ Server MCP GitHub │7│ │8│ Apre la PR │9│ Assegna i revisori │10│ Restituisce conferma │11└─────────────────────────────┘12 ↓13Claude Code riceve il risultato e continua
Senza MCP: Gli dici "Ho finito le modifiche, apri la PR" e Claude Code non può. Devi andare su GitHub, compilare il modulo, assegnare i revisori e fare il merge da solo.
Con MCP: Gli dici la stessa cosa e Claude Code apre la PR, scrive la descrizione, assegna i revisori e ti avvisa quando è pronto. Tutto senza che tu lasci l'agente.
Alcuni server MCP che puoi connettere oggi:
→ GitHub - PR, revisioni, issue
→ Postgres / Supabase - Interroga e modifica database
→ Slack - Messaggi e canali
→ Jira - Ticket e progetti
Strumenti nativi per il tuo ambiente locale. MCP per il mondo esterno.
Come Tutto Si Inserisce Insieme
Claude Code è un agente: un sistema che prende un obiettivo e opera in un ciclo autonomo finché non lo raggiunge.
Ogni componente che hai visto in questo articolo esiste per rendere quel ciclo più potente. Ma il modo migliore per capirlo è vederli interagire insieme.
Caso 1: Revisiona e fai il merge di una PR
Chiedi a Claude Code: "Revisiona la PR #42 e se va tutto bene, falla merge."
→ Usa GitHub MCP per leggere i file modificati e capire i cambiamenti
→ Delega l'analisi della sicurezza a un SubAgent specializzato, per non riempire il contesto principale
→ Un Hook esegue i test localmente e verifica che tutto passi
→ Se i test passano, usa GitHub MCP per eseguire il merge senza che tu tocchi l'interfaccia
Hai scritto una riga. Claude Code ha coordinato quattro sistemi.
Caso 2: Documenta un'API e avvisa il team
Chiedi a Claude Code: "Documenta i nuovi endpoint e informa il team."
→ Attiva una Skill di documentazione che definisce il formato esatto: cosa includere, come strutturare, quali esempi aggiungere
→ Usa gli Strumenti per leggere il codice ed estrarre gli endpoint
→ Un Hook formatta l'output prima di salvarlo
→ Usa Slack MCP per inviare il riepilogo al canale del team
Ogni volta che lo fai, il risultato sarà lo stesso. Senza variazioni, senza che tu debba spiegare nulla.
Tutto ruota attorno al loop.
La memoria per iniziare ogni sessione informata. Gli strumenti per agire. Gli Hook per controllare. Le Skill per standardizzare. I SubAgenti per scalare. MCP per connettersi con il mondo esterno.
Quando capisci questo, capisci Claude Code.
E non solo Claude Code: Cursor, Copilot e qualsiasi agente che userai d'ora in poi opera sugli stessi fondamenti.
I nomi cambiano, l'interfaccia cambia, ma il loop è lo stesso.
L'IA avanza velocemente.
Ogni settimana c'è qualcosa di nuovo. Ma le basi non cambiano così spesso. Averle chiare è ciò che ti permetterà di adattarti più velocemente e ottenere di più da ciò che verrà.
Non usare Claude Code solo per fare prompt. Presta attenzione a ciò che accade sotto. È lì che ci sono le opportunità.
Alcuni punti di partenza per iniziare oggi:
→ Rivedi la tua Auto Memoria e migliora ciò che Claude Code ha salvato
→ Crea un CLAUDE.md per il tuo progetto se non ce l'hai
→ Connetti il server MCP di GitHub
→ Costruisci un SubAgent per attività che riempiono il contesto
→ Configura un Hook che esegue i test dopo ogni modifica
Questo è tutto, ci vediamo domani.
Marcus
