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

Depois de montar o Claude Code para vários projetos, estas são as cinco armadilhas que mais aparecem, com o que a documentação oficial diz sobre cada uma.

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.

---

Tudo isso foi conferido na documentação oficial do Claude Code em 27/10/2026. O Claude Code muda com frequência: confira a versão que você usa. Texto independente, sem vínculo com a Anthropic.

Fontes

• Claude Code Docs: Hooks reference (exit 2 bloqueia; outros códigos não)
• Claude Code Docs: Permissions (regras deny, .claudeignore sem efeito, confiança da pasta e -p)
• Claude Code Docs: Subagents (campo tools)
• Claude Code Docs: Headless (--bare)