SpyBara
Go Premium

best-practices.md 2026-10-26 22:57 UTC to 2026-10-27 22:59 UTC

This page contains 417 additions and 355 deletions.

2026
Fri 2 22:59 Sun 4 23:58 Tue 6 23:59 Tue 20 23:00 Thu 22 22:58 Fri 23 22:59 Tue 27 22:59 Fri 30 23:01

Best practice per Claude Code

Ottieni di più da Claude Code: di' a Claude ciò che non può vedere, dagli un controllo da eseguire e applica le regole che non ammettono eccezioni.

Claude Code è progettato in modo che, nella maggior parte dei casi, il tuo primo prompt semplice in una sessione nuova faccia già la cosa giusta, senza alcuna configurazione da parte tua.

Ad esempio:

  • Per consentire ai comandi di essere eseguiti in sicurezza senza che tu debba approvarli uno per uno, le nuove sessioni di terminale e VS Code si avviano in modalità auto, in cui un classificatore esamina qualsiasi azione rischiosa prima che venga eseguita.
  • Per mantenere concentrata la tua conversazione principale mentre il lavoro indipendente procede in parallelo, Claude delega ai subagent e ti interpella solo quando è necessario.
  • Per far proseguire una sessione lunga senza che tu debba gestirla, la conversazione viene compattata automaticamente prima che la finestra di contesto si riempia.

Questa pagina spiega cosa fare quando le impostazioni predefinite non bastano. Di solito succede quando il tuo progetto ha conoscenze, regole o vincoli che Claude non può vedere dal solo codice:

  • Un processo di deploy che esiste solo nella testa di qualcuno
  • Un file che non deve mai essere letto
  • Un controllo che deve passare prima che qualcosa possa considerarsi completato
  • Un budget da non superare

Nessuna impostazione predefinita può conoscere queste cose sul tuo progetto, quindi è qui che un po' di configurazione da parte tua ripaga.

Quando una sessione non va come ti aspettavi, quasi sempre il motivo è uno di questi:

  • Claude ha creato qualcosa di diverso da quello che avevi in mente, oppure deve riscoprire lo stesso fatto all'inizio di ogni sessione. Gli mancano informazioni che non può ottenere leggendo il repository. Consulta Di' a Claude ciò che non può vedere.
  • Claude ha detto di aver finito ma non era proprio così, di solito perché non aveva modo di verificare il proprio lavoro. Consulta Dai a Claude un controllo da eseguire.
  • Claude ha fatto qualcosa che non deve mai succedere in questo repository, oppure ha saltato un passaggio che deve sempre avvenire. Un prompt da solo non può garantire nessuna delle due cose. Consulta Applica le regole che non ammettono eccezioni.
  • Claude ha fatto la cosa giusta, ma ci ha messo più tempo, token o richieste di permesso di quanto valesse l'attività. Consulta Modifica un'impostazione predefinita.

Lascia che Claude lavori senza di te applica gli stessi quattro punti alle esecuzioni senza supervisione, e Cosa puoi smettere di fare elenca i consigli che i modelli attuali hanno reso superflui.

[!NOTE]

La configurazione per un intero team si trova in una pagina separata: Configura Claude Code per la tua organizzazione.

Istruzioni deterministiche e non deterministiche

Ogni istruzione che dai a Claude Code appartiene a una di queste categorie:

  1. Non deterministica: scrivi tu l'istruzione e Claude (il modello) la legge. Può essere il tuo prompt, CLAUDE.md o una skill. Il modello decide poi cosa fare con queste informazioni. Di solito segue i tuoi comandi, e i modelli attuali sono bravi a comprendere le tue intenzioni senza molto contesto, ma non c'è alcuna garanzia che seguirà le tue istruzioni. Può comunque decidere di non fare certe cose, o di farne altre.
  2. Deterministica: configuri tu l'istruzione e Claude Code (l'harness) deve eseguirla. Può essere un hook, una regola deny o un'impostazione gestita. Claude Code la applica ogni volta, indipendentemente da ciò che il modello ha deciso di fare.

La maggior parte degli elementi di Claude Code esiste in entrambe le forme:

Non deterministico (decide Claude) Deterministico (lo impone Claude Code)
Cosa fare Il tuo prompt, CLAUDE.md, le skill che Claude avvia da sé Gli hook, e le skill che solo tu puoi avviare
Cosa può toccare Il classificatore della modalità auto Regole deny, la sandbox in modalità rigorosa, impostazioni gestite
Quando ha finito Una richiesta di prove, /goal, /code-review Test, controllo dei tipi, un hook Stop, CI
Quanto spende Livello di sforzo, il ritmo di Claude --max-turns o --max-budget-usd con -p, un limite di spesa che hai impostato
Chi ha l'ultima parola Il riepilogo di Claude su ciò che ha fatto Protezione del branch, una persona che approva il merge

Nella maggior parte dei casi, vuoi che sia Claude a decidere. Quasi ogni linea guida ha eccezioni, e i modelli attuali sono bravi a leggere il codice che hanno davanti e a valutare se una linea guida si adatta alla situazione. Con il codice reale davanti, Claude di solito è in una posizione migliore per prendere quella decisione rispetto a una regola che hai scritto in anticipo.

Il tipo deterministico serve quando vuoi assicurarti che certe cose accadano sempre (o non accadano mai), indipendentemente da ciò che decide il modello. Non deve trattarsi di nulla di drammatico. La modalità auto blocca già le cose drammatiche, come un deploy in produzione o un force push sul lavoro di qualcun altro. Di solito si tratta di qualcosa di specifico del tuo progetto, e può essere di nicchia quanto vuoi:

  • Non modificare mai il client generato in src/gen/
  • Esegui sempre lo script dell'intestazione di licenza dopo aver creato un file

Avresti potuto scrivere ciascuna di queste come una riga in CLAUDE.md o nel tuo prompt, e Claude la seguirebbe quasi sempre. Ma per quanto tu la formuli con decisione, se Claude segua quella riga in un dato turno resta comunque una sua scelta.

[!TIP]

Se continui ad aggiungere enfasi a una riga di CLAUDE.md e Claude la ignora comunque, è segno che quella riga va messa in un hook. Vale anche il contrario: se hai hook per cose che sono solo preferenze, eliminali e lascia decidere Claude.

