Claude Code sotto controllo: guida al limite di sforzo

Claude Code: la risposta in breve

È sufficiente aggiornare Claude Code alla versione 2.1.267 o successiva e inserire "maxEffortLevel": "medium" nel file di configurazione relativo all’ambito da governare. ~/.claude/settings.json imposta un limite personale globale, .claude/settings.json lo applica a chiunque lavori in uno specifico repository, mentre le impostazioni gestite consentono di definire una regola per l’intera organizzazione.

L’impostazione accetta low, medium, high, xhigh o max. Il valore max indica che quella sorgente non pone alcun limite allo sforzo. Anche omettere la chiave equivale a non impostare un tetto.

È un limitatore di velocità, non una carta carburante. Controlla quanto Claude può spingersi nel ragionamento per una richiesta, ma non imposta un budget di token, un tetto di spesa o un limite d’uso dell’abbonamento. Questi valori vanno misurati separatamente tramite /usage, Claude Console o OpenTelemetry per Claude Code.

Cosa cambia davvero con maxEffortLevel

effortLevel e maxEffortLevel svolgono due funzioni diverse. Il livello di sforzo è quello richiesto per una sessione o un modello; il livello massimo stabilisce invece il confine che la richiesta non può superare.

Se il tetto è medium, uno sviluppatore può ancora selezionare low o medium. Le richieste di high, xhigh o max verranno invece eseguite a medium. Il limite intercetta anche lo sforzo richiesto tramite /effort, il selettore /model, --effort, CLAUDE_CODE_EFFORT_LEVEL e l’impostazione predefinita del modello. Claude Code applica la regola lato client prima di ogni richiesta: la stessa policy funziona quindi quando il traffico passa da Anthropic, Amazon Bedrock, Agent Platform di Google Cloud o Microsoft Foundry.

La regola decisiva è facile da trascurare: tra tutti gli ambiti caricati prevale sempre il limite più basso. Di norma, le impostazioni di Claude Code seguono una gerarchia in cui le configurazioni gestite hanno priorità su quelle della riga di comando, sui file di progetto e sulle impostazioni utente. maxEffortLevel è un’eccezione restrittiva: un tetto di progetto più basso vince anche se una sorgente gestita o personale consente uno sforzo maggiore.

Come impostare un limite globale, un’esenzione per modello e un tetto di progetto più rigido

Per prima cosa, verificare claude --version. Se la versione è precedente alla 2.1.267, eseguire claude update prima di aggiungere la chiave.

Per applicare un tetto personale a tutti i repository, inserire quanto segue in ~/.claude/settings.json:

{
  "maxEffortLevel": "medium",
  "modelSettings": {
    "claude-sonnet-4-6": {
      "maxEffortLevel": "max"
    }
  }
}

Il valore principale limita a medium tutti i modelli supportati. Nel solo file utente, la voce dedicata a Sonnet 4.6 sostituisce quel valore per Sonnet. Il suo valore max non obbliga il modello a lavorare con lo sforzo massimo: indica che questa specifica sorgente non gli impone alcun tetto.

Ora si può aggiungere una regola più severa per un singolo repository in .claude/settings.json:

{
  "maxEffortLevel": "low"
}

Il risultato effettivo è volutamente restrittivo:

L’esenzione del modello non scavalca la regola di progetto. Annulla soltanto il limite medium della sorgente utente per Sonnet. È l’equivoco che più facilmente può far credere, a torto, di aver creato un’esenzione assoluta.

Per una policy aziendale, la stessa chiave principale va distribuita tramite le impostazioni gestite. Il tetto si applicherà alle persone incluse in quella sorgente gestita, indipendentemente dal provider supportato utilizzato. Se anche un ruolo Enterprise prevede un limite allo sforzo, Claude Code applica quello più basso.

Come verificare il limite prima di farvi affidamento

Un file JSON valido non dimostra che abbia prevalso il tetto desiderato. Bisogna controllare sia le sorgenti caricate sia il livello effettivamente applicato.

