Claude Code Best Practices

Una guida completa alle best practice per utilizzare Claude Code in modo efficace, basata sul talk di Cal Newport del team Applied AI di Anthropic.

Introduzione

Claude Code è un assistente di sviluppo che opera interamente da terminale. Si tratta di uno strumento progettato per sviluppatori che preferiscono l’efficienza della command line, simile a un collega esperto che risolve problemi complessi con pochi comandi bash e modifiche precise al codice.

Cal Newport, del team Applied AI di Anthropic, ha condiviso questa definizione durante un talk interno. Il suo team si occupa di assistere clienti e partner nella costruzione di prodotti e funzionalità basate su Claude, e Newport dedica le sue giornate al prompt engineering per ottenere i migliori risultati possibili dai modelli.

La sua esperienza con Claude Code è iniziata un venerdì sera, quando ha deciso di testare questo nuovo strumento su un’applicazione per note-taking. Quel weekend ha trasformato completamente il suo approccio all’ingegneria del software: osservando Claude Code lavorare, ha visto un’applicazione complessa prendere forma progressivamente.

Come Funziona Claude Code

Claude Code segue la filosofia di Anthropic: “do the simple thing that works”. Si basa su un’architettura agent pura e pulita, composta da:

1. Istruzioni - prompt e system messages
2. Tool potenti - gli stessi che utilizzerebbe uno sviluppatore esperto di terminale
3. Loop autonomo - il modello continua a lavorare autonomamente finché non determina il completamento del task

Senza Indicizzazione: Solo Ricerca Agent-Based

Un anno fa, per costruire un coding agent, l’approccio standard prevedeva l’indicizzazione dell’intera codebase, la creazione di embedding e l’implementazione di un sistema RAG sofisticato per il retrieval.

Claude Code adotta un approccio diverso. Non utilizza alcuna indicizzazione. Invece, Claude esplora e comprende la codebase esattamente come farebbe uno sviluppatore che entra in un nuovo team: attraverso la ricerca iterativa e autonoma.

Utilizza gli stessi strumenti di ricerca familiari agli sviluppatori:

• glob per pattern matching sui file
• grep per la ricerca nel contenuto
• find per navigare la struttura

Il termine “ricerca agent-based” indica che il modello può eseguire ricerche, analizzare i risultati, identificare la necessità di ulteriori approfondimenti, eseguire nuove ricerche e continuare iterativamente fino alla completa comprensione del contesto.

Layer Leggero e Sicurezza

Sopra questi strumenti fondamentali, Claude Code aggiunge:

• UI Layer - un’interfaccia leggera che visualizza il lavoro di Claude in tempo reale
• Sistema di permessi - consente all’agent di operare autonomamente richiedendo l’intervento umano per operazioni potenzialmente rischiose
• Sicurezza - essendo un layer leggero sopra il modello, è facile configurare Claude Code per utilizzare AWS o GCP invece delle API di Anthropic

Casi d’Uso

Claude Code è estremamente versatile. Ecco i principali scenari in cui eccelle.

Discovery e Onboarding

Durante la carriera, ogni sviluppatore si trova a dover lavorare su nuove codebase: cambio di team, nuova azienda, contributi a progetti open source. Inizialmente la produttività è limitata dalla necessità di comprendere l’organizzazione del codice, i pattern utilizzati e la struttura del progetto.

Claude Code può accelerare significativamente questo processo di onboarding.

Esempi pratici:

# Localizzare l'implementazione di una feature
"Claude, dove è implementata la funzionalità di autenticazione?"

# Analizzare la storia di un file
"Analizza questo file e controlla la cronologia git, raccontami
come è cambiato questo codice nelle ultime settimane"

Thought Partner

Questo aspetto è spesso sottovalutato. Invece di iniziare immediatamente a scrivere codice, è possibile utilizzare Claude Code come partner strategico.

# Richiedere opzioni prima di implementare
"Claude, sto pensando di implementare questa funzionalità.
Puoi esplorare la codebase, capire come potremmo realizzarla
e propormi 2-3 opzioni diverse? Non iniziare ancora a scrivere file."

Claude utilizzerà le sue capacità di ricerca, proporrà alcune soluzioni, e sarà possibile validarle insieme prima di iniziare l’implementazione.

Building: Zero-to-One e Codebase Esistenti

Claude Code eccelle in due contesti:

1. Zero-to-one: Avvio in una directory vuota per costruire un’applicazione o un gioco da zero. Produce demo impressionanti ed è molto gratificante.

2. Codebase esistenti: Questo è il focus principale del team. Nella codebase di Claude Code stesso mantengono una copertura di unit test insolitamente alta, proprio perché Claude Code rende semplice l’aggiunta di test.

Anche i messaggi di commit e PR sono di alta qualità: al termine del lavoro, è sufficiente chiedere:

"Claude, scrivi il commit per me, scrivi il messaggio della PR"

Deployment e Automazione

