Il problema
Claude Code ha cinque livelli di contesto distinti: CLAUDE.md, Rules, Skills, Agents e Hooks. Ognuno risponde a una domanda diversa. Metti la conoscenza nel livello sbagliato e appesantirà ogni sessione, verrà ignorata o non si attiverà quando serve.
Questa bussola ti dà un modello mentale per decidere dove mettere cosa e perché quel livello è quello giusto.
Mappa dell'architettura
Segui un prompt reale attraverso i cinque livelli. Useremo ShopFlow, un e-commerce fittizio, per mostrare come appare ogni livello nella pratica.
Uno sviluppatore chiede a Claude di aggiungere una pagina di checkout Stripe...
Albero decisionale
Clicca per trovare il livello giusto per la tua conoscenza.
Ho una conoscenza o una linea guida che voglio far usare a Claude. Di che tipo è?
I 5 livelli
Ogni livello ha uno scopo, un test decisivo e degli anti-pattern. Espandi un livello per vedere i dettagli.
Sempre. La prima cosa da creare.
L'identità del progetto in meno di 200 righe. Stack tecnologico, comandi di build, struttura dei file, convenzioni non deducibili dal codice.
Definisce il contesto di base di ogni sessione. È il README per Claude.
Devi codificare pattern di layout, riferimenti di architettura, preferenze di strumenti specifiche del progetto (per es. strumenti di migrazione, pattern di test) o rimandi alla documentazione centrale, soprattutto in progetti grandi e complessi.
File .md modulari in .claude/rules/. Possono avere ambito per percorso con il frontmatter paths:. Possono riferirsi a doc di architettura esterne, ADR, pagine wiki o convenzioni di strumenti scelte per questo progetto.
Le rule collegano Claude alla tua base di conoscenza più ampia. Codificano le decisioni strutturali specifiche del progetto: come è organizzato il codice, quali pattern e strumenti sono preferiti qui, dove trovare i riferimenti autorevoli. Senza appesantire ogni sessione.
Hai una conoscenza approfondita di una tecnologia, un workflow o un dominio che Claude dovrebbe consultare quando rilevante.
File SKILL.md con frontmatter. Invocati automaticamente per corrispondenza della descrizione, o manualmente via /nome-skill.
Caricate su richiesta, non a ogni sessione. Mantiene pulito il contesto di base rendendo disponibile la competenza approfondita.
Un'attività ricorrente trae vantaggio da un persona specializzato con strumenti limitati e skill precaricate.
File .md di agent che definiscono ruolo, strumenti consentiti, skill precaricate e istruzioni di comportamento.
Isolamento. Un code-reviewer non ha bisogno di accesso in scrittura. Un ricercatore non ha bisogno di Edit. Gli agent limitano contesto e permessi a un ruolo.
Hai bisogno di un'esecuzione garantita e deterministica, non di una linea guida consultiva.
Comandi shell attivati da eventi del ciclo di vita (PreToolUse, PostToolUse, SessionStart, ecc.).
Rule e CLAUDE.md sono consultivi. Claude potrebbe saltarli. Gli hook sono codice che viene eseguito.
Matrice di confronto
Confronto fianco a fianco dei cinque livelli.
| Livello | Ambito | Si carica quando? | Applicazione | Contiene |
|---|---|---|---|---|
CLAUDE.md | Progetto | Sempre, a ogni sessione | Consultivo | Identità, convenzioni |
Rules | Progetto / Utente | Sempre o per percorso | Consultivo | Struttura, riferimenti di architettura |
Skills | Marketplace | Su richiesta / auto-match | Consultivo | Conoscenza tecnica, workflow |
Agents | Marketplace | Quando riceve la delega | Vincolante | Ruolo, restrizioni sugli strumenti |
Hooks | Progetto / Utente | Su evento del ciclo di vita | Vincolante | Comandi shell |
Progetto
Sempre, a ogni sessione
Identità, convenzioni
Progetto / Utente
Sempre o per percorso
Struttura, riferimenti di architettura
Marketplace
Su richiesta / auto-match
Conoscenza tecnica, workflow
Marketplace
Quando riceve la delega
Ruolo, restrizioni sugli strumenti
Progetto / Utente
Su evento del ciclo di vita
Comandi shell
Consultivo vs Vincolante
Consultivo
Claude dovrebbeClaude li legge e li segue, la maggior parte delle volte. Ma può scegliere di discostarsene se ritiene che qualcos'altro sia meglio.
Vincolante
Claude deveSi eseguono meccanicamente. Gli hook girano come comandi shell. Le restrizioni sugli strumenti degli agent sono confini rigidi. Nessuna discrezionalità.
Gerarchia degli ambiti
Clicca su un ambito per vedere cosa contiene. Gli ambiti superiori prevalgono su quelli inferiori.
Gli ambiti superiori prevalgono su quelli inferiori ↓
Skill vs Agent
Skill = il COSA
Conoscenza tecnologica. Come funziona Playwright? Quali sono le best practice per la configurazione di Vite? Come strutturiamo le pipeline GitLab CI?
skill playwright: conosce locator, fixture, Page Object Model, pattern di esecuzione parallela.
Agent = il CHI
Uno specialista che usa quella conoscenza. Ha un persona, strumenti limitati e una mentalità specifica. L'agent precarica le skill di cui ha bisogno.
agent test-writer: precarica la skill playwright + ha accesso in scrittura solo ai file di test + ragiona su casi limite e isolamento.
Se è solo conoscenza senza differenze di permessi → Skill
Cheat sheet decisionale rapida
Documentazione ufficiale
File CLAUDE.md, memoria automatica, gerarchia dei file e ordine di caricamento
Rule con ambito per percorso, frontmatter, symlink, rule a livello utente
Struttura di SKILL.md, frontmatter, auto-invocazione, file di supporto
Agent personalizzati, restrizioni sugli strumenti, precaricamento delle skill, isolamento
Eventi del ciclo di vita, tipi di hook, automazione deterministica
Pattern pratici ed esempi di configurazione degli hook
Permessi, variabili d'ambiente, gerarchia delle impostazioni
Distribuire skill e agent tra i team
Pattern di lavoro per ottenere il massimo da Claude Code