Agenti Claude Code: una guida pratica ai workflow di coding autonomi

Se qualcuno mi chiedesse cosa rende Claude Code diverso da ChatGPT o GitHub Copilot, non comincerei dal modello linguistico. Comincerei dal workflow.

Immagina di aprire un terminale all'interno di un repository Git e digitare un unico prompt:

Add request validation to every FastAPI endpoint,
write tests for the new validation logic, update the documentation, 
and commit everything using a descriptive Git commit message.

Invece di farti decine di domande di follow-up, Claude Code si mette al lavoro. 

Cerca nel tuo progetto per capire la struttura dell'API, identifica ogni endpoint, modifica i file appropriati, genera i test, corregge eventuali errori, aggiorna la documentazione e crea un commit Git che riassume le modifiche.

Dal tuo punto di vista, sembra meno di chiacchierare con un'IA e più di assegnare lavoro a un compagno di squadra capace. 

Questo cambio di prospettiva è ciò che rende così interessanti gli agenti di Claude Code.

La funzione che lo rende possibile sono i sub‑agenti di Claude Code. Anziché forzare una singola sessione di IA a ragionare su un intero repository, Claude Code può avviare worker specializzati che indagano su parti diverse del progetto, costruiscono piani di implementazione o modificano il codice in modo indipendente prima di riferire alla sessione principale. 

Invece di provare a risolvere ogni problema all'interno di una singola conversazione, Claude Code può delegare il lavoro ad agenti specializzati. 

I tre principali tipi di agenti sono: 

• Explore, che si concentra sull'esplorazione dei progetti
• Plan, che si concentra sulla costruzione di piani di implementazione, e
• General-purpose, usato per modificare il codice ed eseguire comandi.

Ho notato che questo cambia il mio approccio allo sviluppo. Invece di chiedermi "L'IA può scrivere questa funzione?", mi ritrovo a chiedermi: "Qual è la parte di lavoro più grande che posso affidare in sicurezza?" 

Alla fine di questa guida saprai come usare efficacemente gli agenti di Claude Code, quando ha senso ciascun tipo di sub‑agente, come configurare una memoria di progetto persistente con CLAUDE.md e come costruire workflow autonomi che fanno risparmiare tempo senza rinunciare al controllo. 

Prerequisiti

Questa guida presuppone che tu sia a tuo agio nell'uso del terminale e nella navigazione tra directory con comandi di base come cd, ls o dir. 

Non serve essere un esperto di Bash, ma dovresti sentirti a tuo agio nel lavorare dalla riga di comando.

Ti serviranno anche:

• Node.js installato sulla tua macchina
• Una chiave API di Anthropic
• Un repository Git su cui fare prove
• Familiarità di base con Python, JavaScript o un altro linguaggio di programmazione

Se sei completamente nuovo a Claude Code, ti consiglio anche di leggere Claude Code: una guida con esempi pratici prima di addentrarti nei sub‑agenti.

Cosa sono gli agenti di Claude Code?

Gli agenti di Claude Code sono worker autonomi che completano attività di sviluppo software multi‑step usando il tuo repository locale, il terminale e gli strumenti di sviluppo. 

A differenza di ChatGPT o Claude Chat, Claude Code può ispezionare file, eseguire comandi Bash, modificare il codice sorgente e verificare il proprio lavoro prima di restituire un risultato.

La maggior parte degli assistenti di coding con IA segue ancora un workflow conversazionale. 

Fai una domanda, ricevi una risposta e poi decidi cosa fare dopo. 

Funziona bene per scrivere una query SQL o spiegare una pipeline di scikit‑learn, ma inizia a vacillare quando un'attività tocca 20 file, richiede diversi comandi da terminale o dipende dalla comprensione di un repository sconosciuto.

Claude Code affronta questi problemi in modo diverso. 

Poiché lavora direttamente all'interno del tuo repository Git, può indagare sul codice prima di prendere decisioni. Invece di chiederti di incollare file in una finestra di chat, legge direttamente il progetto e raccoglie il contesto di cui ha bisogno.

Supponiamo che tu chieda:

Replace every custom customer ID validator with Pydantic models, 
update the FastAPI endpoints, rewrite the affected pytest tests, 
and summarize the migration.

Un chatbot tradizionale probabilmente genererà codice di esempio e chiederà ulteriori informazioni. 