1. Eseguire /status in Claude Code. La riga Setting sources conferma il caricamento delle impostazioni utente, di progetto e di eventuali configurazioni gestite, ma non indica quale sorgente abbia fornito ogni singola chiave.
2. Se manca una sorgente o una nuova chiave sembra ignorata, eseguire claude doctor. Il comando elenca le voci di configurazione rifiutate. Lo schema JSON pubblicato può arrivare dopo una nuova release della CLI, quindi un avviso dell’editor non costituisce da solo un verdetto.
3. Controllare l’intestazione della sessione accanto al nome del modello. Claude Code mostra lì lo sforzo corrente e, quando cambia, lo visualizza brevemente anche nel piè di pagina.
4. Nel repository dell’esempio, richiedere /effort max. Il tetto low definito a livello di progetto continua ad applicarsi: una richiesta superiore non può innalzarlo.
5. Per le flotte non interattive, esaminare l’attributo effort in claude_code.cost.usage e claude_code.token.usage. Registra il livello applicato a ogni richiesta insieme al modello e alla sorgente della query.

Quest’ultimo controllo è importante su Bedrock, Google Cloud e Foundry. La policy viene applicata da Claude Code prima che la richiesta raggiunga il provider, mentre la telemetria mostra ciò che Claude Code ha effettivamente utilizzato.

Qualità e spesa vanno testate su due binari distinti

Non conviene introdurre un tetto medium o low soltanto perché l’etichetta sembra economica. È meglio scegliere un’attività ricorrente che il team conosce già e confrontare esecuzioni equivalenti.

Un buon banco di prova è un piccolo repository con un test del parser che fallisce. Ogni esecuzione deve avere lo stesso modello, commit, prompt, permessi e accesso agli strumenti: correggere il caso limite, aggiungere un test di regressione, eseguire la suite e indicare i file modificati. Prima si esegue la baseline senza limite, poi si ripristina la fixture pulita e infine si prova la condizione con il tetto.

Il risultato va valutato prima di guardare i costi:

La metrica decisiva è il costo per attività accettata, non i token per risposta. Un’esecuzione a sforzo ridotto che richiede una seconda revisione o un intervento correttivo può costare più di un’esecuzione pulita a sforzo maggiore. Lo stesso principio vale per una più ampia analisi dei livelli di sforzo di Claude, ma la nuova impostazione rende vincolante in Claude Code il limite superiore scelto.

Sette contesti in cui un tetto allo sforzo ripaga

Questi casi d’uso sono ordinati in base a chi può ottenere il ritorno operativo più evidente.

1. Team di piattaforma che governano il lavoro ordinario

Un team di piattaforma che supporta 20 o 200 sviluppatori può impostare medium nelle configurazioni gestite, mantenere disponibili i livelli inferiori e riservare le modifiche alla policy alle eccezioni verificate. Il vantaggio non consiste soltanto nel consumare meno token. Un confine predefinito coerente tra portatili, sessioni IDE e percorsi attraverso i cloud provider rende davvero confrontabili costi e qualità.

2. Responsabili FinOps con Claude Code fatturato via API

Un responsabile FinOps può combinare un tetto gestito con dati OpenTelemetry raggruppati per effort, modello, team e centro di costo. Il processo è lineare: osservare la baseline senza limite, introdurre il tetto in un gruppo pilota e confrontare il costo per attività accettata. In questo modo, le discussioni su quale livello sembri costoso lasciano spazio a un report legato al lavoro effettivamente consegnato.

3. Aziende che utilizzano Bedrock, Google Cloud o Foundry

Un’azienda regolamentata può instradare i modelli attraverso il cloud scelto per esigenze di procurement o controllo dei dati. Il client Claude Code applica maxEffortLevel prima di ogni richiesta, permettendo all’organizzazione di mantenere la stessa policy di sforzo su tutti questi provider. Il vantaggio è la parità delle regole senza dover attendere che ogni console esponga lo stesso controllo.

