SpyBara
Go Premium

debug-your-config.md 2026-09-24 22:57 UTC to 2026-09-25 23:58 UTC

This page contains 1 addition and 1 deletion.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Fri 25 23:58

Depure sua configuração

Diagnostique por que CLAUDE.md, configurações, hooks, servidores MCP ou skills não estão tendo efeito. Use /context, /doctor, /hooks e /mcp para ver o que realmente foi carregado.

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:

Comando Mostra
/memory Localizações de arquivos de memória em escopos de usuário e projeto com a opção de abrir cada um em seu editor, além de acesso à pasta de memória automática e ao alternador de memória automática
/skills Skills disponíveis de fontes de projeto, usuário e plugin
/hooks Configurações de hook ativas
/mcp Servidores MCP conectados e seu status
/permissions Regras de permissão e negação resolvidas atualmente em vigor
/doctor Diagnóstico de configuração: saúde da instalação, arquivos de configurações inválidos, extensões não utilizadas, nomes de subagente duplicados no mesmo diretório e conteúdo CLAUDE.md verificado que Claude pode derivar da base de código, com correções propostas
/debug [issue] Ativa o log de depuração para a sessão e solicita que Claude diagnostique usando a saída do log e caminhos de configurações
/status Fontes de configurações ativas, incluindo se as configurações gerenciadas estão em vigor

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 do subdiretório são carregados sob demanda quando Claude lê um arquivo nesse diretório com a ferramenta Read, não no início da sessã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.

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, ele não está sendo lido: hooks vão sob a chave "hooks" em um arquivo de configurações, não em um arquivo autônomo.

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.
  • Um valor de array é um erro de schema: Claude Code mostra um aviso de erro de configurações e rejeita o arquivo de configurações do usuário, projeto ou local inteiro, claude doctor relata a falha de validação, e nenhum hook desse arquivo aparece em /hooks. Em configurações gerenciadas, Claude Code remove a chave hooks inteira do arquivo que contém o array, então nenhum dos hooks desse arquivo se aplica. As outras configurações do arquivo ainda se aplicam, e claude doctor lista a chave removida.

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 todas as personalizações desabilitadas, incluindo CLAUDE.md, skills, plugins, hooks, servidores MCP e comandos e agentes personalizados. Autenticação, seleção de modelo, ferramentas integradas e permissões funcionam normalmente. Se o problema desaparecer no modo seguro, uma dessas superfícies é a causa; use as verificações direcionadas acima para descobrir qual. 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, compare contra uma sessão que não carrega nada de sua configuração usual. Aponte CLAUDE_CONFIG_DIR para um diretório vazio para contornar tudo sob ~/.claude e inicie a partir de um diretório que não tenha pasta .claude, .mcp.json ou CLAUDE.md para que a configuração do projeto também seja ignorada.

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

A sessão limpa não tem configurações de usuário ou projeto, hooks, servidores MCP, plugins ou memória. No primeiro lançamento, espere as telas de configuração inicial, começando com seleção de tema. Se você as vir, o diretório de configuração limpa está em vigor. Lançamentos posteriores com o mesmo diretório pulam essas telas porque Claude Code salva o estado de integração lá.

  • As configurações gerenciadas ainda se aplicam se sua organização as implanta. Claude Code lê perfis MDM, política de registro e managed-settings.json de locais fora do diretório de configuração, e busca configurações gerenciadas pelo servidor novamente para a sessão limpa uma vez que tenha credenciais
  • Você será solicitado a fazer login novamente

Se o problema desaparecer aqui, a causa está em algum lugar em seus arquivos reais ~/.claude ou .claude do projeto. Reintroduza-os um de cada vez, copiando arquivos para o diretório temporário ou iniciando a partir de seu projeto, para encontrar qual. Se persistir na sessão limpa, a causa está fora de sua configuração de usuário e projeto. Execute /status para verificar se as configurações gerenciadas estão em vigor, procure por variáveis de ambiente que afetam Claude Code 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:

Sintoma Causa Correção
Hook nunca dispara matcher é um array JSON em vez de uma string Use uma única string com | para corresponder a várias ferramentas, por exemplo "Edit|Write". Consulte padrões de matcher.
Hook nunca dispara matcher usa , como separador em uma versão anterior a v2.1.191 Claude Code v2.1.191 ou posterior trata , como um separador de lista como |. Versões anteriores avaliam uma vírgula como um caractere literal, então "Edit,Write" não corresponde a nada. Use | em vez disso, ou atualize Claude Code.
Hook nunca dispara O valor de matcher está em minúsculas, por exemplo "bash" A correspondência diferencia maiúsculas de minúsculas. Os nomes das ferramentas são capitalizados: Bash, Edit, Write, Read.
Hook nunca dispara Hooks estão definidos em um arquivo autônomo em vez de em settings.json Não há arquivo de hooks autônomo para configuração de projeto ou usuário. Defina hooks sob a chave "hooks" em settings.json. Apenas plugins carregam um hooks/hooks.json separado. Consulte configuração de hook.
Permissões, hooks ou env definidos globalmente são ignorados A configuração foi adicionada a ~/.claude.json ~/.claude.json contém estado do aplicativo e alternâncias de UI. permissions, hooks e env pertencem a ~/.claude/settings.json. Estes são dois arquivos diferentes.
Um valor de settings.json parece ser ignorado A mesma chave está definida em settings.local.json settings.local.json substitui settings.json, e ambos substituem ~/.claude/settings.json. Consulte precedência de configurações.
Skill não aparece em /skills O arquivo de skill está em .claude/skills/name.md em vez de em uma pasta Use uma pasta com SKILL.md dentro: .claude/skills/name/SKILL.md.
Skill aparece em /skills mas Claude nunca o invoca Skill tem disable-model-invocation: true em seu frontmatter, ou sua descrição não corresponde a como você frasa a solicitação Verifique o badge em /skills: um rótulo "user-only" significa que Claude não o acionará por conta própria. Consulte invocação de skill.
As instruções de CLAUDE.md do subdiretório parecem ser ignoradas Os arquivos do subdiretório são carregados sob demanda, não no início da sessão Eles são carregados quando Claude lê um arquivo nesse diretório com a ferramenta Read, não no lançamento e não ao escrever ou criar arquivos lá. Consulte como os arquivos CLAUDE.md são carregados.
Subagente ignora as instruções de CLAUDE.md Os agentes Explore e Plan integrados pulam CLAUDE.md. Um subagente personalizado o carrega da mesma forma que a conversa principal, a menos que sua definição defina omitClaudeMd Para Explore ou Plan, reafirme a instrução em seu prompt de delegação. Para um subagente que define omitClaudeMd, remova o campo. Para qualquer outro subagente personalizado, coloque instruções críticas no corpo do arquivo do agente, que se torna o prompt do sistema do agente. Consulte o que é carregado na inicialização.
A lógica de limpeza nunca é executada no final da sessão Nenhum hook SessionEnd configurado Adicione um hook SessionEnd em settings.json. Consulte a lista de eventos de hook.
Servidores MCP em .mcp.json nunca são carregados O arquivo está sob .claude/, ou seus servidores estão sob uma chave servers de nível superior, como no mcp.json do VS Code, em vez de mcpServers A configuração MCP do projeto vai na raiz do repositório como .mcp.json, não dentro de .claude/, com servidores sob a chave mcpServers. Consulte configuração MCP.
Servidores MCP adicionados sob mcpServers em settings.json nunca aparecem settings.json não lê uma chave mcpServers Defina servidores de projeto em .mcp.json na raiz do repositório, ou execute claude mcp add --scope user para servidores com escopo de usuário. Consulte configuração MCP.
Servidor MCP do projeto adicionado mas não aparece O prompt de aprovação única foi descartado Servidores com escopo de projeto requerem aprovação. Execute /mcp para ver o status e aprovar.
Servidor MCP falha ao iniciar de alguns diretórios command ou args usa um caminho de arquivo relativo Use caminhos absolutos para scripts locais. Executáveis em seu PATH como npx ou uvx funcionam como estão.
Servidor MCP inicia sem variáveis de ambiente esperadas A entrada de configuração do servidor não as define, e elas não estão no ambiente que Claude Code passa para servidores stdio: seu próprio ambiente, menos as variáveis que ele remove de subprocessos Defina env por servidor dentro da entrada .mcp.json do servidor, que não depende do ambiente de lançamento ou confiança do workspace.
A regra de negação Bash(rm *) não bloqueia /bin/rm ou find -delete As regras de Bash correspondem à string de comando literal, não ao executável subjacente; consulte o que uma regra de Bash não corresponde Use um hook PreToolUse ou o sandbox para uma garantia difícil.

Para referência completa em cada superfície de configuração, consulte a página dedicada: