Introduzione all'agentic coding con Claude Code: installazione e configurazione

Questo articolo è la seconda parte della serie su Claude Code. Nel primo articolo abbiamo visto l’installazione, i comandi di base e la configurazione del tool.

Sistemate le configurazioni di base, possiamo passare all’azione. Ci sono tre modalità di utilizzo per gestire una richiesta, si può cambiare modalità premendo shift+tab:

1. default
2. auto-accept: il tool non chiederà review delle modifiche che applicherà (chiederà i permessi read/write prima di fare qualsiasi modifica)
3. plan mode: il tool non farà implementazioni, ma creerà un piano d’azione per completare la richiesta dell’utente.

Su una codebase che non si conosce, è di solito molto efficiente chiedere di analizzare la struttura del progetto (o di una parte di esso se molto voluminoso): personalmente, trovo utile salvare i risultati in un file .md dedicato, in modo da averli sempre disponibile per me o come parte del contesto per nuove richieste. Si possono infatti referenziare i file (@ mostrerà i file a partire dal path in cui ci si trova) nella chat e Claude lì prenderà in considerazione.

La specifica di un file da leggere, tramite relative o absolute path, è molto utile per modifiche puntuali, permettendo di salvare token di utilizzo e dimensioni del contesto. Come quando si sviluppa di persona, è bene sempre specificare al tool di creare test per verificare la correttezza del codice, senza.

Gestione del contesto

Un concetto chiave nell’agentic coding è la precisione del contesto fornito all’agente con cui stiamo collaborando (idem per una semplice chat con un LLM): il contesto rappresenta infatti la mappa che l’agente usa per orientarsi all’interno del task. Costruire un contesto preciso e della giusta dimensione, il contesto non è infinito, ottimizza notevolmente le performance e la quantità di token utilizzati.

Anche nella gestione del contesto, è possibile istruire il modello per tenere traccia dei progressi. Per esempio, possiamo dire al modello di usare un file .md in modo da poter rigenerare il contesto senza perdere gli avanzamenti degli step già conclusi. Questo tipo di approccio migliora notevolmente l’affidabilità dei modelli su compiti di media/lunga durata.

Architettura e struttura della personalizzazione

Claude Code offre una personalizzazione con una granularità molto elevata. Come visto nel primo articolo, l’architettura del tool è organizzata su due livelli distinti: configurazioni globali e configurazioni specifiche per progetto.

Configurazione globale: ~/.claude/

Nella root directory del tool, possiamo specificare le configurazioni che vogliamo applicare a qualsiasi progetto su cui lavoriamo:

• settings.json: configurazione fondamentale che controlla il comportamento generale del tool (modalità di thinking, limiti di token, plugin abilitati)
• skills/: cartelle contenenti competenze specifiche di dominio (pattern di linguaggio, convenzioni AWS, linee guida per code review)
• commands/: comandi personalizzati che fungono da scorciatoie per workflow ricorrenti (analisi bug, semplificazione codice, review delle modifiche)
• hooks/: regole di enforcement attive che impediscono o avvertono di pattern non desiderati nel codice

Configurazione a livello di progetto

All’interno di ogni progetto, come visto in precedenza con il file CLAUDE.md, possiamo definire configurazioni specifiche:

• .claude/.agent/: documentazione di riferimento caricata on-demand (pattern di coding, strategie di debugging, checklist di review)
• hookify.*.local.md: regole di enforcement specifiche per il progetto***

Il file CLAUDE.md merita, come già detto in precedenza, particolare attenzione: rappresenta di fatto un system prompt che controlliamo direttamente.

Ogni istruzione inserita presente in questo file influenza le risposte di Claude. Definendo pattern di escalation (ad esempio, dopo due tentativi falliti di fix, attiva un’analisi strutturata del bug in 6 step) si evita che Claude continui a iterare sulla stessa soluzione inefficace.

Skills: come insegnare competenze specifiche

Le skills sono file markdown che trasferiscono conoscenza specializzata al modello. Claude le carica automaticamente quando rilevanti. Ad esempio, una skill per pattern TypeScript può specificare:

• Preferire l’inferenza dei tipi rispetto ai type annotation espliciti sui return
• Non usare mai il prefisso I per le interfacce
• Utilizzare for...of invece di .forEach()
• Strutturare i Lambda handler con gestione errori standardizzata

