Skip to main content
Quando Claude ignora uma instrução ou um recurso que você configurou não aparece, a causa geralmente é que o arquivo não foi carregado, foi carregado de um local diferente do esperado, ou outro arquivo o sobrescreveu. Este guia mostra como inspecionar o que Claude Code realmente carregou para que você possa estreitar qual se aplica. Para problemas de instalação, autenticação e conectividade, consulte Troubleshooting installation and login em vez disso.

​
Veja o que foi carregado no contexto

O comando /context mostra tudo que ocupa a janela de contexto para a sessão atual, dividido por categoria: prompt do sistema, ferramentas do sistema, ferramentas MCP, subagentes personalizados com a fonte de cada um carregado, arquivos de memória, skills e mensagens de conversa. Execute-o primeiro para confirmar se seu CLAUDE.md, regras ou descrições de skill estão presentes. A seção de skills em /context também inclui skills agrupadas, que /skills não lista. Para detalhes sobre uma categoria específica, acompanhe com o comando dedicado: Se um arquivo de memória estiver faltando na divisão /context, verifique sua localização em relação a como os arquivos CLAUDE.md são carregados. Os arquivos CLAUDE.md de subdiretórios são carregados sob demanda, e não no início da sessão, portanto não aparecem nessa divisão. Se /context confirmar que o arquivo foi carregado mas Claude ainda não está seguindo uma instrução particular, o problema provavelmente é como a instrução é escrita e não se foi carregada. CLAUDE.md funciona bem para o tipo de orientação que você daria a um novo colega de equipe, como convenções de projeto, comandos de compilação e onde os arquivos pertencem. A aderência diminui quando uma instrução é vaga o suficiente para ser interpretada de várias maneiras, quando dois arquivos dão direções conflitantes, ou quando o arquivo cresceu o suficiente para que regras individuais recebam menos atenção. Escreva instruções eficazes cobre os padrões de especificidade, tamanho e estrutura que mantêm a aderência alta.
CLAUDE.md e permissões resolvem problemas diferentes. CLAUDE.md diz a Claude como seu projeto funciona para que ele tome boas decisões. Permissões e hooks aplicam limites independentemente do que Claude decide. Use CLAUDE.md para “fazemos assim aqui”. Use permissões ou hooks para limites de segurança e qualquer coisa que nunca deve acontecer, onde você precisa de uma garantia em vez de orientação.

​
Verifique as configurações resolvidas

As configurações se mesclam entre escopos gerenciados, de usuário, de projeto e locais. As configurações gerenciadas se aplicam primeiro quando presentes. Entre o resto, o escopo mais próximo substitui o mais amplo na ordem local, depois projeto, depois usuário. Algumas configurações também podem ser definidas por sinalizadores de linha de comando ou variáveis de ambiente, que atuam como outra camada de substituição. Quando uma configuração não parece se aplicar, o valor que você definiu geralmente está sendo substituído por outro escopo ou uma variável de ambiente. Para encontrar arquivos de configurações inválidos, execute claude doctor do seu terminal. Ele imprime diagnósticos de instalação e configurações somente leitura sem iniciar uma sessão. Para uma verificação completa que também propõe correções e pede confirmação antes de aplicá-las, execute /doctor dentro de uma sessão. Execute /status para ver quais fontes de configurações estão ativas, incluindo se as configurações gerenciadas estão em vigor. Para entender qual escopo Claude Code usa para uma chave específica, consulte Precedência de configurações.

​
Verifique os servidores MCP

Execute /mcp para ver cada servidor configurado, seu status de conexão e se você o aprovou para o projeto atual. Um servidor pode ser definido corretamente mas ainda não fornecer ferramentas por alguns motivos comuns:
  • Servidores com escopo de projeto em .mcp.json requerem uma aprovação única. Se o prompt foi descartado, o servidor permanece desabilitado até que você o aprove em /mcp.
  • Um servidor que falha ao iniciar aparece como falho em /mcp. Caminhos de arquivo relativos em command ou args são uma causa frequente, pois são resolvidos em relação ao diretório de onde você iniciou Claude Code em vez da localização de .mcp.json.
  • Um servidor que aparece como conectado mas lista zero ferramentas iniciou com sucesso mas não está retornando uma lista de ferramentas. Selecione Reconnect em /mcp. Se a contagem permanecer em zero, execute claude --debug=mcp e leia a saída stderr do servidor no log de depuração em ~/.claude/debug/<session-id>.txt.
Para localizações de configuração e regras de escopo, consulte MCP.

​
Verifique hooks