4. Responsabili CI che eseguono correzioni ripetitive

Un team che usa Claude Code per aggiornare dipendenze, correggere la formattazione, mantenere i test o modificare la documentazione può limitare quei repository a low o medium. Il livello preciso va ricavato dai fixture delle attività, ma quando la qualità regge il tetto impedisce che un flag, una skill o il valore predefinito del modello spingano l’automazione ordinaria verso una modalità di ragionamento più profonda.

5. Responsabili di monorepo che separano lavoro ordinario e complesso

Chi gestisce un monorepo può mantenere un tetto personale medium, salvare nel repository della documentazione o del codice generato un limite condiviso più basso e lasciare un repository di sistemi complessi con un margine maggiore. Ogni repository porta con sé il proprio confine. La policy di costo segue così il lavoro, senza dipendere dalla memoria di ogni sviluppatore nell’eseguire un comando.

6. Società di consulenza che passano da un repository cliente all’altro

Un consulente può adottare un tetto personale medium come base e lasciare che ogni repository del cliente imponga una configurazione condivisa più severa. Questo riduce le divergenze di configurazione quando lo stesso portatile passa da un piccolo sito di contenuti a un’applicazione matura o a un contratto di manutenzione sensibile ai costi. Il file di progetto documenta inoltre la modalità operativa prevista per chi arriverà dopo.

7. Staff engineer che mantengono un’eccezione mirata per un modello

Uno staff engineer può esentare un modello dal limite globale di una sorgente tramite modelSettings e mantenere al contempo un tetto inferiore diverso in un repository critico per la sicurezza. Il modello ottiene più margine dove la sorgente lo consente, ma l’esenzione non diventa una scorciatoia universale. Il risultato è un’eccezione precisa, ancora subordinata alle policy di progetto o aziendali più restrittive.

Cosa vale la pena costruire attorno a questo limite

1. Gate di regressione dello sforzo, l’opportunità più solida

Si può creare un controllo CLI e CI che esegua ai livelli di sforzo consentiti la suite delle attività ritenute valide per il repository e riporti percentuale di successo, difetti rilevati in revisione, durata, token e costo. I team di engineering platform sarebbero disposti a pagare perché il limite pone subito una domanda di qualità: fin dove può scendere lo sforzo nel lavoro ordinario prima che le correzioni annullino il risparmio?

Il segnale di domanda è particolarmente interessante sul piano commerciale. ai code review registra una stima di 1,300 ricerche mensili negli Stati Uniti e un CPC di $62.38. La versione minima vendibile è un runner locale abbinato a un controllo GitHub che confronta due profili di sforzo sulla stessa fixture pulita e blocca una modifica alla policy quando i test richiesti o le regole di revisione peggiorano.

Il vero ostacolo è il benchmark. Un punteggio generico sul coding è facile da copiare e poco legato al repository del cliente. Il vantaggio difendibile risiede nell’insieme privato di attività del team, nei criteri di revisione e nello storico accumulato attraverso gli aggiornamenti dei modelli. Senza questi dati, resta soltanto un’altra dashboard.

2. Linter per le policy di sforzo di Claude Code

Si può realizzare un analizzatore di sola lettura che ricostruisca le sorgenti utente, condivise di progetto, locali di progetto, da riga di comando e gestite in un’unica tabella dei limiti per modello. I team di piattaforma e sicurezza potrebbero usarlo per individuare un’esenzione max erroneamente ritenuta globale, un tetto di progetto più basso che prevale in modo inatteso o una flotta che usa ancora una versione precedente alla 2.1.267.

claude code registra una stima di 550,000 ricerche mensili negli Stati Uniti e tra le domande rilevate compare “What effort level should I use for a Claude code?”. Il volume è ampio, più che direttamente orientato all’acquisto, ma la confusione sulla configurazione è concreta. Per un MVP bastano rilevamento delle sorgenti, controllo della versione, convalida JSON e spiegazione del limite più basso che prevale.