Di' a Claude ciò che non può vedere

[!TIP]

Scrivi solo ciò che Claude non può trovare leggendo il repository, o ciò che altrimenti passerebbe tempo a riscoprire in ogni sessione.

Claude inizia ogni attività leggendo il tuo codice, e i modelli attuali sono molto bravi in questo. Trovano la struttura dei file, le convenzioni, il framework di test e il modo in cui sono costruiti i componenti esistenti, di solito più velocemente di quanto potresti spiegarli tu. Questo significa che Claude conosce già la maggior parte di ciò che potresti essere tentato di scrivergli.

Quello che non può trovare sono le informazioni che non sono mai state nel repository:

  • Una decisione presa dal tuo team in una riunione
  • Un processo di deploy che esiste solo nella testa di una persona
  • La variabile d'ambiente di cui hanno bisogno i tuoi test di integrazione

Ci sono anche informazioni che sono nel repository ma richiedono qualche minuto di ricerca per essere trovate, e Claude deve rifare quella ricerca all'inizio di ogni sessione.

Un buon test prima di scrivere qualcosa per Claude:

  1. Potrebbe trovarlo leggendo il codice?
  2. Andrebbe davvero a cercarlo?

Se la risposta è sì a entrambe, lascialo fuori.

Scrivi un prompt specifico

Un prompt specifico aiuta per lo stesso motivo, perché fornisce a Claude informazioni che non ha già. Se indichi il file, descrivi il sintomo e dici fin dall'inizio cosa significa "risolto", di solito ti risparmi un giro di correzioni in seguito.

Lo stesso vale per una preferenza tra due approcci ragionevoli: Claude non può ricavarla dal codice, quindi se ti interessa quale dei due sceglie, dillo subito.

Invece di Prova
"correggi il bug del login" "gli utenti segnalano che il login fallisce dopo il timeout della sessione. guarda l'aggiornamento del token in src/auth/, scrivi un test che fallisce e riproduce il problema, poi correggilo"
"aggiungi un widget calendario" "segui il pattern di HotDogWidget.php e crea un widget calendario che permetta di scegliere un mese e di scorrere tra gli anni. nessuna nuova libreria"

Se hai già ciò di cui Claude ha bisogno, passaglielo invece di descriverlo:

  • Un file: digita @ e il percorso per includere il contenuto del file nel tuo messaggio.
  • Un'immagine: incolla nel prompt lo screenshot del design o dell'errore.
  • Output di un comando: invialo tramite pipe dalla tua shell con cat error.log | claude -p "what's going on here".

Frasi come think step by step o be thorough sono normale testo del prompt, non parole chiave. Il controllo principale su quanto Claude ragiona è il livello di sforzo, trattato in Modifica il modello e lo sforzo. Formulazioni di questo tipo possono comunque spingere Claude entro la sua impostazione di sforzo, ma non gliela fanno superare.

Una frase che aiuta ancora è be ambitious. Claude tende a interpretare una richiesta in modo conservativo e a creare la cosa più piccola che la soddisfi, dato che non può vedere quanto speravi di ottenere. Quando vuoi la versione più completa, con i casi limite gestiti e il naturale seguito incluso, dillo:

build the settings page from the mockup. be ambitious: empty and error states, the save flow wired up, keyboard navigation, not just the layout

Questo significa dire a Claude qual è la portata del lavoro, cosa che sai solo tu, piuttosto che quanto ragionare.

E quando stai esplorando anziché correggere qualcosa di specifico, un prompt vago come what would you improve in this file? va benissimo. Dovrai correggere un po' di più strada facendo, ed è questo il compromesso.

Fai prima brainstorming con Claude

Quando non sai ancora esattamente cosa vuoi, non devi chiarire tutto prima di scrivere il prompt. Chiedi invece a Claude di intervistarti:

I want to add rate limiting to the public API but haven't thought it through yet. Interview me until you could write the spec, then write it to SPEC.md.

Claude torna con domande a scelta multipla sugli aspetti che non hai ancora definito: limiti per utente o per chiave, cosa succede alle richieste oltre il limite, cosa è fuori ambito. Continua a chiedere finché le risposte non formano una specifica.

Una volta che SPEC.md esiste, avvia una nuova sessione per svilupparla, in modo che il lavoro parta con un contesto pulito e una definizione scritta di "completato". È anche il file a cui indirizzerai il revisore in seguito, in Dai a Claude un controllo da eseguire.

Mantieni CLAUDE.md breve

Claude Code carica CLAUDE.md in ogni sessione, il che significa che ogni riga al suo interno sottrae un po' dell'attenzione di Claude in ogni attività, che sia pertinente o meno. Ecco perché il file funziona meglio quando contiene solo ciò che Claude non potrebbe ricavare dal codice stesso:

  • Come verificare il lavoro in questo repository: i comandi esatti per test, controllo dei tipi e lint, e come eseguire un singolo file di test
  • Punti in cui il codice è fuorviante: un vecchio pattern presente ovunque che il nuovo codice non deve copiare, o una directory che sembra inutilizzata ma non lo è
  • Decisioni che non sono nel repository: quale helper per gli errori ha scelto il team, come funzionano i deploy, cosa richiede una revisione delle migrazioni
  • Qualsiasi cosa tu abbia già dovuto correggere due volte

Un CLAUDE.md che supera questo test resta breve:

# Commands
- Install: pnpm install
- Run one test file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit

# Conventions
- Use the error helpers in src/lib/errors.ts, never throw raw strings
- src/legacy/ is still live but don't copy its patterns into new code

# Gotchas
- Integration tests need DATABASE_URL set, see .env.example

In una sessione, esegui /context per confermare che Claude ha caricato il file.

Nota che la riga del controllo dei tipi contiene solo il comando. Claude deve conoscere il comando per poter verificare il proprio lavoro man mano. Se vuoi anche che Claude Code imponga il superamento del controllo dei tipi prima che Claude finisca, quello è un compito per un hook Stop. Una riga come Always typecheck before you finish in questo file funziona la maggior parte delle volte, non sempre.