Execute /hooks para listar cada hook registrado para a sessão atual, agrupado por evento. Se um hook que você definiu não aparecer, Claude Code não o carregou. Verifique estas causas:
  • O hook está definido em um arquivo autônomo. Hooks vão sob a chave "hooks" em um arquivo de configurações.
  • O valor de matcher é um array em vez de uma única string. Claude Code lista a entrada como uma configuração inválida quando você inicia uma sessão interativa e em claude doctor. Se o array estiver sob PreToolUse ou PermissionRequest, nenhum dos outros hooks desse arquivo é carregado também.
Se o hook aparecer mas não disparar, o matcher é a causa usual. Verifique-o para estes erros:
  • O campo matcher é uma única string que usa | para corresponder a vários nomes de ferramentas, por exemplo "Edit|Write". Um separador , é equivalente, então "Edit,Write" corresponde às mesmas ferramentas. Antes da v2.1.191, uma vírgula passava para avaliação de regex e o matcher nunca correspondia, então use | se você não estiver na v2.1.191 ainda.
  • Um nome de ferramenta digitado incorretamente produz um matcher que não corresponde a nada, então o hook falha silenciosamente.
Quando você edita settings.json, a alteração entra em vigor na sessão em execução após um breve atraso de estabilidade de arquivo, mesmo que você crie o arquivo ou a pasta .claude/ do projeto após a sessão ter iniciado. Você não precisa reiniciar. Antes da v2.1.257, Claude Code não detectava edições em uma pasta .claude/ criada após a sessão ter iniciado. Se /hooks ainda mostrar a definição antiga alguns segundos após salvar, execute /hooks novamente para atualizar a visualização. Se /hooks mostrar o hook mas ele ainda não disparar, o próximo passo é observar a avaliação do hook ao vivo. Inicie uma sessão com claude --debug e dispare a chamada de ferramenta. O log de depuração registra cada evento, quais matchers foram verificados, e o código de saída e saída do hook. Consulte Debug hooks para o formato do log e troubleshooting de hooks para padrões de falha comuns.

​
Teste contra uma configuração limpa

Comece com claude --safe-mode, que inicia uma sessão com suas personalizações desabilitadas, incluindo:
  • CLAUDE.md
  • Skills, plugins e hooks
  • Servidores MCP
  • Comandos e agentes personalizados
  • Estilos de saída personalizados
  • Atalhos de teclado personalizados
Autenticação, seleção de modelo, ferramentas integradas e permissões funcionam normalmente. Se o problema desaparecer no modo seguro, você reduziu a causa a um dos itens que desativou. Para encontrá-lo, use a verificação correspondente a esse item, como Veja o que foi carregado no contexto, Verifique os servidores MCP ou Verifique os hooks. O modo seguro ainda aplica hooks gerenciados e política de configurações da sua organização. Plugins gerenciados, skills, CLAUDE.md e servidores MCP são desativados. Se o problema persistir no modo seguro, ou suas configurações em si forem suspeitas, inicie uma sessão sem nenhuma configuração própria e verifique se o problema continua.
1

Crie um diretório vazio e entre nele

No seu shell, sem nenhuma sessão do Claude Code em execução, crie o diretório e entre nele:
2

Inicie o Claude Code com um diretório de configuração limpo

No mesmo shell, defina CLAUDE_CONFIG_DIR como um diretório novo no lugar de ~/.claude e passe --setting-sources user para desativar a configuração do projeto, como .claude/settings.json, CLAUDE.md e .mcp.json:
A variável se aplica apenas a este lançamento.
No primeiro lançamento, você passa novamente pelas telas de configuração inicial, um sinal de que o diretório de configuração limpo está em vigor. As configurações gerenciadas ainda se aplicam, e os conectores ainda são carregados se você fizer login com uma conta claude.ai.
3

Reproduza o problema

Repita o que desencadeou o problema na sessão limpa:
  • Problema desapareceu: a causa está na sua configuração de usuário ou de projeto. Copie ~/.claude.json e os arquivos em ~/.claude para ~/claude-clean/config, um de cada vez. Se nenhum deles trouxer o problema de volta, vá para o diretório do seu projeto no mesmo shell e inicie o Claude Code sem --setting-sources user. No Bash ou Zsh, execute CLAUDE_CONFIG_DIR=~/claude-clean/config claude. No PowerShell, a variável ainda está definida, então execute claude.
  • Problema persiste: a causa está fora da sua configuração de usuário e de projeto. Execute /status na sessão para verificar as configurações gerenciadas, verifique seu shell em busca de variáveis de ambiente e consulte Solução de problemas.

​
Verifique as causas comuns

A maioria das surpresas de configuração rastreia um pequeno conjunto de regras de localização e sintaxe. Verifique estas antes de assumir um bug: Para referência completa em cada superfície de configuração, consulte a página dedicada: