Introduzione
Claude Code è diventato un riferimento per chi costruisce un agente LLM: semplice da capire, potente nell'uso e piacevole nell'esperienza.
In sintesi: riduci la complessità, guida il modello con prompt solidi e offri strumenti deterministici.
L'approccio mette al centro una architettura minimale: un solo control loop, tool ben progettati, prompt ricchi di euristiche ed esempi. Il risultato è un agente reattivo, facile da debuggare e coerente nelle decisioni, senza ricorrere a grafo di agenti o RAG complessi.
Contesto
Questo metodo nasce dall'osservazione pratica di un agente utilizzato quotidianamente in sviluppo software. La filosofia è chiara: sfruttare ciò che gli LLM sanno fare bene (lettura, pattern matching, ragionamento guidato) compensando le aree deboli con tool specializzati, regole di stile e una gestione esplicita dei task.
Perché Claude Code funziona
Perché mantiene il controllo con un design minimale e strumenti mirati che riducono gli errori impliciti.
- Un solo main loop con al massimo un ramo secondario
- Modelli piccoli per I/O massivo, parsing e sintesi
- Prompt lunghi con esempi, tag strutturati e regole operative
- LLM search al posto di RAG per cercare nel codice
- Tool a diversi livelli (low/medium/high) e policy d'uso
- Todo list gestita dall'agente per tenere il focus
- Steerability: tono, "IMPORTANTE", algoritmo con euristiche
Control loop semplice
Mantieni una singola conversazione e un solo ramo di lavoro quando serve.
Il control loop resta lineare: lista piatta di messaggi, iterazioni di tool-calling e, solo per compiti corposi, la creazione di un sub-agente che non può a sua volta innestare altri rami. Il risultato del ramo confluisce nella storia come risposta di tool, mantenendo traccia e verificabilità. Questo riduce l'opacità tipica dei sistemi multi-agente e facilita il debug. Inoltre, moltissime invocazioni usano un modello più piccolo (ad esempio per leggere file lunghi, riassumere git o dare etichette di stato), con un risparmio di costi e latenza senza sacrificare qualità nelle decisioni locali.
Prompting che guida davvero
Struttura il prompt con sezioni, tag e casi di esempio.
Il system prompt include tono, stile, proattività, gestione task, policy d'uso dei tool, data e contesto operativo. La presenza costante di un file di regole (tipo claude.md) veicola preferenze dell'utente e vincoli del progetto: directory da ignorare, librerie obbligatorie, convenzioni di stile. L'uso di tag XML per promemoria, esempi buoni/cattivi e di Markdown per sezioni nette aiuta il modello a scegliere il percorso corretto quando ci sono più opzioni plausibili.
Context file (claude.md) e preferenze
Un file di regole condivise codifica vincoli e stile, sempre incluso nei prompt.
Senza questo contesto, l'agente perde coerenza: il file consolida preferenze che non emergono dal codice (es. esclusioni, librerie, convenzioni) e riduce risposte erratiche, soprattutto in sessioni lunghe.
Tag XML, Markdown ed esempi
Tag e heading creano corsie di decisione esplicite per l'LLM.
Promemoria di sistema, esempi positivi/negativi e checklist orientano scelte operative (quando usare un tool, come evitare errori comuni, quali path preferire), riducendo biforcazioni ambigue e regressioni.
Strumenti: LLM search batte RAG
Cerca come uno sviluppatore: comandi mirati e regex efficaci.
Invece di indicizzare e chunkare, l'agente interroga il codice con comandi potenti (regex, glob, filtri) e legge solo ciò che serve, anche a blocchi progressivi con modelli piccoli. Questo evita fallimenti nascosti di RAG (similarity, rerank, chunking di file non strutturati) e lascia al modello il lavoro di comprensione, riducendo il numero di componenti fragili.
Progettare i tool (low, medium, high level)
Combina granularità diverse in base a frequenza e affidabilità d'uso.
Tool low-level (bash, read, write) garantiscono flessibilità; tool medi (grep, glob, edit) ottimizzano azioni frequenti con interfacce più sicure; tool high-level (web fetch, diagnosi IDE, execution) offrono risultati deterministici e rapidi. Definisci descrizioni chiare, esempi d'uso e regole di scelta tra tool equivalenti.
- Task, Bash, Read, Write, Edit/MultiEdit, NotebookEdit
- Glob, Grep, LS per ricerche e navigazione strutturate
- WebFetch, WebSearch per dati esterni in modo controllato
- TodoWrite per tracciare e aggiornare obiettivi
- Diagnostica/execute via IDE come azioni atomiche affidabili
Todo list gestita dall'agente
La lista evita deriva contestuale e mantiene il piano visibile.
L'agente crea e aggiorna i todo, li consulta spesso e li modifica al bisogno. Questo stabilizza sessioni lunghe, facilita correzioni in corsa e sfrutta il ragionamento interleaved per inserire/rifiutare attività quando emergono nuove informazioni.
Steerability: tono, vincoli e algoritmo
Controlla estetica, limiti e passi decisionali con esempi.
Sezioni su tono e stile evitano preamboli inutili o moralismi; frasi forti ("IMPORTANTE", "MAI") restano ancora efficaci per disinnescare comportamenti indesiderati. La parte decisiva è scrivere l'algoritmo operativo: una sequenza di passi con euristiche e casi realistici che spiega come pianificare, scegliere tool, verificare risultati e correggere rotta.
Conclusione
La lezione chiave: semplicità architetturale, prompt espressivi e tool deterministici battono impalcature complesse. Un main loop, modelli piccoli per compiti I/O-intensivi, LLM search e una todo list esplicita producono un agente più controllabile, economico e pronto a evolvere con i progressi dei modelli.
FAQ
-
Cos'ha di speciale Claude Code negli agenti LLM?
Sceglie un loop unico, tool mirati e prompt ricchi, riducendo complessità e fallimenti nascosti. -
Quando usare modelli piccoli in questo approccio?
Per letture massicce, sintesi, parsing, etichettature frequenti: costano meno e sono reattivi. -
Perché Claude Code evita RAG nella ricerca AI sul codice?
Per limitare failure mode di similarity/chunking e sfruttare regex/ricerche progressive. -
Come aiuta il file claude.md?
Incorpora preferenze e vincoli non deducibili dal repo, aumentando coerenza e qualità. -
Qual è il ruolo della todo list dell'agente?
Mantiene il focus, esplicita priorità e consente correzioni in corsa nelle sessioni lunghe. -
Serve davvero un sistema multi-agente?
Nella maggior parte dei casi no: un solo loop con un ramo massimo è più semplice da debuggare.