Esistono grandi opportunità nell’utilizzo di Claude Code in altre fasi del ciclo di vita dello sviluppo, usando il Claude Code SDK in modalità headless e programmatica.

Esempi:

• Integrazione nel CI/CD
• Utilizzo in GitHub Actions per assistenza automatizzata
• Trigger automatici su eventi specifici

Support, Debug e Migrations

Claude Code può accelerare il debug degli errori. Un caso d’uso inaspettato emerso dai clienti:

“Abbiamo rimandato questa grande migrazione di codebase da anni…”

Team su versioni obsolete di Java che vogliono aggiornare, sviluppatori su PHP che vogliono migrare a React o Angular. Uno strumento come Claude Code rende questi progetti molto più gestibili.

Quando si propone al team un mese di refactoring o riscrittura di parti significative della codebase, avere Claude Code come supporto cambia completamente l’equazione.

CLI Tools Mastery

Claude eccelle nell’utilizzo del terminale. Questo si traduce in competenza con numerosi CLI tool:

• Git
• Docker
• BigQuery
• E molti altri

Non è più necessario preoccuparsi di situazioni come:

"Mi sono trovato in un rebase complicato, come ne esco?"

È sufficiente aprire Claude Code, spiegare la situazione e chiedere “Puoi risolvere questo per me?”

Best Practices

1. Usa i File CLAUDE.md

Claude Code è un agent con tool e istruzioni leggere, ma non dispone di memoria persistente. Il metodo principale per condividere stato tra sessioni o tra membri del team è il file CLAUDE.md.

Come Funziona

All’avvio di Claude Code, se esiste un file CLAUDE.md nella working directory, viene inserito direttamente nel contesto. Il prompt comunica essenzialmente:

“Queste sono istruzioni importanti lasciate dallo sviluppatore. Prestare particolare attenzione a queste indicazioni.”

Dove Posizionarlo

È possibile posizionare CLAUDE.md in vari luoghi:

• Project directory - incluso nel repository per condivisione con tutto il team
• Home directory - per informazioni che Claude deve sempre conoscere, indipendentemente dal progetto
• Subdirectories - per istruzioni specifiche di moduli (Claude può leggerle durante la ricerca)

Cosa Includere

# CLAUDE.md

## Running Tests
Per eseguire i test in questo progetto: `npm test`

## Project Layout
- `/src` - Codice principale dell'applicazione
- `/tests` - File di test
- `/lib` - Utility condivise

## Style Guide
- Usare 2 spazi per l'indentazione
- Preferire componenti funzionali in React
- Aggiungere sempre commenti JSDoc per le API pubbliche

## Important Patterns
Questo progetto utilizza dependency injection attraverso la classe Container...

2. Permission Management

Durante l’utilizzo di Claude Code, appariranno vari prompt di permessi.

Comportamento Default

Di default:

• Azioni di lettura (ricerca, lettura) - Claude può procedere liberamente
• Azioni di scrittura o comandi bash - Attivano il sistema di permessi
  • “Sì”
  • “Sì, consenti sempre”
  • “No, voglio fare altro”

Modalità Auto-accept

Premendo Shift+Tab mentre si lavora con Claude Code, l’agent inizierà a operare senza richiedere conferme.

Configurazione Permessi

È possibile configurare nelle impostazioni quali comandi bash vengono sempre approvati.

Esempio: Se si è stanchi di approvare npm run test ogni volta, è possibile approvarlo permanentemente.

3. Integration Setup

Claude eccelle nell’utilizzo del terminale. Se esistono applicazioni accessibili via CLI, è possibile delegare più lavoro a Claude Code.

Esempio GitHub CLI

GitHub offre un potente tool chiamato gh. È possibile eseguire praticamente qualsiasi operazione su GitHub tramite CLI installando questo strumento.

CLI Tools vs MCP Servers

È possibile aggiungere capacità in due modi:

1. Installare più CLI tools
2. Configurare più MCP servers

Strumenti Interni

Se si dispone di strumenti interni (ad esempio, Anthropic utilizza uno strumento chiamato “coup”), è possibile informare Claude di questi tool. Questo tipo di informazione va inserita in CLAUDE.md.

4. Context Management

Claude è un agent che chiama tool, e il contesto si accumula progressivamente. I modelli di Anthropic hanno una finestra di contesto di 200.000 token, che può essere riempita completamente.

Durante una lunga sessione di lavoro con Claude, apparirà in basso a destra un avviso:

“Stai iniziando a riempire la context window”

Due Opzioni

A seconda della situazione, esistono due opzioni:

1. /clear - Ricominciare da zero

/clear

Cancella tutto tranne, ad esempio, CLAUDE.md. Nuovo inizio completo.

2. /compact - Riassumere e continuare

/compact

Inserisce un messaggio utente che richiede:

“Devo creare un riepilogo di tutto ciò che abbiamo fatto. Lo consegnerò a un altro sviluppatore che continuerà da dove ho lasciato.”

Quel riepilogo inizializza la sessione successiva, permettendo di continuare il lavoro.

5. Efficient Workflows

Planning e To-Dos