Claude Code cerca nel repository, identifica la logica di validazione esistente, modifica i file pertinenti, esegue la suite di test, corregge eventuali regressioni introdotte e riporta il lavoro completato.

Questo passaggio dal rispondere a domande al completare obiettivi è ciò che rende il coding agentico con Claude Code diverso nello sviluppo quotidiano.

Come funziona il loop dell'agente? 

Ogni agente di Claude Code segue lo stesso ciclo decisionale: leggere le informazioni, decidere cosa fare dopo, agire e poi valutare il risultato prima di ripetere il processo. 

Il loop è semplice, ma ripeterlo decine di volte consente a un agente di riprendersi dagli errori invece di fermarsi dopo un singolo tentativo fallito.

Immagina di chiedere a Claude Code di riparare una test suite che fallisce. Il workflow di solito è qualcosa del genere:

Diagramma che mostra come opera Claude Code mentre corregge test falliti

Penso che questo sia il modello mentale più semplice per capire Claude Code. 

L'agente non cerca di risolvere l'intero problema in un solo passaggio. Prende una serie di piccole decisioni basate su ciò che è successo dopo l'azione precedente.

Un sub‑agente segue esattamente lo stesso loop, ma lo fa all'interno del proprio contesto isolato. 

Questa distinzione è importante perché una chiamata allo strumento esegue una singola azione, mentre un sub‑agente può spendere decine di passaggi di ragionamento lavorando verso un unico obiettivo prima di riferire.

Perché Claude Code usa i sub‑agenti? 

Claude Code usa i sub‑agenti perché i repository di grandi dimensioni raramente rientrano in un singolo contesto di lavoro. Un monorepo con servizi Python, applicazioni React, migrazioni SQL e configurazioni Terraform contiene molte più informazioni di quante un agente dovrebbe ragionare in una volta sola. 

Invece di trattare il repository come un unico enorme compito, Claude Code delega indagini mirate a worker specializzati. 

Un agente Explore potrebbe analizzare l'autenticazione, un altro ispezionare i modelli del database, mentre un terzo rivede le route dell'API. L'orchestratore combina queste scoperte prima di decidere il passo successivo.

Questa architettura ha un altro vantaggio pratico: molte indagini avvengono in parallelo. 

Invece di leggere ogni directory da solo o aspettare che un agente ispezioni l'intero repository, diversi sub‑agenti possono esplorare aree diverse contemporaneamente.

Vedrai questo schema nel resto del tutorial. Gli agenti Explore raccolgono informazioni, gli agenti Plan organizzano l'implementazione e gli agenti general‑purpose eseguono il vero lavoro di sviluppo.

Se vuoi un'introduzione più ampia a come funzionano i sistemi di IA autonomi oltre Claude Code, l'articolo di DataCamp LLM Agents Explained: Architecture, Frameworks, and Use Cases offre un'ottima panoramica concettuale.

Come si installa e configura Claude Code? 

Prima di iniziare a usare gli agenti di Claude Code, ci serve un'installazione funzionante. 

Fortunatamente, iniziare richiede solo pochi minuti.

Installare Claude Code

Claude Code è distribuito come pacchetto npm, quindi avrai bisogno di Node.js installato sulla tua macchina. Per le istruzioni, ti consiglio di seguire la documentazione npm sull'installazione di Node.js e npm.

Installa Claude Code globalmente con:

npm install -g @anthropic-ai/claude-code

Poi crea una chiave API di Anthropic dalla Anthropic Console e aggiungila al tuo ambiente.

Su macOS o Linux:

export ANTHROPIC_API_KEY="your_api_key_here"

Su Windows PowerShell:

$env:ANTHROPIC_API_KEY="your_api_key_here"

Per verificare che tutto sia installato correttamente, esegui:

claude --version

Se Claude Code stampa la sua versione installata, sei pronto per iniziare.

A questo punto vale anche la pena verificare che Git sia disponibile, dato che molti workflow di Claude Code prevedono la lettura della cronologia del repository, la creazione di commit o il confronto delle modifiche. 

Se non hai Git, segui le istruzioni di installazione di Git per iniziare.

Entrambi i comandi dovrebbero essere eseguiti con successo prima di procedere.

La tua prima sessione con Claude Code

Con Claude Code installato, entra in un qualsiasi progetto Git usando cd my-project.