Non devi scrivere il file da zero:

  • /init genera una versione iniziale a partire dal tuo codebase. Da lì il lavoro consiste soprattutto nel rimuovere righe. La guida alla memoria consiglia di restare sotto le 200.
  • /doctor suggerisce tagli per tutto ciò che Claude può già ricavare dal codice.
  • /doctor prompt-audit segnala le istruzioni scritte per modelli precedenti, che fanno riferimento a file che non esistono più o che si contraddicono a vicenda.

Le tue preferenze personali vanno in CLAUDE.local.md invece che in CLAUDE.md, e aggiungi quel file a .gitignore in modo che resti fuori dal repository.

[!NOTE]

Se Claude continua a ignorare una riga che è in CLAUDE.md, aggiungere IMPORTANT probabilmente non risolverà il problema. O il file è diventato così lungo che la riga si perde, oppure la riga è una regola che non ammette eccezioni, nel qual caso va messa in un hook.

Limita le regole a una parte del codebase

Se una regola conta solo in una parte del codebase, mettila in .claude/rules/ con un filtro paths: in modo che venga caricata solo quando Claude sta effettivamente lavorando lì. Ad esempio, questo .claude/rules/api.md viene caricato per i file TypeScript sotto src/api/:

---
paths:
  - "src/api/**/*.ts"
---
- Validate request bodies with the zod schemas in src/api/schemas/, don't hand-roll checks
- Every new endpoint needs an entry in openapi.yaml, CI fails without it

Inserisci le procedure del team nelle skill

Un modello più capace sa di più sull'ingegneria, ma non sa come il tuo team esegue un rilascio, cosa dice il tuo runbook per gli incidenti o come vuoi che sia scritta la documentazione delle API. Questo tipo di conoscenza va in una skill: una procedura o un elemento di conoscenza del team salvato in .claude/skills/<name>/SKILL.md.

Per questo genere di cose le skill pesano anche meno sul contesto rispetto a CLAUDE.md. Per una skill che Claude può avviare da solo, vede il nome e la descrizione in ogni sessione, ma legge il file completo solo quando l'attività lo richiede. Una lunga procedura di rilascio in una skill non pesa sulla correzione di un bug non correlato come farebbe in CLAUDE.md.

[!NOTE]

La regola di CLAUDE.md vale anche per le skill: scrivi solo ciò che Claude non può trovare da solo.

Per un workflow con effetti collaterali, come eseguire davvero quel rilascio, aggiungi disable-model-invocation: true. Claude allora non può avviare la skill da solo, e questa viene eseguita solo quando digiti tu stesso /release. Salvata come .claude/skills/release/SKILL.md, potrebbe apparire così:

---
name: release
description: Cut a new release. Bumps the version, writes the changelog entry, tags it and pushes the tag so CI can publish.
disable-model-invocation: true
---
1. Make sure you're on main with a clean tree. If not, stop and ask.
2. Run `pnpm changeset version` and commit the result.
3. Summarize the PRs merged since the last tag into CHANGELOG.md, one line each, user-facing changes only.
4. Tag `v<new version>` and push the tag. CI publishes from there, never publish from your machine.

Collega gli strumenti di cui Claude ha bisogno

Alcune delle cose che Claude non può vedere si trovano del tutto in un altro sistema, come il tuo issue tracker o la tua dashboard degli errori. Se quel sistema ha una CLI, di solito è il modo più semplice per accedervi. Con gh installato e autenticato, ad esempio, Claude apre pull request e legge i commenti di revisione senza alcuna spiegazione da parte tua. Per una CLI che non ha mai visto, basta indirizzarlo a --help.

Per i sistemi senza CLI c'è MCP. Aggiungi un server dalla tua shell:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Il server compare quindi sotto /mcp all'interno di una sessione. I server connessi aggiungono i nomi dei propri strumenti e le proprie istruzioni al contesto anche quando non li stai usando, quindi conviene disattivare quelli che non ti servono da lì.

E se lavori con un linguaggio tipizzato, un plugin di code intelligence permette a Claude di saltare direttamente a una definizione invece di leggere molti file per trovarla.

Dai a Claude un controllo da eseguire

Claude si ferma quando il lavoro sembra completato. Se non ha nulla da eseguire che gli dica se il lavoro è effettivamente completato, "sembra completato" è l'unico segnale su cui può basarsi. In pratica questo fa di te la suite di test, e ogni errore resta lì finché non ti capita di notarlo.

Se gli dai qualcosa che restituisce un esito positivo o negativo, Claude può chiudere quel ciclo da solo. Apporta la modifica, esegue il controllo e, se qualcosa si è rotto, legge l'output e lo corregge prima di eseguire di nuovo il controllo.

[!TIP]

Dai a Claude qualcosa che può eseguire e che restituisce un esito positivo o negativo. Una volta che lo ha, può andare avanti da solo e tu non devi stare a guardare.

Il controllo può essere quasi qualsiasi cosa, purché Claude possa leggerne il risultato:

  • Un file di test
  • Il codice di uscita di una build
  • Un linter
  • Uno script che confronta l'output con una fixture
  • Uno screenshot del browser accanto al mockup

Se il tuo repository ha già uno di questi, la riga più utile in assoluto del tuo CLAUDE.md è il comando che lo esegue.

Quanto rendere rigoroso il controllo dipende da te. Le opzioni vanno da Claude che decide da sé fino a Claude Code che lo impone:

  • Nel prompt: run the auth tests after, and keep going until they pass. Claude decide da sé quando è soddisfatto. Funziona con qualsiasi attività, oggi stesso, senza configurazione.
  • Come obiettivo: /goal all tests in tests/auth pass and lint is clean imposta una condizione che un modello separato verifica rispetto alla conversazione dopo ogni turno, e Claude continua finché non è soddisfatta. Raramente ti serve in una sessione che segui tu stesso. Conta per le lunghe esecuzioni in background, in cui Claude a volte termina un turno con un riepilogo dei progressi mentre alcuni punti sono ancora aperti, e l'obiettivo lo rimanda al lavoro.
  • Come hook Stop: un hook Stop esegue il tuo script ogni volta che Claude cerca di terminare il turno, e rimanda Claude al lavoro se lo script termina con codice di uscita 2. Questo viene imposto da Claude Code (l'harness), quindi il turno non termina finché il controllo dei tipi non passa o non viene raggiunto il limite di blocchi. C'è un esempio più avanti.
  • Da qualcuno che non ha scritto il codice: nel terminale, /code-review esamina il diff in un subagent nuovo che non ha mai visto la tua conversazione. Non è influenzato dal ragionamento che ha prodotto il codice.

Qualunque opzione usi, chiedi a Claude delle prove: il comando che ha eseguito e il suo output, oppure lo screenshot. "Tutti i test passano" da solo ti dice ben poco, e leggere l'output è più veloce che rieseguire il controllo tu stesso. Per una sessione che non stavi seguendo, è anche l'unica prova che hai.

[!TIP]

Una volta che Claude dice di aver finito, puoi anche eseguire /verify nella sessione, che fa sì che Claude compili ed esegua l'app e ne esamini il risultato. In questo modo si individuano i problemi che test e controlli dei tipi non rilevano.

Revisiona rispetto alla tua specifica

Se preferisci che la revisione controlli il lavoro rispetto al tuo piano anziché cercare bug in generale, scrivi tu stesso il prompt di revisione:

use a subagent to review the rate limiter diff against SPEC.md, check every requirement is implemented and the listed edge cases have tests, report gaps that affect correctness and skip style

[!NOTE]

Non eliminare la parte skip style di quel prompt. Un revisore a cui viene chiesto di trovare problemi troverà sempre qualcosa. Se correggi ogni segnalazione, finisci con livelli di astrazione in più e test per casi che non possono verificarsi.

Imponi il controllo con un hook Stop

La versione con hook Stop della regola sul controllo dei tipi è composta da poche righe in .claude/settings.json. Il codice di uscita 2 è ciò che blocca l'arresto. Tutto ciò che il comando stampa su stderr torna a Claude come motivo per cui non può ancora finire, ed è per questo che l'output del compilatore viene reindirizzato lì:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" }
        ]
      }
    ]
  }
}

Per vederlo in azione, chiedi a Claude una modifica che rompa un tipo: invece di finire, riceve gli errori del compilatore e continua finché tsc non passa. Se l'hook blocca otto arresti consecutivi senza chiamate agli strumenti nel mezzo, Claude Code scavalca il blocco successivo e termina il turno. Per alzare il limite, imposta CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.

Applica le regole che non ammettono eccezioni

[!TIP]

Se qualcosa deve accadere ogni volta, rendilo un hook, una regola deny o un'impostazione gestita. CLAUDE.md è per le linee guida, e Claude può decidere che una linea guida non si applica.

Prendi tre regole che potresti avere oggi in CLAUDE.md: Never read .env, Always run the formatter after editing, Don't touch the migrations folder. Claude le seguirà quasi sempre. Per le poche in cui "quasi" non basta, spostale fuori da CLAUDE.md e inseriscile in una configurazione che Claude Code (l'harness) applica da sé. Da quel momento, il risultato non dipende da ciò che il modello ricorda o decide.

Imponi i passaggi con gli hook

Gli hook eseguono qualcosa di tuo in punti fissi del ciclo di Claude: prima o dopo una chiamata a uno strumento, quando Claude cerca di fermarsi, quando inizia una sessione e così via. Quel qualcosa può essere:

  • Un comando shell (il caso abituale)
  • Una richiesta POST a un endpoint HTTP
  • Una chiamata a uno strumento su uno dei tuoi server MCP
  • Un hook prompt o agent, che lascia decidere a un modello

Un hook prompt o agent chiede a un altro modello di decidere, quindi non è deterministico nemmeno lui. Per un'applicazione effettiva, usa un hook command o http, e aggiungi onFailure: "block" se l'azione deve essere fermata anche quando l'hook stesso va in crash o in timeout. Per un hook che analizza i commit alla ricerca di segreti, ad esempio, preferiresti bloccare il commit piuttosto che lasciarlo passare senza analisi mentre lo scanner non è disponibile.

Ecco la regola del formatter come hook PostToolUse. Viene eseguito dopo ogni Edit o Write, e che Claude ricordi la regola non conta più, perché non è Claude a eseguirla:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write --ignore-unknown \"$(jq -r '.tool_input.file_path')\"" }
        ]
      }
    ]
  }
}

Per verificare l'hook, chiedi a Claude di aggiungere una riga indentata male in un file formattato da Prettier. Il file salvato torna con l'indentazione corretta.

La regola sulle migrazioni diventa un hook PreToolUse che termina con codice di uscita 2 per qualsiasi percorso sotto migrations/. Non devi scriverlo tu: write a hook that blocks edits to the migrations folder funziona come prompt, e /hooks mostra il risultato. Non esagerare, però: un hook è per una regola con zero eccezioni, e Prefer named exports ne ha molte, quindi quella resta in CLAUDE.md.

Limita l'accesso con le regole di permesso e la sandbox

Le regole di permesso decidono cosa Claude può eseguire, leggere e recuperare. Le regole deny valgono in ogni modalità di permesso, incluse auto e bypassPermissions, ed è esattamente per questo che la regola su .env va lì:

{
  "permissions": {
    "allow": ["Bash(pnpm tsc --noEmit)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./.env.local)", "Read(./secrets/**)"]
  }
}

Con questa configurazione salvata, chiedere a Claude cosa c'è in .env non funziona, sia tramite lo strumento Read sia tramite cat .env.

Le regole corrispondono alle chiamate agli strumenti, non alle intenzioni, quindi conviene sapere dove sono i limiti:

  • La regola Read intercetta cat .env, perché Claude Code riconosce i comandi comuni di lettura dei file.
  • Non intercetta uno script che apre il file.
  • Una regola deny WebFetch per un dominio non ha effetto su un curl verso lo stesso dominio, a meno che la sandbox non sia attiva.

Per un limite a livello di sistema operativo sull'accesso al filesystem o alla rete, attiva la sandbox con /sandbox in una sessione. Confina i comandi shell di Claude su macOS, Linux e WSL2 e recepisce anche le tue regole deny Read e le regole WebFetch(domain:...), quindi per qualsiasi cosa legata alla sicurezza ti conviene usare entrambe.

Per impostazione predefinita Claude può comunque chiedere di riprovare un comando bloccato fuori dalla sandbox, e quella richiesta passa per il normale flusso dei permessi. La modalità sandbox rigorosa, nella scheda Overrides di /sandbox, disattiva questo nuovo tentativo.

[!WARNING]

