La cartella .claude: il centro di controllo di Claude Code

La maggior parte degli sviluppatori che usano Claude Code convive con la cartella .claude senza mai aprirla davvero. La vede comparire nella radice del progetto, sa che esiste, ma la considera una scatola nera generata dallo strumento. È un’occasione persa, perché quella cartella non è un dettaglio implementativo ma il centro di controllo da cui dipende il comportamento di Claude in ogni sessione di lavoro. Capire cosa contiene, quali file si modificano spesso e quali si impostano una volta sola è la differenza tra subire le risposte dell’assistente e configurarlo in modo che si comporti come il team vuole.

Due cartelle, non una

Il primo punto da chiarire è che le cartelle .claude sono due, non una. Quella di progetto vive nella radice del repository e va versionata insieme al codice, perché contiene la configurazione condivisa: ogni membro del team eredita le stesse regole, gli stessi comandi personalizzati e le stesse politiche di permesso. Quella globale vive in ~/.claude/ ed è personale, contiene preferenze individuali, cronologia delle sessioni e memoria automatica che Claude accumula nel tempo. Confondere i due livelli porta a configurazioni che funzionano sulla macchina di chi le ha scritte ma si rompono appena qualcun altro apre il progetto, o all’opposto a regole personali finite per errore nel repository condiviso.

Il file CLAUDE.md

CLAUDE.md è il file più importante dell’intero sistema. Quando Claude Code apre una sessione lo carica direttamente nel prompt di sistema e ne tiene conto per tutta la conversazione. Quello che si scrive lì viene rispettato in modo costante, dalle convenzioni sui nomi alle scelte architetturali, dai comandi per build e test alle abitudini sul logging. Il valore del file dipende molto dalla disciplina con cui viene mantenuto. Funzionano bene i comandi reali da eseguire, le decisioni di architettura non ovvie, le trappole specifiche del progetto come una modalità strict del compilatore o convenzioni di import non standard. Funzionano male le copie di documentazione già linkabile altrove, le spiegazioni teoriche e le liste interminabili di preferenze stilistiche che un linter coprirebbe meglio.

C’è una soglia pratica sopra cui CLAUDE.md smette di essere efficace. Oltre le duecento righe il modello inizia a perdere aderenza alle istruzioni e il file diventa una di quelle wiki interne che nessuno legge davvero. Quando il progetto cresce conviene affidarsi alla cartella rules/, che permette di spezzare le istruzioni in file separati caricati automaticamente accanto a CLAUDE.md. Ogni regola può essere ulteriormente vincolata a determinati percorsi tramite un frontmatter YAML, in modo che le convenzioni sulle API non vengano caricate quando Claude sta lavorando su un componente React e viceversa. È lo stesso principio dei file di configurazione modulari di strumenti come ESLint o Prettier, applicato alle istruzioni in linguaggio naturale.

Comandi personalizzati

La cartella commands/ trasforma file markdown in slash command invocabili dalla conversazione. Un file review.md diventa il comando /review, invocato col solo nome nelle versioni recenti e non più col vecchio prefisso /project:. Il valore di questi comandi non sta nel salvare un prompt riutilizzabile, come farebbe uno snippet, ma nella possibilità di iniettare nel contesto l’output di comandi shell eseguiti al volo o argomenti passati dall’utente. Un comando di fix issue, per esempio, può ricevere come argomento il numero dell’issue e caricarne il contenuto. L’esempio nell’immagine è un comando di questo tipo: il frontmatter dichiara i permessi necessari, la riga che esegue git diff ne inserisce l’output nel prompt e $ARGUMENTS raccoglie l’area su cui concentrare la revisione, così basta invocare /review per avere il diff corrente già davanti a Claude. Va aggiunto che nelle versioni recenti comandi personalizzati e skill sono confluiti nello stesso meccanismo, tanto che un file in commands/ e una skill equivalente producono lo stesso comando.

Skill e agent, due forme diverse di automazione

Skill e agent sono spesso confusi perché vivono entrambi in cartelle dedicate dentro .claude, ma rispondono a esigenze opposte. Una skill è un workflow che Claude attiva di propria iniziativa quando la conversazione corrisponde alla descrizione nel frontmatter del file SKILL.md, senza che l’utente debba invocarla esplicitamente. Quando si chiede a Claude di rivedere una pull request per problemi di sicurezza, una skill chiamata security-review può essere riconosciuta e caricata automaticamente. Le skill hanno il vantaggio di poter portare con sé file di supporto, guide dettagliate e documentazione di riferimento che vivono accanto a SKILL.md e vengono inclusi nel contesto solo al momento dell’attivazione.

Gli agent sono invece personalità specialistiche con un proprio system prompt, una propria selezione di tool e perfino una propria preferenza di modello. Quando un task è abbastanza complesso da meritare un contesto isolato, Claude può delegarlo a un agent che lavora nel proprio spazio, restituisce un risultato compresso e mantiene pulita la sessione principale. La possibilità di restringere i tool disponibili a un agent è una scelta progettuale importante: un auditor di sicurezza non ha alcun motivo di poter scrivere file, e limitarne i permessi a Read, Grep e Glob è una forma di principio del minimo privilegio applicata all’automazione.

Permessi e settings.json

Il file settings.json definisce cosa Claude può fare senza chiedere conferma, cosa è bloccato in modo assoluto e cosa rientra nella zona intermedia che richiede approvazione. La struttura prevede una lista di allow per i comandi sicuri e ripetitivi come gli script di npm o i comandi git in sola lettura, una lista di deny per le operazioni pericolose come rm -rf, l’accesso a file sensibili o le chiamate di rete dirette, e un comportamento di default che chiede sempre conferma per tutto ciò che non rientra nelle due liste. Questa terza zona è quella che rende il sistema usabile in pratica, perché non costringe a prevedere ogni possibile comando in anticipo ma fornisce comunque una rete di sicurezza ragionevole. Come per CLAUDE.md, esiste un equivalente locale, settings.local.json, automaticamente escluso dal versionamento, in cui inserire le deroghe personali senza inquinare la configurazione di team.

Una progressione realistica

Adottare tutta questa struttura dal primo giorno è eccessivo per la maggior parte dei progetti. Una progressione che funziona parte da un CLAUDE.md essenziale prodotto con /init e ridotto manualmente alle voci che contano, prosegue con un settings.json che dichiara esplicitamente i permessi di base, aggiunge uno o due comandi personalizzati per i flussi più ripetuti come la code review o il fix di una issue, e solo quando CLAUDE.md inizia a gonfiarsi promuove le sue sezioni in file separati dentro rules/. Skill e agent arrivano dopo, quando emergono workflow complessi che meritano di essere impacchettati. La cartella .claude è in fondo un protocollo per dire a Claude chi sei, cosa fa il progetto e quali regole vuoi che rispetti. Più chiaramente lo definisci, meno tempo passerai a correggere le sue risposte e più tempo userà davvero per produrre lavoro utile.