/checkup di Claude Code spiegato: contesto pulito, correzione della configurazione e miglioramento della sicurezza dell'agente

Introduzione

Claude Code ha acquisito un controllo di configurazione integrato più potente. Nella versione 2.1.205, Anthropic ha ampliato il flusso di lavoro /doctor esistente in modo che possa diagnosticare problemi di configurazione e aiutarne la risoluzione. /checkup è disponibile come alias per lo stesso flusso di lavoro in sessione.

La modifica può sembrare piccola perché viene attivata da un singolo comando con barra. In pratica, affronta un problema comune per le configurazioni di Claude Code a lunga durata: competenze inutilizzate, server Model Context Protocol obsoleti, file di istruzioni sovradimensionati, hook lenti, installazioni non aggiornate e richieste di autorizzazione ripetute rendono progressivamente l'ambiente più difficile da comprendere.

L'obiettivo non è solo segnalare che qualcosa non va. Il controllo aggiornato può ispezionare la configurazione, spiegare le modifiche proposte e chiedere approvazione prima di applicarle.

/checkup

Puoi anche utilizzare il comando canonico:

/doctor

Un controllo di configurazione con un solo comando

Secondo il changelog di Claude Code 2.1.205, /doctor è ora un controllo di configurazione completo in grado di diagnosticare e risolvere problemi, mentre /checkup è il suo alias.

Questo è diverso dal comando terminale separato:

claude doctor

Il comando terminale stampa diagnosi di installazione e impostazioni in sola lettura senza avviare una sessione interattiva. Il flusso di lavoro in sessione /doctor o /checkup può andare oltre proponendo correzioni e permettendo a Claude di coordinare la pulizia attraverso i suoi strumenti disponibili.

Il creatore di Claude Code, Boris Cherny, ha descritto diversi compiti che il controllo è progettato per gestire:

1. Pulire competenze inutilizzate, server MCP e plugin.
2. Deduplicare le istruzioni locali CLAUDE.md rispetto alle istruzioni di progetto nel repository.
3. Suddividere un file CLAUDE.md principale sovradimensionato in file annidati e competenze riutilizzabili.
4. Identificare e disabilitare hook lenti.
5. Aggiornare Claude Code all'ultima versione disponibile.
6. Abilitare la modalità automatica per impostazione predefinita quando appropriato.
7. Pre-approvare comandi di sola lettura frequentemente rifiutati.
8. Rilevare altri problemi di configurazione che rendono l'ambiente più lento o meno affidabile.

Il comando chiede conferma prima di apportare modifiche.

Cosa controlla effettivamente il controllo

1. Competenze inutilizzate, server MCP e plugin

Claude Code può essere esteso con competenze, plugin, hook e server MCP. Queste integrazioni sono utili, ma una configurazione matura spesso accumula componenti che non sono più

rilevanti.

Potrebbe essere stato aggiunto un server MCP per un vecchio sistema di tracciamento delle issue. Potrebbe essere stata creata un'abilità per un flusso di lavoro che il team non utilizza più. Un plugin potrebbe essere ancora attivo anche se i suoi comandi sono stati sostituiti.

La verifica può far emergere questi componenti inutilizzati e proporne la rimozione o la disattivazione.

Questo è importante perché strumenti e istruzioni possono assorbire attenzione e contesto anche quando non stanno aiutando attivamente nel compito corrente. Meno integrazioni irrilevanti rendono anche il modello di autorizzazione più facile da controllare.

2. Istruzioni CLAUDE.md duplicate o eccessivamente estese

I file CLAUDE.md forniscono istruzioni persistenti per Claude Code. Possono contenere comandi di build, convenzioni di codifica, note architetturali, requisiti di test e regole specifiche del progetto.

Questi file vengono caricati nel contesto della sessione. Anthropic consiglia di mantenere ogni file conciso e di rivedere regolarmente i file di istruzioni nidificati per individuare regole obsolete o in conflitto.

Con il tempo, un progetto può sviluppare diversi problemi comuni:

• La stessa regola appare sia nei file locali che in quelli sottoposti a versionamento.
• Le vecchie istruzioni rimangono dopo cambiamenti nella codebase.
• Un file radice si trasforma in una lunga raccolta di procedure non correlate.
• Regole a livello di team e regole specifiche di directory vengono mescolate insieme.
• Flussi di lavoro dettagliati vengono memorizzati in CLAUDE.md, anche se funzionerebbero meglio come abilità su richiesta.

