(articolo redatto da Alessio Civillo e Angelo Matarazzo)
Claude Code è il tool di coding agentivo sviluppato da Anthropic che opera direttamente nel terminale, leggendo l’intera codebase, modificando file, eseguendo comandi e interagendo con i tool di sviluppo. Con oltre 500.000 utenti attivi, si sta affermando come lo standard de facto per l’AI-assisted development in contesti professionali.
Questa guida raccoglie le best practice più efficaci che vogliono portare Claude Code in produzione, con attenzione a configurazione, workflow agentico e integrazione CI/CD.
1. Setup e Configurazione
1.1 Installazione
Il progetto è in continua evoluzione quindi accedi a code.claude.com
e segui la guida ufficiale.
Ci sono vecchie guide che indicano l’installazione tramite npm; segui sempre la doc ufficiale come indicato sopra.
1.2 Il File CLAUDE.md: Il Cervello del Progetto
CLAUDE.md è il file più importante da configurare. Si posiziona nella root del progetto e viene letto da Claude Code all’inizio di ogni sessione. Centralizza convenzioni, regole architetturali e contesto di progetto, eliminando il bisogno di re-istruire l’AI ad ogni sessione.
Impatto reale
Il 60% dei problemi segnalati dagli utenti di Claude Code è riconducibile all’assenza di un file CLAUDE.md correttamente configurato. Un buon file risolve il problema nel 90% dei casi.
Consigliamo di digitare per nuovi progetti:
Struttura consigliata per un CLAUDE.md efficace:
1.3 Configurazione dei Permessi
Claude Code opera con un sistema di permessi granulare. Evitare almeno all’inizio il flag –dangerously-skip-permissions: concede accesso illimitato e annulla ogni controllo di sicurezza. Con SHIFT+ TAB si può sempre però scegliere la tipologia di controllo
Ci sono vecchie guide che indicano l’installazione tramite npm; segui sempre la doc ufficiale come indicato sopra.
1.4 Comandi Slash Essenziali
Comando | Funzione |
|---|---|
| /plan | Attiva la modalità pianificazione: Claude elabora un piano d’azione prima di eseguire. Fondamentale per task che coinvolgono più di 3 file. |
| /compact | Comprime il contesto della conversazione mantenendo le informazioni essenziali. Da usare quando la sessione diventa lunga. |
| /status | Mostra lo stato corrente dell’agente e i file aperti. |
| /project:[nome] | Esegue un workflow personalizzato definito nella cartella .claude/commands/. |
| /resume | Riprende una sessione chiusa precedentemente |
2. Workflow avanzato e agentico
2.1 Plan Mode: Prima Pianifica, Poi Esegui
La modalità /plan trasforma Claude Code da semplice esecutore ad architetto. Attivandola, l’agente elabora e presenta un piano d’azione prima di toccare qualsiasi file. Il team può revisionare, modificare l’ordine delle operazioni o escludere file specifici.
Best Practice
Usare sempre /plan per task che coinvolgono più di 3 file, refactoring architetturali, o implementazioni di nuove funzionalità cross-modulo.
2.2 Sub-agent e Parallelizzazione
Per task complessi, Claude Code supporta la delega a sub-agenti specializzati che lavorano in parallelo su parti diverse del problema. Questo approccio mantiene il contesto principale focalizzato e accelera le operazioni multi-step.
Esempio pratico di delegazione a sub-agente:
2.3 Headless Mode e Automazione
Il flag -p (prompt) consente di eseguire Claude Code in modalità non interattiva, perfetta per script e automazioni. È la base per qualsiasi integrazione CI/CD.
2.4 Hooks: Event-Driven Automation
Gli hooks sono trigger event-driven che eseguono script personalizzati in momenti specifici del ciclo di vita dell’agente: prima o dopo che Claude modifica un file, prima di eseguire un comando bash, ecc.
2.5 Workflow Personalizzati e skill
I team possono definire workflow ripetibili salvando file Markdown nella cartella .claude/commands/. Ogni file diventa un comando /project:[nome] riutilizzabile da tutto il team.
Vantaggio per i PM
I workflow personalizzati riducono il tempo di onboarding dei nuovi sviluppatori del 25% e garantiscono coerenza nelle pratiche di review su tutto il team.
Le Skill: istruzioni strutturate e riutilizzabili
Oltre ai semplici workflow slash, Claude Code introduce il concetto di skill: istruzioni specializzate, modulari e componibili che definiscono come l’agente deve affrontare una categoria specifica di task. A differenza di un semplice comando slash — che descrive cosa fare — una skill descrive con precisione il comportamento atteso, i criteri di qualità, gli esempi di input/output e le condizioni di errore. Possono essere archiviate nella cartella .claude/skills/, versionare con Git e condivise tra i membri del team come qualsiasi altro artefatto di progetto.
Concetto avanzato — approfondimento dedicato in arrivo
Quello delle skill è un tema ricco e strutturato che merita un articolo dedicato. Le skill sono infatti il mattone fondamentale che porta al concetto di agent harness: “ingabbiare” un sistema probabilistico attraverso strumenti e permessi specifici, abilitando automazioni complesse e pipeline AI su larga scala. Ne parleremo approfonditamente in un prossimo articolo della Redazione Tecnica Nexsoft.
2.6 MCP: Model Context Protocol
MCP è uno standard aperto che consente a Claude Code di connettersi a sorgenti dati esterne: Google Drive, Jira, Slack, database interni, API custom. Ogni integrazione MCP diventa un tool nativo per l’agente.
3. Integrazione con CI/CD
3.1 GitHub Actions: Setup Base
Claude Code si integra nativamente con GitHub Actions tramite l’action ufficiale di Anthropic (anthropics/claude-code-action). La configurazione richiede esclusivamente una API key di Anthropic salvata come GitHub Secret.
3.2 GitLab CI/CD
Per GitLab, la configurazione avviene tramite variabili CI/CD nel progetto. Attenzione: alcuni ambienti richiedono un login interattivo (/login) che può bloccare le run headless. In questi casi, preferire l’approccio via Anthropic API SDK.
3.3 Sicurezza e Governance nei Pipeline
PRATICA | Perché è importante |
|---|---|
| Least-privilege permissions | Concedere solo i permessi strettamente necessari. Mai contents: write a meno di dover aprire PR. |
| Branch protection | Richiedere status check e review umane per ogni PR toccata dall’AI. L’AI non dovrebbe mai mergeare autonomamente. |
| Pin versioni action | Bloccare l’action a un commit SHA specifico per sicurezza supply-chain. |
| Observability | Caricare un artifact Markdown con il report di ogni run. Etichettare le PR modificate dal bot per tracciabilità. |
| SLO di latenza | Impostare un target di latenza ≤3–5 minuti per i job di review e cap sui max-turns/output tokens. |
3.4 Rollout Graduale: Il Piano in 3 Fasi
Introdurre Claude Code nei pipeline in modo incrementale riduce i rischi e consente al team di costruire fiducia nel sistema.
- Fase 1 — Pilota: abilitare su un singolo repository o team. Testare manualmente con PR contenenti issue intenzionali per misurare precision/recall dei flag generati.
- Fase 2 — Staging: estendere a tutti i repo non critici. Validare i workflow in modalità interattiva prima di automatizzare completamente.
- Fase 3 — Produzione: abilitare la full automation con quality gate, branch protection e runbook di rollback documentato.
Nota per i PM
Documentare un rollback path chiaro prima di attivare l’automazione completa. In caso di degradazione della qualità o latenza eccessiva, il team deve poter disabilitare il workflow in meno di 5 minuti.
4. Anti-Pattern da Evitare
Alcune pratiche ricorrenti che riducono l’efficacia di Claude Code e creano problemi in produzione:
- Ghost context: avviare sessioni senza CLAUDE.md o senza fornire contesto di progetto. L’AI opera senza conoscere le convenzioni e genera codice non conforme.
- Over-automation prematura: abilitare headless mode e automazioni CI/CD prima di validare i workflow in modalità interattiva. Validare sempre in locale prima di automatizzare.
- Permessi eccessivi: usare –dangerously-skip-permissions in ambienti condivisi o di staging. Configurare sempre permessi granulari.
- Contesto non gestito: ignorare il segnale di contesto pieno. Usare /compact regolarmente nelle sessioni lunghe per mantenere le performance.
- Aspettarsi autonomia totale: il coding agentico richiede supervisione. Stimare il 10–30% del tempo totale per review dei diff generati dall’AI.
Conclusioni
Claude Code rappresenta un cambio di paradigma nel development workflow: non è un semplice autocomplete ma un partner di sviluppo capace di orchestrare operazioni complesse su un’intera codebase. Le tre pratiche ad impatto più alto per qualsiasi team sono:
- Configurare subito un CLAUDE.md completo e mantenuto aggiornato con le convenzioni del progetto.
- Abilitare la modalità /plan per ogni task che coinvolge più di 3 file o logica cross-modulo.
- Introdurre l’integrazione CI/CD in modo graduale, con rollout a 3 fasi e governance esplicita.
Risorse Utili
- Documentazione ufficiale: docs.claude.com
- Claude Code Best Practices: anthropic.com/engineering/claude-code-best-practices
- GitHub Action ufficiale: github.com/anthropics/claude-code-action
- npm Package: npmjs.com/package/@anthropic-ai/claude-code
Se anche tu vuoi occuparti di importanti progetti di sviluppo software
dai un’occhiata alle nostre opportunità di lavoro e conosciamoci subito!
