Cinque componenti, cinque cicli di vita

Claude Code non ha un unico meccanismo di configurazione: ne ha cinque, e la differenza vera è quando ciascuno entra nel contesto.

  • Rules — i CLAUDE.md e i markdown in .claude/rules/. Li scrivi tu, entrano all’avvio di ogni sessione.
  • Skills — una cartella con dentro SKILL.md. All’avvio entra solo il nome con la sua description; il corpo arriva quando la skill viene invocata. La doc lo dice così: «full skill content only loads when invoked».
  • Commands — i vecchi file in .claude/commands/. Sono confluiti nelle skill: .claude/commands/deploy.md e .claude/skills/deploy/SKILL.md producono entrambi /deploy.
  • Agents — i subagenti in .claude/agents/. Partono con una finestra di contesto propria e restituiscono al thread principale solo un riassunto.
  • Agent memory — la auto memory che Claude scrive da sé, un indice MEMORY.md più un file per argomento; dell’indice vengono caricate le prime 200 righe o i primi 25 KB, il primo dei due che arriva.

Regola pratica: un fatto che serve sempre va in CLAUDE.md; una procedura che serve ogni tanto va in una skill, perché il suo corpo non costa nulla finché non la usi; qualcosa che deve accadere comunque, a prescindere da quello che il modello decide, non va scritto in prosa da nessuna parte — va in un hook.

La gerarchia dei CLAUDE.md

I file vengono cercati nella directory di lavoro e in tutte quelle sopra. Non si sovrascrivono: «All discovered files are concatenated into context rather than overriding each other», dalla radice del filesystem in giù, e dentro ogni directory il CLAUDE.local.md viene accodato dopo il CLAUDE.md. Quelli nelle sottocartelle non si caricano all’avvio: entrano quando Claude legge un file lì dentro.

/Library/Application Support/ClaudeCode/CLAUDE.md   macOS, policy aziendale
/etc/claude-code/CLAUDE.md                          Linux e WSL, policy aziendale
~/.claude/CLAUDE.md                                 tuo, tutti i progetti
./CLAUDE.md  oppure  ./.claude/CLAUDE.md            di progetto, da committare
./CLAUDE.local.md                                   tuo, questo progetto, da gitignorare
.claude/rules/*.md                                  modulari, con `paths:` opzionale

Le regole in .claude/rules/ senza campo paths si caricano all’avvio con la stessa priorità di .claude/CLAUDE.md; quelle con paths in frontmatter entrano solo quando Claude tocca un file che matcha il glob. È il modo giusto di tenere sotto controllo la dimensione: l’obiettivo dichiarato è meno di 200 righe per file, e gli import con @percorso/file.md — profondità massima quattro salti — organizzano ma non risparmiano contesto, perché l’importato viene espanso al lancio comunque.

Su un repository nuovo si parte da /init, che analizza il codice e genera un CLAUDE.md; se ne esiste già uno propone migliorie invece di sovrascriverlo. Poi si verifica con /context, che elenca i Memory files effettivamente caricati: se un file non compare lì, Claude non lo sta vedendo, e continuare a riscriverlo è tempo perso.

settings.json: chi vince

La precedenza va dall’alto verso il basso, e il primo che definisce una chiave vince:

managed-settings.json / MDM / console   organizzazione, non sovrascrivibile
claude --settings                        questa sessione
.claude/settings.local.json              tu, in questo progetto
.claude/settings.json                    tutto il team, versionato
~/.claude/settings.json                  tu, ovunque

Le chiavi che userai davvero sono permissions (con allow, ask, deny, defaultMode e additionalDirectories), hooks, env, model, enabledPlugins, statusLine. Committa .claude/settings.json; settings.local.json resta personale — Claude Code lo aggiunge alle esclusioni git globali la prima volta che lo scrive, ma se lo crei a mano l’ignore lo metti tu.

Sessioni ed esecuzione programmatica

Le sessioni sono trascrizioni JSONL salvate in continuo sotto ~/.claude/projects/. Le riprendi con claude --continue (l’ultima in questa directory), claude --resume (selettore) o /resume da dentro. /branch duplica la conversazione e ti ci sposta, lasciando intatta l’originale: è il modo per provare una strada alternativa senza perdere quella su cui sei.

Per l’esecuzione non interattiva la Exam Guide usa il termine headless mode. Attenzione: è il termine della guida, non della documentazione — la pagina si chiama «Run Claude Code programmatically» e quella parola non ci compare. In pratica:

claude -p "Trova e correggi il bug in auth.py" --allowedTools "Read,Edit,Bash"
claude -p "Riassumi il progetto" --output-format json | jq -r '.result'
claude -p "Spiega la ricorsione" --output-format stream-json --verbose --include-partial-messages

--output-format accetta text (default), json e stream-json; con --json-schema la risposta arriva nel campo structured_output. Due cose che si scoprono tardi. La prima: in -p la modalità di permessi di partenza è manuale su ogni piano, quindi la auto-mode va chiesta esplicitamente con --permission-mode auto. La seconda: senza --bare una sessione -p carica hook, skill, plugin, server MCP e CLAUDE.md della macchina su cui gira, anche in una cartella mai aperta prima — in CI è esattamente quello che non vuoi, e infatti --bare è la modalità raccomandata per script e SDK. Le sessioni create con -p non compaiono nel selettore né in --continue, ma restano riprendibili passando il session id a claude --resume.