2
HenriqueFernandes
2 min de leitura ·

5 armadilhas de configuração do Claude Code (e o que a documentação diz)

Depois de montar o Claude Code em vários projetos, estas são as cinco armadilhas de configuração que mais vejo, com o que a documentação oficial diz sobre cada uma (conferido em 27/10/2026).

1. Hook de segurança que sai com exit 1 não bloqueia nada

Para o Claude Code, só o código de saída 2 bloqueia: o que o hook escreve no stderr vira o motivo, e o Claude ajusta o plano. Qualquer outro código, inclusive 1, vira erro não bloqueante, e a ação acontece. Se o seu hook de "nunca rode isso" sai com 1, ele só avisa.

2. "Nunca leia o .env" no CLAUDE.md é pedido, não regra

O CLAUDE.md é contexto. Quem impõe o bloqueio é uma regra deny no .claude/settings.json, por exemplo "Read(./.env)". Mesmo assim, ela não pega um script que abre o arquivo sozinho, e por isso segredo continua morando em variável de ambiente.

3. O .claudeignore não tem efeito

A documentação diz isso com todas as letras. Para tirar arquivos do alcance do Claude, use regras Read(...) no deny.

4. Em claude -p não existe o diálogo de confiança da pasta

No modo não interativo, os hooks do projeto rodam e os servidores do .mcp.json conectam sem perguntar. Antes de rodar -p no repositório de um cliente, leia o .claude/settings.json, o .mcp.json e as skills. Ou rode com --bare ou --setting-sources user.

5. Revisor "somente leitura" com Bash não é somente leitura

Tirar Edit e Write do campo tools de um subagente faz o Claude Code remover essas ferramentas dele. Mas, se o revisor mantiver o Bash, um comando de shell ainda altera arquivos, e o subagente herda o modo de permissão da sessão.

Fontes

Transparência: eu escrevi um guia pago em português com isso e com o resto da configuração (CLAUDE.md, permissões, subagentes, skills, hooks, MCP e automação com claude -p), com um pacote de templates comentados. É produto independente, sem vínculo com a Anthropic: https://go.hotmart.com/V108208708E

Carregando publicação patrocinada...
1
1

Sobre o 1, tem um caso parecido que pega bastante gente: o hook que nem consegue rodar. Se o script não existe, falta o jq na máquina ou estoura o timeout, por padrão isso também vira erro não bloqueante e a ação passa. Dá pra colocar "onFailure": "block" no hook, aí falha e timeout num PreToolUse bloqueiam igual ao exit 2.

E no 2, a regra Read(./.env) pega um pouco mais do que as ferramentas de arquivo. A doc de permissões diz que ela também vale pra cat, head, tail e redirecionamento no Bash. O que escapa é um grep -r rodado na pasta e script que abre o arquivo por conta própria, como você falou, e pra esses só o sandbox resolve.

1

Ótimo complemento, obrigado! Os dois pontos batem com a documentação:

  • "onFailure": "block": nas versões recentes (a doc cita a 2.1.295 ou mais nova), faz a falha do hook bloquear a ação. Vale muito em hook de política, justamente para script ausente, dependência faltando ou timeout não deixarem passar. Só confira a versão antes, porque em versão antiga o campo não existe.
  • Read(./.env) no deny: sim, a página de permissões diz que ele também pega cat, head, tail e redirecionamento no Bash. O que escapa é grep -r e script que abre o arquivo por conta própria. Para esses, sandbox, e o segredo fora do repositório.
1

verdade, a ressalva da versão é importante. em versão antiga o campo provavelmente só é ignorado sem erro nenhum, aí a pessoa acha que tá protegida e não tá.