Poi avvia Claude Code: claude.

Prima di chiedergli di scrivere codice, dedica qualche minuto a capire come esplora un repository. Di solito inizio con prompt come questi:

• "Cosa fa questo repository?"
• "Spiega l'architettura."
• "Trova ogni commento TODO."
• "Quali moduli contengono la logica di business principale?"
• "Come è implementata l'autenticazione?"

Queste domande non producono nuove funzionalità, ma forniscono a Claude Code lo stesso contesto che un nuovo compagno di squadra raccoglierebbe prima di scrivere codice. 

Ho riscontrato che investire 2 o 3 minuti nell'esplorazione di solito porta a implementazioni migliori che saltare direttamente a una richiesta di funzionalità.

Il passo successivo è configurare una memoria di progetto persistente con CLAUDE.md. Per esperienza, nessun singolo file ha un impatto maggiore sulla qualità del lavoro di Claude Code nel lungo periodo.

Perché CLAUDE.md è il file più importante per Claude Code?

CLAUDE.md è un file di istruzioni persistente che informa Claude sulle tue preferenze e su come funziona il tuo progetto prima che inizi a ragionare su un'attività. 

Invece di rispiegare ogni volta stack tecnologico, convenzioni di coding e workflow di sviluppo, li documenti una volta sola e lasci che ogni agente futuro costruisca su quel contesto condiviso.

Quando le persone vengono a conoscenza degli agenti di Claude Code, di solito si concentrano sui prompt. Secondo me è il contrario. 

Un CLAUDE.md ben scritto fa di più per la qualità dei risultati che affinare all'infinito la formulazione del prompt, perché ogni agente parte dalla stessa comprensione del tuo progetto.

Pensa a come faresti l'onboarding di un nuovo ingegnere. 

Probabilmente non cominceresti mettendogli in mano un ticket Jira. Gli spiegheresti il repository, come eseguire la test suite, indicheresti alcune convenzioni di coding e lo avviseresti delle parti della codebase da non toccare. 

CLAUDE.md serve esattamente allo stesso scopo.

Il vantaggio diventa ancora più evidente quando inizi a usare i workflow autonomi di Claude Code.

Un agente che dovrebbe lavorare in autonomia ha bisogno di un contesto di progetto affidabile. 

Senza di esso, Claude Code perde tempo a riscoprire informazioni o fa assunzioni che potrebbero non corrispondere agli standard del tuo team.

Cosa dovresti inserire nel tuo CLAUDE.md?

Un buon CLAUDE.md non sostituisce la documentazione del progetto o il tuo README.md. È una raccolta di istruzioni di cui Claude Code ha ripetutamente bisogno mentre legge il codice, scrive funzionalità ed esegue strumenti di sviluppo.

Di solito lo organizzo in cinque sezioni: panoramica del progetto, stack tecnologico, convenzioni di coding, comandi comuni e directory da evitare. Le vedo brevemente una per una.

Panoramica del progetto

Inizia con una breve descrizione di cosa fa effettivamente il progetto.

Customer analytics platform built with FastAPI.
The application serves machine learning predictions through REST APIs.
Production deployments run through GitHub Actions.

Queste tre righe dicono subito a Claude Code che sta lavorando con FastAPI, GitHub Actions e un'applicazione di machine learning, non con un generico repository Python.

Stack tecnologico

Poi, letteralmente, elenca solo le principali librerie e framework che definiscono il progetto.

Python 3.12
FastAPI
Pydantic v2
SQLAlchemy
PostgreSQL
Pytest
Ruff

Inserisco sempre i numeri di versione quando contano. 

L'approccio consigliato per Pydantic v2 differisce da Pydantic v1 e Claude Code non dovrebbe dover indovinare quale API stai usando. 

Questo è particolarmente importante se stai usando un pacchetto datato, così da non partire da assunzioni sbagliate.

Convenzioni di coding

Questa sezione cattura le regole che ti ritrovi a ripetere.

Always use type hints.
Prefer dependency injection.
Write tests for every new feature.
Keep business logic separate from API routes.
Reuse existing utility functions before creating new ones.

Nota che si tratta di regole ingegneristiche pratiche, non di preferenze di stile. 

Claude Code di solito può dedurre la formattazione dai file esistenti, ma non saprà automaticamente che il tuo team si aspetta che ogni endpoint usi la dependency injection o che ogni funzionalità includa un test pytest.