La verifica può confrontare le istruzioni locali e quelle di progetto, identificare duplicazioni e suggerire una struttura più focalizzata.

Una disposizione pratica potrebbe essere simile a questa:

progetto/
├── CLAUDE.md
├── .claude/
│   ├── rules/
│   │   ├── frontend.md
│   │   ├── backend.md
│   │   └── testing.md
│   └── skills/
│       └── release/
│           └── SKILL.md
└── packages/
    └── api/
        └── CLAUDE.md

Il file radice può contenere solo le regole necessarie per l'intero repository. Istruzioni più specifiche possono essere caricate quando Claude opera all'interno della directory pertinente, mentre le procedure riutilizzabili possono diventare abilità che si caricano quando vengono invocate.

3. Hook lenti o ridondanti

Gli hook sono azioni deterministiche che vengono eseguite in punti specifici del ciclo di vita di Claude Code. Possono formattare file, validare comandi, applicare politiche, inviare notifiche o integrare Claude Code con sistemi interni.

Un hook è utile solo quando il suo valore giustifica il suo costo. Uno script che aggiunge due o tre secondi a ogni chiamata di strumento può creare un grande ritardo in una sessione lunga.

La verifica può aiutare a identificare hook che sono:

• Costantemente lenti.
• Attivati più spesso del previsto.
• Duplicanti un altro passaggio di validazione.
• Che fanno riferimento a script che non esistono più.
• Che producono errori che l'utente ha imparato a ignorare.
• Non più collegati a un flusso di lavoro attivo.

Disattivare un hook non necessario non solo migliora la velocità. Riduce anche il rumore, rendendo più facili da notare i fallimenti importanti.

4. Problemi di installazione e aggiornamento

Un launcher danneggiato, un'installazione obsoleta o un aggiornamento parziale possono creare comportamenti confusi. La verifica dell'installazione può ispezionare lo stato di salute dell'installazione e raccomandare l'aggiornamento di Claude Code.

Per controllare manualmente la versione installata, usa:

claude --version

Il metodo esatto di aggiornamento dipende da come è stato installato Claude Code.

Le distribuzioni enterprise gestite potrebbero fissare intenzionalmente una versione, quindi gli utenti non dovrebbero ignorare la policy dell'organizzazione solo perché esiste una versione più recente.

5. Richieste Ripetute di Permessi di Sola Lettura

Claude Code utilizza un sistema di permessi che separa le ispezioni a basso rischio dalle azioni che modificano l'ambiente.

La documentazione di sicurezza di Anthropic afferma che un insieme predefinito di comandi di sola lettura, inclusi comandi come ls, cat e git status, può essere eseguito senza richiesta di approvazione. I comandi che modificano file, eseguono operazioni Bash potenzialmente modificanti o accedono a sistemi aggiuntivi potrebbero richiedere approvazione.

Se un utente rifiuta ripetutamente o approva manualmente un comando innocuo di sola lettura, il controllo può suggerire una regola di autorizzazione più chiara. L'obiettivo è ridurre l'affaticamento da richieste senza concedere ampi permessi di scrittura.

Una buona regola di autorizzazione dovrebbe essere ristretta. Approvare uno schema specifico di sola lettura è più sicuro che consentire un'intera categoria di shell o strumenti.

Perché il Mantenimento del Contesto è Importante

Un agente di codifica AI deve inserire diversi tipi di informazioni in un unico contesto di lavoro:

• La conversazione corrente.
• I file sorgente pertinenti.
• I risultati degli strumenti e l'output dei comandi.
• Le istruzioni CLAUDE.md.
• Le descrizioni delle competenze.
• Le definizioni degli strumenti MCP.
• I piani, lo stato delle attività e i risultati intermedi.

La finestra di contesto è limitata. Una grande quantità di informazioni di configurazione irrilevanti può lasciare meno spazio al problema reale.

