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, arquivos de memória, skills, ferramentas MCP e mensagens de conversa. Execute-o primeiro para confirmar se seu CLAUDE.md, regras ou descrições de skill estão presentes.
Para detalhes sobre uma categoria específica, acompanhe com o comando dedicado:
| Comando | Mostra |
|---|---|
/memory | Quais arquivos CLAUDE.md e rules foram carregados, além de entradas de auto-memória |
/skills | Skills disponíveis de fontes de projeto, usuário e plugin |
/agents | Subagentes configurados e suas configurações |
/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ósticos de configuração: chaves inválidas, erros de schema, saúde da instalação |
/status | Fontes de configurações ativas, incluindo se as configurações gerenciadas estão em vigor |
/memory, 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 /memory 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 sempre vencem 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. Execute/doctor para validar seus arquivos de configuração e expor chaves inválidas ou erros de schema. 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 vence para uma chave específica, consulte Como os escopos interagem.
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.jsonrequerem 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 emcommandouargssã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, executeclaude --debug mcppara ver a saída stderr do servidor.
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. O campo matcher é uma única string que usa | para corresponder a vários nomes de ferramentas, por exemplo "Edit|Write". Um nome de ferramenta digitado incorretamente falha silenciosamente porque o matcher nunca corresponde. Um valor de array é um erro de schema: Claude Code mostra um aviso de erro de configurações, /doctor relata a falha de validação e a entrada do hook é descartada para que não apareça em /hooks.
As edições em settings.json entram em vigor na sessão em execução após um breve atraso de estabilidade de arquivo. Você não precisa reiniciar. 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 hooks 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.
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 | 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 em um arquivo .claude/hooks.json autônomo | Não há arquivo de hooks autônomo. Defina hooks sob a chave "hooks" em settings.json. 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 | Subagentes nem sempre herdam memória de projeto | Coloque regras críticas no corpo do arquivo do agente, que se torna o prompt do sistema do subagente. Consulte configuração de subagente. |
| A lógica de limpeza nunca é executada no final da sessão | Nenhum hook SessionEnd configurado | SessionStart e SessionEnd existem. Consulte a lista de eventos de hook. |
Servidores MCP em .mcp.json nunca são carregados | O arquivo está sob .claude/ ou usa o formato de configuração do Claude Desktop | A configuração MCP do projeto vai na raiz do repositório como .mcp.json, não dentro de .claude/. 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 | As variáveis estão em settings.json env, que não se propaga para processos filhos MCP | Defina env por servidor dentro de .mcp.json em vez disso. |
A regra de negação Bash(rm *) não bloqueia /bin/rm ou find -delete | As regras de prefixo correspondem à string de comando literal, não ao executável subjacente | Adicione padrões explícitos para cada variante, ou use um hook PreToolUse ou o sandbox para uma garantia difícil. |
Recursos relacionados
Para referência completa em cada superfície de configuração, consulte a página dedicada:- Referência do diretório
.claude: cada localização de arquivo de configuração e o que o lê - Configurações: ordem de precedência e a lista completa de chaves
- Referência de hooks: nomes de eventos, payloads e formato de saída
--debug hooks - MCP: configuração de servidor, aprovação e saída
/mcp - Troubleshooting:
claude doctor, problemas de plataforma e problemas de instalação