Comandi comuni

Spesso Claude Code convalida il proprio lavoro eseguendo comandi di sviluppo. Fornire i comandi esatti usati dal tuo team evita tentativi ed errori inutili. 

Può trattarsi di qualsiasi cosa, come specifiche azioni task o script di CI.

pytest
Run one test file:
pytest tests/test_api.py
Lint:
ruff check .
Format:
ruff format .
Start the development server:
uvicorn app.main:app --reload

Questa sezione è particolarmente utile in repository con script personalizzati, workflow Docker o strumenti come poetry, uv o tox.

File e directory da evitare

Ogni repository ha file che non dovrebbero cambiare automaticamente.

Esempi includono:

Never edit generated files.
Do not modify Alembic migrations.
Avoid changing Terraform configuration unless requested.
Do not update dependency versions automatically.

Ho visto che questa sezione previene più errori di quasi ogni altra. Una singola frase che dice a Claude Code di lasciare in pace il codice generato costa molto meno del rivedere decine di modifiche inutili ai file.

Un esempio di CLAUDE.md

Ecco un esempio semplificato per un progetto API Python. 

Nota come uso la formattazione markdown per rendere più leggibile agli umani e per fornire a Claude più contesto.

# Project Overview

Customer analytics platform built with FastAPI.

## Technology

- Python 3.12
- FastAPI
- PostgreSQL
- SQLAlchemy
- Pydantic v2
- Pytest
- Ruff

## Coding Standards

- Use type hints everywhere.
- Write tests for new features.
- Prefer dependency injection.
- Keep business logic separate from API routes.

## Common Commands

pytest
ruff check .
ruff format .

## Avoid Editing

generated/
alembic/versions/
terraform/

Non preoccuparti di rendere perfetta la prima versione. 

Il mio CLAUDE.md è cambiato più volte man mano che notavo istruzioni ricorrenti che valeva la pena documentare. Trattalo come codice sorgente, non come documentazione che non cambia mai. 

Se vuoi approfondire la scrittura di file di istruzioni efficaci, la guida di DataCamp Scrivere il miglior CLAUDE.md: guida completa per Claude Code copre esempi più grandi e pattern più avanzati.

Meglio un CLAUDE.md a livello di progetto o a livello utente?

Claude Code supporta due ambiti per le istruzioni persistenti. Capire la differenza mantiene separate le regole del progetto dalle tue preferenze personali.

Project-level CLAUDE.md

Un file a livello di progetto vive all'interno del repository.

	my-project/
	│
	├── CLAUDE.md
	├── app/
	├── tests/
	└── pyproject.toml

Tutto ciò che è in questo file si applica solo a quel repository. Lo uso per scelte tecnologiche, comandi di testing, convenzioni di coding, struttura delle directory e regole specifiche del repository. 

Poiché il file vive accanto al codice sorgente, ogni contributor riceve le stesse istruzioni dopo aver clonato il progetto. Pensalo come fornire a ogni agente un manuale prima che inizi.

User-level CLAUDE.md

Claude Code supporta anche un file di configurazione globale.

Questo file ti segue da progetto a progetto. Lo considero il mio manuale operativo personale più che documentazione di progetto.

Per esempio, il mio file a livello utente potrebbe includere istruzioni come:

Explain architectural trade-offs.
Suggest performance improvements when appropriate.
Default to Python examples unless another language is requested.
Keep explanations concise.

Queste preferenze hanno senso indipendentemente dal fatto che stia lavorando con FastAPI, React o PyTorch.

Come funzionano insieme i due file

Un dettaglio che mi ha confuso quando ho iniziato a usare Claude Code è che questi file non si escludono a vicenda. 

Il CLAUDE.md a livello utente viene caricato per primo, poi il CLAUDE.md a livello di progetto aggiunge istruzioni specifiche del repository.

La considero una gerarchia. 

Il file globale definisce come mi piace lavorare. Il file del progetto spiega come funziona questo repository. 

Insieme, danno a ogni agente sia preferenze personali sia contesto di progetto prima che inizi a ragionare.

Claude Code combina preferenze a livello utente con istruzioni specifiche del progetto prima di iniziare un'attività.

Quali sono i tre tipi di sub‑agenti di Claude Code?