Ciò non significa che ogni competenza installata o server MCP venga caricato automaticamente per intero. Claude Code utilizza meccanismi come corpi di competenza su richiesta e scoperta di strumenti per controllare l'uso del contesto. Tuttavia, una configurazione non necessaria crea complessità aggiuntiva e aumenta la probabilità che istruzioni o integrazioni obsolete influenzino una sessione.

Una configurazione sana richiede quindi lo stesso tipo di manutenzione di un progetto software:

1. Rimuovere ciò che non è più utilizzato.
2. Mantenere le istruzioni globali brevi.
3. Spostare le procedure specializzate in file o competenze con ambito limitato.
4. Verificare integrazioni e permessi.
5. Misurare il costo degli hook.
6. Rivedere la configurazione dopo modifiche importanti al progetto.

Dalla Diagnosi alla Pulizia Assistita

Gli strumenti diagnostici precedenti spesso si fermavano dopo aver elencato gli errori. L'utente doveva ancora comprendere ogni avviso, trovare il file pertinente, decidere una soluzione e applicarla manualmente.

Il controllo aggiornato in sessione segue uno schema più agentico:

1. Ispezionare l'ambiente corrente.
2. Identificare problemi specifici.
3. Stimare il beneficio di una pulizia.
4. Presentare le modifiche proposte.
5. Consentire all'utente di scegliere tra una pulizia completa, correzioni selezionate o un'opzione di solo report.
6. Applicare solo le modifiche approvate.
7. Lasciare le modifiche ai file visibili per la revisione.

Questo rende il flusso di lavoro più simile a un assistente di manutenzione interattivo che a un report di errori passivo.

La fase di approvazione è importante. Uno strumento non dovrebbe

rimuovere silenziosamente una competenza del progetto, riscrivere i file di istruzione o modificare il comportamento delle autorizzazioni semplicemente perché ritiene la configurazione inefficiente.

Miglioramenti alla sicurezza per i comandi autonomi

La stessa versione ha incluso anche modifiche mirate a ridurre i rischi quando Claude Code agisce in modo più autonomo.

Protezione contro approvazioni falsificate nei registri di sessione

Le notifiche delle attività in background ora dichiarano esplicitamente quando non è avvenuto alcun input umano. Ciò ha lo scopo di evitare che il testo all'interno di una trascrizione venga scambiato per una reale approvazione dell'utente.

Per un agente, la differenza tra "la trascrizione contiene testo simile a un'approvazione" e "l'utente ha effettivamente approvato questa azione tramite l'interfaccia" è fondamentale. Le decisioni sensibili alla sicurezza necessitano di un canale di approvazione affidabile.

Conferma aggiuntiva per comandi rm -rf rischiosi

Il changelog nota anche un miglioramento alla modalità automatica: Claude Code chiede conferma prima di eseguire rm -rf quando il percorso contiene una variabile che non riesce a risolvere dal contesto.

Un esempio pericoloso è:

rm -rf "$TARGET_DIR/"

Se TARGET_DIR è vuota o espansa in modo errato, il risultato può essere molto diverso da ciò che l'autore dello script intendeva.

La lezione corretta non è che un singolo prompt di conferma renda sicuri i comandi shell distruttivi. Gli utenti dovrebbero comunque ispezionare il percorso risolto, utilizzare un sandbox o un ambiente usa e getta quando possibile, mantenere backup ed evitare comandi di eliminazione estesi nei sistemi di produzione.

L'autonomia ha bisogno di confini

La versione combina due obiettivi che potrebbero apparire in conflitto:

• Ridurre le interruzioni non necessarie per lavori di routine, di sola lettura.
• Aggiungere una conferma più forte intorno ad azioni incerte o distruttive.

Questi obiettivi lavorano insieme. Un agente utile dovrebbe muoversi rapidamente all'interno di un'area sicura ben definita e rallentare quando si avvicina a un confine con conseguenze irreversibili.

/doctor, /checkup e claude doctor

I nomi simili possono creare confusione.

Comando	Dove viene eseguito	Scopo principale	Può proporre o applicare correzioni?
/doctor	All'interno di una sessione Claude Code	Controllo completo della configurazione	Sì
/checkup	All'interno di una sessione Claude Code	Alias per /doctor	Sì
claude doctor	Terminale, senza aprire una sessione	Diagnostica di sola lettura dell'installazione e delle impostazioni	No

