Gestire il contesto di Claude Code: un manuale pratico

Il codice Claude di Anthropic e la più ampia famiglia Claude ora offrono agli sviluppatori un controllo senza precedenti su quanto il modello vede e quanto profondamente Le sue ragioni. I recenti aggiornamenti del prodotto (in particolare la finestra di contesto Sonnet 4 da 1 milione di token e i controlli "thinking" estesi di Claude) rendono la gestione del contesto più potente e importante: è possibile elaborare interi repository in una singola sessione, ma solo se si strutturano in modo mirato prompt, file e stato della sessione. Questo articolo spiega come gestire in modo affidabile il contesto di Claude Code: comandi e utilizzo, controllo del budget di pensiero, pattern CLAUDE.md, flussi di lavoro dei subagenti, suggerimenti per utenti esperti, risoluzione dei problemi ed esempi di codice concreti che è possibile copiare e incollare.

Cosa è Codice Claude?

Claude Code è di Anthropic CLI di codifica agentica — uno strumento che si basa sul terminale e che connette il tuo ambiente di sviluppo ai modelli Claude, consentendo all'assistente di leggere il tuo repository, eseguire comandi, modificare file, eseguire test, creare commit ed eseguire flussi di lavoro multi-step dal terminale. È progettato in modo che l'IA possa "vivere" nella tua shell e agire sulla tua base di codice, con funzionalità come la scansione del repository, i comandi slash, i subagenti (assistenti specializzati con contesto isolato) e l'integrazione con il Model Context Protocol (MCP) per strumenti esterni.

---

Perché dovrei gestire il contesto del Codice Claude?

Poiché contesto = rilevanza + costo + sicurezza. Se non controllate, le storie lunghe causano:

• Maggiore utilizzo di token (maggiori costi, risposte più lente).
• Deriva del contesto (informazioni vecchie/irrilevanti confondono gli output).
• Perdita di informazioni (segreti o registri sensibili bloccati nella sessione).
  La gestione del contesto garantisce risultati accurati, prevedibili ed economici.

In che modo Claude Code organizza e preserva il contesto del progetto?

Claude Code è una CLI agentica che tratta il tuo repository, gli strumenti e la configurazione come fonti di contesto di prima classe. Legge i file di progetto, CLAUDE.md, strumenti locali e server MCP configurati; supporta anche subagenti, ognuno dei quali ha la propria finestra di contesto (utile per evitare di contaminare la conversazione principale). Utilizzalo per mantenere la strategia di livello principale separata dalla memoria dell'agente specializzato (ad esempio, test runner, revisore del codice).

In che modo Claude Code acquisisce il contesto del repository e i file di supporto?

• Esegue la scansione della directory di lavoro e di tutte le directory extra aggiunte (--add-dir).
• cerca .claude/ sottocartelle (comandi, agenti) e CLAUDE.md.
• È possibile collegare i server Model Context Protocol (MCP) per l'accesso a strumenti esterni; Claude Code può ereditare tali strumenti nel suo set di strumenti.

Quali metodi posso adottare per gestire il contesto nel codice Claude?

1. Padroneggia i comandi base della CLI per il contesto. Salva i prompt riutilizzabili come comandi slash in .claude/commands/ per evitare di incollare ripetutamente prompt lunghi.
2. Progetta un file CLAUDE.md in modo appropriato. Aggiungi CLAUDE.md alla radice del repository per definire obiettivi, strumenti consentiti, stile, regole di escalation e comandi slash utili. (Claude Code legge automaticamente queste informazioni e le utilizza come guida autorevole.)
3. Utilizzare i subagenti per l'isolamento delle attività: ogni subagente ha la propria finestra di contesto e i propri permessi per gli strumenti, impedendo che la sessione principale venga interrogata. Memorizzare i subagenti in .claude/agents/ e controllarne la versione.

Quali sono i comandi di base per la gestione del contesto?

Di seguito sono riportati i comandi che utilizzerai più spesso per gestire lo stato conversazionale in Claude Code. Elencherò il comportamento, gli esempi di utilizzo, gli scenari consigliati e i puntatori ai flag CLI correlati.

---

/clear — “ricominciare da capo”

Cosa fa: cancella la cronologia delle conversazioni correnti dalla sessione, in modo che i prompt successivi partano da zero. La sessione REPL continua, ma i messaggi avanti e indietro vengono rimossi dal contesto del modello. (File di progetto e CLAUDE.md rimangono accessibili a Claude Code.)

Quando usare

• Dopo aver completato una funzionalità o un ticket, desideri una sessione pulita per un'attività non correlata.
• Se la sessione ha accumulato molti turni esplorativi e le risposte sono degradanti.
• Prima di passare la sessione a un altro utente/agente per evitare di perdere lo stato della conversazione precedente.

Impiego

# in the interactive REPL

/clear

Note e suggerimenti

• /clear è distruttivo per la cronologia delle conversazioni di quella sessione; usa /resume/--continue se vuoi tornare alle vecchie sessioni salvate sul disco.

---

/compact — “riassumere e condensare”

Cosa fa: Comprime la conversazione corrente in un riepilogo più breve che conserva i fatti e le decisioni salienti, quindi sostituisce la cronologia dettagliata con tale riepilogo in modo che la sessione possa proseguire senza perdere il contesto importante. Ciò riduce l'utilizzo di token mantenendo la continuità.

Quando usare

• Quando si desidera mantenere lo stato importante del thread ma ridurre l'ingombro del token.
• Prima di un nuovo compito lungo che altrimenti spingerebbe la finestra del contesto verso i limiti.
• Quando si desidera una sessione "memory" succinta, mantenendo al contempo le decisioni chiave.

Impiego

# in the interactive REPL

/compact
# or with an instruction to guide the summary

/compact Summarize decisions, open TODOs, and config changes only

Note e suggerimenti

• auto-compact, microcompacte altri comportamenti di compattazione intelligenti potrebbero essere eseguiti automaticamente quando la lunghezza della conversazione si avvicina ai limiti in alcune build o configurazioni; queste funzionalità sono in fase di distribuzione e potrebbero essere disponibili nella tua installazione o nell'ambiente ospitato. (La community e i changelog discutono i comportamenti di microcompattazione e compattazione automatica.)

---

--continue, --resumee controlli di sessione (livello CLI)

Cosa fanno: controllare la persistenza della sessione e la selezione dalla CLI.

• claude --continue (o claude -c) — riapri e continua la conversazione più recente nella directory del progetto corrente.
• claude --resume (o claude -r <session-id>) — mostra un selettore interattivo (o riprende una sessione specifica tramite ID). Utile quando hai salvato molte sessioni e vuoi sceglierne una per continuare.

Esempi di utilizzo

# continue the most recent session

claude --continue

# open an interactive session picker

claude --resume

# resume by id (non-interactive)

claude --resume 550e8400-e29b-41d4-a716-446655440000

---

Scorciatoie in modalità interattiva che contano per il contesto (UX del terminale)

• Ctrl+L — pulisce lo schermo del terminale (visivo), ma continua cronologia delle conversazioni. Usa /clear per resettare effettivamente la cronologia.
• Ctrl+D — uscire dalla sessione (EOF).
• Ctrl+C — annullare la generazione corrente.
  Questi sono controlli di convenienza; influenzano solo il comportamento del terminale a meno che non vengano eseguiti esplicitamente /clear or --continue/--resume.

---

Altri controlli e flag correlati al contesto

• --add-dir <path> — include directory aggiuntive che Claude può leggere (utile per definire a cosa Claude può accedere e ridurre le letture di file inutili).
• --allowedTools — pre-autorizza gli strumenti in modo che Claude possa eseguirli senza ripetute richieste di autorizzazione (riduce i dialoghi avanti e indietro e rumorosi per l'autorizzazione degli strumenti).
• Comandi barra (/.claude/commands/ o forniti da MCP) — memorizzano prompt usati frequentemente e token-efficienti; richiamare un comando slash è più economico che incollare ripetutamente prompt lunghi.

Come dovrei progettare un file CLAUDE.md per controllare il contesto del progetto?

Cos'è CLAUDE.md e perché è importante

CLAUDE.md è un prompt preflight a livello di progetto che Claude Code legge automaticamente all'avvio di un repository. Utilizzatelo per inserire informazioni brevi, concrete e stabili sul progetto (nomi, architettura, standard). Poiché il modello ingerisce CLAUDE.md nel prompt, un file ben strutturato riduce la necessità di incollare ripetutamente le stesse informazioni e preserva il prezioso budget di token.

CLAUDE.md: modello pratico (consigliato)

Mantieni queste regole: sezioni brevi (100-200 righe ove possibile), gerarchiche (override globale → progetto → sottodirectory) e leggibili dalla macchina.

# CLAUDE.md — top of repository

Project: Acme Payment Gateway
Primary language: typescript
Build: pnpm build
Run tests: pnpm test
API routing: src/api/*
Database: Postgres via prisma (schema at prisma/schema.prisma)

# Conventions

- commit format: Conventional Commits
- test coverage threshold: 80%
- style: eslint + prettier (configs in .eslintrc, .prettierrc)

# What I'm asking Claude to do

- When asked to create a feature, always include tests and update the CHANGELOG.
- When modifying DB schema, present migration plan and migration files.

Note:

• Metti al primo posto gli elementi di valore elevato (API, file importanti, comandi infrastrutturali, comandi di test).
• Usa separato CLAUDE.md file in sottodirectory quando moduli diversi hanno convenzioni diverse; Claude combinerà e darà priorità a file più specifici.

Come posso assemblare flussi di lavoro e subagenti per gestire il contesto e parallelizzare il lavoro?

Cosa sono i subagenti?

I subagenti sono modelli di codice Claude in cui l'agente principale delega compiti discreti ad agenti subordinati (ad esempio: frontend-agent, backend-agent, qa-agent) e poi l'agente principale riconcilia i rispettivi output. I subagenti consentono di lavorare su diverse parti del sistema in parallelo, senza dover concentrare tutto in un'unica chat.

Esempio di flusso di lavoro: implementazione delle funzionalità (agenti paralleli)

1. main-agent legge CLAUDE.md, crea il piano.
2. frontend-agent (subagente) ottiene il contesto focalizzato: contratti UI, libro di fiabe, file specifici.
3. backend-agent (subagente) ottiene lo schema del DB, i contratti API e implementa gli endpoint.
4. qa-agent esegue i test, riscrive i test non riusciti su main-agent.
5. main-agent orchestra commit, richieste di merge e aggiorna CLAUDE.md.

Modello CLI:

# start main session

claude --session main

# spawn frontend subagent (conceptually: new session with scoped CLAUDE.md)

claude --session frontend --cwd frontend/

Suggerimento: crea un ambito CLAUDE.md file nelle sottodirectory (frontend/CLAUDE.md, backend/CLAUDE.md) quindi ogni subagente inizia con il contesto minimo di cui ha bisogno.

Esempio di subagente: .claude/agents/code-reviewer.md

---
name: code-reviewer
description: Focused code reviewer. Limited tools: Read, Grep, Bash
---

You are a code reviewer. When invoked:
1. Run `git diff --name-only` to see changed files.
2. Prioritize security, correctness, tests.
3. Return a patch (diff) and a 3-item actionable checklist.

---

Quali sono i suggerimenti degli utenti esperti per mantenere un contesto sano e ridurre i costi?

1) Mantenere CLAUDE.md snello e gerarchico

Evita file CLAUDE.md monolitici di grandi dimensioni. Utilizza un file globale per le preferenze dello sviluppatore e file di modulo più piccoli per le specifiche di area. Vedi il modello precedente.

2) Utilizzare i comandi slash per i verbi, CLAUDE.md per i nomi

Rendi CLAUDE.md il posto per fatti (quali file esistono, architettura) e slash comanda il posto per procedure (creare test, eseguire il refactoring). Questo impedisce di reinviare la logica procedurale a ogni sessione. La saggezza della community sottolinea questa separazione.

3) Modalità dettagliata + modalità di pianificazione come strumenti di debug

Quando Claude si comporta in modo imprevisto, esegui verbose per vedere il contesto esatto e usa la modalità di pianificazione per forzare un piano esplicito che puoi approvare prima delle modifiche.

4) Pensare attentamente al budget

Inizia con token di pensiero predefiniti/minimi e aumentali solo quando le attività richiedono un ragionamento multifase (refactoring complessi, verifica formale). Utilizza budget inferiori per le modifiche di routine.

5) Output e commit dello strumento

Avere hook che eseguono automaticamente i test e collegano il loro output alla sessione (modalità bash ! per eseguire un comando shell e includere l'output come contesto). Utilizzare i commit hook per creare commit atomici chiari con messaggi.

Come posso risolvere i problemi quando il contesto "cade" o Claude dimentica le istruzioni?

Sintomi comuni e soluzioni

• sintomo: Claude ignora CLAUDE.md o le istruzioni precedenti.
• correzioni: Verificare che il file si trovi nella directory di lavoro corrente della sessione; verificare la presenza di una sottodirectory più specifica, CLAUDE.md, che la sovrascriva; utilizzare la modalità dettagliata per visualizzare il prompt corrente.
• sintomo: Le prestazioni peggiorano nel corso di sessioni lunghe (il modello "dimentica" le parti iniziali).
• correzioni: Compatta la sessione: estrai i dati stabili in CLAUDE.md, oppure crea snapshot di parti della conversazione in file e fai riferimento a esse invece di ripeterle. Valuta anche la possibilità di riavviare sessioni brevi e di passare solo un contesto conciso.
• sintomo: Pensare in modo prolungato richiede troppo tempo o scade.
• correzioni: Ridurre thinking_budget, suddividere l'attività in sottoproblemi più piccoli o eseguire analisi batch offline se sono necessari budget estremamente elevati. Anthropic consiglia l'analisi batch quando i budget di pensiero ottimali superano i ~32 token per evitare timeout.

Conclusione

La gestione del contesto in Claude Code è ora un problema multidimensionale: scelta del modello, progettazione del subagente, CLAUDE.md disciplina, budget di pensiero e architettura degli strumenti interagiscono tra loro. Inizia investendo 1-2 ore per scrivere un documento chiaro CLAUDE.md, crea 2-3 subagenti mirati e aggiungi strumenti di utilizzo per token e budget di pensiero: vedrai guadagni immediati in termini di affidabilità, prevedibilità dei costi e produttività del team.

Utilizzare il codice Claude tramite CometAPI

CometAPI è una piattaforma API unificata che aggrega oltre 500 modelli di intelligenza artificiale (IA) di provider leader, come la serie GPT di OpenAI, Gemini di Google, Claude di Anthropic, Midjourney, Suno e altri, in un'unica interfaccia intuitiva per gli sviluppatori. Offrendo autenticazione, formattazione delle richieste e gestione delle risposte coerenti, CometAPI semplifica notevolmente l'integrazione delle funzionalità di IA nelle tue applicazioni. Che tu stia sviluppando chatbot, generatori di immagini, compositori musicali o pipeline di analisi basate sui dati, CometAPI ti consente di iterare più velocemente, controllare i costi e rimanere indipendente dal fornitore, il tutto sfruttando le più recenti innovazioni nell'ecosistema dell'IA.

Siamo lieti di annunciare che CometAPI ora supporta pienamente il potente Claude Code. Per utilizzare il modello API Comet su Claude Code, è sufficiente installare Claude Code ed eseguire l'autenticazione con la chiave API Comet ottenuta e l'indirizzo di base.

Perché utilizzare il codice Claude tramite CometAPI?

Principali funzionalità dell'intelligenza artificiale: genera, esegui il debug e ottimizza facilmente il codice utilizzando modelli creati appositamente per gli sviluppatori.

• Selezione flessibile dei modelli: la nostra ampia gamma di modelli ti consente di svilupparti in modo più fluido.
• Integrazione perfetta: le API sono sempre disponibili. Integra Claude Code direttamente nel tuo flusso di lavoro esistente in pochi minuti.
• Utilizzando Claude Code tramite CometAPI si risparmieranno più costiL'API fornita da CometAPI ha uno sconto del 20% sul prezzo ufficiale ed è aggiornata con l'ultimo modello ufficiale. L'ultimo modello è Claude Opus 4.1.

Pronto a usare Claude Code? consulta il Guida API per le istruzioni dettagliate.

Vedere anche Come installare ed eseguire Claude Code tramite CometAPI?