Passa al contenuto principale

Feature flag: perché il tuo Claude Code non è il mio

Avanzato

Due sviluppatori installano la stessa versione di Claude Code, sullo stesso sistema operativo, nello stesso repository. Uno dei due ha una funzione che all'altro manca, e nessuno dei due riceve un messaggio di errore. Non è folklore: è il design documentato. Claude Code attiva alcune funzioni usando feature flag che scarica da Anthropic all'avvio, e diverse configurazioni ordinarie e ben intenzionate disattivano quel download del tutto.

La conseguenza che sorprende: un'operazione puramente locale può dipendere da una chiamata di rete. A settembre 2026 è diventato un thread di Hacker News da 437 punti, perché leggere un file Markdown dal tuo disco si è rivelato richiedere una di queste chiamate.

What you'll learn
  • Come vengono scaricati, messi in cache e valutati i feature flag remoti di Claude Code
  • Le quattro configurazioni che disattivano in silenzio il download dei flag
  • Perché DISABLE_TELEMETRY=0 ti esclude comunque, e perché DO_NOT_TRACK=0 no
  • Le quindici funzioni che perdi con il download disattivato
  • Come individuare il gating in due minuti e fissare il comportamento perché non ti freghi

Il meccanismo​

Claude Code include un valore predefinito nel codice per ogni flag e poi prova a scaricare i valori reali. Il provider è GrowthBook: esiste una variabile d'ambiente dedicata DISABLE_GROWTHBOOK, e il changelog ha voci come una correzione di crash "when a GrowthBook feature evaluates to null" (v2.1.214).

Quattro proprietà di quel sistema spiegano quasi ogni caso strano in cui ti imbatterai:

Guided walkthrough1 of 4
  1. Il binario conosce i nomi dei flag e un valore di ripiego per ciascuno. I valori che decidono cosa può fare la tua sessione arrivano da Anthropic via rete. Senza download, ogni flag ricade sul suo valore predefinito nel codice, che per una funzione a metà rollout di solito è off.

I quattro modi in cui il download si spegne​

La documentazione è esplicita. Claude Code salta il download dei flag in queste sessioni:

  • Imposti una di quattro variabili d'ambiente: DISABLE_GROWTHBOOK, DISABLE_TELEMETRY, DO_NOT_TRACK o CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC.
  • Sei su un provider di terze parti: Amazon Bedrock, Claude Platform on AWS, Agent Platform di Google Cloud o Microsoft Foundry, a meno che una piattaforma host che incorpora Claude Code imposti CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST.
  • Sei in una sessione tramite gateway delle app Claude.
  • È la tua prima sessione dopo un'installazione nuova o un aggiornamento: i flag non sono ancora arrivati. Ne parliamo più sotto.

Nota cosa hanno in comune le prime due: sono le configurazioni che sceglie un'azienda attenta alla sicurezza. La popolazione più propensa a disattivare la telemetria e a passare da Bedrock è esattamente quella che si ritrova in silenzio con l'insieme di funzioni più ridotto.

Watch out
  • Disattivare la telemetria non è solo una scelta di privacy: è anche un interruttore di funzioni. La documentazione dice che DISABLE_TELEMETRY 'also disables feature-flag fetching with the same effect as DISABLE_GROWTHBOOK'.
  • Se vuoi la privacy senza perdere funzioni, non esiste alcuna combinazione che ti dia entrambe le cose: ogni modo documentato per fermare la telemetria ferma anche il download dei flag.
  • I runner di CI con un HOME effimero sono un'installazione nuova a ogni esecuzione, quindi finiscono nel caso senza flag ogni singola volta.

La trappola dei valori: tre variabili, tre regole di parsing​

Questa è la parte che costa un pomeriggio. Queste variabili appartengono alla stessa famiglia, si leggono come se facessero la stessa cosa e interpretano i loro valori con tre regole diverse.

