Explicação do /checkup do Claude Code: Contexto Limpo, Corrigir Configuração e Melhorar a Segurança do Agente

Introdução

O Claude Code ganhou uma verificação de configuração integrada mais capaz. Na versão 2.1.205, a Anthropic expandiu o fluxo de trabalho existente /doctor para diagnosticar problemas de configuração e ajudar a corrigi-los. /checkup está disponível como um alias para o mesmo fluxo de trabalho na sessão.

A mudança pode parecer pequena porque é acionada por um único comando de barra. Na prática, ela resolve um problema comum em configurações do Claude Code de longa duração: skills não utilizadas, servidores Model Context Protocol obsoletos, arquivos de instrução muito grandes, hooks lentos, instalações desatualizadas e solicitações de permissão repetidas tornam gradualmente o ambiente mais difícil de entender.

O objetivo não é apenas relatar que algo está errado. A verificação atualizada pode inspecionar a configuração, explicar as alterações propostas e solicitar aprovação antes de aplicá-las.

/checkup

Você também pode usar o comando canônico:

/doctor

Uma Verificação de Configuração em Um Comando

De acordo com o changelog do Claude Code 2.1.205, /doctor agora é uma verificação completa de configuração que pode diagnosticar e corrigir problemas, enquanto /checkup é seu alias.

Isso é diferente do comando de terminal separado:

claude doctor

O comando de terminal imprime diagnósticos de instalação e configuração somente leitura sem iniciar uma sessão interativa. O fluxo de trabalho na sessão /doctor ou /checkup pode ir além, propondo correções e permitindo que o Claude coordene a limpeza através de suas ferramentas disponíveis.

O criador do Claude Code, Boris Cherny, descreveu várias tarefas que a verificação foi projetada para realizar:

1. Limpar skills não utilizadas, servidores MCP e plugins.
2. Desduplicar instruções locais CLAUDE.md em relação às instruções do projeto versionadas.
3. Dividir um CLAUDE.md raiz muito grande em arquivos aninhados e skills reutilizáveis.
4. Identificar e desabilitar hooks lentos.
5. Atualizar o Claude Code para a versão mais recente disponível.
6. Ativar o modo automático por padrão quando apropriado.
7. Pré-aprovar comandos de leitura frequentemente rejeitados.
8. Detectar outros problemas de configuração que tornam o ambiente mais lento ou menos confiável.

O comando solicita confirmação antes de fazer alterações.

O que a Verificação Realmente Analisa

1. Skills, Servidores MCP e Plugins Não Utilizados

O Claude Code pode ser estendido com skills, plugins, hooks e servidores MCP. Essas integrações são úteis, mas uma configuração madura frequentemente acumula componentes que não são mais

relevante.

Pode ser que um servidor MCP tenha sido adicionado para um rastreador de problemas antigo. Uma habilidade pode ter sido criada para um fluxo de trabalho que a equipe não usa mais. Um plugin pode ainda estar ativado mesmo que seus comandos tenham sido substituídos.

A verificação pode identificar esses componentes não utilizados e sugerir sua remoção ou desativação.

Isso é importante porque ferramentas e instruções podem consumir atenção e contexto mesmo quando não estão ajudando ativamente na tarefa atual. Menos integrações irrelevantes também tornam o modelo de permissão mais fácil de auditar.

2. Instruções CLAUDE.md Duplicadas ou Exageradas

Os arquivos CLAUDE.md fornecem instruções persistentes para o Claude Code. Eles podem conter comandos de compilação, convenções de codificação, notas arquiteturais, requisitos de teste e regras específicas do projeto.

Esses arquivos são carregados no contexto da sessão. A Anthropic recomenda manter cada arquivo conciso e revisar regularmente os arquivos de instruções aninhados para regras desatualizadas ou conflitantes.

Com o tempo, um projeto pode desenvolver vários problemas comuns:

• A mesma regra aparece tanto no arquivo local quanto no versionado.
• Instruções antigas permanecem após alterações na base de código.
• Um arquivo raiz cresce e se torna uma longa coleção de procedimentos não relacionados.
• Regras da equipe e regras específicas de diretório são misturadas.
• Fluxos de trabalho detalhados são armazenados em CLAUDE.md, embora funcionassem melhor como habilidades sob demanda.

A verificação pode comparar instruções locais e do projeto, identificar duplicações e sugerir uma estrutura mais focada.

Um layout prático pode ser assim:

projeto/
├── CLAUDE.md
├── .claude/
│   ├── regras/
│   │   ├── frontend.md
│   │   ├── backend.md
│   │   └── testes.md
│   └── habilidades/
│       └── release/
│           └── HABILIDADE.md
└── pacotes/
    └── api/
        └── CLAUDE.md

O arquivo raiz pode conter apenas as regras necessárias em todo o repositório. Instruções mais específicas podem ser carregadas quando Claude trabalha dentro do diretório relevante, enquanto procedimentos reutilizáveis podem se tornar habilidades que são carregadas quando invocadas.

3. Hooks Lentos ou Redundantes

Hooks são ações determinísticas que são executadas em pontos específicos do ciclo de vida do Claude Code. Eles podem formatar arquivos, validar comandos, aplicar políticas, enviar notificações ou integrar o Claude Code com sistemas internos.

Um hook é útil apenas quando seu valor justifica seu custo. Um script que adiciona dois ou três segundos a cada chamada de ferramenta pode criar um grande atraso em uma sessão longa.

A verificação pode ajudar a identificar hooks que são:

• Consistentemente lentos.
• Acionados com mais frequência do que o pretendido.
• Duplicando outra etapa de validação.
• Referenciando scripts que não existem mais.
• Produzindo erros que o usuário aprendeu a ignorar.
• Não mais conectados a um fluxo de trabalho ativo.

Desativar um hook desnecessário não apenas melhora a velocidade. Também reduz o ruído, tornando as falhas importantes mais fáceis de notar.

4. Problemas de Instalação e Atualização

Um inicializador quebrado, uma instalação desatualizada ou uma atualização parcial podem criar comportamentos confusos. A verificação de configuração pode inspecionar a integridade da instalação e recomendar a atualização do Claude Code.

Para verificar a versão instalada manualmente, use:

claude --version

O método exato de atualização depende de como o Claude Code foi instalado.

Implantações empresariais gerenciadas podem fixar intencionalmente uma versão, portanto os usuários não devem substituir a política da organização simplesmente porque existe uma versão mais recente.

5. Solicitações Repetidas de Permissão Somente Leitura

O Claude Code utiliza um sistema de permissões que separa inspeções de baixo risco de ações que modificam o ambiente.

A documentação de segurança da Anthropic afirma que um conjunto integrado de comandos somente leitura, incluindo comandos como ls, cat e git status, pode ser executado sem solicitação. Comandos que editam arquivos, executam operações Bash potencialmente modificadoras ou acessam sistemas adicionais podem exigir aprovação.

Se um usuário rejeitar ou aprovar manualmente repetidamente um comando inofensivo somente leitura, a verificação pode sugerir uma regra de permissão mais clara. O objetivo é reduzir a fadiga de solicitações sem conceder acesso amplo de escrita.

Uma boa regra de permissão deve ser restrita. Aprovar um padrão específico somente leitura é mais seguro do que permitir uma categoria inteira de shell ou ferramenta.

Por que a Manutenção do Contexto é Importante

Um agente de codificação de IA precisa encaixar vários tipos de informação em um único contexto de trabalho:

• A conversa atual.
• Arquivos de origem relevantes.
• Resultados de ferramentas e saída de comandos.
• Instruções do CLAUDE.md.
• Descrições de habilidades.
• Definições de ferramentas MCP.
• Planos, estado de tarefas e descobertas intermediárias.

A janela de contexto é finita. Uma grande quantidade de informações de configuração irrelevantes pode deixar menos espaço para o problema real.