La modalità auto è un modello classificatore che valuta ogni azione, non una regola rigida. È bravo a farlo, ma come ogni valutazione può sbagliare. Puoi anche regolare ciò che considera rischioso, e la tua organizzazione può disattivarla del tutto, quindi le tue regole "mai" vanno nelle regole deny o negli hook.

Scegli a chi si applica una regola

Il punto in cui si trova una regola determina a chi si applica:

  • .claude/settings.local.json e ~/.claude/settings.json sono solo tuoi. Quando selezioni Yes, and don't ask again per un comando, Claude Code salva quella regola nel file locale.
  • .claude/settings.json e gli hook al suo interno appartengono al repository. Una volta che ne fai il commit, si applicano a chiunque lavori nel repository. Le sue regole deny si applicano subito. Le sue regole allow attendono che ogni persona accetti la finestra di dialogo di attendibilità per quella cartella, e anche l'attendibilità del workspace determina quando i suoi hook iniziano a essere eseguiti sulla loro macchina.
  • Le impostazioni gestite appartengono all'organizzazione. Provengono dalla console di amministrazione, da MDM o da un file managed-settings.json, e nessun file di impostazioni personale può sovrascriverle, il che le rende l'unico posto adatto per la policy di un team di sicurezza. Se sei tu la persona che le imposta, consulta Configura Claude Code per la tua organizzazione.

Qualunque sia l'ambito, mantieni ridotto l'insieme delle regole imposte. Ogni hook e ogni regola deny scatterà di tanto in tanto quando non dovrebbe, e qualcuno deve mantenerli. Se ti ritrovi ad averne quaranta, la maggior parte sono probabilmente preferenze che Claude avrebbe potuto valutare da solo.

Modifica un'impostazione predefinita

[!TIP]

Le impostazioni predefinite sono abbastanza buone da lasciarle così finché un'attività non costa più tempo, token o interruzioni del dovuto. Quando succede, esegui /usage nella sessione per vedere dove sono finiti.

Una nuova sessione prende già alcune decisioni per te:

  • Le sessioni interattive di terminale e VS Code si avviano in modalità auto.
  • Usa Claude Opus 5.5 con sforzo medio sulla maggior parte dei piani e dei provider.
  • Delega il lavoro ai subagent quando vede un motivo per farlo.
  • Compatta la conversazione man mano che cresce.

Nella maggior parte dei casi non ci pensi nemmeno. Quando un'attività costa più del dovuto, di solito il motivo è uno di questi quattro.

Modifica la modalità di permesso

Entrambi gli estremi della gamma dei permessi hanno un costo:

  • Modalità Manual: approvi tu stesso ogni modifica e ogni comando che non sia di sola lettura. È sicura, ma dopo la decima richiesta inizi ad approvare senza leggere, e nulla va avanti mentre sei lontano dalla tastiera.
  • bypassPermissions: approva tutto ciò che non è coperto dalle tue regole deny e ask, il che ha senso solo in un container usa e getta.

La modalità auto si colloca tra i due, ed è la modalità in cui si avviano le sessioni interattive di terminale e VS Code. Claude lavora senza fermarsi per le approvazioni di routine, e un modello classificatore separato controlla le azioni in un ordine fisso prima che vengano eseguite. Si concentra sulle cose che vorresti fossero fermate da una persona:

  • curl | bash
  • Deploy e migrazioni in produzione
  • Force push sul lavoro di altre persone
  • Dati sensibili inviati a endpoint esterni
  • Azioni che sembrano guidate da contenuti letti da Claude anziché da te

Quando blocca qualcosa, ricevi una notifica e l'azione compare sotto Recently denied in /permissions, dove puoi riprovarla con un'approvazione manuale. Dopo tre blocchi consecutivi (o venti in totale), la modalità auto si mette in pausa e torna a chiederti conferma.

Niente di tutto questo sostituisce i tuoi controlli deterministici, perché viene eseguito dopo di essi. Le regole deny e ask e gli hook PreToolUse si applicano prima che il classificatore veda qualsiasi cosa, quindi una regola deny blocca in modalità auto esattamente come altrove. La sandbox continua a confinare i comandi shell che avvolge.

[!NOTE]

Puoi anche dire don't push until I've reviewed nella conversazione, e il classificatore lo tratta come un segnale di blocco. Si tratta comunque di un modello che legge la trascrizione, e la frase può andare persa quando la conversazione viene compattata, quindi tutto ciò che conta va in una regola deny.

Il problema opposto è il classificatore che blocca ripetutamente qualcosa che nella tua configurazione è di routine. Invece di approvarlo manualmente ogni volta, aggiungilo a autoMode.allow o descrivi la tua infrastruttura attendibile nella configurazione della modalità auto. Si scrive in linguaggio naturale anziché con pattern, e /auto-mode-setup può redigere per te la parte environment a partire dal tuo progetto e dalle sessioni recenti:

{
  "autoMode": {
    "environment": [
      "$defaults",
      "Source control: github.com/example-org and every repo under it",
      "Trusted internal domains: *.internal.example.com"
    ],
    "allow": [
      "$defaults",
      "Deploying to the staging namespace is fine, it's isolated from production and resets nightly"
    ]
  }
}

[!WARNING]

Mantieni "$defaults" in ogni elenco che imposti, perché senza di esso le tue voci sostituiscono le regole integrate di quell'elenco invece di aggiungersi a esse. Per environment e allow perderesti il contesto e le eccezioni integrati, e un elenco soft_deny senza di esso elimina i blocchi integrati su force push e deploy in produzione.

Il blocco autoMode deve inoltre trovarsi in ~/.claude/settings.json anziché nel progetto, perché il classificatore ignora autoMode nelle impostazioni di progetto.

Se preferisci vedere ogni modifica e ogni comando prima che avvengano, Shift+Tab nella sessione passa ciclicamente tra le modalità di permesso, Manual inclusa, oppure avvia con claude --permission-mode manual dalla tua shell. E se poi Manual chiede troppo spesso, /fewer-permission-prompts analizza le tue trascrizioni recenti alla ricerca di chiamate Bash e MCP di sola lettura comuni e le aggiunge a un'allowlist in .claude/settings.json.

Modifica il modello e lo sforzo

