Source: https://aiprimetech.io/it/blog/claude-code-cli-guide/ Giu 19, 2026 · 6 min · Strumenti # Claude Code e la nuova ondata di strumenti di programmazione IA da terminale A Di [AI Prime Tech](https://aiprimetech.io/it/) · Con l'assistenza dell'AI Alle 2:13 del mattino, ho osservato un agente di programmazione nel terminale consumare 1.8 milioni di token di input nel tentativo di «correggere soltanto il test che falliva». Il bug reale era una discrepanza nello schema di tre righe. L'agente non era stupido; aveva vincoli definiti male. Continuava a rileggere il repository, a rieseguire comandi di test ad ampio raggio, a reinserire enormi stack trace nel modello e a chiedere riscritture di interi file quando sarebbe bastata una modifica mirata. Quell'episodio ha cambiato il modo in cui uso gli agenti di programmazione nella CLI. Strumenti come Claude Code, Aider, Cline e OpenCode non sono semplicemente chatbot con un pulsante git diff . Sono cicli di controllo basati su API che operano sulla shell, sull'editor, sul filesystem e talvolta sul browser. Possono essere estremamente produttivi, soprattutto con modelli potenti come Claude Opus 4.8, Sonnet 4.6, GPT-5.5, Gemini 3 e sistemi con contesto lungo come Fable 5. Possono anche consumare silenziosamente token a un ritmo che sorprende i team abituati a chiamate API a turno singolo. Questo articolo offre una prospettiva pratica: cosa fanno davvero gli agenti di programmazione nel terminale, come usano le API dei modelli, perché i cicli degli agenti cambiano l'economia dei token e come li configuro affinché una sessione lunga resti utile invece di diventare una costosa messinscena. ## Cosa sono davvero gli agenti di programmazione nella CLI Un agente di programmazione nel terminale è solitamente composto da cinque elementi collegati tra loro: - Un ciclo di conversazione con un modello di frontiera o aperto - Un indicizzatore del repository o un livello di individuazione dei file - Un livello di esecuzione degli strumenti per i comandi shell e le modifiche ai file - Un meccanismo di applicazione delle patch - Un livello di persistenza per la cronologia della conversazione e lo stato della sessione La differenza fondamentale rispetto al completamento automatico è l'autonomia d'azione. Il completamento automatico prevede il codice nella posizione del cursore. Un agente può decidere di esaminare file, eseguire test, modificare codice, analizzare gli errori e ripetere il ciclo. Un ciclo tipico si presenta così: ``` User task ↓ Agent builds prompt from instructions + repo context + prior messages ↓ Model proposes actions: read file, edit file, run command ↓ CLI executes allowed actions ↓ Results are added back into context ↓ Model plans next step ↓ Repeat until done or stopped ``` È questo ciclo a far sembrare potenti questi strumenti. È anche il motivo per cui costi e latenza si comportano in modo diverso dal normale uso delle API del tipo «fai una domanda, ricevi una risposta». In pratica, la maggior parte dei costi imprevisti deriva dal percorso di feedback: output dei comandi, contenuti dei file, messaggi precedenti e diff inclusi ripetutamente nei turni successivi. ## Claude Code, Aider, Cline e OpenCode: forme diverse dello stesso schema Gli strumenti hanno stili di interazione diversi, ma lo schema ingegneristico di base è simile. | Strumento | Interfaccia principale | Punto di forza tipico | Rischio di costo comune | Claude Code | Agente nativo del terminale | Flusso di lavoro ben integrato tra shell e repository, efficace ciclo di pianificazione e modifica | Sessioni autonome lunghe che accumulano contesto | Aider | Assistente di programmazione in coppia nella CLI con supporto a Git | Modifiche incentrate sui diff, selezione esplicita dei file | Aggiunta di troppi file al contesto | Cline | Agente incentrato sull'editor | Integrazione con VS Code, uso visibile degli strumenti | Output voluminosi del terminale o del browser che entrano nel contesto | OpenCode | Flusso di lavoro con agente nel terminale o nell'editor | Flessibilità nella scelta dei modelli e controllo del flusso di lavoro locale | Provider configurati male o scansioni estese del repository La distinzione importante non è «quale sia il più intelligente». È quanto contesto invia lo strumento, come seleziona i file, come riassume la cronologia e quanto controllo hai sull'esecuzione nella shell. Aider, per esempio, tende a funzionare bene quando aggiungi intenzionalmente i file pertinenti. Claude Code ha una maggiore autonomia d'azione e può dare l'impressione di un ingegnere senior che si muove nel repository, ma questa autonomia richiede scelte consapevoli riguardo alle autorizzazioni e all'ambito di lavoro. Cline è comodo all'interno dell'editor, soprattutto quando vuoi osservare le azioni, ma la comodità dell'editor può rendere facile approvare troppi passaggi costosi. I flussi di lavoro in stile OpenCode attirano i team che vogliono flessibilità nella scelta dei provider: Claude per i lavori di architettura complessi, GPT per l'implementazione, Gemini per l'analisi di contesti ampi oppure modelli aperti come Qwen, DeepSeek, Kimi, MiniMax e Llama per passaggi più economici in locale o su infrastruttura propria. ## Come questi agenti usano l'API Una singola richiesta «correggi questo bug» può trasformarsi in decine di chiamate API. Il corpo semplificato di una richiesta per un passaggio dell’agente si presenta così: ``` { "model": "claude-sonnet-4.6", "messages": [ { "role": "system", "content": "You are a coding agent. Follow repo instructions. Use tools safely." }, { "role": "user", "content": "Fix the failing invoice total test." }, { "role": "assistant", "content": "I will inspect the test and related invoice code." }, { "role": "tool", "name": "read_file", "content": "tests/test_invoice_totals.py contents..." } ], "tools": [ { "name": "read_file" }, { "name": "apply_patch" }, { "name": "run_shell" } ] } ``` Le implementazioni reali variano, ma lo schema resta lo stesso: - La CLI raccoglie il contesto. - Il modello decide l’operazione successiva. - La CLI esegue l’operazione. - Il risultato viene restituito al modello. - Il modello prosegue. Di solito gli strumenti vengono esposti in due modi. ### Protocolli testuali per gli strumenti Alcuni agenti chiedono al modello di produrre testo strutturato: ``` RUN: pytest tests/test_invoice_totals.py -q ``` La CLI lo analizza e lo esegue. È un approccio semplice e portabile, ma fragile. Se il modello formatta il comando in modo anomalo, il sistema che lo esegue ha bisogno di meccanismi di protezione. ### Chiamata nativa di funzioni Altri agenti usano le chiamate a strumenti o funzioni dell’API del modello. Il modello restituisce un’invocazione strutturata dello strumento: ``` { "tool_name": "run_shell", "arguments": { "command": "pytest tests/test_invoice_totals.py -q", "timeout_seconds": 60 } } ``` È più facile da validare. L’agente può rifiutare comandi che corrispondono a schemi pericolosi, richiedere l’approvazione per l’accesso alla rete o limitare le scritture allo spazio di lavoro. In entrambi i casi, la parte costosa non è il comando di shell. È il prompt sempre più grande che lo circonda. ## Perché i cicli degli agenti cambiano l’economia dei token Una normale integrazione API potrebbe inviare 2,000 token di input e ricevere 500 token di output. Una sessione di programmazione con un agente potrebbe svolgersi così: | Passaggio | Cosa succede | Profilo dei token di input | Profilo dei token di output | 1 | L’utente chiede una correzione | Ridotto | Piano | 2 | L’agente legge i file | Medio | Richiesta di uno strumento | 3 | L’agente modifica il codice | Medio-alto | Patch | 4 | Il test fallisce | Elevato se vengono inclusi i log completi | Diagnosi | 5 | L’agente legge altri file | Più elevato a causa della cronologia | Richiesta di uno strumento | 6 | L’agente riprova | Ancora più elevato | Patch | 7 | L’esecuzione completa dei test fallisce altrove | Molto elevato se l’output viene incollato senza elaborazione | Riepilogo/analisi preliminare L’insidia: spesso i token di input sono predominanti. Ogni ciclo può reinviare istruzioni di sistema, cronologia della conversazione, file selezionati, output degli strumenti e riepiloghi. Anche con la cache o la compressione del contesto, le lunghe sessioni autonome possono diventare costose, perché il modello ha bisogno di informazioni sufficienti sullo stato per evitare di agire alla cieca. Ci sono quattro fattori comuni che moltiplicano i token: - File interi nel contesto: inviare file di 900 righe quando contano solo due funzioni. - Output prolisso dei test: includere avvisi sulle dipendenze, barre di avanzamento ed errori non pertinenti. - Scansioni ripetute del repository: eseguire find, tree, oppure rg su un ambito ampio e reinserire l’output nel contesto. - Cronologia della conversazione senza limiti: conservare ogni tentativo fallito invece di riepilogare le decisioni. In una sessione disordinata, ciò che accade davvero non è che «l’agente ragiona più a fondo». Spesso vede solo più contesto ormai superato. Un maggior numero di token può rendere il modello più lento e meno preciso se le informazioni rilevanti sono sepolte nel resto. ## Il modello mentale: budget per ciclo, non per prompt Quando stimo la spesa, ragiono in termini di cicli. Un’attività piccola e mirata potrebbe essere: ``` 8 turns × 12k input tokens average = 96k input tokens 8 turns × 1.5k output tokens average = 12k output tokens ``` Un’attività che procede senza una direzione precisa potrebbe essere: ``` 35 turns × 55k input tokens average = 1.9M input tokens 35 turns × 3k output tokens average = 105k output tokens ``` Stesso prompt dell’utente. Costi molto diversi. Non servono prezzi esatti per capire la natura del problema. Le sessioni con agenti crescono in funzione di: ``` total cost ≈ Σ(input_tokens_per_step × input_price) + Σ(output_tokens_per_step × output_price) + tool/runtime overhead ``` I token di output sono visibili perché osservi l’agente mentre scrive. I token di input sono nascosti perché vengono assemblati dalla CLI. È su questo lato nascosto che conta la disciplina di budget. ## Scegliere i modelli per il lavoro degli agenti Raramente uso un solo modello per tutto. Per gli agenti da terminale, la scelta del modello dovrebbe essere adatta alla fase: | Fase | Tipo di modello più adatto | Motivo | Ricognizione del repository | Modello con contesto lungo o più economico ma capace | Richiede una lettura ampia, non modifiche perfette | Decisione architetturale | Modello con forti capacità di ragionamento | Richiede capacità di valutare i compromessi | Generazione di patch | Modello con forti capacità di programmazione | Richiede diff precisi | Analisi preliminare dei test falliti | Modello veloce di fascia media | Spesso si tratta di riconoscere schemi | Refactoring meccanici | Modello economico o aperto con meccanismi di protezione | Lavoro ripetitivo e verificabile Una configurazione pratica potrebbe usare modelli della classe Sonnet per la maggior parte delle attività di programmazione, modelli della classe Opus/GPT-5.5 per il debugging complesso o la progettazione, modelli a contesto lungo in stile Gemini/Fable per analisi estese e modelli aperti per refactoring locali basati su controlli di lint. I nomi esatti cambieranno; lo schema resta valido. Un errore comune è usare il modello più costoso per l’intero ciclo. Il modello costoso finisce così per spendere token a prezzo elevato per leggere rumore informativo attorno a node_modules, avvisi dei test e file generati. Riserva il modello più potente alle decisioni che ne hanno davvero bisogno. ## Consigli di configurazione che contano La configurazione migliore non è «massima autonomia». È «feedback rapido con permessi limitati». ### 1. Ignora i file generati e quelli di terze parti Ogni agente di programmazione dovrebbe avere un elenco di esclusioni. Inizia dagli stessi elementi che escludi dalla ricerca e dalla revisione: ``` node_modules/ dist/ build/ coverage/ .venv/ __pycache__/ target/ vendor/ *.lock *.min.js *.map ``` Di solito non escludo globalmente i file di lock se l’attività riguarda la risoluzione delle dipendenze, ma li escludo dal contesto predefinito. Un file di lock può essere incluso esplicitamente quando serve. ### 2. Usa comandi di test mirati Non lasciare che l’agente esegua per impostazione predefinita l’intera suite a ogni iterazione. Forniscigli una sequenza di comandi progressivamente più ampia: ``` # First loop: fastest relevant test pytest tests/billing/test_invoice_totals.py -q # Second loop: nearby package pytest tests/billing -q # Final confidence check pytest -q ``` Per JavaScript o TypeScript: ``` pnpm test invoice-total.test.ts -- --runInBand pnpm lint src/billing pnpm test ``` Non è solo una questione di tempi di esecuzione. Output più piccoli significano prompt più piccoli nel ciclo successivo. ### 3. Limita l’output dei comandi Se il tuo agente supporta limiti all’output, usali. Altrimenti, applicali tu tramite comandi di supporto: ``` pytest tests/billing -q 2>&1 | tail -120 ``` Oppure, per build con output molto prolisso: ``` pnpm test 2>&1 | grep -E "FAIL|Error|Expected|Received|at " | head -200 ``` Fai attenzione: il filtraggio può nascondere contesto utile. Lo uso dopo il primo errore, non prima. Prima osservo le caratteristiche dell’errore, poi limito le esecuzioni ripetute. ### 4. Chiedi diff, non riscritture Per i file grandi, indica esplicitamente all’agente: ``` Make the smallest safe patch. Do not rewrite unrelated functions. Show a concise diff summary before running tests. ``` Questo riduce il rischio e di solito anche i token di output. Soprattutto, mantiene gestibile la revisione del codice. ### 5. Separare la pianificazione dall'esecuzione Per le modifiche non banali, spesso inizio così: ``` Inspect the relevant files and propose a plan. Do not edit yet. Limit repo inspection to payment, invoice, and tax modules unless needed. ``` Poi approvo il piano e lascio che lo implementi. Questo evita il problema dell'«agente che modifica prima di aver capito». ## Controllare la spesa durante le sessioni lunghe Le sessioni lunghe sono quelle in cui gli agenti CLI danno il meglio e in cui diventano pericolosi. Ecco la lista di controllo della spesa che uso nel lavoro quotidiano: - Definisci un obiettivo per la sessione: «Fai in modo che test_invoice_rounding superi i test», non «sistema la fatturazione». - Specifica i file quando possibile: fornisci i percorsi esatti invece di chiedere all'agente di scoprire tutto. - Reimposta il contesto dopo i cambi di direzione: avvia una nuova sessione con un riepilogo quando l'attività cambia. - Riassumi manualmente gli insuccessi: incolla le 30 righe importanti, non un log di 3,000 righe. - Passa a modelli più potenti in modo ponderato: usa un modello più potente solo dopo aver incontrato un ostacolo chiaro. - Fermati dopo cicli ripetuti: se l'agente fallisce due volte nello stesso modo, intervieni. Un buon prompt per reimpostare il contesto si presenta così: ``` We are fixing invoice rounding. Known facts: - Failure is in tests/billing/test_invoice_totals.py::test_round_half_even - Expected 10.24, actual 10.25 - Decimal quantization happens in src/billing/money.py - Tax calculation calls round_money() from src/billing/tax.py Continue from this summary. Inspect only those files first. ``` Quel prompt può essere meno costoso e più chiaro rispetto al trascinarsi dietro un'intera conversazione fallita. ## Chiavi API, provider e instradamento La maggior parte degli agenti CLI può comunicare direttamente con l'API di un provider di modelli o attraverso un gateway compatibile. Gli aspetti tecnici principali da considerare sono: - Autenticazione: dove vengono conservate le chiavi API e se finiscono nella cronologia della shell o nei log. - Instradamento dei modelli: quale modello gestisce ciascuna fase. - Limiti di frequenza: i cicli degli agenti possono generare rapidamente picchi di richieste. - Osservabilità: rendicontazione dei token e dei costi per sessione. - Confini dei dati: se il codice può essere inviato ad API esterne. Una configurazione minima dell'ambiente spesso si presenta così: ``` export ANTHROPIC_API_KEY="..." export OPENAI_API_KEY="..." export GEMINI_API_KEY="..." ``` Per i team, preferisco uno script wrapper che selezioni i modelli e registri l'utilizzo: ``` #!/usr/bin/env bash set -euo pipefail export AGENT_MODEL="${AGENT_MODEL:-sonnet}" export AGENT_MAX_OUTPUT_TOKENS="${AGENT_MAX_OUTPUT_TOKENS:-4096}" export AGENT_SESSION_BUDGET_USD="${AGENT_SESSION_BUDGET_USD:-10}" coding-agent "$@" ``` Se usi un gateway multimodello, è qui che può essere utile instradare il traffico di Claude, GPT, Gemini o dei modelli aperti attraverso un'unica interfaccia. La caratteristica importante non è l'elenco dei loghi, ma la disponibilità di una rendicontazione affidabile dell'utilizzo e di controlli a livello di modello. ## Cosa inserisco nelle istruzioni del repository La maggior parte degli agenti rispetta una qualche forma di file di istruzioni del repository. Mantengo il mio breve e operativo: ``` ## Agent Instructions - Prefer minimal diffs over rewrites. - Do not run full test suites until targeted tests pass. - Never edit generated files in `dist/`, `build/`, or `coverage/`. - Use `rg` for search. - Before large refactors, propose a plan and wait. - If a command emits more than 200 lines, rerun with a narrower command. ``` Non è una questione di cortesia. Serve a plasmare il ciclo di lavoro. L'agente continuerà a commettere errori, ma buone istruzioni riducono gli sprechi ripetuti. Un'insidia comune: i file di istruzioni troppo lunghi diventano rumore di fondo. Se le istruzioni del tuo agente contengono 300 righe di filosofia sullo stile, il modello potrebbe non cogliere i tre vincoli operativi che contano. Metti per prime le regole di maggior valore. ## Latenza: l'altro costo Anche quando la spesa per i token è accettabile, la latenza può spezzare il ritmo di lavoro. La latenza degli agenti deriva da: - Tempo di inferenza del modello - Tempo di esecuzione degli strumenti - Tempo di indicizzazione dei file - Tempo di esecuzione dei test - Pause per l'approvazione umana Per cicli rapidi, ottimizzo il «tempo fino alla prossima osservazione utile». Un test mirato di 15 secondi è preferibile a una simulazione completa della CI di 6 minuti. Un modello più piccolo che identifica correttamente un errore di sintassi in 4 secondi è preferibile a un modello premium che impiega 45 secondi a produrre una bellissima spiegazione. Le sessioni migliori sembrano programmazione in coppia: ``` inspect → patch → targeted test → inspect failure → patch → targeted test → final suite ``` Le sessioni peggiori sembrano un cosplay della CI: ``` scan repo → edit many files → run everything → drown in logs → repeat ``` ## Limiti e modalità di errore Gli agenti da terminale sono utili, non magici. Fanno fatica quando: - Il repository ha dipendenze nascoste in fase di esecuzione che i test non coprono. - L'attività richiede valutazioni sul prodotto anziché una trasformazione del codice. - L'errore dipende da servizi esterni o da uno stato instabile. - La base di codice presenta astrazioni fuorvianti o documentazione obsoleta. - L'agente non può eseguire il comando di validazione pertinente. Possono anche produrre correzioni plausibili ma sbagliate. Questo è particolarmente comune quando i test sono poco solidi. Se l'agente non può verificare il comportamento, tratta il suo output come una patch non revisionata di un ingegnere junior: potenzialmente utile, ma mai automaticamente affidabile. Anche la sicurezza conta. Non concedere a un agente accesso illimitato alla shell in un repository sensibile senza comprendere il modello di approvazione dello strumento. «Eseguire comandi» include la possibilità di stampare variabili d'ambiente, modificare file, installare pacchetti o accedere alla rete, salvo restrizioni. ## Indicazioni pratiche - Tratta gli strumenti CLI di programmazione come cicli di controllo basati su API, non come singoli prompt. - Ottimizza i costi riducendo il numero di cicli e le dimensioni del contesto, soprattutto l'output dei comandi. - Usa modelli potenti per i ragionamenti complessi, non per ogni passaggio meccanico. - Mantieni le istruzioni del repository brevi, operative e concentrate sul comportamento dell'agente. - Dai la precedenza ai test mirati e lascia la validazione più ampia alla fine. - Reimposta le sessioni lunghe con riepiloghi concisi invece di trascinarti dietro una cronologia ormai superata. - Tieni d'occhio i token di input: sono la fonte di costo nascosta nella programmazione con agenti. - Fermati e intervieni quando l'agente ripete la stessa strategia fallimentare. Claude Code, Aider, Cline e OpenCode fanno parte di un cambiamento reale: l'assistenza alla programmazione sta passando dai motori di suggerimento a collaboratori che operano direttamente nel terminale. I team che ne trarranno il maggior beneficio non saranno quelli che si limiteranno ad «attivare gli agenti». Saranno quelli che progetteranno il ciclo di lavoro: contesto circoscritto, strumenti sicuri, spesa osservabile e verifiche a ogni passaggio. [Programmazione](/it/blog/tag/coding/)[Claude](/it/blog/tag/claude/)[Agenti](/it/blog/tag/agents/) A [AI Prime Tech](https://aiprimetech.io/it/) AI Prime Tech pubblica questo blog. Gli articoli sono redatti con l'assistenza dell'AI; verifica nella documentazione ufficiale i dettagli specifici della versione, come gli ID dei modelli, i prezzi e i limiti, prima di farvi affidamento. Ottieni accesso all'API Claude a un costo inferiore Un'unica chiave API per Claude Opus 5.5, Sonnet 5, Haiku 4.5 e Fable 5.1, oltre a GPT-6 modelli. Pagamento a consumo, senza abbonamento. [Ottieni la tua chiave API →](/register) AI Prime Tech è un gateway API indipendente di terze parti. Claude™ e Anthropic® sono marchi di Anthropic, PBC. Non si intende suggerire alcuna affiliazione o approvazione.