Isso não significa que toda habilidade instalada ou servidor MCP é automaticamente carregado na íntegra. O Claude Code usa mecanismos como corpos de habilidade sob demanda e descoberta de ferramentas para controlar o uso do contexto. Ainda assim, configurações desnecessárias criam complexidade adicional e aumentam a chance de instruções desatualizadas ou integrações influenciarem uma sessão.

Uma configuração saudável, portanto, precisa do mesmo tipo de manutenção que um projeto de software:

1. Remova o que não é mais usado.
2. Mantenha as instruções globais curtas.
3. Mova procedimentos especializados para arquivos ou habilidades com escopo definido.
4. Audite integrações e permissões.
5. Meça o custo dos hooks.
6. Revise a configuração após grandes mudanças no projeto.

Do Diagnóstico à Limpeza Assistida

Ferramentas de diagnóstico anteriores frequentemente paravam após listar erros. O usuário ainda precisava entender cada aviso, encontrar o arquivo relevante, decidir sobre uma correção e aplicá-la manualmente.

A verificação atualizada na sessão segue um padrão mais agente:

1. Inspecione o ambiente atual.
2. Identifique problemas específicos.
3. Estime o benefício de uma limpeza.
4. Apresente as alterações propostas.
5. Permita que o usuário escolha entre uma limpeza completa, correções selecionadas ou uma opção apenas de relatório.
6. Aplique apenas as alterações aprovadas.
7. Deixe as modificações de arquivo visíveis para revisão.

Isso torna o fluxo de trabalho mais próximo de um assistente de manutenção interativo do que de um relatório de erros passivo.

A etapa de aprovação é importante. Uma ferramenta não deve

remover silenciosamente uma habilidade de projeto, reescrever arquivos de instrução ou alterar o comportamento de permissão simplesmente por considerar a configuração ineficiente.

Melhorias de Segurança em Comandos Autônomos

A mesma versão também incluiu alterações voltadas a reduzir riscos quando o Claude Code atua de forma mais autônoma.

Proteção Contra Aprovação Falsificada em Registros de Sessão

Notificações de tarefas em segundo plano agora declaram explicitamente quando não houve entrada humana. Isso tem como objetivo evitar que um texto dentro de uma transcrição seja confundido com uma aprovação real do usuário.

Para um agente, a diferença entre "a transcrição contém texto semelhante a uma aprovação" e "o usuário realmente aprovou esta ação através da interface" é crítica. Decisões sensíveis à segurança precisam de um canal de aprovação confiável.

Confirmação Adicional para Comandos rm -rf Arriscados

O registro de alterações também observa uma melhoria no modo automático: o Claude Code pergunta antes de executar rm -rf quando o caminho contém uma variável que ele não pode resolver a partir do contexto.

Um exemplo perigoso é:

rm -rf "$TARGET_DIR/"

Se TARGET_DIR estiver vazio ou expandido incorretamente, o resultado pode ser muito diferente do que o autor do script pretendia.

A lição correta não é que um único prompt de confirmação torne comandos destrutivos de shell seguros. Os usuários ainda devem inspecionar o caminho resolvido, usar uma sandbox ou ambiente descartável quando possível, manter backups e evitar comandos de exclusão ampla em sistemas de produção.

Autonomia Precisa de Limites

A versão combina dois objetivos que podem parecer conflitantes:

• Reduzir interrupções desnecessárias para tarefas rotineiras e somente leitura.
• Adicionar confirmação mais forte em torno de ações incertas ou destrutivas.

Esses objetivos trabalham juntos. Um agente útil deve se mover rapidamente dentro de uma área segura bem definida e desacelerar quando se aproxima de um limite com consequências irreversíveis.

/doctor, /checkup e claude doctor

Os nomes semelhantes podem ser confusos.

Comando	Onde é executado	Objetivo principal	Pode propor ou aplicar correções?
/doctor	Dentro de uma sessão do Claude Code	Verificação completa da configuração	Sim
/checkup	Dentro de uma sessão do Claude Code	Apelido para /doctor	Sim
claude doctor	Terminal, sem abrir uma sessão	Diagnóstico de instalação e configurações somente leitura	Não

