Claude Code: setup, risparmio token, MCP e skill

Chi comincia con Claude Code di solito nota due cose: funziona molto bene e i limiti d’uso si consumano in fretta. Il motivo quasi sempre non è il modello, ma il modo in cui viene usato: contesto che si gonfia, istruzioni ripetute a ogni sessione, strumenti collegati che nessuno usa. Questo è il setup iniziale che consiglio, con i comandi di esempio, per spendere meno e ottenere risposte più precise.

Il principio: il contesto costa

Claude Code lavora dentro una “finestra di contesto” che contiene la conversazione, i file letti, l’output dei comandi e le istruzioni iniziali. Ogni messaggio rimanda al modello tutto ciò che sta in quella finestra: più è piena, più il consumo cresce e più le risposte diventano meno nitide. Quasi tutte le buone pratiche che seguono servono a una cosa sola: tenere il contesto piccolo e pertinente.

I comandi da conoscere subito

Dentro una sessione, i comandi con la barra sono il cruscotto. Quelli che uso di più:

/init       crea un CLAUDE.md di partenza analizzando il progetto
/context    mostra quanto contesto è occupato e da cosa
/cost       mostra il consumo della sessione
/clear      azzera la conversazione (da usare quando cambi argomento)
/compact    riassume la conversazione per liberare spazio
/model      cambia modello
/permissions  mostra e modifica i permessi
/mcp        stato dei server MCP collegati

Dal terminale, claude -c riprende l’ultima sessione e claude -r ti fa scegliere quale riprendere. L’elenco dei comandi cambia con le versioni: /help mostra quello aggiornato.

Un’abitudine che da sola cambia il consumo

Un compito, una sessione. Quando finisci un lavoro e ne inizi un altro, usa /clear. Trascinarsi dietro cinquanta messaggi su un tema ormai chiuso è il modo più comune di sprecare risorse.
/compact prima che sia tardi. Se la sessione deve continuare, riassumila a metà strada, indicando cosa conservare: /compact conserva le decisioni prese e l'elenco dei file modificati.
Richieste mirate. «Leggi src/login.php e dimmi perché fallisce l’accesso» costa molto meno di «guarda il progetto e dimmi cosa non va».
Modalità di pianificazione (si attiva con i tasti Maiusc+Tab, oppure con --permission-mode plan): Claude Code propone prima il piano e non modifica nulla. Correggere un piano costa meno che disfare un lavoro fatto nel verso sbagliato.

Scegliere il modello giusto

Non serve il modello più potente per ogni compito. Per attività semplici e ripetitive (rinominare variabili, riassumere un log, scrivere un commento) basta un modello più leggero e veloce; per l’analisi di un problema difficile o per l’architettura conviene quello più capace. Il cambio si fa dentro la sessione:

/model

oppure all’avvio, con claude --model nome-del-modello. I nomi e le caratteristiche dei modelli cambiano nel tempo: controlla l’elenco aggiornato nella documentazione ufficiale.

Il CLAUDE.md: scritto bene, risparmia ogni volta

Il file CLAUDE.md nella cartella del progetto viene letto a ogni sessione. Ripeterne il contenuto a voce, ogni volta, è spreco; ma anche un file troppo lungo lo è, perché viene caricato sempre. La regola è: poche righe, solo ciò che Claude Code non può dedurre da solo.

# Progetto sito aziendale
- Stack: WordPress, PHP 8.3, tema in theme/
- Comandi: ./deploy/deploy-clone.sh per il clone; test con composer test
- Convenzioni: commenti in italiano, nessuna dipendenza nuova senza chiedere
- NON toccare: wp-config.php, cartella uploads/
- Dati sensibili: mai scrivere password o chiavi nei file né nei messaggi

Non metterci la descrizione del codice che si può leggere nei file, né lunghe storie del progetto. Se un argomento serve solo ogni tanto (per esempio la procedura di rilascio), mettilo in un file a parte e scrivi nel CLAUDE.md solo dove si trova. Con /init ottieni una bozza da accorciare, e con /memory apri i file di istruzioni per modificarli.

Permessi: meno interruzioni e più sicurezza

Ogni richiesta di conferma ferma il lavoro. Nel file .claude/settings.json del progetto si possono consentire in automatico i comandi di lettura e vietare quelli rischiosi:

{
  "permissions": {
    "allow": ["Bash(git status:*)", "Bash(git diff:*)", "Bash(ls:*)"],
    "deny": ["Read(./.env)", "Read(./secrets/**)", "Bash(rm -rf:*)"]
  }
}

I file in deny servono anche a risparmiare: se una cartella enorme (node_modules, vendor, file compilati) non deve essere letta, escludila. La sintassi precisa delle regole può cambiare fra le versioni: verificala nella documentazione. Le impostazioni personali che non vuoi condividere vanno in .claude/settings.local.json, fuori dal repository.

MCP: collegare strumenti esterni, ma pochi

