Il miglior setup di Claude Code per il 2026 (30 min)

Ogni setup di Claude Code che abbiamo rivisto rientra in una di due modalità di fallimento. La prima è il default nudo: niente CLAUDE.md, niente skill, prompt dei permessi a ogni comando, e l'utente che si chiede perché Claude continui a dimenticare come builda il suo progetto. La seconda è la macchina iper-configurata: 40 skill, 9 server MCP, un CLAUDE.md lungo come una tesi, e una finestra di contesto già mezza consumata prima del primo prompt.

Il setup giusto sta nel mezzo, e ci vogliono circa 30 minuti per costruirlo se segui i livelli nell'ordine di dipendenza corretto. Quell'ordine conta. Le skill presuppongono un'installazione funzionante. Le decisioni sui permessi dipendono da quali server MCP usi. La suddivisione per-progetto ha senso solo quando sai cosa stai dividendo. Questa è la guida che diamo ai nuovi membri del team SkillProof il primo giorno, con le parti che abbiamo sbagliato nei primi sei mesi tolte di mezzo.

Livello 1: installazione e autenticazione, cinque minuti

Probabilmente l'hai già fatto, quindi la faccio breve.

npm install -g @anthropic-ai/claude-code
cd your-project
claude

Al primo avvio, /login ti guida nell'autenticazione. Hai due percorsi di fatturazione: un abbonamento Claude (Pro o Max) oppure una API key con fatturazione a consumo. Se programmi con Claude ogni giorno, l'abbonamento è quasi sempre più economico; la fatturazione API su sessioni agentiche pesanti sale più in fretta di quanto la gente si aspetti. Se sei in un team, controlla se la tua organizzazione ha già un seat Claude for Work prima di bruciare una API key personale.

Verifica con qualcosa di banale ("cosa fa questo repo?") e conferma che Claude riesca a leggere i tuoi file. Questo è tutto il livello. Tutto il resto è dove i setup iniziano davvero a divergere.

Livello 2: un CLAUDE.md che si guadagna i suoi token

CLAUDE.md è un file markdown che Claude carica in contesto all'inizio di ogni sessione in quel progetto. Ogni sessione, che il contenuto sia rilevante o no. Questo comportamento di caricamento detta tutto quello che ci deve stare dentro.

