0. TL;DR
Questo articolo nasce da sei mesi di uso approfondito di Claude Code e dagli insegnamenti tratti spendendo 40 $/mese su due account. Spero di fornire spunti utili a tutti.
All'inizio lo usavo come ChatBot, ma presto mi sono reso conto che le cose andavano storte: il contesto diventava caotico, gli strumenti aumentavano ma l'efficacia diminuiva e le regole venivano ignorate nonostante fossero più lunghe. Dopo aver studiato Claude Code stesso, ho capito che non era un problema di Prompt, ma un problema di progettazione del sistema.
Voglio discutere: come funziona Claude Code sotto il cofano, perché il contesto diventa confusionario e come governarlo, come progettare Skills e Hooks, l'uso corretto dei Subagent, l'impatto architetturale del Prompt Caching e come scrivere un CLAUDE.md davvero utile.
Il modo più diretto per capirlo è suddividere Claude Code in sei strati:
Rafforzare un solo strato crea squilibrio. Se CLAUDE.md è troppo lungo, inquina il contesto; troppi strumenti creano confusione; troppi subagent portano a derive di stato; saltare la verifica rende impossibile capire dove le cose sono fallite.
1. Come funziona sotto il cofano
Il cuore di Claude Code non è "rispondere", ma un loop agente ripetitivo:
1Raccogli Contesto → Esegui Azione → Verifica Risultato → [Fine o Loop]2 ↑ ↓3 CLAUDE.md Hooks / Permessi / Sandbox4 Skills Strumenti / MCP5 Memoria
Mi sono reso conto che i colli di bottiglia raramente sono dovuti al fatto che il modello non è abbastanza intelligente, ma piuttosto che gli viene fornito il contesto sbagliato o non si ha modo di giudicare se l'output è corretto o di tornare indietro.
Cinque strati su cui concentrarsi:
Guardare questi strati semplifica la risoluzione dei problemi. Risultati instabili? Controlla l'ordine di caricamento del contesto. Automazione fuori controllo? Controlla il livello di controllo. Qualità in calo nelle sessioni lunghe? I prodotti intermedi hanno inquinato il contesto; avviare una nuova sessione è meglio che ritoccare i prompt.
2. Confini concettuali: MCP / Plugin / Strumenti / Skills / Hooks / Subagent
Regola semplice: usa Strumenti/MCP per nuove azioni, Skills per flussi di lavoro, Subagent per ambienti isolati, Hooks per vincoli/audit obbligatori e Plugin per la distribuzione tra progetti.
3. Ingegneria del Contesto: Il Vincolo di Sistema Più Importante
Molti trattano il contesto come un "problema di capacità", ma il collo di bottiglia è di solito il rumore. Le informazioni utili vengono sepolte in contenuti irrilevanti.
Composizione Reale del Costo del Contesto
Il contesto da 200K di Claude Code non è completamente disponibile:
1200K Contesto Totale2├── Sovraccarico Fisso (~15-20K)3│ ├── Istruzioni di sistema: ~2K4│ ├── Descrittori di Skill: ~1-5K5│ ├── Definizioni degli strumenti del server MCP: ~10-20K ← Il più grande assassino nascosto6│ └── Stato LSP: ~2-5K7│8├── Semi-fisso (~5-10K)9│ ├── CLAUDE.md: ~2-5K10│ └── Memoria: ~1-2K11│12└── Dinamico Disponibile (~160-180K)13 ├── Cronologia chat14 ├── Contenuto dei file15 └── Risultati degli strumenti
Un tipico server MCP (es. GitHub) contiene 20-30 definizioni di strumenti, ciascuna ~200 token, per un totale di 4.000-6.000 token. Collegare 5 server consuma 25.000 token (12,5%). Questo è critico quando si leggono grandi quantità di codice.
Stratificazione del Contesto Consigliata
1Sempre Residente → CLAUDE.md: Contratto di progetto / comandi di build / divieti2Basato su Percorso → regole: Regole specifiche per lingua / directory / tipo di file3Su Richiesta → Skills: Flussi di lavoro / conoscenze di dominio4Isolato → Subagent: Esplorazione su larga scala / ricerca parallela5Fuori dal Contesto → Hooks: Script deterministici / audit / blocco
Non caricare cose che usi solo occasionalmente.
Buone Pratiche per il Contesto
- Mantieni CLAUDE.md breve, solido ed eseguibile. Quello di Anthropic è ~2.5K token.
- Sposta i documenti di riferimento grandi nei file di supporto delle Skills.
- Usa .claude/rules/ per regole di percorso/lingua.
- Usa /context per monitorare il consumo.
- Usa /clear per cambiare attività e /compact per nuove fasi.
- Scrivi Istruzioni Compatte in CLAUDE.md per controllare cosa viene preservato.
Rumore dell’Output degli Strumenti: Un Altro Assassino Nascosto
L'output dinamico degli strumenti (come cargo test o git log) può facilmente riempire il contesto. Claude non ha bisogno di vedere tutto.
RTK (Rust Token Killer) è un buon approccio: filtra l'output dei comandi prima che arrivi a Claude. Ad esempio, può condensare migliaia di righe di output di test in un singolo messaggio di successo.
Trappole di Compressione
La compressione predefinita potrebbe cancellare decisioni architetturali e vincoli.
Soluzione: Specifica Istruzioni Compatte in CLAUDE.md per dare priorità a decisioni architetturali, file modificati, stato di verifica e TODO.
Un'altra soluzione proattiva: Chiedi a Claude di scrivere un HANDOFF.md prima di iniziare una nuova sessione per spiegare progressi e vicoli ciechi.
Valore Ingegneristico della Modalità Plan
La Modalità Plan separa esplorazione ed esecuzione.
Per refactoring complessi, questo è meglio che precipitarsi a scrivere codice. Consiglio avanzato: Usa un Claude per scrivere il piano e un altro come "Senior Engineer" per revisionarlo.
4. Progettazione delle Skills: Flussi di Lavoro Caricati su Richiesta
Le Skills sono conoscenze e flussi di lavoro su richiesta.
Cosa rende buona una Skill
- La descrizione dovrebbe dire "quando usarmi", non "cosa faccio".
- Avere passaggi completi passaggi, input, output e condizioni di arresto.
- Mantenere il corpo principale per la navigazione e i vincoli principali; spostare i dettagli nei file di supporto.
- Impostare disable-model-invocation: true per le skills con effetti collaterali.
Divulgazione Progressiva
Claude Code enfatizza la "divulgazione progressiva": prima fornire indici e navigazione, poi estrarre i dettagli secondo necessità.
Tre Tipi Tipici di Skill
- Checklist (Cancello di Qualità): es. release-check.
- Flusso di Lavoro (Operazioni Standardizzate): es. config-migration con rollback.
- Esperto di Dominio (Quadro Decisionale): es. runtime-diagnosis.
Mantieni i descrittori brevi per risparmiare spazio nel contesto.
5. Progettazione degli Strumenti: Aiutare Claude a Scegliere Correttamente
Gli strumenti per gli agenti dovrebbero concentrarsi sulla facilità di uso corretto piuttosto che sulla completezza delle funzionalità.
Buoni vs. Cattivi Strumenti
Principi di progettazione: Usa prefissi (github_pr_*), supporta formati concisi, fornisci messaggi di errore utili ed evita di esporre troppi strumenti frammentati.
Evoluzione degli Strumenti Interni</b
L'evoluzione dello strumento "AskUserQuestion" mostra che uno strumento dedicato è più stabile della formattazione markdown o dei parametri di uscita.
Gli strumenti Todo sono diventati un "ostacolo" man mano che i modelli diventavano più forti. Gli strumenti di ricerca si sono evoluti da RAG a Grep per una migliore flessibilità e "divulgazione progressiva".
6. Hooks: Logica Obbligatoria Prima/Dopo le Operazioni
Gli Hooks riprendono il controllo deterministico su processi come formattazione, protezione dei file e notifiche.
Adatti per Hooks
Bloccare file protetti, formattazione automatica dopo le modifiche, iniezione di contesto dinamico (ramo Git) e notifiche.
Rilevamento Precoce degli Errori
7. Subagent: Istanze Claude Indipendenti
I Subagent forniscono isolamento. Attività come la scansione di repository o l'esecuzione di test producono output massiccio che non dovrebbe ingombrare il thread principale.
Vincoli Espliciti
Limita gli strumenti, scegli il modello giusto (Haiku per l'esplorazione, Opus per la revisione) e imposta maxTurns.
8. Prompt Caching: Il Cuore dell’Architettura di Claude Code
Claude Code è costruito attorno al Prompt Caching. Tassi di hit elevati fanno risparmiare denaro e aumentano i limiti di frequenza.
Disposizione del Prompt per il Caching
L'ordine è importante per il prefisso di corrispondenza: Prompt di Sistema → Definizioni degli Strumenti → Cronologia Chat → Input Utente.
Non Cambiare Modello a Metà Sessione
Cambiare modello interrompe la cache. Usa Subagent per i passaggi di consegna.
Implementazione della Compattazione
La compattazione usa un fork per riassumere la cronologia a 1/10 del costo grazie agli hit nella cache.
9. Cicli di Verifica: Nessun Verificatore, Nessun Agente di Ingegneria
"Claude dice che è fatto" è inutile senza verifica. Definisci la verifica esplicitamente nel Prompt, nella Skill e in CLAUDE.md.
10. Comandi ad Alta Frequenza
Comandi come /context, /clear, /compact e /memory aiutano a gestire attivamente il contesto.
Governance e Parallelismo
Comandi nascosti utili: /simplify (revisione del codice), /rewind (checkpoint), /btw (domande collaterali), /insight (analizza la sessione per aggiornamenti a CLAUDE.md).
11. Come Scrivere un Buon CLAUDE.md
È un contratto, non una base di conoscenza.
Includi comandi di build/test, confini architetturali, convenzioni di codifica, barriere di sicurezza e Istruzioni Compatte. Chiedi a Claude di aggiornare CLAUDE.md dopo aver corretto i suoi errori.
12. Esperienze Recenti
Lezioni dalla creazione di Kaku (Rust + Lua): la trasparenza dell'ambiente è vitale (usa un comando 'doctor') e gli Hooks sono ottimi per progetti multi-lingua.
13. Anti-pattern
14. Health Check
Usa npx skills add tw93/claude-health per controllare la tua configurazione.
15. Conclusione
L'attenzione si sposta da "come usare le funzionalità" a "come far funzionare l'agente sotto vincoli". Se non riesci a definire "fatto", l'attività non è pronta per un agente.