Claude Code utilizza tre tipi di sub‑agenti specializzati perché attività di sviluppo diverse richiedono strumenti diversi. 

Un agente che indaga su un repository non ha bisogno del permesso di modificare file, mentre un agente che implementa una funzionalità probabilmente necessita di accesso a Bash, Git e alla tua test suite.

Quando ho iniziato a usare Claude Code, sceglievo sempre l'agente general‑purpose perché mi sembrava l'opzione più capace. 

Col tempo ho capito che stavo pagando più in tempo e token del necessario. La maggior parte dei workflow diventa più veloce se prima esplori, poi pianifichi e infine implementi.

Confronto tra i tre sub‑agenti di Claude Code

I nomi sono abbastanza descrittivi, ma ogni agente ricopre un ruolo distinto in un workflow più ampio.

Cos'è un agente Explore di Claude Code?

Un agente Explore di Claude Code è un investigatore in sola lettura che cerca in un repository e riassume ciò che trova senza modificare alcun file.

È l'agente che uso più spesso quando apro un progetto sconosciuto. Invece di scorrere da solo decine di moduli Python o componenti JavaScript, chiedo all'agente Explore di spiegarmi come funziona un sottosistema e di indicarmi i file che contano.

Casi d'uso validi includono:

• Trovare dove è implementata l'autenticazione
• Tracciare una richiesta attraverso diversi servizi
• Audit del logging o della gestione degli errori
• Individuare API deprecate
• Riassumere un pacchetto o una directory
• Identificare logica di business duplicata

Poiché gli agenti Explore non possono modificare file o eseguire comandi shell, sono anche gli agenti più sicuri da eseguire in parallelo.

Scegliere un livello di approfondimento

Gli agenti Explore supportano diverse profondità di indagine.

Se devo solo localizzare una funzione, uso l'impostazione più rapida. Se mi preparo a un refactor su più pacchetti, aspettare un minuto in più per un'indagine più profonda di solito ripaga.

Cos'è un agente Plan di Claude Code?

Un agente Plan di Claude Code analizza una modifica richiesta e produce una strategia di implementazione senza modificare il repository.

Quasi mai salto questo passaggio. Dedicare un minuto in più a rivedere un piano costa molto meno che scoprire a metà implementazione che un altro sottosistema dipende dal codice che stai cambiando.

Un piano tipico include:

• File che dovrebbero cambiare
• Ordine di implementazione raccomandato
• Dipendenze e punti di integrazione
• Strategia di testing
• Rischi o assunzioni

Una volta rivisto il piano, puoi affinarlo o consegnarlo direttamente a un agente general‑purpose.

L'articolo di DataCamp Claude Code Plan Mode: loop di refactoring con revisione del design prima esplora in dettaglio questo workflow orientato alla revisione.

Cos'è un agente general‑purpose di Claude Code?

Un agente general‑purpose può leggere file, modificare codice sorgente, eseguire comandi Bash, lanciare i test e continuare a lavorare finché non soddisfa l'obiettivo richiesto.

È l'agente che effettivamente costruisce software. Ha accesso allo stesso contesto del repository degli altri agenti, ma ha anche il permesso di apportare modifiche e verificare il proprio lavoro.

Attività tipiche includono:

• Implementare nuove funzionalità
• Refactoring di più moduli
• Migrazione di dipendenze
• Aggiornamento della documentazione
• Coordinare modifiche su più pacchetti

Gli agenti general‑purpose consumano più token perché svolgono un lavoro sostanzialmente maggiore. 

Questo è un altro motivo per cui mi piace lo schema Explore → Plan → Implement. 

Gli agenti più economici rispondono alle domande iniziali, lasciando il lavoro di implementazione più costoso quando il percorso è chiaro.

A questo punto abbiamo coperto gli elementi che rendono gli agenti di Claude Code efficaci: memoria di progetto persistente tramite CLAUDE.md e sub‑agenti specializzati per indagine, pianificazione e implementazione. 

Ora metteremo insieme questi pezzi costruendo workflow agentici completi che puoi iniziare a usare nei tuoi progetti.

Eseguire i tuoi primi workflow con gli agenti di Claude Code

Il modo migliore per ottenere il massimo da Claude Code è dargli un obiettivo invece di chiedere singoli componenti.

Sono arrivato a un workflow semplice che funziona bene per progetti Python, repository di data science e applicazioni web:

