Cinco regras que o Claude Code não pode pular
Demos ao Claude Code funcionalidades reais na nossa própria API de faturas em TypeScript e o flagramos copiando um validador em vez de reutilizá-lo. Este artigo lista cinco regras contra a deterioração do código e, para cada uma, o hook ou a configuração do Claude Code que a impõe. A documentação da Anthropic diz que um arquivo CLAUDE.md é contexto, não configuração imposta, então uma regra escrita ali é uma frase que o modelo pesa contra a tarefa. Os mecanismos abaixo são arquivos que o harness executa: um bloqueador de duplicação que dispara logo depois de uma edição, um turno que não termina enquanto os testes estão vermelhos e portões de configuração que o agente não pode tocar.
Uma regra que você escreve, uma verificação que o harness executa
Um hook do Claude Code é um pequeno script que o próprio Claude Code executa em um momento fixo, antes ou depois de uma chamada de ferramenta. Quando o script sai com um código de erro, o que ele imprimiu volta para o Claude como uma recusa. As boas práticas da Anthropic dividem as instruções em dois tipos: as que você escreve e o modelo lê (um prompt, um arquivo CLAUDE.md, uma skill) e as que você configura e o harness executa (um hook, uma regra deny, uma configuração gerenciada). A documentação de memória diz que o CLAUDE.md serve para diretrizes, e que o Claude pode decidir que uma diretriz não se aplica.
Testamos essa divisão em uma pequena API de faturas sem nenhuma regra escrita, pedindo ao Claude agendamentos recorrentes e uma exportação em CSV do relatório de pendências. O Claude voltou no verde: typecheck passando, todos os testes passando. Um detector de duplicação contou outra história: o parser de faturas tinha sido copiado linha por linha para o novo parser de agendamentos, e a busca de cliente do handler tinha sido copiada para o novo handler.
| Configuração | Funcionalidades | Clones exatos encontrados | Testes passando |
|---|---|---|---|
| Regras escritas como prosa no CLAUDE.md | 1 | 0 | 45 |
| Nenhuma regra escrita | 1, depois uma segunda por cima | 3, ainda 3 | 47, depois 55 |
Os clones continuaram invisíveis no relatório do Claude nas duas funcionalidades. Todo mecanismo deste artigo vive em um único arquivo de configuração dentro da pasta .claude, com um bloco de hooks e uma lista deny.
Regra um: reutilize antes de escrever
O mecanismo é um hook PostToolUse nas ferramentas Edit e Write. O script lê o caminho do arquivo editado na sua entrada, executa o jscpd na pasta de código-fonte e compara o número de clones com uma linha de base guardada no repositório, para que a duplicação antiga não bloqueie o trabalho de hoje. Quando o número sobe, o script imprime a regra e a localização do gêmeo e sai com o código 2. A referência de hooks diz que, depois que uma ferramenta rodou, o código de saída 2 mostra a mensagem ao Claude; um script que sai com 0 nunca é visto, não importa o que imprima.
No replay da funcionalidade de agendamentos com o hook instalado, o Claude escreveu o novo handler e o hook disparou na hora, apontando a busca de cliente do handler de faturas como o gêmeo. A frase seguinte do Claude foi que a verificação agora estava nos dois handlers e que ele a moveria para o repositório de clientes como um único método chamado dos dois lugares. O detector terminou limpo e a verificação compartilhada passou a viver em um só lugar.
Os limites: o jscpd pega uma cópia exata, não um helper reescrito do zero, e um hook que roda depois da edição não pode desfazê-la. Ele devolve feedback.
Regra dois: nenhum módulo que ninguém pediu
O mecanismo é um hook PreToolUse na ferramenta Write. O script verifica uma única coisa: o caminho está dentro da pasta de código-fonte e o arquivo ainda não existe. Se sim, ele imprime uma decisão em JSON que diz ask com um motivo, e o Claude Code a transforma em um pedido de permissão. A referência de hooks dá a um hook PreToolUse quatro decisões possíveis: allow, deny, ask ou defer.
No replay, o Claude Code parou e perguntou antes de cada novo módulo da funcionalidade de agendamentos. A funcionalidade pedia um módulo de agendamento, um store e um handler, como o resto do repositório, então cada um foi aprovado. Um pedido posterior para mover os helpers de CSV para um novo módulo utils gerou o mesmo prompt, que foi recusado: o Claude Code rejeitou as duas escritas desse lote, o turno terminou sem nada escrito e o Claude não tentou de novo.
Dois limites na versão que rodamos, a 2.1.294: o prompt mostra o nome do arquivo e o motivo vai para a transcrição do Claude, não para a caixa de diálogo; e um arquivo criado por um comando de shell não é uma chamada da ferramenta Write, então escapa desse hook.
Regra três: convenções são lint, não prosa
O mecanismo é o linter do projeto, executado em cada arquivo editado por um hook. As convenções (aliases de tipo em vez de interfaces, nenhum enum, nenhum any, uma camada de domínio sem entrada nem saída) passam da prosa para a configuração do ESLint: uma regra de sintaxe restrita rejeita uma interface ou um enum com a mensagem do próprio projeto, e uma regra de imports restritos mantém o acesso a arquivos fora da pasta de domínio. Um hook PostToolUse em Edit e Write executa o ESLint no arquivo que acabou de mudar e sai com o código 2 em caso de erro, de modo que a violação chega ao Claude na linha exata.
As palavras da convenção ficam em um arquivo de regras em .claude/rules/ com um cabeçalho paths, que carrega o arquivo apenas quando o Claude toca naquela pasta. A documentação de memória diz que uma regra com escopo de caminho carrega quando o Claude lê, escreve ou edita um arquivo correspondente, e avisa que um cabeçalho que não é interpretado faz a regra carregar em todo lugar.
Quando pedimos para transformar uma união de status em enum e um type em interface, o Claude não editou nada. Disse que a refatoração quebraria as regras do próprio projeto, nomeou a configuração de lint e o hook que sinalizariam a mudança e ofereceu um objeto const no lugar. Quando pedimos uma funcionalidade de feriados que tentava uma leitura de arquivo dentro do domínio, o Claude passou a lista de fora, porque o domínio não pode fazer entrada nem saída. O hook nunca precisou disparar. Alimentado com um arquivo ruim à mão, ele devolveu os erros nas suas linhas e a recusa.
Regra quatro: pronto significa que as verificações passaram
O mecanismo é um hook Stop, um script que roda quando o Claude quer encerrar seu turno e pode responder "ainda não". O script executa o typecheck e a suíte de testes; quando algo está vermelho, imprime a saída com falha e sai com o código 2. Ele também compara o número de testes passando com uma linha de base guardada, de modo que uma suíte que parece verde porque um teste foi apagado ainda conta como vermelha. Ele verifica a flag stop_hook_active descrita na documentação, verdadeira quando o Claude já está continuando por causa do hook, e sai com 0 nesse caso para que o hook nunca entre em loop.
Fazendo o papel do desenvolvedor apressado, pedimos um renome rápido de um campo do relatório e dissemos ao Claude para não rodar os testes. O Claude fez a edição por um comando de shell, disse que a suíte agora falharia e tentou encerrar o turno. O hook executou os testes e recusou com "Rule 4: tests fail. Not done yet." seguido das asserções que falharam. A frase seguinte do Claude foi que o stop hook do projeto exige testes verdes, então ele atualizaria as expectativas desatualizadas. Os testes continuaram no lugar.
A documentação limita o loop a 8 recusas consecutivas, depois das quais o turno termina de qualquer forma. Um teste reescrito para passar não é pego; um apagado é. Uma armadilha: uma thread muito compartilhada reclamava que o Claude ignora stop hooks, e o script dela saía com 0, então o harness nunca bloqueou nada. O código que bloqueia é 2, com o motivo no canal de erro.
Regra cinco: o agente não pode afrouxar os próprios portões
Toda verificação acima tem um atalho: desligar strict na configuração do compilador, excluir o teste que falha na configuração do runner, apagar o hook do arquivo de configurações. O mecanismo é uma lista deny no bloco de permissões do arquivo de configurações, uma linha Edit(...) por arquivo: a configuração do compilador, a configuração de testes, a configuração de lint e tudo dentro da pasta .claude. A documentação de permissões diz que as regras deny são avaliadas primeiro e que uma regra allow não pode abrir uma exceção dentro de um deny.
Quando pedimos para remover o stop hook porque ele deixa tudo lento, o Claude leu as configurações e não tentou: disse que o arquivo tem uma regra deny sobre a pasta .claude, que poderia contorná-la com um comando de shell e que fazer isso passaria por cima de uma proteção que a equipe montou de propósito. Quando pedimos para desligar strict, ele recusou com base na regra escrita e rodou o typecheck com uma flag no lugar. Quando mandamos mudar mesmo assim, o Claude recorreu a um comando de shell sobre o arquivo, e o harness respondeu que a permissão para usar aquele comando tinha sido negada. A resposta do Claude foi que ele não tentou outro caminho para contornar, porque isso anularia o que colocou o bloqueio ali.
O limite também está documentado: uma regra deny não cobre um script que abre o arquivo por conta própria, e o arquivo ainda pode ser editado à mão. É justamente essa a ideia.
Qual regra instalar primeiro
Cada regra é um arquivo que você copia, não uma frase que você espera que o Claude leia. Com as regras em prosa, uma funcionalidade não quebrou nenhuma; sem nada escrito, as funcionalidades seguintes deixaram três clones exatos que permaneceram; com os mecanismos ligados, cada um recusou uma edição real.
| Se você instalar uma coisa | Por quê |
|---|---|
| O Stop hook | A maior proteção com a menor configuração |
| Depois a lista deny | Quatro linhas no arquivo de configurações |
| Nada | Em um protótipo descartável |
Quando a suíte leva minutos, mantenha a parte rápida no hook e mova o resto para o pipeline. O limite honesto vem de uma longa issue no repositório do Claude Code: um hook impõe o que uma chamada de ferramenta consegue mostrar, e saber se uma abstração é a certa continua sendo uma decisão humana. A regra prática da própria documentação: se você continua acrescentando ênfase a uma linha do CLAUDE.md e o Claude ainda a ignora, essa linha pertence a um hook.
AIDive