CLAUDE.md, hooks e permissões: como o Claude Code decide o que pode fazer

O Claude Code decide o que fazer em duas camadas diferentes: CLAUDE.md molda o comportamento, e permissões — allow, deny, hooks — decidem o que ele tem autorização de executar. Confundir as duas é o erro mais comum de quem configura o Claude Code pela primeira vez.

CLAUDE.md não é permissão — é contexto

CLAUDE.md existe em camadas: um arquivo de usuário (vale para todos os projetos), um de projeto (compartilhado, versionado no git) e um CLAUDE.local.md pessoal, que fica fora do controle de versão. O que você escreve ali molda o que o Claude tenta fazer — mas é uma instrução em linguagem natural, e instrução em linguagem natural pode ser esquecida no meio de uma conversa longa ou perder para um pedido mais recente.

Por isso escrever "nunca rode DROP TABLE em produção" no CLAUDE.md é um bom hábito, mas não é uma garantia. Ele guia o comportamento na maioria das vezes; não impõe nada no nível de execução.

Deny sempre vence allow — sem exceção de especificidade

As permissões seguem escopos parecidos com o CLAUDE.md, mas com uma regra fixa que não tem exceção: quando uma regra de deny e uma de allow se aplicam à mesma chamada, o deny vence — não importa de qual escopo cada uma vem, nem qual das duas é mais específica.

Isso derruba uma intuição comum: um allow bem específico, como permitir só `git push origin main`, não escapa de um deny mais genérico, como bloquear `git push *`. A hierarquia é fixa de propósito, para que uma restrição de segurança não possa ser contornada por um allow mais fino escrito em outro lugar.

Hooks são a única camada de fato determinística

Um hook PreToolUse roda antes de a ferramenta ser executada e pode bloquear a chamada de verdade, independentemente do que o modelo decidiu fazer. É a diferença entre pedir para o Claude evitar algo e impedir que aconteça.

PostToolUse já roda depois: útil para reagir a um resultado, como rodar o linter após uma edição, mas inútil como barreira — no momento em que ele dispara, o comando destrutivo já rodou. Escolher o hook errado para o objetivo é o erro mais comum: quem quer bloquear precisa de PreToolUse; quem quer reagir usa PostToolUse.

Onde configurar o quê

Uma preferência pessoal, que não faz sentido impor ao time, vai no CLAUDE.local.md, fora do controle de versão. Uma regra que todo o time precisa seguir, e que não pode ser silenciosamente ignorada por um desenvolvedor, vai no CLAUDE.md de projeto ou num hook versionado — porque só o que está no repositório é compartilhado por construção.

A pergunta que decide onde algo mora não é "isso é importante?" — é "isso precisa valer para todo mundo, mesmo que ninguém lembre de configurar de novo?". Se sim, é hook ou CLAUDE.md de projeto. Se é só a sua preferência, é local.

Além de perguntar a cada vez: os modos de permissão

Perguntar antes de cada edição não é o único jeito de operar. O modo `acceptEdits` deixa o Claude escrever e editar arquivos sem confirmar um por um; o modo `plan` bloqueia toda escrita durante a sessão, útil quando você só quer que ele explore e proponha, sem executar nada. Cada modo troca segurança por velocidade de um jeito diferente — a escolha certa depende de quanto você já confia na tarefa que está sendo automatizada, não de uma preferência fixa.

Isso é configuração de sessão, então vale só enquanto a sessão dura — não substitui um deny permanente nem um hook. Um modo mais permissivo é uma escolha consciente para uma tarefa específica, não um jeito de contornar uma regra que deveria continuar fixa.