1. Esplora il repository.
2. Crea un piano.
3. Rivedi il piano.
4. Implementa le modifiche.
5. Verifica i risultati.

Questo processo non è obbligatorio, ma rispecchia il modo in cui gli ingegneri esperti affrontano cambiamenti più grandi. 

Passare un minuto a capire il repository di solito fa risparmiare parecchi minuti di correzioni successive di modifiche inutili. 

Creare un prompt più accurato, persino dedicare un'ora a rifinirlo, può farti risparmiare ore di lavoro dopo.

Workflow 1: Esplorare una codebase sconosciuta

Un agente Explore è il punto di partenza ideale quando erediti un nuovo repository o torni su un progetto che non tocchi da mesi. 

Invece di leggere manualmente le directory, chiedi a Claude Code di indagare sull'architettura e riassumere ciò che conta.

Per esempio:

Use an Explore agent to explain how authentication works. 
Identify the main modules involved, summarize the request flow, 
and highlight any technical debt or TODO comments.

Il risultato non sarà un muro di codice sorgente copiato. Riceverai invece una spiegazione concisa del flusso di autenticazione, dei file coinvolti e delle aree che meritano attenzione. 

Spesso uso quel sommario come punto di partenza per il passo successivo invece di scrivere un altro prompt da zero.

Workflow 2: Pianificare prima di implementare

Una volta compreso il repository, chiedi a un agente Plan di progettare l'implementazione prima di scrivere codice. 

È una delle abitudini più facili da adottare e mi ha evitato diversi refactor che avrebbero preso una direzione sbagliata.

Un prompt potrebbe essere così:

Create an implementation plan for adding role-based access control.
Identify the files that should change, potential risks,
dependencies, and a recommended implementation order.
Do not modify any code.

Rivedi il piano prima di procedere. Se tutto sembra ragionevole, puoi consegnarlo direttamente a un agente general‑purpose. 

Se no, è molto più facile modificare un documento di design che annullare cambi in una dozzina di file.

Un ottimo modo per sfruttare questo passaggio è usare un'altra sessione di Claude Code per rivedere il lavoro della prima. Un semplice prompt potrebbe essere:

This is my current goal: to add role-based access control to this repository. 
Take a look at this existing implementation plan and do an adversarial review.
Once done, create a report that summarizes the strong and weak points of the plan.

Workflow 3: Parallelizzare l'esplorazione del repository

Una delle mie funzioni preferite di Claude Code è che l'esplorazione non deve avvenire in sequenza. Se il tuo progetto contiene più sottosistemi indipendenti, puoi indagarli contemporaneamente.

Per esempio, potresti avviare un agente Explore per ispezionare il layer API, un altro per rivedere i modelli del database e un terzo per esaminare la pipeline di machine learning. 

Mentre questi agenti lavorano in modo indipendente, l'orchestratore combina i loro risultati in una singola risposta.

Non uso agenti paralleli per ogni attività, ma sono perfetti per grandi monorepo o applicazioni mature con molti servizi. Invece di aspettare una lunga indagine, spesso puoi capire il repository molto più velocemente perché più parti del progetto vengono analizzate simultaneamente.

Il modo migliore per farlo è usare un agente principale per orchestrare più agenti. 

Questa orchestrazione agentica è un ottimo modo per svolgere lavoro in parallelo senza più sessioni, condivisione in un contesto unico. 

Un buon prompt potrebbe essere questo:

I want you to look at the following components: 
Inspect the API layer, review the DB models, and examine the ML pipeline. 
Look for weaknesses. 
I want this done in parallel, so spawn subagents using Opus/Sonnet models 
in order to do this work and have each generate a concise report and share out 
one master document that outlines the work needed to be done.

Best practice per gli agenti di Claude Code

La maggior parte dei problemi che le persone incontrano con Claude Code non sono causati dal modello. Sono causati da prompt vaghi, contesto di progetto mancante o dal chiedergli di risolvere un problema che non comprende appieno.

Dopo aver usato regolarmente Claude Code, queste sono le abitudini che hanno avuto il maggiore impatto sui miei risultati.

Scrivi prompt che gli agenti possano eseguire

Claude Code rende al meglio quando obiettivo, ambito e criteri di successo sono espliciti. 