Una delle migliori pratiche all’apertura di Claude Code: invece di dire “Devo fixare questo bug”, è possibile chiedere:

"Ho questo bug. Puoi esplorare, capire cosa lo causa
e fornirmi un piano per risolverlo?"

Questo può far risparmiare molto tempo permettendo di verificare il piano di Claude prima che inizi a scrivere codice.

To-Do List Feature

Spesso quando Claude lavora su un task complesso, crea una to-do list. Monitorando questa lista, se si nota qualcosa di anomalo o privo di senso, è il momento di premere Escape e intervenire:

"Claude, modifichiamo la to-do list. Penso tu sia
sulla strada sbagliata."

6. Smart Vibe Coding

È tentante e potente lasciare semplicemente Claude lavorare e osservare il risultato finale. Alcune pratiche possono migliorare questo approccio:

Test-Driven Development

• Far eseguire a Claude piccoli cambiamenti incrementali
• Eseguire i test dopo ogni modifica
• Assicurarsi che i test passino
• Commit regolari per poter tornare indietro se necessario

Type Checking e Linting

Verificare sempre TypeScript e linting. Questo aiuta a identificare errori precocemente.

# Esempi di comandi
"Esegui il compilatore TypeScript e verifica la presenza di errori"
"Esegui ESLint e correggi eventuali problemi"

7. Using Screenshots

Claude è costruito sui modelli di Anthropic che sono multimodali. È sempre possibile:

• Fare uno screenshot e incollarlo
• Chiedere a Claude di analizzare un file immagine:

"Claude, analizza questo mock.png e costruisci il sito web"

Estremamente utile per costruire UI a partire da design mockup.

Tecniche Avanzate

Multiple Claude Instances

Con l’esperienza, diventa allettante utilizzare multiple istanze di Claude contemporaneamente.

Alcuni dipendenti di Anthropic e clienti eseguono 4 istanze di Claude contemporaneamente. Esistono vari approcci:

• Tmux
• Diverse tab del terminale
• Setup personalizzati

Usa il Tasto Escape

Escape è lo strumento più importante.

Mentre Claude lavora, è possibile monitorare le sue azioni e premere Escape per fermarlo e intervenire:

"Penso tu stia prendendo la strada sbagliata"
"Voglio che tu faccia qualcos'altro"

Capire quando intervenire con escape versus lasciare che Claude risolva autonomamente è fondamentale per ottenere il massimo dallo strumento.

Hidden Feature: Double Escape

Una funzionalità poco conosciuta: premendo Escape due volte, è possibile tornare indietro nella conversazione ed effettuare un ripristino.

MCP Expansion

Se bash e i tool disponibili a Claude non sono sufficienti per un task specifico, è il momento di considerare i MCP servers.

Possono fornire a Claude capacità aggiuntive oltre bash e i tool standard.

Headless Automation

Questo è l’ambito più promettente per il team, ancora in fase di esplorazione:

Come utilizzare Claude in modo programmatico?

È già integrato in GitHub Actions. Il team sta esplorando altri contesti creativi per l’utilizzo.

Rimani Aggiornato

Miglioramenti con Claude 4

Per lungo tempo hanno sviluppato la funzionalità “think hard” o “extended thinking”. È eccellente, ma con i modelli precedenti non permettevano al modello di pensare tra le chiamate ai tool - probabilmente il momento in cui il thinking è più utile.

Con Claude 4, i modelli ora possono pensare tra le chiamate ai tool. È possibile osservare questo processo:

# Attivare il thinking esteso
"Pensa approfonditamente e analizza cosa contiene questo progetto"

Apparirà testo grigio chiaro (il thinking), poi verranno chiamati alcuni tool, letti alcuni file, seguito da altro thinking.

Switch Models

È possibile cambiare modello facilmente:

/model          # Visualizzare il modello corrente e cambiarlo
/config         # Configurazione completa

È possibile passare da Sonnet a Opus o altri modelli secondo le necessità.

Check the Changelog

Il team rilascia aggiornamenti molto rapidamente. Newport controlla il changelog settimanalmente per rimanere aggiornato su tutte le nuove funzionalità rilasciate.

È possibile consultare il changelog pubblico nel progetto GitHub chiamato “Claude Code” sotto Anthropic. Lì è possibile:

• Segnalare issues
• Consultare il changelog
• Rimanere aggiornati sulle nuove feature

Conclusione

Claude Code rappresenta un nuovo approccio allo sviluppo software. Non è semplicemente un tool di autocomplete o un generatore di codice - è un partner di lavoro che assiste durante l’intero processo di sviluppo.

Le best practice fondamentali da ricordare:

• Utilizzare CLAUDE.md per fornire a Claude il contesto del progetto
• Gestire i permessi in modo intelligente per velocizzare il workflow
• Pianificare prima di agire - utilizzare Claude come thought partner
• Monitorare la to-do list e usare escape quando necessario
• Rimanere aggiornati - lo strumento evolve rapidamente

Buon coding! 🚀