Para a maioria dos usuários que desejam que o Claude inspecione e ajude a limpar a configuração ativa, /doctor ou /checkup é o comando relevante.

Para scripts, verificações de suporte ou diagnósticos rápidos de instalação fora de uma sessão, claude doctor é mais apropriado.

Uma Maneira Segura de Executar /checkup

Etapa 1: Verificar o Estado Atual do Repositório

Antes de permitir que uma ferramenta modifique arquivos de configuração, certifique-se de que o trabalho importante foi commitado ou salvo em backup.

git status

Revise os arquivos não commitados e evite misturar alterações de código não relacionadas com a limpeza de configuração.

Etapa 2: Iniciar o Claude Code no Projeto Desejado

cd /caminho/para/o/projeto
claude

Executar a verificação a partir do repositório correto é importante porque instruções, hooks, plugins e configurações MCP do projeto podem ter escopo definido.

Etapa 3: Executar a Verificação

/checkup

Leia o relatório antes de aceitar alterações.

Etapa 4: Escolher o Escopo

Dependendo do que o Claude

以下是根据要求翻译的葡萄牙语版本：

encontra, a interface pode oferecer opções como:

• Aplicar a limpeza recomendada.
• Selecionar categorias individuais.
• Manter a configuração atual e gerar um relatório.
• Discutir uma recomendação antes de decidir.

Prefira limpeza seletiva quando o repositório tiver ferramentas internas personalizadas ou configuração compartilhada da equipe.

Etapa 5: Revisar o Diff

Após a alteração dos arquivos de configuração, inspecione-os:

git diff

Preste atenção especial a:

• CLAUDE.md e CLAUDE.local.md.
• Arquivos em .claude/.
• Definições de hooks.
• Configurações de plugins.
• Configuração MCP.
• Regras de permissão.
• Quaisquer habilidades geradas.

Etapa 6: Testar um Fluxo de Trabalho Normal

Execute uma tarefa que represente o uso diário. Confirme se as ferramentas necessárias ainda funcionam, se as instruções relevantes ainda carregam, se os hooks ainda aplicam regras importantes e se os prompts de permissão se comportam conforme o esperado.

Etapa 7: Confirmar a Limpeza Separadamente

Quando a configuração compartilhada do projeto mudar, use um commit focado para que os colegas de equipe possam revisá-lo e revertê-lo de forma independente.

git add CLAUDE.md .claude/
git commit -m "chore: limpar configuração do Claude Code"

Ajuste os caminhos para corresponder aos arquivos realmente alterados.

Quando Não Aceitar a Limpeza Automática Imediatamente

Não aprove todas as recomendações sem revisão quando:

• O repositório usar configurações gerenciadas pela organização.
• Os servidores MCP fornecerem integrações críticas para os negócios.
• Os hooks aplicarem políticas de segurança ou conformidade.
• CLAUDE.md contiver duplicação intencional para portabilidade.
• O projeto fixar o Claude Code em uma versão testada.
• Várias equipes dependerem do mesmo plugin ou hierarquia de instruções.
• A limpeza propor alterar o comportamento de permissão.
• A árvore de trabalho contiver alterações não confirmadas e não relacionadas.

Nesses casos, use a verificação primeiro como um relatório de auditoria. Discuta ou aplique alterações através do processo normal de revisão da equipe.

FAQ

O que é o comando /checkup do Claude Code?

/checkup é um alias para o fluxo de trabalho expandido /doctor em sessão introduzido no Claude Code 2.1.205. Ele audita problemas de configuração e pode propor correções para configuração, contexto, integrações, hooks, integridade da instalação e problemas relacionados.

/checkup é diferente de /doctor?

Nas versões atuais do Claude Code, /checkup é um alias para /doctor. Ambos invocam a mesma verificação completa de configuração dentro de uma sessão interativa do Claude Code.

claude doctor é igual a /doctor?

Não. claude doctor é executado a partir do terminal e imprime diagnósticos de instalação e configuração somente leitura, sem abrir uma sessão. O comando de barra pode coordenar correções após solicitar aprovação.

O /checkup pode excluir habilidades ou servidores MCP automaticamente?