Invece di descrivere l'obiettivo finale in termini generici, indica esattamente quale repository dovrebbe ispezionare, quali file dovrebbe modificare e come saprai che il compito è completo.

Per esempio:

❌ Vago Migliora l'API.

✅ Specifico Aggiorna gli endpoint di autenticazione FastAPI per usare la validazione di Pydantic v2, genera o aggiorna i relativi test pytest, esegui la test suite e riassumi ogni file modificato.

Il secondo prompt dà a Claude Code un obiettivo chiaro, dei confini e un modo per verificare il successo. Di solito porta a meno prompt di follow‑up e a meno pulizia manuale.

Gestisci il contesto prima che diventi un problema

Le conversazioni lunghe accumulano alla lunga abbastanza contesto da far spendere a Claude Code token per ricordare discussioni precedenti invece che per ragionare sull'attività attuale.

Quando succede, usa /compact per riassumere la conversazione preservando il contesto importante. Ho visto che è meglio compattare presto che aspettare che le prestazioni calino in modo evidente.

Un buon CLAUDE.md aiuta anche qui perché le convenzioni del progetto non devono essere ripetute in ogni sessione. Claude Code carica quel contesto automaticamente, lasciando più tempo per il lavoro che gli chiedi di svolgere.

Per altri consigli sulla gestione del contesto, sul test‑driven development e sul design dei prompt, vedi Claude Code Best Practices: pianificazione, trasferimento del contesto, TDD.

Pensa ai costi in token

Non ogni attività richiede un agente general‑purpose.

Se ti serve solo trovare dove è definita una funzione, un agente Explore è di solito più veloce e meno costoso. 

Se stai rivedendo un grande cambiamento architetturale, un agente Plan spesso ti dà informazioni sufficienti senza modificare il repository.

Riserva gli agenti general‑purpose per attività che richiedono davvero esecuzione: modificare file, eseguire comandi Bash o i test. Abbinare l'agente al compito mantiene sotto controllo sia il tempo di esecuzione sia l'uso di token.

Sappi quando non usare gli agenti

Gli agenti di Claude Code introducono un po' di overhead perché c'è uno scambio di contesto e token. 

Indagano sul repository, ragionano sul compito e verificano il loro lavoro. Per modifiche molto piccole, quell'overhead non sempre vale la pena.

Probabilmente non ti serve un agente per:

• Rinominare una singola variabile.
• Correggere un refuso in un file Markdown.
• Spiegare un messaggio di errore Python.
• Rispondere a una rapida domanda SQL.

In queste situazioni, una normale conversazione con Claude Code o anche una modifica manuale è spesso più veloce. Di solito mi faccio una domanda prima di lanciare un agente: Ci metterei più tempo a spiegare questo compito che a farlo da solo? Se la risposta è sì, resto sul semplice.

Considerazioni finali

Gli agenti di Claude Code cambiano il ruolo dell'IA nello sviluppo software. Invece di generare snippet isolati, possono affrontare problemi più complessi come l'esplorazione dei repository, la progettazione delle implementazioni, la modifica del codice, l'esecuzione dei test e il completamento di obiettivi multi‑step con relativamente poca supervisione.

La lezione più grande che ho imparato è che i workflow migliori contano più dei prompt migliori. 

Un CLAUDE.md chiaro, qualche minuto di esplorazione del repository e un piano di implementazione ragionato producono costantemente risultati migliori che saltare subito alla generazione di codice.

Con il tempo svilupperai probabilmente un tuo workflow. Il mio inizia ancora quasi sempre allo stesso modo: esplora prima, pianifica poi, implementa per ultimo.

È un'abitudine semplice, ma mi ha risparmiato innumerevoli cicli di revisione e mi ha aiutato a fidarmi dei workflow autonomi molto più di quanto facessi agli inizi.

Se vuoi saperne di più sulle idee alla base dei sistemi autonomi, ti consiglio le seguenti risorse:

• Introduzione agli AI Agents 
• Introduzione ai modelli Claude 
• Claude Code Hooks: guida pratica all'automazione dei workflow 
• Tutorial Claude Agent SDK: crea agenti con Claude Sonnet 4.5 
• Come creare plugin per Claude Code 
• Claude Code 2.1: guida con esempi pratici 
• Model Context Protocol (MCP): guida con progetto demo 
• AI Agents con Hugging Face smolagent