VariabileCome legge il valoreQuindi =0 significa
DISABLE_TELEMETRYQualsiasi valore non vuoto la attivaTi esclude comunque. Rimuovila per riattivare
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICQualsiasi valore non vuoto la attivaDisattiva comunque il traffico. Rimuovila per riattivare
DISABLE_ERROR_REPORTINGQualsiasi valore non vuoto la attivaTi esclude comunque. Rimuovila per riattivare
DISABLE_GROWTHBOOKBooleano standard: imposta 1 o trueLascia il download attivo
DO_NOT_TRACKBooleano standard: imposta 1Lascia la telemetria attiva

Leggi quella tabella due volte. DISABLE_TELEMETRY=0 disattiva la telemetria. DO_NOT_TRACK=0 no. Entrambe le cose sono documentate, volute e opposte.

What you'll learn
  • La documentazione enuncia la regola direttamente: alcune variabili 'read only whether you set them at all, so any non-empty value including 0 turns the behavior on'.
  • Per annullarne una devi rimuovere la variabile o impostarla a un valore vuoto: assegnare 0 o false non è un interruttore di spegnimento.
  • Morde più forte in un Dockerfile o in una configurazione CI dove qualcuno l'ha 'disattivata' cambiando 1 in 0.

Cosa perdi davvero​

Con il download dei flag disattivato, quindici capacità documentate spariscono. Raggruppate per ciò che ti costano:

Permessi e avvio

  • Le sessioni non possono partire in auto mode per impostazione predefinita sui piani Pro, Max e Team
  • L'estensione VS Code non può leggere i file di impostazioni per la modalità di permessi iniziale
  • /auto-mode-setup non può abbozzare le voci autoMode.environment

Tutto ciò che va oltre la sessione locale

  • Remote Control
  • Sessioni di messaggistica su altre macchine (la messaggistica sulla stessa macchina funziona ancora)
  • Sincronizzazione nelle sessioni da terminale delle skill e dei plugin abilitati per il tuo account claude.ai
  • Lettura o risposta ai commenti su un artifact
  • Il tool advisor

Comandi e diagnostica

  • claude import e il comando /import
  • /skill-doctor e il suo report nella scheda Stats di /plugin

Cambi di comportamento silenziosi: il gruppo pericoloso

  • MCP: Claude Code smette di escludere i tool MCP il cui schema di input verrebbe rifiutato dall'API. Invia comunque lo schema, e la richiesta fallisce con un 400 che nomina il tool per posizione
  • MCP: nessun sondaggio dei server connettore claude.ai per la revisione di protocollo 2026-07-28, a meno che tu imposti MCP_PROTOCOL_NEGOTIATION=auto
  • I testi incollati di grandi dimensioni non vengono più trattati come incollati ma come digitati: il contenuto dietro un segnaposto [Pasted text #N] arriva a Claude senza segnalazione
  • Su Windows con Git Bash installato, gli account claude.ai e Console non ricevono per impostazione predefinita il tool PowerShell; imposta CLAUDE_CODE_USE_POWERSHELL_TOOL=1
  • Il feedback abbozzato da Claude è disattivato

L'ultimo gruppo è quello da interiorizzare. Un comando slash mancante si fa notare. Un errore 400 che nomina un tool per la sua posizione nell'array non somiglia a un'impostazione di telemetria, e debuggerai il tuo server MCP per un'ora prima di pensare a controllare una variabile d'ambiente.

Il raggio d'azione ha dei precedenti​

Le impostazioni di flag e telemetria sono trapelate in posti che nessuno avrebbe previsto. Due esempi corretti ma istruttivi dal changelog:

  • La v2.1.108 ha corretto gli abbonati che impostavano DISABLE_TELEMETRY e ricadevano su un TTL della prompt cache di 5 minuti invece di 1 ora. Una variabile per la privacy costava in silenzio denaro a ogni sessione lunga: una finestra di cache 12 volte più breve.
  • La v2.1.105 ha corretto CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC impostata nelle impostazioni di un solo progetto che disattivava in modo permanente le metriche d'uso per tutti i progetti sulla macchina.

Entrambi sono corretti. Entrambi mostrano la forma del rischio: questi interruttori attraversano sottosistemi che sembrano non correlati.

La prima sessione dopo un'installazione o un aggiornamento​

Questo merita un titolo a sé perché produce la classica segnalazione di bug irriproducibile.

Alla prima sessione dopo aver installato Claude Code, o dopo l'aggiornamento a una versione che aggiunge una funzione, una funzione dietro flag può semplicemente mancare, e la sessione può partire in modalità Manual su un piano che altrimenti parte in auto mode. Claude Code scarica i flag durante quella sessione, quindi la volta successiva sono presenti entrambi.

Due corollari:

  • Si risolve da solo, ed è esattamente per questo che è difficile da segnalare. Quando qualcuno guarda, la seconda sessione ha già i flag.
  • Non si risolve mai da solo negli ambienti effimeri. Un runner di CI, un container nuovo o qualsiasi configurazione con una home directory usa e getta è alla sua prima sessione ogni volta.

La documentazione cita una mitigazione: dopo un'installazione nuova, una sessione non interattiva come claude -p, l'Agent SDK o l'estensione VS Code può comunque ottenere i flag prima di scegliere la modalità di permessi iniziale.

Caso di studio: AGENTS.md, un file locale dietro un interruttore remoto​

L'esempio più chiaro dell'intero schema, e quello che è finito in prima pagina.

Guided walkthrough1 of 5
  1. La voce del changelog: in un progetto senza CLAUDE.md, Claude Code legge AGENTS.md; si cambia sotto 'Project instructions' in /config. La voce stessa segnala che non è ancora disponibile su Bedrock, Vertex o Foundry.

La lezione si generalizza oltre questo singolo bug. Chiediti, per ogni nuova funzione di Claude Code: è gated? Se lo è, la tua postura sulla telemetria, il tuo provider e quanto recentemente hai installato diventano tutti input per decidere se funziona.

Diagnosticarlo in due minuti​

Non serve indovinare. Tre controlli, dal più economico.

1. Chiediti se l'impostazione esiste almeno. Quando il supporto ad AGENTS.md non è disponibile, la riga Project instructions non compare affatto nel pannello /config. Un'impostazione mancante è già di per sé la diagnosi: la funzione non è spenta, è assente.

2. Guarda cosa ti dice una sessione interattiva. Quando funziona, Claude Code stampa nella conversazione una riga come no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md. Niente riga, niente caricamento.

3. Esegui un canary. La tecnica che ha risolto la segnalazione originale: metti nel file una parola che non compare da nessun'altra parte, poi chiedila in una sessione pulita e non interattiva. Se la parola torna, il file ha raggiunto il modello. Funziona per qualsiasi file di istruzioni, su qualsiasi versione.

Test canary: il file di istruzioni è stato davvero caricato?

mkdir -p /tmp/canary && cd /tmp/canary
echo 'The project codeword is PERIWINKLE.' > AGENTS.md
claude -p 'What is the project codeword? Answer with one word.'

Eseguilo una volta con il tuo ambiente normale, poi una volta con le variabili per la privacy azzerate, e confronta. Nota l'assegnazione a stringa vuota: ricorda che DISABLE_TELEMETRY=0 non la azzererebbe.

Stesso test con il download dei flag consentito: nota i valori vuoti, non gli zeri

cd /tmp/canary
env DISABLE_TELEMETRY= CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC= DISABLE_GROWTHBOOK=false \
claude -p 'What is the project codeword? Answer with one word.'

4. Se ti serve il dettaglio, attiva il debug logging. Avvia con --debug o /debug, e i log finiscono in ~/.claude/debug/<session-id>.txt. Un'avvertenza: la variabile d'ambiente DEBUG accetta solo i valori veritieri 1, true, yes e on: un pattern di namespace come DEBUG=express:* rimasto da un altro strumento non la attiverà.

Fissare il comportamento invece di affidarsi a un flag​

La soluzione duratura è smettere di dipendere dal gate. Due schemi.

Fissa esplicitamente l'impostazione. Per i file di istruzioni, il valore di Project instructions può stare in un file di impostazioni sotto l'ID del plugin integrato, invece di essere lasciato al valore predefinito. Un limite importante: Claude Code ignora questa chiave nei file di impostazioni di progetto e locali: la legge solo da ~/.claude/settings.json, da un file --settings o dalle impostazioni gestite. Metterla nel .claude/settings.json del tuo repo non farà nulla.

Caricare insieme CLAUDE.md e AGENTS.md: solo impostazioni utente o gestite

{
"pluginConfigs": {
  "agents-md@builtin": {
    "options": { "instructionFiles": "claude-md-and-agents-md" }
  }
}
}

Usa un percorso che non è mai stato gated. Un CLAUDE.md che importa AGENTS.md ha funzionato su ogni versione, ogni provider e con la telemetria disattivata, perché è la normale espansione dell'import @path, non un percorso di codice dietro flag. È la raccomandazione che la documentazione stessa dà per le sessioni Bedrock, Vertex e Foundry.

Il CLAUDE.md di una riga che non ha mai avuto bisogno di un flag

@AGENTS.md

Una sottigliezza se scegli questa strada: un AGENTS.md letto tramite l'impostazione si comporta in modo leggermente diverso da uno richiamato tramite import. Gli hook InstructionsLoaded non scattano per il percorso basato sull'impostazione, ma scattano normalmente per un AGENTS.md che un CLAUDE.md importa o a cui punta con un symlink. Se hai hook sul caricamento delle istruzioni, l'import è il percorso più sicuro.

Il gating dei flag in sintesi
Premi Invio o Spazio per girare la carta. Usa le frecce sinistra e destra per spostarti tra le carte.Termine mostrato.
1 / 8

Verifica la tua comprensione​

Verifica la tua comprensione

0/4
  1. Il tuo Dockerfile ha ENV DISABLE_TELEMETRY=0 perché un collega ha 'riattivato la telemetria'. Cosa sta succedendo davvero?
  2. Un job di CI segnala che Claude Code non carica mai l'AGENTS.md del repo, mentre funziona benissimo su ogni laptop degli sviluppatori. Qual è la causa più probabile?
  3. Con il download dei flag disabilitato, quale fallimento è più difficile da ricondurre all'impostazione dei flag?
  4. Vuoi che AGENTS.md si carichi in modo affidabile su Amazon Bedrock, su qualsiasi versione. Qual è la mossa robusta?
Key takeaways
  • Claude Code scarica i feature flag da Anthropic (GrowthBook), li mette in cache su disco e li valuta rispetto alla tua versione e al tuo livello di abbonamento: due installazioni identiche possono quindi legittimamente comportarsi in modo diverso.
  • Quattro variabili d'ambiente, tre provider di terze parti, le sessioni tramite gateway delle app e la prima sessione dopo un'installazione saltano tutti quel download, costandoti quindici funzioni documentate.
  • DISABLE_TELEMETRY, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC e DISABLE_ERROR_REPORTING trattano come attivo qualsiasi valore non vuoto, 0 incluso. DO_NOT_TRACK e DISABLE_GROWTHBOOK sono veri booleani. Rimuovi, non azzerare.
  • Le perdite peggiori sono silenziose: schemi MCP non filtrati che causano 400 posizionali, e testo incollato non segnalato.
  • AGENTS.md è stato il caso di studio: nativo dalla v2.1.277, gated, corretto nella v2.1.281. Un CLAUDE.md che contiene @AGENTS.md non ha mai avuto bisogno del flag.

Prossimi passi​

Fonti e letture di approfondimento​