Cosa ci va: fatti che si applicano a quasi ogni sessione. Comandi di build e test. La versione in due frasi della tua architettura. Convenzioni che Claude continua a sbagliare se non gliele dici (l'ordine dei tuoi import, il formato dei tuoi commit). Dove sono sepolti i cadaveri: il modulo deprecato che nessuno dovrebbe toccare, il file di config che sembra inutilizzato ma non lo è.

Cosa non ci va: conoscenza procedurale che ti serve occasionalmente. Come scrivere una migration del database. La tua checklist di release. Lo stile aziendale per le email ai clienti. Ognuna di queste si applica forse al 5% delle sessioni, e in CLAUDE.md la paghi anche nell'altro 95%. Quel materiale vuole diventare una skill (livello successivo), che si carica solo quando viene attivata.

La nostra regola empirica dopo averla testata sul nostro stesso repo: se il tuo CLAUDE.md supera le 60 righe, qualcosa dentro dovrebbe uscirne. Il nostro partiva da 400 righe perché lo trattavamo come documentazione. Claude lo seguiva peggio, non meglio, perché il segnale annegava. La versione compressa, circa 50 righe di comandi e vincoli duri, viene rispettata quasi sempre.

Scrivi la prima bozza in dieci minuti e fermati. La affinerai per settimane man mano che noti Claude ripetere errori; quel ciclo iterativo è il vero metodo. Il trattamento completo, comprese le anti-pattern che vediamo nei file inviati dai lettori, è nella nostra guida CLAUDE.md.

Livello 3: le skill, il livello che quasi tutti saltano

Questo è il livello che separa un setup da una semplice installazione, ed è quello che quasi nessuno tocca mai. Una skill è una cartella con un file SKILL.md che insegna a Claude un modo di lavorare. Costa circa 100 token di metadati mentre è inattiva e carica le istruzioni complete solo quando un task corrisponde alla sua descrizione. Installata una volta, si applica per sempre, in ogni sessione.

La gente salta questo livello per un motivo razionale: circa metà delle skill della community su GitHub falliscono alla prima installazione. Lo sappiamo perché installarle e testarle è il nostro intero lavoro. Ogni skill nel catalogo SkillProof riceve un'installazione su macchina pulita e controlli di attivazione, poi task reali vengono eseguiti contro una baseline senza skill, prima di ricevere un verdetto. Delle 73 skill che abbiamo catalogato finora, 35 hanno superato il test.

Per un setup da sviluppatore, queste sono le cinque da installare per prime, con i punteggi dei nostri test:

1. Test-Driven Development, 9.6. Forza un rigoroso ciclo red-green-refactor: prima il test che fallisce, poi l'implementazione minima, poi la pulizia. Nella nostra sessione con tre feature non ha mai saltato il ciclo, nemmeno quando abbiamo provato a convincerla a farlo.
2. Systematic Debugging, 9.6. Sostituisce le correzioni a tentativi con un ciclo ipotesi-test-verifica. Ha trovato la causa radice di una race condition che Claude aveva precedentemente "risolto" tre volte a caso.
3. Frontend Design, 9.6. Il divario prima/dopo più grande che abbiamo misurato su qualsiasi skill. Stesso brief per una landing page, eseguito due volte: la baseline produceva il classico look gradiente-neon-tutto-centrato, la versione con skill aveva una vera scala tipografica e una palette che sembrava scelta.
4. Memory Management, 9.2. Dà a Claude una memoria persistente tra le sessioni. In una settimana di test ha richiamato in modo affidabile decisioni e preferenze del progetto, e il richiamo è rimasto accurato man mano che l'archivio cresceva.
5. Webapp Testing, 8.8. Claude guida la tua app in un vero browser tramite Playwright e riporta cosa si rompe. Ha catturato una regressione che i nostri unit test avevano perso.

Le prime due vengono dalla collezione Superpowers di Jesse Vincent (/plugin marketplace add obra/superpowers-marketplace, poi /plugin install superpowers). Frontend Design è inclusa nel repo ufficiale delle skill di Anthropic e si copia direttamente in ~/.claude/skills/. I passaggi esatti, comprese le modalità di fallimento che divorano la prima ora di chi le prova, sono nella guida all'installazione. Dopo l'installazione, riavvia Claude Code e testa ogni trigger chiedendo il lavoro senza nominare la skill. Se non cambia nulla in modo visibile, la skill non si sta attivando, e una skill installata che non si attiva mai è solo una cartella.

Se il tuo lavoro va in una direzione diversa, la nostra lista delle migliori skill per il coding classifica l'intera categoria, aggiornata man mano che arrivano nuovi test.

Livello 4: server MCP, solo quelli che userai davvero

I server MCP collegano Claude a cose fuori dal repo: il tuo database, il tuo issue tracker, un browser live. Sono potenti e sono la voce più costosa del tuo budget di contesto. Ogni server connesso inietta le definizioni dei suoi tool in ogni sessione, usato o no, e un singolo server chiacchierone può costare più token fissi di 50 skill installate messe insieme. Lo abbiamo misurato nella guida ai costi in token, e i numeri hanno cambiato come configuriamo le nostre stesse macchine.

Quindi la soglia per un server MCP dovrebbe essere alta: si guadagna un posto solo se Claude ha bisogno di raggiungere qualcosa che altrimenti non può toccare. Tre tendono a superare questo test per gli sviluppatori:

Un server database (Postgres o quello che usi). Claude che scrive query contro il tuo schema reale invece che uno indovinato è un prodotto diverso. Questa è la connessione MCP a più alto valore per la maggior parte dei team.

Automazione browser (Playwright MCP), se rilasci UI e non usi il setup integrato della skill Webapp Testing. Vedere la pagina renderizzata batte sempre inferirla dal JSX.

Il tuo issue tracker, ma solo se lavori davvero ticket per ticket dentro Claude Code. Se dai un'occhiata a Linear due volte al giorno, il browser basta e i token non ne valgono la pena.

Nota cosa manca: il server MCP di GitHub. La CLI gh fa tutto quello che fa lui, Claude sa già come usarla, e costa zero token fissi. Questo schema di sostituzione si generalizza. Prima di aggiungere qualsiasi server, chiediti se un tool a riga di comando che Claude può chiamare ti dà la stessa portata gratis. E se stai valutando se un problema richiede MCP oppure solo una skill, la regola decisionale è in skill vs MCP: le skill cambiano cosa Claude sa fare, MCP cambia cosa può toccare.

Livello 5: permessi e impostazioni di sicurezza che vale la pena cambiare

L'esperienza di permessi di default è un prompt per quasi ogni comando, il che addestra le persone a cliccare "consenti" per riflesso. Questo è il peggior risultato possibile: tutto l'attrito, zero sicurezza in più. Due modifiche lo risolvono.

Primo, metti in allowlist i comandi che approveresti comunque. In .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

Secondo, nota il blocco deny, perché è la metà che la gente salta. Claude non ha motivo di leggere il tuo .env, e una regola deny lo rende una proprietà del sistema invece che una speranza. Se usi server MCP o skill di terze parti, questo conta ancora di più, perché un'istruzione malevola non può esfiltrare quello che l'harness non legge. La nostra guida alla sicurezza copre il lato audit.

Su --dangerously-skip-permissions: il nome del flag è onesto. Dentro un container usa-e-getta senza credenziali, è un buon modo per far girare job lunghi non presidiati. Sul tuo laptop, con le tue chiavi SSH e le sessioni browser già loggate, è come finire protagonista di un post-mortem. Lo usiamo nei sandbox di CI e da nessun'altra parte.

Per-progetto vs globale: dove vive ogni pezzo

Tutto quanto sopra esiste su due livelli, e confonderli è il pasticcio di configurazione più comune che vediamo. La suddivisione:

Elemento	Globale (~/.claude/)	Per-progetto (.claude/ nel repo)
CLAUDE.md	Il tuo stile personale: lunghezza risposte, lingue, manie	Comandi di build, architettura, convenzioni del progetto (da committare)
Skill	Tutto ciò che è generale: debugging, TDD, scrittura	Solo workflow specifici del team
Impostazioni	La tua allowlist personale	Allowlist e regole deny del team (da committare)
settings.local.json	—	Le tue sovrascritture locali (da mettere in gitignore)
Server MCP	Server che usi ovunque	.mcp.json del progetto, così i colleghi hanno le stesse connessioni

Il principio: tutto ciò che servirebbe a un collega va nel repo, tutto ciò che riguarda te va globale. Il vantaggio si vede quando qualcuno di nuovo clona il progetto e Claude conosce già i comandi di build e le convenzioni, con la connessione al database già pronta. Il loro livello 2 e metà del livello 4 arrivano gratis.

Il mio setup dopo sei mesi

Cosa sopravvive davvero sulla mia macchina, per calibrare: un CLAUDE.md di progetto di 54 righe, nove skill, due server MCP (Postgres e Playwright), e il blocco di permessi qui sopra. Le sessioni di setup sembrano identiche a sei mesi fa; la differenza è tutto quello che ho cancellato.

Le rimozioni mi hanno insegnato più delle aggiunte:

Rimosso il server MCP di GitHub. Tenuto per quattro mesi per inerzia. Le sue definizioni di tool costavano migliaia di token fissi per sessione e gh faceva lo stesso lavoro. Niente è peggiorato. Questa singola rimozione ha ripagato il tempo speso a scrivere questo articolo.

Rimosso un server MCP di memoria a favore della skill Memory Management. Il server era un altro processo da tenere d'occhio e un'altra autenticazione da mantenere. La skill fa lo stesso lavoro in file di testo semplici che posso leggere e modificare io stesso. Quando la memoria si comporta male, apro il markdown e lo sistemo, cosa che non potevo mai fare con un archivio opaco.

Tagliato CLAUDE.md da 400 a 54 righe. La versione lunga si leggeva come buona documentazione e si comportava come rumore. La conformità alle regole che contavano è salita quando quelle che non contavano sono state cancellate.

Disinstallate 19 skill su 28. La maggior parte erano installazioni "potrebbero servire" che non si sono mai attivate nel lavoro reale. Il caricamento lazy fa sì che costino poco, ma descrizioni sovrapposte hanno causato due veri conflitti di attivazione, e l'audit che li ha trovati è stato noioso. Nove skill che si attivano ogni settimana battono 28 che per lo più no.

Annullata una regola blanket Bash(*) allow. Aggiunta durante una settimana di scadenza, tenuta troppo a lungo. Il giorno in cui Claude ha eseguito con sicurezza una migration distruttiva contro un database di sviluppo che si è rivelato meno usa-e-getta di quanto etichettato, ho rimesso i prompt per qualsiasi cosa che scrive.

Lo schema in tutte e cinque: non mi sono mai pentito di una rimozione. Mi sono pentito spesso di un'aggiunta.

Errori comuni della prima settimana

Cinque cose che quasi tutti fanno nella prima settimana, così puoi evitarle:

1. Scrivere il CLAUDE.md di 500 righe il primo giorno. Non sai ancora cosa Claude sbaglia nel tuo repo. Parti con 15 righe e fallo crescere in base agli errori osservati.
2. Installare ogni server MCP che sembra interessante. Ognuno tassa ogni sessione. Parti da zero e aggiungine uno quando incontri un muro che risolve.
3. Usare --dangerously-skip-permissions sulla tua macchina principale perché i prompt ti infastidivano. Metti in allowlist i comandi sicuri invece; elimina il 90% dei prompt senza l'esposizione.
4. Installare skill senza mai verificare che si attivino. Metà del valore di una skill muore in un campo descrizione vago. Testa ognuna con una richiesta naturale, senza nominare la skill.
5. Tenere la configurazione fuori dal repo. Se il CLAUDE.md e il settings.json del tuo progetto non sono committati, ogni collega ricostruisce il tuo setup male, a memoria.

Manutenzione: cosa rivedere dopo ogni release di Claude

Un setup calibrato per una versione del modello si scosta dalla successiva. Dopo ogni release significativa di Claude, dedica 20 minuti a quattro controlli.

Rileggi il tuo CLAUDE.md ed elimina le regole di cui il nuovo modello non ha più bisogno. Gli aggiornamenti del modello rendono regolarmente obsolete delle istruzioni; la regola "esegui sempre il linter" che hai scritto un anno fa potrebbe ormai essere comportamento di default che paghi in token per ripetere.

Ritesta i trigger delle tue skill. Il matching dei trigger è comportamento del modello, non keyword matching, quindi una descrizione che si attivava in modo affidabile su un modello può ammutolirsi sul successivo. Il nostro catalogo riesegue i test sulle skill migliori dopo le release importanti, e le pagine di ogni skill portano il verdetto attuale.

Rimisura il tuo overhead di contesto. Le nuove release a volte cambiano come vengono contate o messe in cache le definizioni dei tool MCP. Gli strumenti di efficienza nella nostra lista delle skill di efficienza sono dove indirizziamo chi vuole verificare cosa sta davvero bruciando il proprio budget; diverse skill in quella categoria esistono proprio per questo controllo.

E controlla il changelog per modifiche al modello dei permessi prima che le impostazioni del tuo team significhino silenziosamente qualcos'altro. Richiede cinque minuti e ci ha salvato due volte.

Domande frequenti

30 minuti sono realistici, onestamente?

Per i livelli da 1 a 5 come descritti, sì, li abbiamo cronometrati con nuovi assunti. Quello che richiede più tempo è la calibrazione: il tuo CLAUDE.md raggiunge la sua forma stabile dopo due o tre settimane in cui cattura gli errori ripetuti di Claude. Prevedi 30 minuti per la costruzione e qualche minuto di rifinitura al giorno per le prime due settimane.

Ho bisogno di server MCP?

Molti setup solidi ne usano zero. Se il tuo lavoro vive nel repo (codice, test, documentazione), skill più tool da riga di comando coprono tutto. MCP si guadagna il suo costo quando Claude ha bisogno di accesso live a qualcosa di esterno, e un database è il caso genuino più comune. Nel dubbio, inizia senza e aggiungi il server la prima volta che senti il muro.

CLAUDE.md dovrebbe essere globale o per-progetto?

Entrambi, con cose diverse dentro. Il globale (~/.claude/CLAUDE.md) porta le tue preferenze personali e si applica ovunque. Il per-progetto porta comandi di build e convenzioni, e appartiene al git così tutto il team lo condivide. L'errore è mettere fatti del progetto nel file globale, dove inquinano le sessioni di tutti gli altri progetti.

Quante skill sono troppe?

In termini di token, il tetto è alto: anche 50 skill costano solo qualche migliaio di token di metadati fissi. Il tetto pratico è più basso perché skill con descrizioni sovrapposte iniziano a competere per gli stessi trigger. Noi ne usiamo nove. Oltre le 15 circa, dovresti potare quelle che non si attivano da un mese invece di aggiungerne altre.

Posso saltare il livello dei permessi se lavoro in un sandbox?

Se il sandbox è genuinamente usa-e-getta, senza credenziali, senza volumi montati a cui tieni, allora sì, e --dangerously-skip-permissions esiste proprio per questo. Il livello conta sulle macchine con segreti reali. Il "sandbox" di molte persone è un laptop con le chiavi AWS di produzione in un dotfile, che non è un sandbox.