O fluxo de trabalho pode identificar componentes não utilizados e propor limpeza, mas é projetado para perguntar antes de fazer alterações. Os usuários devem revisar cada remoção proposta, especialmente em projetos compartilhados ou gerenciados.

Por que um CLAUDE.md grande afeta o Claude Code?

As instruções do CLAUDE.md entram no contexto da sessão, portanto arquivos longos ou duplicados consomem espaço que poderia ser usado para a tarefa ativa. A Anthropic recomenda instruções concisas e arquivos com escopo definido para projetos grandes.

Todo procedimento deve ser removido do CLAUDE.md?

Não. Procedimentos estáveis

facts do projeto, regras de codificação e comandos necessários pertencem ao CLAUDE.md. Procedimentos reutilizáveis e longos geralmente são mais adequados às habilidades, pois seu conteúdo completo é carregado apenas quando necessário.

O /checkup torna o modo automático completamente seguro?

Não. Ele pode melhorar as configurações padrão e adicionar proteções, mas os usuários continuam responsáveis por revisar comandos e permissões. Operações destrutivas, gravações externas, acesso à produção e manipulação de credenciais ainda exigem controles rigorosos.

Com que frequência devo executar a verificação de configuração?

Não há uma periodicidade obrigatória. É útil após grandes mudanças de configuração, quando o Claude Code parece mais lento ou menos consistente, após adicionar várias integrações, ou como parte de uma revisão periódica de manutenção do projeto.

Ferramentas Relacionadas

• Claude Code: A ferramenta de codificação agêntica da Anthropic para terminais, IDEs, desktop e web.
• Claude Code Skills: Crie procedimentos reutilizáveis e sob demanda que estendem o Claude Code.
• Model Context Protocol no Claude Code: Conecte o Claude Code a ferramentas externas, APIs, bancos de dados e serviços.
• Claude Code Hooks: Execute automação determinística em pontos definidos do ciclo de vida do agente.
• Claude Code Plugins: Empacote e distribua habilidades, agentes, hooks e integrações MCP.
• Claude Agent SDK: Construa agentes programáveis com as mesmas ferramentas principais e loop de agente usados pelo Claude Code.

Links Relacionados

• Claude Code Changelog: Histórico oficial de versões, incluindo as alterações de verificação de configuração da versão 2.1.205.
• Referência de Comandos do Claude Code: Referência para comandos internos de barra e habilidades agrupadas.
• Referência CLI do Claude Code: Referência oficial para comandos de terminal e flags da CLI.
• Como o Claude Lembra de um Projeto: Orientação para estruturar e manter arquivos CLAUDE.md.
• Segurança do Claude Code: Comportamento de permissões, sandboxing, controles de aprovação e orientações de segurança.
• Configurações do Claude Code: Escopos de configuração, configurações gerenciadas, plugins, políticas MCP e controles de sistema de arquivos.
• Solução de Problemas do Claude Code: Orientação oficial de diagnóstico e recuperação.
• Automatize Ações com Hooks: Orientação prática para criar e auditar hooks de ciclo de vida.

Resumo

O Claude Code 2.1.205 transforma o /doctor em um fluxo de trabalho mais amplo de manutenção de configuração e adiciona /checkup como um alias. O comando pode inspecionar extensões não utilizadas, instruções duplicadas, arquivos CLAUDE.md muito grandes, hooks lentos, problemas de instalação,

e comportamento de permissão repetitivo.

A parte mais útil da atualização não é esconder a manutenção atrás de um único comando. É que o fluxo de trabalho pode explicar as alterações propostas e manter o usuário envolvido antes de modificar o ambiente.

O lançamento também reforça um padrão importante para ferramentas de agente: tarefas rotineiras de somente leitura devem exigir menos atrito, enquanto operações incertas ou destrutivas devem receber proteções mais fortes.

Uma configuração mais saudável do Claude Code não é aquela com mais habilidades, ganchos e integrações — é aquela onde cada componente carregado tem um propósito claro e cada ação poderosa tem um limite apropriado.