Lo sforzo è il controllo principale su quanto a lungo ragiona Claude, e sostituisce la maggior parte di ciò che in passato si faceva con la formulazione del prompt. Claude Opus 5.5, Sonnet 5.5 e Haiku 5.5 usano medium per impostazione predefinita, che è più che sufficiente per il lavoro quotidiano sulle funzionalità con un ambito chiaro. I casi in cui cambiarlo, con /effort nella sessione:

  • Alzalo con /effort high o /effort xhigh quando la riuscita dipende da casi facili da trascurare. Pensa a un bug in codice che non hai scritto tu, a un test instabile o a una modifica dello schema in cui Claude deve trovare ogni lettore della vecchia struttura. Claude allora controlla più casi limite e verifica una parte maggiore del suo lavoro prima di rispondere, ed è lì che vanno il tempo e i token in più.
  • Abbassalo con /effort low quando procedi rapidamente avanti e indietro e rivedi comunque ogni risultato: brainstorming, una prima bozza, una ridenominazione su alcuni file. Claude ti dà un punto di partenza prima e, dato che guidi ogni passaggio, la riflessione aggiuntiva non avrebbe cambiato molto oltre all'attesa.
  • Riserva max a un problema difficile che vuoi che Claude risolva senza di te, come la ricerca di una vulnerabilità di sicurezza. Nelle attività ordinarie tende a ragionare troppo, quindi paghi di più per una risposta che potrebbe non essere migliore di quella che avresti ottenuto con high.
  • Quando ne ha bisogno solo il messaggio successivo, come una domanda complicata nel mezzo di un lavoro altrimenti di routine, inserisci ultrathink in quel prompt invece di cambiare l'impostazione.

Per quanto riguarda il modello, Opus 5.5 predefinito gestisce bene la maggior parte del lavoro di programmazione e Sonnet costa meno per il lavoro di routine. Claude Fable 5.1 è disponibile quando lo selezioni esplicitamente con /model fable, e Haiku è adatto ai subagent che svolgono compiti semplici. Configurazione del modello contiene l'elenco completo per piano e provider.

Sappi quanto costano i subagent