MCP (Model Context Protocol) è lo standard che permette a Claude Code di usare strumenti e dati esterni: un database, un sistema di ticket, un browser, la documentazione di una libreria. Si aggiunge un server con un comando:

# server remoto (HTTP)
claude mcp add --transport http nome-server https://indirizzo-del-server/mcp

# server locale, avviato come programma
claude mcp add nome-server -- npx -y nome-pacchetto-mcp

# vedere, ispezionare, togliere
claude mcp list
claude mcp get nome-server
claude mcp remove nome-server

I server possono essere registrati per il solo progetto corrente, per te in tutti i progetti, oppure condivisi con il team tramite il file .mcp.json del repository. Valuta bene la prima e la terza ipotesi: un server MCP condiviso vale per tutti.

Tre avvertenze pratiche:

Ogni server occupa contesto. Le descrizioni degli strumenti vengono caricate in ogni sessione, anche se non li usi. Collega solo quelli che servono davvero al progetto e rimuovi gli altri: /context mostra quanto pesano.
Sono codice di terzi. Un server MCP può leggere dati e agire per tuo conto. Installa solo server di cui ti fidi, controlla chi li pubblica e cosa possono fare, e dai loro il minimo dei permessi.
Mai segreti nei comandi condivisi. Le chiavi di accesso vanno in variabili d’ambiente, non nel file .mcp.json del repository.

Skill: istruzioni che si caricano solo quando servono

Una skill è una cartella con un file SKILL.md che spiega a Claude Code come svolgere un compito specifico (per esempio «prepara l’articolo del blog» oppure «controlla un server Linux»). La differenza rispetto al CLAUDE.md è decisiva per i consumi: della skill viene caricata all’inizio solo la breve descrizione, e il resto del contenuto solo quando il compito lo richiede. Si possono quindi tenere molte procedure senza appesantire ogni sessione.

La struttura minima, nella cartella .claude/skills/ del progetto (oppure in ~/.claude/skills/ per averla ovunque):

.claude/skills/audit-server/SKILL.md

---
name: audit-server
description: Usa questa skill per un controllo di sicurezza in sola lettura di un server Linux (SSH, porte, firewall, aggiornamenti) e per scrivere il rapporto.
---

# Audit di un server Linux
1. Chiedi all'utente di fornire l'output dei comandi (ss -tulpn, sshd -T, ufw status).
2. Analizza l'output e ordina i problemi per rischio.
3. Scrivi il rapporto in report/AAAA-MM-GG.md con evidenza e correzione proposta.
4. Non eseguire correzioni: proponile soltanto.

La description è la parte più importante: è ciò che permette a Claude Code di capire quando usare la skill, quindi deve dire che cosa fa e in quali casi. Esistono anche gli agenti secondari (subagent), definiti in .claude/agents/: lavorano in un contesto separato e restituiscono solo il risultato, ideali per esplorazioni lunghe che altrimenti riempirebbero la sessione principale.

Come orientarsi: CLAUDE.md per le regole che valgono sempre, skill per le procedure che servono ogni tanto, MCP per collegarsi a sistemi esterni, subagent per le ricerche voluminose.

Hook: automatismi che non dipendono dalla memoria

Gli hook sono comandi che il sistema esegue in momenti precisi (per esempio dopo ogni modifica a un file). Si configurano in settings.json e sono la scelta giusta quando una regola deve valere sempre, come lanciare il controllo di sintassi dopo ogni modifica: a differenza di una frase nel CLAUDE.md, non si dimentica. Cominciali solo dopo aver preso confidenza con il resto; la sintassi si trova nella documentazione ufficiale.

Uso da script: la modalità non interattiva

Per compiti puntuali non serve la sessione interattiva: l’opzione -p esegue una richiesta e restituisce il risultato, e si presta bene alle pipe.

git diff | claude -p "Scrivi un messaggio di commit chiaro in italiano"
journalctl -p err --since today --no-pager | claude -p "Raggruppa gli errori per causa"

Il vantaggio è che ogni chiamata parte con un contesto pulito e contiene solo ciò che le dai.

Una scheda di ripasso

Un CLAUDE.md breve, con regole e comandi che non si deducono dal codice.
Permessi in sola lettura per i comandi frequenti, divieti su segreti e cartelle inutili.
/clear quando cambi compito, /compact quando la sessione è lunga.
Pianificazione prima di modifiche grandi, modello leggero per i lavori semplici.
Pochi server MCP, scelti con cura, e controllati con /context.
Le procedure ripetibili in skill, le ricerche voluminose nei subagent.
Mai password, chiavi o dati dei clienti in chat, nei file di istruzioni o nei comandi.

In sintesi

Un buon setup iniziale richiede mezz’ora e si ripaga in poche sessioni: meno consumi, risposte più centrate e meno interruzioni. Per le applicazioni pratiche sui server leggi Claude Code su server Linux, il controllo di sicurezza di un server e l’aggiornamento di più server con Ansible. Se vuoi introdurre Claude Code nel tuo team con regole chiare, qui trovi come lavoriamo e offriamo formazione.