Per la maggior parte degli utenti che vogliono che Claude ispezioni e aiuti a pulire la configurazione attiva, /doctor o /checkup è il comando pertinente.

Per script, controlli di supporto o diagnostica rapida dell'installazione al di fuori di una sessione, claude doctor è più appropriato.

Un modo sicuro per eseguire /checkup

Passo 1: Controlla lo stato attuale del repository

Prima di consentire a uno strumento di modificare i file di configurazione, assicurati che il lavoro importante sia stato salvato o sottoposto a backup.

git status

Esamina i file non tracciati ed evita di mescolare modifiche al codice non correlate con la pulizia della configurazione.

Passo 2: Avvia Claude Code nel progetto desiderato

cd /path/to/project
claude

Eseguire il checkup dal repository corretto è importante perché le istruzioni del progetto, gli hook, i plugin e le impostazioni MCP potrebbero essere con ambito limitato.

Passo 3: Esegui il checkup

/checkup

Leggi il rapporto prima di accettare le modifiche.

Passo 4: Scegli l'ambito

A seconda di ciò che Claude

se, l'interfaccia potrebbe offrire opzioni come:

• Applicare la pulizia consigliata.
• Selezionare singole categorie.
• Mantenere la configurazione attuale e generare un report.
• Discutere un consiglio prima di decidere.

Preferisci una pulizia selettiva quando il repository ha strumenti interni personalizzati o una configurazione di team condivisa.

Passaggio 5: Rivedere il Diff

Dopo che i file di configurazione sono stati modificati, esaminali:

git diff

Presta particolare attenzione a:

• CLAUDE.md e CLAUDE.local.md.
• File nella directory .claude/.
• Definizioni degli hook.
• Impostazioni dei plugin.
• Configurazione MCP.
• Regole di autorizzazione.
• Eventuali skill generate.

Passaggio 6: Testare un Flusso di Lavoro Normale

Esegui un'attività che rappresenta l'uso quotidiano. Conferma che gli strumenti necessari funzionino ancora, che le istruzioni pertinenti vengano ancora caricate, che gli hook applichino ancora regole importanti e che i prompt delle autorizzazioni si comportino come previsto.

Passaggio 7: Effettuare il Commit della Pulizia Separatamente

Quando la configurazione del progetto condiviso cambia, utilizza un commit mirato in modo che i colleghi possano rivederlo e annullarlo indipendentemente.

git add CLAUDE.md .claude/
git commit -m "chore: pulire la configurazione di Claude Code"

Modifica i percorsi in base ai file effettivamente modificati.

Quando Non Accettare Immediatamente la Pulizia Automatica

Non approvare ogni raccomandazione senza revisione quando:

• Il repository utilizza impostazioni gestite dall'organizzazione.
• I server MCP forniscono integrazioni critiche per l'azienda.
• Gli hook applicano policy di sicurezza o conformità.
• CLAUDE.md contiene duplicazioni intenzionali per la portabilità.
• Il progetto blocca Claude Code su una versione testata.
• Più team dipendono dallo stesso plugin o dalla stessa gerarchia di istruzioni.
• La pulizia propone di modificare il comportamento delle autorizzazioni.
• L'albero di lavoro contiene modifiche non committate non correlate.

In questi casi, utilizza prima il controllo come report di audit. Discuti o applica le modifiche attraverso il normale processo di revisione del team.

FAQ

Cos'è il comando /checkup di Claude Code?

/checkup è un alias per il flusso di lavoro /doctor esteso in-sessione introdotto in Claude Code 2.1.205. Controlla i problemi di configurazione e può proporre correzioni per configurazione, contesto, integrazioni, hook, salute dell'installazione e problemi correlati.

/checkup è diverso da /doctor?

Nelle versioni attuali di Claude Code, /checkup è un alias per /doctor. Invocano lo stesso controllo completo della configurazione all'interno di una sessione interattiva di Claude Code.

claude doctor è uguale a /doctor?

No. claude doctor viene eseguito dal terminale e stampa diagnostiche di installazione e impostazioni in sola lettura senza aprire una sessione. Il comando slash può coordinare le correzioni dopo aver chiesto l'approvazione.

/checkup può eliminare automaticamente skill o server MCP?