Claude delega ai subagent di sua iniziativa:

  • Le ricerche ampie nel codebase vanno all'agente Explore integrato.
  • Le attività secondarie vengono biforcate mentre la modalità fork è attiva (l'impostazione predefinita).
  • I subagent che avvia vengono eseguiti in background per impostazione predefinita, quindi la tua conversazione principale continua ad andare avanti.

Raramente devi chiedere qualcosa di tutto ciò, ma è utile sapere cosa ottieni e quanto costa.

I subagent ripagano in queste situazioni:

  • Eseguire contemporaneamente parti di lavoro indipendenti, in modo che l'intera attività finisca prima
  • Tenere l'output lungo, come un'esecuzione completa dei test o una ricerca ampia, fuori dalla tua conversazione principale, dove altrimenti resterebbe per il resto della sessione
  • Avere un revisore che non ha visto come è stato scritto il codice
  • Dare a un'attività meno strumenti di quelli della sessione principale, come un revisore che può leggere ma non modificare

Ciò che ti costano sono soprattutto token, dato che ogni subagent invia le proprie richieste e queste contano sullo stesso utilizzo della tua conversazione principale. A volte costano anche tempo: un subagent nuovo deve prima raccogliere il contesto che la tua conversazione aveva già, quindi può finire per essere più lento che svolgere l'attività dove ti trovi.

E per impostazione predefinita è lo stesso modello (o uno più piccolo) sulla stessa attività. Ne ottieni parallelismo o uno sguardo nuovo, ma non una risposta più intelligente.

Per spendere meno:

  • Imposta model: haiku nella definizione di un subagent se il suo lavoro è semplice, come raccogliere i file che importano un modulo o controllare i link nella documentazione. Quel tipo di lavoro non ha bisogno del modello più grande, e Haiku costa molto meno per richiesta.
  • Chiedi riepiloghi brevi in risposta, così venti risultati non finiscono comunque per riempire il tuo contesto.
  • Controlla /usage per vedere quale quota del tuo utilizzo occupa ciascun tipo di subagent, così puoi capire quali valgono il loro costo.
  • Dai a un subagent personalizzato in .claude/agents/ solo tools: Read, Grep, Glob. Ora è un revisore che non può modificare nulla, e quel limite è imposto da Claude Code anziché richiesto in un prompt.

Quel revisore è un breve file, .claude/agents/reviewer.md:

---
name: reviewer
description: Reviews changed files against the spec they were built from. Use after implementing a feature, before opening the PR.
tools: Read, Grep, Glob
---
You're reviewing code you didn't write. Compare the changed files against the spec you're given,
check that every requirement is implemented and the listed edge cases have tests,
and report only the gaps that affect correctness. Skip style.

Chiedi a Claude di have the reviewer compare the rate limiter against SPEC.md e le lacune tornano nella tua sessione, dove Claude può correggerle.

Contieni costi e contesto

Con una finestra da 1M di token sulla maggior parte dei modelli attuali e la compattazione vicino al limite, raramente esaurirai il contesto. Puoi comunque pagare per un contesto che non ti serve. Ogni richiesta invia l'intera conversazione, quindi una sessione che ha accumulato tre attività non correlate le rilegge tutte e tre a ogni turno della quarta. Questo è scontato finché la cache è calda e a prezzo pieno una volta scaduta.

/usage è il primo posto in cui guardare. Su Pro, Max, Team ed Enterprise suddivide il tuo utilizzo per skill, subagent, plugin e server MCP. Segnala anche pattern come contesto lungo o frequenti cache miss quando uno di essi supera il 10% del tuo utilizzo. Da lì, le soluzioni abituali:

  • /clear tra attività non correlate. Non costa nulla, e fa sì che l'attività successiva non continui a pagare per la cronologia della precedente. /clear oauth-migration assegna un nome alla sessione che stai lasciando, così puoi tornarci in seguito.
  • /compact con un focus, come /compact keep the API changes and the test commands. In una sessione lunga /compact è a sua volta una richiesta grande, dato che legge l'intera conversazione per riassumerla, e ancora di più una volta scaduta la cache.
  • Tieni d'occhio il lavoro in background: un /loop, il controllo di un obiettivo dopo ogni turno e i subagent di Claude continuano tutti a inviare richieste mentre non stai scrivendo.

[!NOTE]

La prompt cache dura circa un'ora con un abbonamento e cinque minuti con una chiave API, un cloud provider o i crediti di utilizzo. I subagent hanno cinque minuti, a meno che tu non lo modifichi.

Con la cache di un'ora, una sessione oltre circa 200K token che resta inattiva viene compattata poco prima della scadenza della cache, quindi dopo pranzo riprendi da un riepilogo. Se non ti serve affatto la cronologia, una sessione nuova costa comunque meno.

Guida la sessione

[!TIP]

Osserva il primo minuto, premi Esc nel momento in cui Claude devia e, dopo due correzioni non riuscite, esegui /clear e scrivi un prompt migliore invece di una terza correzione.

Nessuna configurazione sostituisce l'osservare il primo minuto e intervenire quando Claude si dirige da qualche parte che non intendevi. Ci sono solo pochi controlli per farlo, e vale la pena conoscerli a memoria:

  • Esc ferma Claude a metà azione e mantiene tutto fino a quel punto, così puoi reindirizzarlo senza perdere lavoro.
  • /rewind, o Esc due volte su un prompt vuoto, apre il menu di rewind, dove riporti il codice, la conversazione o entrambi a un prompt precedente. Questo rende poco rischioso provare prima l'approccio più audace e tornare indietro se non funziona. Lo stesso menu può anche riassumere parte della conversazione quando è diventata obsoleta.
  • /clear ricomincia da capo. Se hai corretto la stessa cosa due volte ed è ancora sbagliata, una terza correzione non fa che aggiungersi a una conversazione che contiene già due tentativi falliti che Claude continua a rileggere. /clear più un nuovo prompt che incorpora ciò che hai imparato funziona meglio quasi sempre.

[!WARNING]

I checkpoint coprono i file che Claude ha modificato con i propri strumenti per i file nella tua conversazione principale, quindi un file toccato solo da un comando Bash non viene ripristinato. Funzionano insieme a git anziché sostituirlo.

Due controlli minori: /btw risponde a una domanda veloce senza aggiungere nulla alla cronologia. E per un lavoro che si estende su più giorni, /rename oauth-migration nella sessione le assegna un nome, in modo che claude --resume oauth-migration dalla tua shell la riprenda in seguito, checkpoint inclusi. claude --continue riprende quella più recente.

Lascia che Claude lavori senza di te

[!TIP]

Prima che un'esecuzione proceda senza supervisione, assicurati che sappia com'è il lavoro completato, che possa verificare il proprio lavoro e che possa toccare solo ciò che deve. Dalle un limite di turni o di spesa, e fai approvare il risultato finale a una persona.

Tutto ciò che è in questa pagina conta un po' di più quando non sei presente per individuare gli errori. Mentre osservi, il fatto che a Claude manchi qualche elemento di contesto non è un grosso problema: te ne accorgi entro un messaggio o due e glielo dici. In un'esecuzione avviata prima di andare a dormire, nessuno glielo dice, e la mattina dopo scopri che ha passato tutta la notte a costruire su un presupposto sbagliato.

Prima di lasciare un'attività in esecuzione da sola, conviene rispondere a queste cinque domande pensando a quell'attività specifica:

  1. Sa com'è il lavoro completato? Una condizione di obiettivo, un file di specifica o un test che fallisce e che deve far passare.
  2. Può verificare il proprio lavoro? La suite di test, un hook Stop, una qualche fase di revisione.
  3. Cosa può toccare? Regole di permesso, dontAsk, la sandbox, un worktree, l'unico branch su cui può fare push.
  4. Cosa lo ferma? --max-turns, --max-budget-usd, un limite di spesa.
  5. Dove va il risultato e chi lo approva? Una PR, un commento o un riepilogo, e poi una persona che approva il merge, il deploy o qualsiasi altra cosa irreversibile.

Una volta avviata, Claude porterà avanti da solo un'attività lunga. Le parti che restano a te sono avviarla, decidere cosa significa "completato" questa volta e approvare il merge alla fine.

Esegui Claude da uno script

claude -p "prompt" viene eseguito una volta e termina, ed è così che Claude Code finisce nei job di CI, negli hook git e nei cicli della shell.

In uno script vorrai quasi sempre qualche flag in più:

  • --bare salta hook, skill, plugin, server MCP e file CLAUDE.md, sia quelli del repository sia quelli della macchina, in modo che l'esecuzione faccia la stessa cosa ovunque venga eseguita. Inoltre non tocca mai il tuo accesso a claude.ai: l'autenticazione proviene da ANTHROPIC_API_KEY, da un apiKeyHelper nel file che passi con --settings o dalle credenziali del tuo cloud provider.
  • --append-system-prompt, --mcp-config e --settings passano esplicitamente ciò di cui l'esecuzione ha bisogno.
  • --allowedTools pre-approva i suoi strumenti, e --permission-mode dontAsk rifiuta qualsiasi altra cosa che avrebbe richiesto conferma.
  • --output-format json ti fornisce un singolo oggetto risultato da analizzare, e stream-json con --verbose trasmette gli eventi man mano che accadono.

Messo tutto insieme, appare così:

for file in $(cat files.txt); do
  claude --bare -p "Migrate $file to the new logger API and commit. Reply OK or FAIL." \
    --allowedTools "Read,Edit,Bash(git add *),Bash(git commit *)" \
    --permission-mode dontAsk \
    --max-turns 20
done

Al termine di un'esecuzione, Claude risponde OK o FAIL, mentre un'esecuzione che raggiunge il limite di turni termina con un errore. Provalo prima su tre file, vedi cosa va storto, correggi il prompt, poi esegui il resto.

La modalità auto funziona anche con -p se passi --permission-mode auto. In un'esecuzione non interattiva, un blocco del classificatore nega quella singola azione e Claude prosegue, e i blocchi ripetuti non mettono in pausa l'esecuzione come fanno in un terminale. Leggi come si applicano le soglie in quel caso prima di farci affidamento.

Avvia esecuzioni su pianificazione o in base a un evento

Una volta avviata un'esecuzione, Claude può gestire il resto da solo. L'unica cosa che non può fare è decidere di iniziare, quindi qualcosa deve farlo: tu, un timer o un evento come un controllo CI fallito o una nuova PR.

All'interno di una sessione aperta c'è /loop, che ripete un prompt a intervalli:

/loop 15m check CI on this branch, and if it's red pull the failing job's log, fix it and push

Ogni esecuzione è un ulteriore turno nella stessa sessione, quindi non lasciarne uno attivo in una conversazione lunga. Per tutto ciò che deve avvenire mentre il tuo laptop è chiuso, /schedule configura un'attività pianificata nel cloud che viene eseguita in base a un timer. Richiede un accesso a claude.ai anziché una chiave API. Puoi aggiungere un trigger basato su eventi GitHub chiedendolo a Claude, o un trigger API su claude.ai/code/routines.

[!WARNING]

Prima di lasciare in esecuzione un'attività pianificata nel cloud, proteggi main con una regola di branch GitHub che l'attività non può aggirare. E osserva le prime esecuzioni di qualsiasi cosa nuova prima di fidarti a lasciarla senza supervisione.

Esegui sessioni in parallelo

Quando hai più parti di lavoro separate in corso contemporaneamente, dai a ciascuna il proprio checkout in modo che le modifiche non possano scontrarsi. claude -w feature-auth avvia una sessione in un nuovo worktree, l'app desktop ne esegue diverse fianco a fianco, e le sessioni cloud le eseguono nel cloud anziché sulla tua macchina.

Un worktree è un checkout nuovo, il che significa che i file ignorati da git come .env non sono presenti e le dipendenze non sono installate. Per i primi, elenca i file ignorati da git di cui hai bisogno in un .worktreeinclude nella root del repository (stessa sintassi di .gitignore) e Claude Code li copia in ogni worktree che crea:

.env
.env.local
config/dev-credentials.json

Limitati a file piccoli: li copia anziché collegarli, quindi inserire node_modules significherebbe una copia completa per ogni worktree. Per directory di grandi dimensioni c'è l'impostazione worktree.symlinkDirectories, oppure tieni il comando di installazione in CLAUDE.md in modo che Claude lo esegua ogni volta che inizia in un nuovo checkout.

Raramente devi ripulire tu stesso:

  • Quando esci da una sessione worktree senza nome, Claude Code rimuove il worktree se non contiene nulla. Per una sessione con nome, o con modifiche, ti chiede cosa fare.
  • I worktree dei subagent scompaiono quando il subagent termina senza modifiche.
  • I worktree dei subagent e delle sessioni in background che restano comunque vengono eliminati quando sono più vecchi di cleanupPeriodDays e non contengono lavoro.

[!NOTE]

Un'esecuzione claude -p --worktree va ripulita da te, dato che termina senza chiedere. Rimuovi questi worktree con git worktree remove <path> e, se git si rifiuta perché il worktree è bloccato, esegui prima git worktree unlock <path>.

Per una grande modifica meccanica su molti file, /batch migrate every handler to the v2 response helpers divide il lavoro in 5-30 unità e ti mostra il piano. Poi esegue ogni unità nel proprio worktree e apre una PR per ciascuna. Dalla tua shell, claude agents (ancora in anteprima di ricerca) ti offre un'unica schermata per tutto ciò che è in esecuzione in background sulla tua macchina.

Una seconda sessione è anche il revisore indipendente più semplice che puoi avere. Una sessione scrive il rate limiter, un'altra esamina @src/middleware/rateLimiter.ts senza averne osservato la scrittura, e tu incolli i risultati nella prima. Stessa idea di /code-review, con te a fare da messaggero.

Cosa puoi smettere di fare

Ognuno di questi era un buon consiglio quando è stato scritto. La maggior parte erano soluzioni alternative per qualcosa che il modello non riusciva ancora a fare in modo affidabile, e da allora i modelli si sono messi al passo. Se alcuni sono ancora tue abitudini, ecco perché puoi abbandonarli in sicurezza.

Il vecchio consiglio Perché non serve più
La finestra di contesto è il tuo vincolo principale, gestiscila in modo aggressivo La maggior parte dei modelli attuali ha una finestra da 1M di token e la compattazione avviene da sola, quindi esaurirla è raro. /clear tra un'attività e l'altra vale ancora la pena, perché un contesto focalizzato ti dà risposte migliori e costa meno.
Aggiungi IMPORTANT o TUTTO MAIUSCOLO alle istruzioni che Claude continua a ignorare I modelli più vecchi a volte avevano bisogno dell'enfasi. Quelli attuali seguono una riga formulata in modo semplice, e accumulare enfasi porta soprattutto Claude ad applicare la regola in modo eccessivo. Se è una regola che non può piegarsi, trasformala in un hook o in una regola deny. Se la riga si perde in un file lungo, il file deve essere più breve.
Usa i subagent per proteggere la tua finestra di contesto Esaurire il contesto raramente è più un problema. I subagent restano ottimi per il lavoro in parallelo, per tenere fuori dai piedi l'output rumoroso e per la revisione indipendente, ma ognuno di questi usi costa token in più.
Delega a un subagent per ottenere una risposta migliore Affidare la stessa attività a un subagent non rende la risposta migliore. Un revisore nuovo aiuta, perché non ha visto il tuo ragionamento, ma questa è una cosa diversa dal delegare.
think hard, think harder, be thorough nel prompt Lo sforzo è il controllo giusto per questo. Quelle frasi sono normale testo del prompt che spinge Claude entro la sua impostazione di sforzo, non parole chiave che la alzano. ultrathink funziona ancora: chiede un ragionamento più profondo per quel singolo turno senza toccare la tua impostazione di sforzo.
Di' a Claude di andare avanti, di ripetere finché non ha finito, di non essere pigro I modelli attuali di solito portano avanti un'attività concordata senza che glielo si dica, e righe del genere hanno più probabilità di causare lavoro eccessivo che di risolvere un arresto. Dare a Claude un controllo da superare è diverso, e vale ancora la pena farlo. Se un'esecuzione si ferma prima del tempo, di' continue, e per le esecuzioni che nessuno sta osservando, /goal o un hook Stop lo impongono.
Descrivi la tua architettura e la struttura dei file in CLAUDE.md Claude legge il repository da solo. Scrivi solo ciò che non c'è.

Se qualche altro consiglio in questa pagina inizia a sembrarti lavoro inutile, probabilmente è segno che anche quello appartiene a questa tabella.

Risorse correlate