GUIDA · CLAUDE CODE
01 / 07
La cartella
.claude/
spiegata bene.
Ogni file che Claude Code legge davvero. Cosa va dove, cosa è opzionale, e i tre errori che fanno tutti la prima volta.
SCORRI
02 / 07
LA MAPPA
02 / 07
IN DUE MINUTI
Quattro livelli, niente di più.
Tutto quello che Claude Code legge sta in due posti : la radice del progetto e la cartella .claude/ Il resto è dettaglio.
└─
your-project
├─
CLAUDE.md
— le regole del progetto
├─
.mcp.json
— server MCP (alla radice!)
└─
.claude
— skills, agents, hooks, settings
LIVELLO 1 · RADICE
03 / 07
COSA STA NELLA ROOT
I quattro file che contano.
Sono i primi che Claude Code apre. Tienili corti.
CLAUDE.md
Le regole del progetto. Sotto le 200 righe — è advisory, non deterministico. Se diventa lungo, taglia.
CLAUDE.local.md
Override personali, non commitati. Va in .gitignore
.gitignore
Ignora i *.local.* e i secrets. Stop.
.mcp.json
Deve stare alla radice, non dentro .claude/ Definisce i server MCP del progetto.
03 / 07
LIVELLO 2 · DENTRO .CLAUDE/
04 / 07
IL CUORE DELLA CONFIG
Skills, agents, output styles.
Tre cartelle "facili" che fanno il 90% del lavoro.
skills
La casa canonica. Si attivano da sole quando il task lo richiede. Le tue skill personalizzate vivono qui.
agents
Subagenti con context window isolato — code-reviewer, researcher, log-analyzer
output-styles
Formati di risposta personalizzati. Es. terse.md = solo codice, niente prosa.
rules
Path-scoped via frontmatter paths: Si caricano solo quando matcha il glob.
04 / 07
ERRORE #1
05 / 07
IL PRIMO ERRORE
01
Gli hooks non si auto-caricano.
Mettere PostToolUse.sh dentro .claude/hooks/ non basta. Vanno dichiarati in settings.json sotto la chiave "hooks" , con un event matcher esplicito.
✗ COSÌ NON FUNZIONA
.claude/hooks/PostToolUse.sh
# il file c'è, ma Claude
# non lo chiama mai
✓ FUNZIONA COSÌ
// settings.json
"hooks": {
"PostToolUse": [{
"matcher": "Edit|Write",
"hooks": [{
"type": "command",
"command": ".claude/hooks/PostToolUse.sh"
}]
}]
}
05 / 07
ERRORI #2 E #3
06 / 07
ALTRI DUE CLASSICI
02·03
Plugins e statusLine non si mettono a mano.
I plugins si installano col comando /plugin dentro Claude Code — non creando cartelle in .claude/plugins/. La statusLine non è un file: è una chiave dentro settings.json che punta a uno script shell.
// settings.json
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh"
}
}
06 / 07
LA REGOLA D'ORO
07 / 07
CLAUDE.md propone. Gli hooks impongono.
Le skills e i commands si caricano on-demand. Il resto è scenografia. Verificato sulla documentazione ufficiale di Anthropic