Il flusso di lavoro può identificare componenti inutilizzati e proporre una pulizia, ma è progettato per chiedere prima di apportare modifiche. Gli utenti dovrebbero rivedere ogni rimozione proposta, specialmente in progetti condivisi o gestiti.

Perché un CLAUDE.md grande influisce su Claude Code?

Le istruzioni in CLAUDE.md entrano nel contesto della sessione, quindi file lunghi o duplicati consumano spazio che altrimenti potrebbe essere utilizzato per l'attività attiva. Anthropic raccomanda istruzioni concise e file con ambito limitato per progetti grandi.

Ogni procedura dovrebbe essere spostata fuori da CLAUDE.md?

No. Le istruzioni

I fatti del progetto, le regole di codifica e i comandi richiesti appartengono a CLAUDE.md. Le procedure lunghe e riutilizzabili sono spesso più adatte alle skill, poiché il loro contenuto completo viene caricato solo quando necessario.

/checkup rende la modalità automatica completamente sicura?

No. Può migliorare le impostazioni predefinite e aggiungere protezioni, ma gli utenti rimangono responsabili della revisione dei comandi e delle autorizzazioni. Le operazioni distruttive, le scritture esterne, l'accesso alla produzione e la gestione delle credenziali richiedono ancora controlli attenti.

Con quale frequenza dovrei eseguire il checkup di configurazione?

Non esiste una pianificazione obbligatoria. È utile dopo modifiche importanti alla configurazione, quando Claude Code sembra più lento o meno coerente, dopo aver aggiunto diverse integrazioni o come parte di una revisione periodica della manutenzione del progetto.

Strumenti correlati

• Claude Code: Lo strumento di codifica agentico di Anthropic per terminali, IDE, desktop e web.
• Claude Code Skills: Crea procedure riutilizzabili e su richiesta che estendono Claude Code.
• Model Context Protocol in Claude Code: Collega Claude Code a strumenti esterni, API, database e servizi.
• Claude Code Hooks: Esegui automazione deterministica in punti definiti del ciclo di vita dell'agente.
• Claude Code Plugins: Impacchetta e distribuisci skill, agenti, hook e integrazioni MCP.
• Claude Agent SDK: Crea agenti programmabili con gli stessi strumenti principali e ciclo dell'agente utilizzati da Claude Code.

Link correlati

• Claude Code Changelog: Cronologia ufficiale delle versioni, incluse le modifiche di setup-checkup della versione 2.1.205.
• Claude Code Commands Reference: Riferimento per i comandi slash integrati e le skill incluse.
• Claude Code CLI Reference: Riferimento ufficiale per i comandi del terminale e i flag CLI.
• How Claude Remembers a Project: Guida per strutturare e mantenere i file CLAUDE.md.
• Claude Code Security: Comportamento delle autorizzazioni, sandboxing, controlli di approvazione e linee guida sulla sicurezza.
• Claude Code Settings: Ambiti di configurazione, impostazioni gestite, plugin, policy MCP e controlli del filesystem.
• Claude Code Troubleshooting: Guida ufficiale alla diagnostica e al ripristino.
• Automate Actions with Hooks: Guida pratica per creare e verificare gli hook del ciclo di vita.

Riepilogo

Claude Code 2.1.205 trasforma /doctor in un flusso di lavoro più ampio per la manutenzione della configurazione e aggiunge /checkup come alias. Il comando può ispezionare estensioni inutilizzate, istruzioni duplicate, file CLAUDE.md eccessivamente grandi, hook lenti, problemi di installazione,

e un comportamento di autorizzazione ripetitivo.

La parte più utile dell'aggiornamento non è che nasconde la manutenzione dietro un singolo comando, ma che il flusso di lavoro può spiegare le modifiche proposte e mantenere l'utente coinvolto prima di modificare l'ambiente.

La versione rafforza anche un pattern importante per gli strumenti agentici: il lavoro di sola lettura di routine dovrebbe richiedere meno attriti, mentre le operazioni incerte o distruttive dovrebbero ricevere garanzie più solide.

Una configurazione più sana di Claude Code non è quella con più skill, hook e integrazioni, ma quella in cui ogni componente caricato ha uno scopo chiaro e ogni azione potente ha un limite appropriato.