Le skills possono coprire qualsiasi dominio: pattern serverless AWS, convenzioni di code review, anti-pattern da evitare nel codice generato dall’IA: la differenza rispetto a semplici linee guida è che Claude le applica attivamente, non passivamente.

Sistema di hooks

Gli hooks intercettano pattern indesiderati in tempo reale, prima che il codice venga scritto. Utilizzando il plugin hookify (parleremo dei plugin tra pochissimo), è possibile creare regole di enforcement dichiarative. Qualche esempio restando nel dominio TypeScript:

• warn-any-type: avvisa quando si usa : any, <any> o any[]
• block-as-any: blocca completamente i cast as any
• warn-foreach: segnala l’uso di .forEach() suggerendo for...of
• block-hardcoded-secrets: impedisce l’inserimento di chiavi API hardcoded

Ogni hook è un file markdown con frontmatter YAML che specifica il pattern regex da intercettare e l’azione da intraprendere (warn o block). Il feedback è immediato: Claude vede il warning, si corregge, continua. Poiché Claude Code non mantiene stato tra sessioni, gli hooks forniscono enforcement consistente ogni volta. Data l’ampio spettro di personalizzazione, è bene definire Hooks e Skills a livello globale, in modo da poterle utilizzare in ogni progetto evitando ridondanze o inconsistenza non necessarie.

Plugin per capacità estese

I plugin aggiungono strumenti e workflow al toolkit di Claude. Ne esistono molti, ne riportiamo alcuni molto famosi:

• dev-browser: automazione browser per testare applicazioni web in sviluppo
• pr-review-toolkit: esegue sei agenti di review in parallelo (analisi commenti, test coverage, errori silenziosi, design dei tipi, compliance, semplificazione)
• ralph-wiggum: loop iterativi auto-referenziali per task complessi, dove Claude migliora il proprio lavoro leggendo l’output delle iterazioni precedenti
• commit-commands: automatizza generazione di commit message, creazione PR, pulizia branch

Il plugin ralph-wiggum è particolarmente interessante per task greenfield con criteri di successo chiari e verifiche automatiche. Funziona intercettando i tentativi di uscita di Claude e reinviando lo stesso prompt, permettendo a Claude di iterare vedendo file modificati e git history. Ogni iterazione migliora basandosi sul lavoro precedente.

Nota importante: prima di installare un plugin, informatevi sempre sull’origine del plugin e come viene distribuito, i rischi di utilizzare plugin malevoli non va mai trascurato.

Comandi personalizzati

I comandi sono scorciatoie per workflow complessi. Invece di specificare ogni volta istruzioni dettagliate, si invoca un comando /bug-analyser o /simplify e si ottiene una risposta strutturata e consistente. Alcuni possibili esempi pratici:

• /bug-analyser: analisi root cause in 6 step per bug ostinati
• /feature-planner: scomposizione di feature complesse in stage implementabili
• /review-diff: review delle modifiche rispetto alle linee guida del progetto
• /take-notes: cattura decisioni e contesto durante lo sviluppo

È interessante notare come l’effetto combinato di skills, hooks, comandi e plugin porti a miglioramenti esponenziali: ogni layer rinforza gli altri. Le skills definiscono le convenzioni, gli hooks garantiscono che vengano rispettati, i comandi aiutano a standardizzare i processi, i plugin aggiungono capacità. Il risultato è quello di avere la sensazione di collaborare con un collega esperto che conosce le nostre preferenze, aumentando la confidenza sulla qualità del lavoro che viene svolta.

Conclusioni: il valore dell’approccio avanzato

L’utilizzo base di Claude Code può già portare benefici significativi nella produttività quotidiana, ma è certamente con un approccio più avanzato che si può portare l’esperienza di utilizzo a un livello superiore.

La differenza tra usare Claude Code vanilla rispetto a un utilizzo con configurazione più profonda è sostanziale: si passa da un assistente generico e decisamente più incline all’errore a uno strumento che emula il nostro modo di lavorare e applica le regole definite in maniera consistente.

Questo approccio è molto utile anche a livello di team per garantire uno stile unico condiviso a livello di good practice and coding style.

Promemoria per gestire correttamente l’euforia: il tool lavora per conto nostro, chi lo usa risponde di quello che viene prodotto. Non dimentichiamoci mai questo piccolo ma fondamentale dettaglio.