AIDiveTL;DR e veredito
Uma regra que você escreve no CLAUDE.md é um conselho que o Claude pondera. Uma regra transformada em comando roda, o Claude a leia ou não. Pegamos uma API de faturamento (Node 20, TypeScript, vitest) na nossa própria máquina, com o Claude Code 2.1.294, e rodamos cinco hábitos como cinco comandos.
- Pronto: com o
/goal, a resposta imprimiu a saída completa do vitest, "Tests 44 passed (44)", e o goal foi marcado como atingido após 1 turno. Sem ele, o Claude só disse "pnpm test passes (37/37)" e a saída ficou escondida numa chamada de ferramenta recolhida. - Uma regra que precisa valer: um hook PreToolUse bloqueou 2 edições no arquivo de migrations protegido, e o Claude editou o resto.
- Uma tarefa por contexto: o
/clearlevou a conversa de 26.4k tokens para 130 tokens. - Carregue o que você usa: o
/skill-doctorencontrou 52 skills carregadas e nunca invocadas (13 + 14 + 25). - Revisão com olhos novos: um revisor somente leitura achou o mesmo bug de ordem de empate que a sessão autora, mais um teste que faltava, e afirmou uma checagem de tipos limpa que não poderia ter rodado.
Veredito: configure o hook primeiro, na regra que já foi quebrada no seu repo. O /clear e o /skill-doctor não custam nada. Guarde o /goal para execuções longas e o revisor para o merge. O pack traz os arquivos.
Síntese com fontes
Uma linha do CLAUDE.md não é imposta. As boas práticas da Anthropic dizem que uma linha como Always typecheck before you finish funciona quase sempre, não sempre s1. A documentação de memória acrescenta uma meta de menos de 200 linhas por CLAUDE.md, porque arquivos maiores consomem mais contexto e reduzem a aderência s6. Nosso arquivo de teste tinha quatro regras, uma delas em maiúsculas: "NEVER edit src/store/migrations.ts".
O /goal julga o que está na tela. O avaliador não executa comandos nem lê arquivos, então a condição precisa ser algo que a própria saída do Claude consiga demonstrar s2. Por isso a nossa condição pede que a saída completa dos testes seja impressa na conversa. Um relato de campo de uma equipe com cerca de 600 PRs achou que o pior bug passou no tsc, no lint e nos testes do próprio agente s8. Uma verificação de pronto que nunca pode ser atendida entra em loop até um limite de bloqueios s9.
Um hook que sai com 2 bloqueia a chamada. No guia de hooks, sair com 2 significa bloquear a ação s3. Na nossa execução, com a regra removida do CLAUDE.md, o Claude foi atrás do arquivo de migrations duas vezes e as duas edições voltaram bloqueadas com a nossa mensagem. Com a linha em maiúsculas no lugar, o Claude recusou por conta própria, e em 2 execuções posteriores ele leu o script do hook primeiro e nunca tentou o arquivo. Uma discussão no Hacker News faz a crítica mais afiada: um bloqueio é determinístico, o que o modelo faz depois não é s10.
O /clear é de graça e esvazia a coisa certa. As boas práticas dizem que o /clear entre tarefas sem relação não custa nada s1. Depois da nossa feature, o /context mostrou 57.5k de 1m tokens, com Mensagens em 26.4k. Depois do /clear, mostrou 31.1k, com Mensagens em 130 tokens. Instruções, ferramentas e skills continuaram.
O /skill-doctor nomeia o que você nunca usa. Ele destaca as skills da listagem que nunca foram invocadas e diz onde desligá-las s7. Na nossa máquina ele relatou 13 skills carregadas mas nunca invocadas, 14 sincronizadas do claude.ai e 25 skills de plugin: 52 no total, mais 4 plugins não usados recentemente. O espaço da listagem é apertado: um texto achou que 267 caracteres a mais numa descrição transformaram outras 7 skills em nomes soltos s12. O ganho é menos ruído, não um contexto pela metade.
Um revisor novo ajuda porque não viu o seu raciocínio. As boas práticas dizem isso diretamente, e acrescentam que entregar a mesma tarefa a um subagent não melhora a resposta s1. Cada subagent começa com uma janela de contexto nova e isolada s5. Isso tem um custo: um usuário mediu cada subagent em cerca de 51k tokens no início s14, então chame-o uma vez por feature. Nosso revisor rodou 28 s em segundo plano.
Código
goal-conditions.md
# /goal conditions
The /goal judge reads only the conversation. It does not run commands or read files, so write the condition as something Claude's own output can demonstrate. Name one end state and the proof you want printed on screen.
## 1. The one we used (overdue invoices endpoint)
```
/goal GET /invoices/overdue returns the overdue invoices with page and pageSize query params, new tests cover it, and the full pnpm test output showing every test passing is printed in this conversation
```
Result on our run: the reply printed the full vitest output, then the goal was marked achieved.
## 2. Template: a bug fix
```
/goal <the failing behaviour> no longer happens, a new test reproduces it and passes, and the full <your test command> output showing every test passing is printed in this conversation
```
## 3. Template: a refactor
```
/goal <the old name or pattern> no longer appears in the code, the output of <your search command> showing no matches is printed in this conversation, and the full <your test command> output showing every test passing is printed too
```
## Rules for all three
- One end state, not a list of wishes.
- The proof is output Claude prints (test results, a search result), never "it works".
- Do not write a condition Claude cannot meet; an unsatisfiable goal loops.
- Check it with `/goal` alone; remove it with `/goal clear`.
protect-migrations.sh
#!/bin/sh
# Block edits to the append-only migrations file
path=$(jq -r '.tool_input.file_path // empty')
case "$path" in
*src/store/migrations.ts)
echo "migrations.ts is append-only: add a new migration file instead" >&2
exit 2 ;;
esac
exit 0
protect-migrations.sh on GitHub
: o script do hook. Ele lê o caminho do arquivo e sai com 2 com um motivo quando o caminho termina em `src/store/migrations.ts`. Salve como `.claude/hooks/protect-migrations.sh` e rode `chmod +x` nele. Precisa do `jq`. Troque o caminho pelo arquivo que você protege. -settings.json
{
"hooks": {
"PreToolUse": [
{ "matcher": "Edit|Write",
"hooks": [ { "type": "command", "command": ".claude/hooks/protect-migrations.sh" } ] }
]
}
}
reviewer.md
---
name: reviewer
description: Read-only code reviewer. Use it to review the current git diff before a merge, against the conventions in README.md.
tools: Read, Grep, Glob, Bash(git diff:*), Bash(git status:*)
---
You review a diff you did not write. You never edit files.
1. Run `git diff` and read every changed file in full.
2. Read README.md and check the diff against each of its conventions.
3. Look for bugs: wrong edge cases, missing validation, untested branches, behaviour that breaks existing routes.
Report each finding with the file, the line, what is wrong and why it matters. Say plainly when you find nothing real. No style nits.
checklist.md
# Clear and skill-doctor checklist
After every finished task
1. Run `/context` and read what the session carries.
2. Run `/clear` before the next unrelated task.
3. Run `/context` again; the conversation should be near empty while instructions, tools and skills stay.
4. In the middle of a task, do not clear: use `/compact` with a focus instead.
Once a month
1. Run `/skill-doctor` (needs a recent Claude Code release).
2. Skills loaded but never invoked: turn them off in `/skills` (space bar cycles).
3. Skills synced from claude.ai: switch them off on the web side, deleting them locally brings them back.
4. Plugin skills: disable the plugin in the Installed tab.
5. Keep what you use rarely but still need.
Faça isto na segunda
- Abra o seu CLAUDE.md e marque cada linha que precisa valer todas as vezes, não quase sempre.
- Copie
protect-migrations.shesettings.jsonpara.claude/, aponte o caminho para o seu arquivo protegido, depois peça ao Claude para editá-lo e veja o bloqueio. - Antes da sua próxima feature, digite
/goalcom uma condição que peça a impressão da saída completa dos testes. - Quando essa tarefa terminar, rode
/context, depois/clear, depois/contextde novo. - Rode
/skill-doctore desligue o que você nunca invocou. Para as skills sincronizadas, faça isso no lado web. - Copie
reviewer.mdpara.claude/agents/e peça uma revisão do diff antes do seu próximo merge. - Rode você mesmo a checagem de tipos depois da revisão. Nosso revisor afirmou uma que não podia rodar.
Para ir além
Deixamos estes de fora.
- Auditoria de prompt.
/doctor prompt-audite o argumento "regra mais alta, arquivo mais longo". Confira a referência de comandos para a versão mínima s4. - Skills que nunca disparam. Isso é sobre descrições, não sobre o que carrega. O texto da primeline é o lugar para começar s12.
- Poda de MCP. Um artigo mediu 12 servidores MCP em 5.8k tokens com tool search e 63k sem, então importa menos do que antes s13.
- CLAUDE.md maiores. Um post reduziu 455,530 caracteres para 88,584 em nove arquivos, e nota que os imports
@pathcarregam de forma ansiosa enquanto links simples carregam sob demanda s11. /batch. Para refatorações grandes, a referência de comandos lista de 5 a 30 unidades, um worktree cada s4. Não o rodamos.- Limiares manuais de
/compact. Não achamos fonte para uma porcentagem fixa, então não damos nenhuma.
FAQ
O /goal substitui rodar os testes eu mesmo?
Não. O juiz só lê a conversa. Ele confere que a saída foi mostrada, não que ela é verdadeira.
O hook impede o Claude de tentar a edição? Não. Ele impede a edição quando o Claude tenta. Na nossa execução, o Claude foi atrás do arquivo duas vezes sem uma regra no CLAUDE.md, e as duas edições foram bloqueadas.
Devo apagar as regras do meu CLAUDE.md depois que tiver um hook? Não. Com a linha em maiúsculas, o Claude recusou a edição por conta própria, o que poupa uma chamada bloqueada. Guarde-a para o que o Claude não consegue deduzir do seu código.
Por que não usar o revisor em toda edição? Cada subagent começa com seu próprio contexto completo, então custa tokens de verdade. Use-o uma vez por feature, antes do merge.
O /skill-doctor vai rodar na minha versão?
Ele depende de uma feature flag e de uma versão recente da referência de comandos s4. Na 2.1.294 ele rodou na nossa máquina, mas atualize o Claude Code primeiro se o seu não rodar.