Resumo e veredito
Demos ao Claude Code funcionalidades reais na nossa própria pequena API de faturas em TypeScript (Claude Code 2.1.294, Opus 5.5, modo auto) e conferimos o resultado com um detector de copia e cola, typecheck e testes. Depois instalamos um mecanismo por regra: um hook ou uma configuração, não uma linha no CLAUDE.md.
- Com as cinco regras escritas como prosa no CLAUDE.md, a funcionalidade A (notas de crédito) não quebrou nenhuma: 0 clones, 45 testes passando (34 da linha de base mais 11), nenhum teste foi apagado e nenhuma configuração foi tocada.
- Sem nenhuma regra escrita, a funcionalidade B1 (agendamentos recorrentes e uma exportação em CSV) deixou 3 clones exatos. O parser do corpo da fatura foi copiado para o parser de agendamentos, e o boilerplate de busca de um handler foi copiado para um segundo handler. O typecheck estava verde e 47 testes passaram. Uma segunda passada, B2, deixou os 3 clones no lugar.
- Com os mecanismos instalados, repetimos os mesmos prompts. O hook de clones disparou no handler de agendamentos (o jscpd achou 1 clone, linha de base 0) e o Claude moveu a verificação compartilhada para um único método. O hook de arquivo novo gerou três pedidos de permissão para os módulos de agendamento, respondidos com sim, e um para um arquivo utils, respondido com não, e nada foi escrito. No prompt de enum e interface, o Claude não editou nada e nomeou a configuração de lint e o hook. O stop hook recusou um renome feito por um comando de shell com "Rule 4: tests fail. Not done yet." e o Claude corrigiu as duas expectativas. Um comando de shell sobre o tsconfig.json foi negado pelo harness.
- Cada mecanismo também recebeu uma edição ruim feita à mão: o clone, as violações de lint, o build vermelho e o teste apagado foram todos recusados.
Veredito: instale o stop hook primeiro, depois a lista deny, que é curta. Pule tudo isso em um protótipo descartável. Um hook impõe o que uma chamada de ferramenta consegue mostrar. Saber se uma abstração é a certa continua sendo uma decisão sua.
Síntese com fontes
O CLAUDE.md é contexto, não configuração imposta. A documentação de memória do Claude Code diz que o CLAUDE.md e as regras são carregados como contexto, não como configuração imposta s2. A página de boas práticas diz o mesmo pelo outro lado: o CLAUDE.md serve para diretrizes, e o Claude pode decidir que uma não se aplica. O comportamento obrigatório pertence a um hook, uma regra deny ou uma configuração gerenciada s1.
Isso dá dois tipos de instrução. No primeiro tipo, você escreve uma linha e o modelo a lê: um prompt, o CLAUDE.md, uma skill. No segundo tipo, você configura uma verificação e o harness a executa: um hook, uma regra deny, uma configuração gerenciada s1. As cinco regras deste pacote são todas do segundo tipo.
O exit 2 faz algo diferente em cada evento de hook. No PostToolUse, o exit 2 mostra o stderr ao Claude embora a ferramenta já tenha rodado s3. Um aviso de PostToolUse precisa sair com exit 2 para chegar ao Claude, porque o stderr de um hook que sai com 0 nunca é visto s3. No PreToolUse, o exit 2 bloqueia a chamada mesmo que o hook tenha impresso uma decisão allow s3. No Stop, o exit 2 bloqueia a parada, e tudo o que o comando imprime no stderr volta para o Claude como o motivo pelo qual ele ainda não pode terminar s1.
Um Stop hook precisa de uma guarda e tem um limite. Os Stop hooks recebem stop_hook_active, que é verdadeiro quando o Claude já está continuando por causa de um stop hook, então você o verifica para evitar bloquear por uma condição que nunca vai se resolver s3. A guarda documentada sai com 0 quando ele é verdadeiro s18. O Claude Code também aplica um limite de 8 continuações consecutivas, elevado com CLAUDE_CODE_STOP_HOOK_BLOCK_CAP s3. O changelog da 2.1.143 diz que o turno agora termina com um aviso depois de 8 bloqueios consecutivos s19.
O PreToolUse tem quatro decisões. Um hook PreToolUse devolve sua decisão em hookSpecificOutput com quatro resultados: allow, deny, ask ou defer s3. O hook de arquivo novo deste pacote responde ask, o que traz você de volta ao loop como um pedido de permissão. Um hook PreToolUse que estoura o tempo não bloqueia a chamada. Desde a 2.1.295 você pode definir onFailure: "block" para fazê-lo bloquear s3 s19.
O matcher tem um ponto cego. O matcher Edit|Write dispara apenas nas ferramentas Edit e Write, não no Bash s18. As edições feitas pelo Bash podem chegar a um hook PostToolUse em tool_response.bashEditDiff a partir da 2.1.269, atrás da configuração bashEditDiffEnabled s3 s19.
Regras deny: use Edit(path) e conheça o limite. Uma regra deny Write(path) não corresponde. Use Edit(path), que cobre todas as ferramentas internas de edição de arquivos s4. As regras deny também não cobrem um script Python ou Node que abre o arquivo por conta própria s4.
Regras com escopo de caminho e a armadilha do frontmatter. Uma regra com escopo de caminho carrega quando o Claude usa Read, Write ou Edit em um arquivo correspondente s2. Antes da 2.1.288, só o Read as carregava s19. Se o YAML entre os marcadores não for interpretado, o Claude Code ignora o frontmatter e carrega a regra como se não tivesse paths, então ela vale em todo lugar s2.
O jscpd pega só clones exatos. Executado como npx jscpd ., ele varre em busca de clones. As execuções padrão relatam apenas clones exatos, e os clones renomeados ou quase iguais são opcionais s20. O tamanho mínimo padrão de clone é 50 tokens s20. Nosso hook reduz para 30 tokens e 4 linhas. No nosso teste, uma quase-cópia reescrita, com linhas diferentes e o mesmo comportamento, não foi pega.
Por que portões a cada edição e não um CLAUDE.md mais longo. O SlopCodeBench constatou que o melhor agente passa em 14,8% dos checkpoints. Isso é uma taxa de aprovação, não uma fatia de lixo. A erosão estrutural sobe em 77% das trajetórias e a verbosidade em 75,5% s6. O código de agente é 2,3x mais verboso e 2,0x mais erodido do que 473 repositórios Python de código aberto s6. Uma orientação explícita de qualidade reduz a verbosidade e a erosão iniciais em até um terço, sem afetar as taxas de degradação s6. A orientação ajuda no começo. Um portão em cada edição age sobre a inclinação.
O stop hook que "não faz nada". Uma thread do Hacker News, "Claude is ignoring stop hooks", mostra um script que terminava em cat com exit 0. O harness nunca bloqueou nada, porque bloquear exige exit 2 com o motivo no stderr s8.
O que um hook não consegue julgar. Uma issue do Claude Code sobre regras do CLAUDE.md que não são seguidas chama os hooks PreToolUse de um paliativo parcial. Um hook impõe o que uma chamada de ferramenta consegue mostrar. "Esta é a abstração certa?" não pode ser decidido por um hook, e se você desativa o hook o comportamento volta s7.
Código
Nota de instalação: o settings.json vai para .claude/settings.json, os quatro scripts de hook para .claude/hooks/, o domain.md para .claude/rules/domain.md e o eslint.config.js para a raiz do repositório. Adicione eslint, typescript-eslint e jscpd como devDependencies. Crie dois arquivos de linha de base: .claude/jscpd-baseline (o número de clones) e .claude/test-baseline (o número de testes passando). Os hooks usam jq, e o stop hook chama pnpm typecheck e pnpm test, então esses scripts precisam existir no seu package.json.
O arquivo de configurações contém a lista deny da regra 5 (tsconfig.json, vitest.config.ts, eslint.config.js e .claude/**) e as entradas de hook das regras 1 a 4. Coloque-o em .claude/settings.json.
settings.json
{
"permissions": {
"deny": [
"Edit(tsconfig.json)",
"Edit(vitest.config.ts)",
"Edit(eslint.config.js)",
"Edit(.claude/**)"
]
},
"hooks": {
"PreToolUse": [
{ "matcher": "Write", "hooks": [ { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/new-file-ask.sh\"", "timeout": 10 } ] }
],
"PostToolUse": [
{ "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/no-clone.sh\"", "timeout": 60 } ] },
{ "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/lint-edit.sh\"", "timeout": 60 } ] }
],
"Stop": [
{ "hooks": [ { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/done-check.sh\"", "timeout": 120 } ] }
]
}
}
Regra 1, reutilize antes de escrever. Um hook PostToolUse em Edit|Write. Ele executa o jscpd em src/ depois de cada edição em um arquivo .ts, compara o número de clones com a linha de base e sai com exit 2 com a localização do gêmeo quando o número sobe. Coloque-o em .claude/hooks/no-clone.sh.
no-clone.sh
#!/usr/bin/env bash
# PostToolUse hook (matcher: Edit|Write). Rule 1: reuse before you write.
# Runs the copy-paste detector on src/ after every edit. A clone that was not
# there at the baseline blocks with the twin's location (exit 2 -> stderr reaches Claude).
set -u
INPUT=$(cat)
FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty')
case "$FILE" in *.ts) ;; *) exit 0 ;; esac
cd "$(printf '%s' "$INPUT" | jq -r '.cwd')" || exit 0
BASE=$(cat .claude/jscpd-baseline 2>/dev/null || echo 0)
OUT=$(mktemp -d)
npx --no-install jscpd src --min-lines 4 --min-tokens 30 --reporters json --output "$OUT" --silent >/dev/null 2>&1
COUNT=$(jq '.statistics.total.clones // 0' "$OUT/jscpd-report.json" 2>/dev/null || echo 0)
if [ "$COUNT" -gt "$BASE" ]; then
echo "Rule 1 (reuse before you write): jscpd found $COUNT clone(s), baseline is $BASE. A helper you just wrote already exists:" 1>&2
jq -r '.duplicates[] | " \(.firstFile.name):\(.firstFile.start)-\(.firstFile.end) == \(.secondFile.name):\(.secondFile.start)-\(.secondFile.end)"' "$OUT/jscpd-report.json" 1>&2
echo "Import and reuse the existing one; do not keep both." 1>&2
rm -rf "$OUT"; exit 2
fi
rm -rf "$OUT"; exit 0
Regra 2, nenhum módulo que ninguém pediu. Um hook PreToolUse em Write. Quando o caminho está sob src/ e o arquivo ainda não existe, ele responde ask com um motivo, e o Claude Code mostra um pedido de permissão. Coloque-o em .claude/hooks/new-file-ask.sh.
new-file-ask.sh
#!/usr/bin/env bash
# PreToolUse hook (matcher: Write). Rule 2: no module nobody asked for.
# Creating a file that does not exist yet under src/ becomes a permission prompt:
# the human says yes or no, the model does not decide alone.
set -u
INPUT=$(cat)
FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty')
CWD=$(printf '%s' "$INPUT" | jq -r '.cwd')
case "$FILE" in "$CWD"/src/*) ;; *) exit 0 ;; esac
[ -e "$FILE" ] && exit 0
REL=${FILE#"$CWD"/}
jq -cn --arg r "Rule 2: new module under src/ ($REL). One new file needs a reason: approve only if the task asked for it, otherwise put the code in the module it belongs to." \
'{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"ask",permissionDecisionReason:$r}}'
Regra 3, convenções são lint. Um hook PostToolUse em Edit|Write que executa o ESLint no arquivo .ts editado e sai com exit 2 em qualquer erro. Ele só faz lint e nunca corrige. Coloque-o em .claude/hooks/lint-edit.sh.
lint-edit.sh
#!/usr/bin/env bash
# PostToolUse hook (matcher: Edit|Write). Rule 3: conventions are lint, not prose.
# Runs ESLint on the file that was just edited; a violation is a lint error at the
# exact line, every edit (exit 2 -> stderr reaches Claude). Lint only, never --fix.
set -u
INPUT=$(cat)
FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty')
case "$FILE" in *.ts) ;; *) exit 0 ;; esac
cd "$(printf '%s' "$INPUT" | jq -r '.cwd')" || exit 0
if ! npx --no-install eslint --no-warn-ignored "$FILE" 1>&2; then
echo "Rule 3: the conventions above are enforced by eslint.config.js; fix the file, do not change the config." 1>&2
exit 2
fi
exit 0
As regras de lint que ele executa: type em vez de interface, nenhum enum, nenhum any, nenhum import de I/O ou de store em src/domain/ e nenhum import direto de store nos handlers. Coloque o arquivo na raiz do repositório.
eslint.config.js
// Conventions as lint rules. Run on every edited file by .claude/hooks/lint-edit.sh.
import tseslint from "typescript-eslint";
export default [
{
files: ["src/**/*.ts", "test/**/*.ts"],
languageOptions: { parser: tseslint.parser },
plugins: { "@typescript-eslint": tseslint.plugin },
rules: {
"no-restricted-syntax": [
"error",
{ selector: "TSInterfaceDeclaration", message: "Use `type`, never `interface` (project convention)." },
{ selector: "TSEnumDeclaration", message: "Use a const object or a union type, never `enum` (project convention)." },
],
"@typescript-eslint/no-explicit-any": "error",
},
},
{
files: ["src/domain/**/*.ts"],
rules: { "no-restricted-imports": ["error", { patterns: [
{ group: ["node:fs", "node:http", "fs", "http"], message: "src/domain has no I/O." },
{ group: ["../store/*", "../http/*", "**/store/*", "**/http/*"], message: "src/domain imports nothing from store or http." },
] }] },
},
{
files: ["src/http/handlers/**/*.ts"],
rules: { "no-restricted-imports": ["error", { patterns: [
{ group: ["../../store/*", "**/store/*"], message: "Handlers reach the store through the app context only." },
] }] },
},
];
As palavras das convenções vivem em um arquivo de regras com escopo de caminho. Ele carrega apenas quando o Claude toca em src/domain/. Mantenha o cabeçalho YAML válido, ou a regra carrega em todo lugar. Coloque-o em .claude/rules/domain.md.
domain.md
---
paths:
- "src/domain/**"
---
# src/domain: pure functions, nothing else
- No I/O here: no `node:fs`, no `node:http`, nothing from `src/store/` or `src/http/`.
- `type`, never `interface`; const objects or union types, never `enum`; no `any`.
- Money is an integer number of cents; reuse `money.ts` (`assertCents`, `formatCents`, `sum`) instead of writing a new helper.
- One new file needs a reason the task gives. No class, factory or generic helper for one caller.
These conventions are checked by ESLint on every edit (`.claude/hooks/lint-edit.sh`).
Regra 4, pronto significa que as verificações passaram. Um Stop hook com a guarda stop_hook_active. Ele executa o typecheck e os testes, compara o número de testes passando com .claude/test-baseline e sai com exit 2 com a saída com falha enquanto algo está vermelho ou um teste sumiu. Coloque-o em .claude/hooks/done-check.sh.
done-check.sh
#!/usr/bin/env bash
# Stop hook. Rule 4: done means the checks passed.
# Refuses the end of the turn while typecheck or tests are red, or while the test
# count dropped under the baseline (a suite made green by deleting tests is red).
set -u
INPUT=$(cat)
# Guard: when Claude Code is already continuing because of this hook, let it stop.
[ "$(printf '%s' "$INPUT" | jq -r '.stop_hook_active')" = "true" ] && exit 0
cd "$(printf '%s' "$INPUT" | jq -r '.cwd')" || exit 0
# Nothing changed since the last commit: nothing to check.
[ -z "$(git status --porcelain -- src test 2>/dev/null)" ] && exit 0
LOG=$(mktemp)
if ! pnpm --silent typecheck > "$LOG" 2>&1; then
echo "Rule 4: typecheck fails. Not done yet." 1>&2; tail -30 "$LOG" 1>&2; rm -f "$LOG"; exit 2
fi
if ! pnpm --silent test > "$LOG" 2>&1; then
echo "Rule 4: tests fail. Not done yet." 1>&2; grep -v '^\s*$' "$LOG" | tail -30 1>&2; rm -f "$LOG"; exit 2
fi
BASE=$(cat .claude/test-baseline 2>/dev/null || echo 0)
COUNT=$(grep -oE 'Tests +[0-9]+ passed' "$LOG" | grep -oE '[0-9]+' | head -1)
rm -f "$LOG"
if [ -n "$COUNT" ] && [ "$COUNT" -lt "$BASE" ]; then
echo "Rule 4: $COUNT tests passed, the baseline is $BASE. A test disappeared; restore it." 1>&2; exit 2
fi
exit 0
Faça isto na segunda-feira
- Execute
claude --versione confira se você está na 2.1.288 ou mais recente, para que as regras com escopo de caminho carreguem em Write e Edit s19. - Instale
eslint,typescript-eslintejscpdcomo devDependencies, e confira se ojqestá no seu PATH. - Copie primeiro o
done-check.sh, crie.claude/test-baselinecom o seu número atual de testes passando e adicione a entrada Stop ao.claude/settings.json. - Adicione a lista
permissions.denycom linhasEdit(...)para a configuração do compilador, a configuração de testes, a configuração de lint e.claude/**. Não escreva linhasWrite(...). - Copie o
eslint.config.js, executenpx eslint srcno repositório intocado e corrija ou registre na linha de base o que aparecer antes de ligar o hook. - Execute
npx jscpd src --min-lines 4 --min-tokens 30, grave o número de clones em.claude/jscpd-baselinee depois adicioneno-clone.shenew-file-ask.sh. - Copie o
domain.mdpara.claude/rules/, adapte o caminho às suas próprias pastas e confira se o cabeçalho YAML é interpretado. - Repita o gesto para o qual cada regra foi escrita e leia a recusa. Depois edite um arquivo à mão para provar que uma regra dispara.
Medições
Nossa execução: uma pequena API de faturas em TypeScript com 34 testes, Claude Code 2.1.294, Opus 5.5, modo auto, 2026-11-07. Clones contados com o jscpd em --min-lines 4 --min-tokens 30.
| Configuração | Funcionalidades pedidas | Clones achados pelo jscpd | Testes passando | O que disparou |
|---|---|---|---|---|
| Regras como prosa no CLAUDE.md | A: notas de crédito (1 min 21 s) | 0 | 45 (34 da linha de base + 11) | Nada para disparar. Nenhuma regra quebrada |
| Nenhuma regra escrita | B1: agendamentos recorrentes e exportação em CSV (2 min 27 s) | 3 | 47 (34 + 13) | Nada instalado. 3 módulos novos, 14 arquivos alterados |
| Nenhuma regra escrita | B2: endpoint de cancelamento e duas exportações em CSV (cerca de 1 min 30 s) | 3, os mesmos | 55 | Nada instalado. O Claude extraiu src/http/csv.ts e o reutilizou |
| Mecanismos ligados, replay ao vivo | B1 de novo, depois a refatoração para enum, um renome apressado, a remoção de um hook e uma mudança no tsconfig | 0 no final | 54 | Hook de clones uma vez (1 clone, linha de base 0), 3 pedidos de arquivo novo mais 1 recusado, hook de lint nunca necessário, stop hook uma vez, deny uma vez |
| Mecanismos ligados, teste mecânico | Edições ruins feitas à mão | 0 na linha de base, 1 depois de colar uma cópia de 5 linhas de formatCents |
33 de 34 depois de apagar um teste | Hook de clones, ask de arquivo novo, hook de lint (4 erros), stop hook (build vermelho, número de testes abaixo da linha de base) |
Detalhes do teste mecânico. A configuração do ESLint deu 0 problemas no repositório intocado. O lint-edit.sh em um arquivo com um import de node:fs, uma interface, um enum e um any relatou 4 erros nas suas linhas e saiu com exit 2. O hook de clones relatou domain/money.ts:21 == http/views.ts:5. Um caminho sob src/ que não existia devolveu ask com o motivo. O stop hook disse "Rule 4: 33 tests passed, the baseline is 34. A test disappeared; restore it." Uma quase-cópia reescrita não foi pega pelo jscpd.
Para ir além
O que deixamos fora das cinco, e onde cada coisa se encaixa.
Git hooks e Lefthook. Um git hook ou um portão de pipeline é um lugar válido para as mesmas verificações. Ele roda quando você faz commit, não enquanto o Claude edita, então o feedback chega mais tarde. É uma configuração diferente da deste pacote. Se a sua suíte leva minutos, mantenha a parte rápida no stop hook e mova o resto para o pipeline.
Hooks de prompt em nível de agente. Hooks que pedem a um modelo para julgar uma edição não são determinísticos, por isso não estão entre as cinco. Uma regra que você consegue verificar com um comando pertence a um script.
Comandos de revisão. /simplify e /code-review são manuais. São úteis, mas a revisão continua sendo sua, e nenhum dos dois é imposição.
Números de incidentes de fornecedores. Os relatórios de fornecedores sobre taxas de incidentes por pull request são um sinal de correlação, não específico do Claude Code e não medido no nosso código. Não os usamos. Todo número deste pacote vem das fontes linkadas acima ou da nossa própria execução.
Um conjunto de regras pronto. O repositório anti-slop é um conjunto de regras Oxlint para ser copiado, com 18 regras genéricas e 5 regras Effect. Ele foi feito para ser copiado para o projeto, sem pacote npm oficial s10. É um bom modelo de regra: um erro de lint na linha exata, a cada execução.
Regras em prosa. Coleções de regras de CLAUDE.md são úteis para as palavras de uma convenção. Mantenha-as em arquivos de regras com escopo de caminho e deixe que uma verificação carregue a garantia.
FAQ
Uma regra deny impede um script Python que escreve o arquivo? Não. As regras deny não cobrem um script Python ou Node que abre arquivos por conta própria s4. Quem tem as chaves ainda pode editar o arquivo à mão. A lista deny barra as ferramentas internas de edição do agente e os atalhos óbvios.
Por que o meu stop hook nunca bloqueia?
Verifique primeiro o código de saída. Bloquear exige exit 2 com o motivo no stderr. Um script que termina em cat com exit 0 nunca bloqueia s8. Depois verifique a guarda: se stop_hook_active for verdadeiro, o hook deve sair com 0. O limite também encerra o turno depois de 8 bloqueios consecutivos s3.
O matcher Edit|Write pega edições feitas pelo Bash?
Não. Ele dispara apenas nas ferramentas Edit e Write, não no Bash s18. Desde a 2.1.269, um diff dos arquivos que um comando Bash alterou pode ser adicionado ao resultado da ferramenta Bash atrás de bashEditDiffEnabled s19. Nosso stop hook ainda pega o resultado, porque executa o typecheck e os testes no fim do turno.
E os arquivos criados por um comando de shell?
Um arquivo criado assim não é uma chamada da ferramenta Write, então o hook de arquivo novo nunca o vê. Adicione um matcher Bash se precisar vigiar isso, ou revise o git status no fim do turno.
O hook desfaz a edição? Não. Um hook PostToolUse roda depois da ferramenta, que já rodou. Ele mostra o stderr ao Claude com exit 2 s3. Aí o Claude corrige o arquivo. Só o hook PreToolUse e a lista deny impedem uma ação antes que ela aconteça.
AIDive