Il rischio è legato alla piattaforma. Anthropic potrebbe aggiungere un analizzatore nativo delle impostazioni effettive. Per essere duraturo, il prodotto dovrebbe includere avvisi sulle divergenze di policy, inventario della flotta e prove per gli audit, non soltanto una schermata di configurazione più gradevole.

3. Monitor dei costi di Claude Code sensibile allo sforzo

Si può creare una dashboard OpenTelemetry mirata, capace di unire l’attributo effort applicato a token, costo, modello, sorgente della query, repository e controlli di qualità nelle installazioni Anthropic e cloud. I team FinOps e developer experience pagherebbero per il collegamento tra policy e risultato, non per un altro totale di token.

llm observability registra una stima di 590 ricerche mensili negli Stati Uniti e un CPC di $37.45. I prezzi esistenti confermano la presenza di un budget: Datadog Agent Observability parte da un piano gratuito per 40,000 span LLM, mentre Pro parte da $160 al mese per 100,000 span. Un MVP specializzato potrebbe presentarsi come preset per un collector OpenTelemetry, inventario dei limiti e tre viste: sforzo applicato, costo per attività accettata e regressioni dopo una modifica al modello o alla policy.

Il problema è duplice: concorrenza e causalità. I fornitori di osservabilità raccolgono già token e costi, mentre una bolletta più bassa dopo l’introduzione di un tetto non dimostra che sia stato il limite a produrla. Per meritare fiducia, il prodotto deve offrire valutazioni equivalenti o evidenze ricavate dall’analisi dei punti di cambiamento.

Il gate di regressione dello sforzo è la migliore delle tre opzioni. La domanda è più vicina a una decisione tecnica per cui si è disposti a pagare, e lo storico privato delle valutazioni acquista valore ogni volta che Anthropic modifica un modello o la calibrazione dello sforzo.

Cosa non risolve il limite

Un tetto allo sforzo non garantisce una bolletta più bassa. Lo sforzo incide sui token di output, sul comportamento degli strumenti e sul ragionamento, ma contano anche il modello scelto, le dimensioni del codebase, l’uso della cache e l’automazione parallela. Per gli abbonati Claude Max e Pro, l’utilizzo è incluso nel piano, quindi il costo di sessione indicato da /usage non corrisponde alla fattura.

Inoltre, low non diventa automaticamente sicuro per ogni attività di sviluppo. Anthropic raccomanda esplicitamente di testare il carico di lavoro, e lo stesso nome di livello viene calibrato in modo diverso a seconda del modello. Un’esecuzione medium su un modello non rappresenta una quantità fissa di ragionamento confrontabile meccanicamente con medium su un altro.

Il limite non crea neppure un bypass assoluto per un modello. Una voce max specifica per modello rimuove soltanto il tetto principale definito nella stessa sorgente. Un’altra sorgente può ancora imporre un limite inferiore, così come può farlo un limite allo sforzo dell’organizzazione.

Infine, /status conferma quali file sono stati caricati, non quale abbia prevalso per ogni chiave. Nelle automazioni, l’attributo telemetrico effort applicato offre una traccia più chiara.

La mossa da fare lunedì

La prossima settimana, scegliere un’attività ordinaria in un repository. Registrare una baseline senza limite, aggiungere un tetto utente medium, inserire l’esenzione Sonnet documentata e poi impostare low nel file condiviso di progetto. Dopo aver verificato le sorgenti caricate e lo sforzo nell’intestazione della sessione, ripetere l’attività partendo dalla stessa fixture pulita e confrontare prima la qualità rispetto ai criteri di accettazione, poi il costo indicato da /usage. Se la qualità regge, promuovere il limite testato nell’ambito condiviso o gestito appropriato. Se non regge, alzare o rimuovere il tetto più restrittivo per quel carico di lavoro, conservando i dati raccolti.

Per costruire una policy dello sforzo, un gate di valutazione e una telemetria dei costi adatti al proprio flusso di engineering, si possono consultare i sistemi AI in produzione.