Meu CLAUDE.md tem 582 linhas. Seis camadas, e a falha por trás de cada uma

Toda nova conversa do Claude Code começa do zero. Ele não conhece o projeto, não se lembra do que discutimos uma hora antes numa outra janela e não tem ideia de que uma porta em um servidor não pode ser mexida. Este post percorre o CLAUDE.md que montei para lidar com isso: seis camadas, o incidente que originou cada uma, por que um hook funciona onde uma regra escrita falha, a única configuração que manteve um pacote npm comprometido fora da minha máquina e quais partes eu manteria em um projeto comum. Em 12 de abril de 2026, quando saiu o original em russo, a configuração tinha 582 linhas.

Um CLAUDE.md deveria resolver dois problemas ao mesmo tempo: carregar o contexto entre sessões e impedir que o agente faça algo irreversível. O r/ClaudeAI tem uma história de terror nova toda semana. Um agente derrubou um banco de dados de produção. Um agente enviou segredos para um repositório público. Um agente "otimizou" um serviço de cobrança até que todo cliente recebesse uma fatura zerada. O CLAUDE.md típico, de cinco a dez linhas, não resolve nenhum dos dois problemas. Decidi tratá-lo como uma tarefa de arquitetura, e não como uma lista de desejos, e cada regra nele tem uma história específica por trás.

Três incidentes por trás das primeiras regras

O agente "consertou" um sistema que funcionava. Domingo à noite. O agente vê 127.0.0.1 na configuração de um serviço de armazenamento externo e decide que uma sessão anterior deixou um erro ali. Ele coloca o IP real. Os uploads quebram. Meia hora de depuração depois, fica claro que o tráfego passava por um proxy SNI sobre um túnel local, e 127.0.0.1 era o valor correto. Sem contexto, o conserto óbvio era o dano.

A regra que saiu disso: não altere uma configuração antes de entender por que os valores atuais são o que são. Se um valor parece estranho, entenda primeiro e aja depois.

O fail2ban tomou o agente por um brute-forcer. O agente estava verificando o estado de um servidor e abria uma nova conexão SSH para cada verificação. Uma dúzia de conexões em um minuto parecia um ataque, e o IP ficou banido por meia hora. Uma rodada de treinamento estava rodando naquela máquina na hora, e eu não conseguia mais alcançá-la.

Regra: uma única ponte SSH para tudo, um cliente por sessão e nenhum script separado para verificar, corrigir e validar. Agrupe tudo em uma única chamada.

"Filtrar" acabou significando "apagar". Pedi que um dataset fosse filtrado, querendo dizer que as imagens inadequadas fossem retiradas. O agente leu literalmente e apagou os arquivos. Não movidos, não marcados. Apagados.

Regra: filtrar significa mover ou marcar, nunca apagar. Antes de qualquer exclusão, confirme que o usuário pediu exclusão com essas palavras.

Escrever "tome cuidado" não funciona. É preciso um sistema.

Seis camadas, nenhuma planejada

Cada camada apareceu depois de uma falha específica.

Regras, 9 arquivos. Carregadas conforme a situação. Quando o agente escreve um artigo, ele não precisa das regras de SSH; quando depura código, não precisa das regras sobre prosa. O Claude Code pode trazer o arquivo de regras que corresponde à tarefa.

Memória, 78 arquivos. Apareceu quando o agente esqueceu a configuração de um servidor pela terceira vez. Entre sessões, ele agora guarda configurações de infraestrutura, decisões do projeto, minhas preferências e erros passados. Os arquivos se linkam entre si como [[filename]], 178 referências cruzadas no total, então Markdown simples vira um grafo de conhecimento. Uma parte sempre é carregada, o resto conforme o tema.

Handoffs. Apareceram quando uma conversa nova voltava direto para o beco sem saída da conversa anterior. Quando uma sessão termina, o agente escreve um resumo: o que foi feito, o que NÃO funcionou (a parte valiosa) e uma ação seguinte. Um exemplo real, traduzido do russo:

## Session goal
Colour checker: CNN sweep + diffusion, first visual results.

## Done
- CNN baseline: median 1.99 deg (11M params, 21 MB)
- Sweep on 5 GPUs: crop128 (3.17), bs16 (2.04), lr3e-4 (NaN)
- Diffusion training started: epoch 5/50, loss 0.827

## Did NOT work
- EfficientNet-B0: hash mismatch in the Docker image
- lr=3e-4: NaN after epoch 10-13, no gradient clipping
- CNN, visually: three numbers give stray colour casts

## Next step
Inference script for diffusion + visual sheets with 24 patches

A conversa seguinte lê cerca de 1.500 tokens em vez de analisar o projeto do zero. Em quatro dias se acumularam 27 handoffs, e nenhum beco sem saída foi repetido. Ele também funciona entre contas: tenho três assinaturas, duas para o trabalho e uma pessoal, e um handoff me permite continuar em outra sem explicar tudo de novo. Como isso cresceu para uma ferramenta para várias pessoas trabalhando ao mesmo tempo está em Vários Claudes num repo.

Crônicas. Apareceram quando, depois de vinte handoffs, já não estava claro como o projeto tinha chegado ao estado atual. Um handoff responde "e agora?"; uma crônica responde "como chegamos aqui". Decisões-chave, viradas e becos sem saída, de três a sete linhas por marco.

Hooks. Apareceram quando a regra "verifique os links no CLAUDE.md" deixou de ser seguida vinte minutos depois do início de uma sessão. A próxima seção trata deles.

Skills, 16. Conhecimento empacotado para trabalhos específicos. A descrição é escrita como um gatilho para o modelo, "use quando: GPU travada, é preciso checar a saúde do servidor", e não como "ajuda com servidores".

Uma regra é um desejo, um hook é uma garantia

Esta foi a coisa menos óbvia que aprendi naquele mês. Uma regra no CLAUDE.md é uma instrução dentro de um prompt. O modelo pode esquecê-la, reinterpretá-la ou deixá-la de lado no fim de uma sessão longa, quando o contexto está cheio de outras coisas. Minha regra de "verificar os links antes de trabalhar" se manteve por cerca de dez minutos, e depois o agente se absorveu na tarefa.

Um hook é um script Python que o Claude Code executa num evento: SessionStart, Stop, PreToolUse. Ele não esquece e não reinterpreta. Roda sempre. Este é o que pede um handoff antes que uma sessão longa seja encerrada:

# remind_handoff.py  (Stop hook, simplified)
age = session_age_minutes()
if age < 15:
    return                      # short session, nothing to hand off

if fresh_handoff_exists():
    return                      # already written

print(json.dumps({              # block the close, ask for the handoff
    "decision": "block",
    "reason": f"Session ran {int(age)} min with no handoff. "
              f"Write one into .claude/handoffs/ before exiting."
}))

O modelo geralmente sabe por conta própria quando é hora, quando uma tarefa terminou ou o contexto está enchendo. O hook cobre as vezes em que ele esquece.

Se algo precisa acontecer toda vez, é um hook, não uma regra.

Uma linha de configuração contra um ataque à cadeia de suprimentos

Em 31 de março de 2026, o pacote npm oficial axios, com cerca de 100 milhões de downloads por semana, foi comprometido por meio da conta de um mantenedor (Elastic Security Labs). Uma versão maliciosa 1.14.1 foi publicada às 00:21 UTC, e as versões ruins ficaram no npm até 03:15 UTC, cerca de três horas (o post-mortem do axios). A Microsoft atribui o ataque ao Sapphire Sleet, um ator estatal norte-coreano (Microsoft Security Blog).

Meu .npmrc tinha uma linha:

min-release-age=7

Pacotes publicados há menos de sete dias não são instalados. A maioria dos pacotes maliciosos é detectada em um a três dias, então sete é uma margem confortável. Eu não fui afetada, e custou uma linha. O equivalente em Python vai no uv.toml:

exclude-newer = "7 days"

A pesquisa por trás disso: 37 artigos

Boa parte das regras não veio dos meus próprios erros, mas de trabalhos acadêmicos: 37 artigos do arXiv reescritos como princípios. Quatro deles mudaram mais o meu fluxo de trabalho.

• Ciclo de prova. O agente diz que os testes passam; você confere, e eles não passam. O ciclo de prova proíbe o agente de dar o aval ao próprio trabalho. Ele exige artefatos: a saída dos testes e um veredito de um verificador em uma sessão nova que nunca viu o trabalho sendo feito. Fonte: arXiv 2603.10165.
• Raciocínio estruturado. Em vez de um "talvez isto, talvez aquilo" livre: o que sabemos com certeza pelo código e pelos logs, um rastro passo a passo, o que decorre disso e quais hipóteses foram testadas e descartadas. Nos experimentos de Ugare e Chandra, esse tipo de raciocínio semiformal elevou a acurácia na equivalência de patches de 78% para 88% em exemplos selecionados, e para 93% em patches reais gerados por agentes (arXiv 2603.01896).
• Orquestração determinística. Tudo que é determinístico, como testes, linters e formatação, roda por um script de shell. Um modelo perde a conta em loops e confunde condições de ramificação. Um script não.
• Linhas vermelhas. Regras comuns são interpretadas de forma criativa. Linhas vermelhas são proibições absolutas, sem exceções, cada uma ligada a um incidente: não apague sem confirmação, não altere configurações de produção sem entendê-las. O padrão vem de equipes de engenharia chinesas, 红线, literalmente "linha vermelha".

O resto, de gerador-avaliador e autoresearch até decomposição multiagente, contexto codificado, segurança de agentes e integridade da documentação, está descrito no repositório.

Números, e o lugar em que falhou

78 arquivos de memória. 178 referências cruzadas. 27 handoffs em quatro dias. Uma taxa de acerto de 96,9% no cache KV em 83 sessões numa semana. A configuração se mantém sozinha: depois de cada mudança, o agente verifica se algum link ficou obsoleto, e um hook de SessionStart valida tudo automaticamente.

Funciona perfeitamente? Não. Uma auditoria encontrou quatro arquivos de memória que tinham saído do índice. Deriva de documentação, dentro do sistema criado para impedir deriva de documentação. Sem o sistema, teria sido pior.

Do que não tenho certeza

Não estou convencida de que todo mundo precise de tudo isso. Para a maioria dos projetos, cinco princípios provavelmente bastariam: orquestração determinística, raciocínio estruturado, defesa contra ataques à cadeia de suprimentos, contexto codificado e handoffs.

Também não estou convencida de que seis camadas sejam o mínimo. Talvez eu tenha exagerado na construção. Mas, naquele mês, nenhum contexto foi perdido e nenhum beco sem saída voltou.

Um dos princípios, o teste de premissas, diz isso com clareza. Cada componente da configuração codifica uma premissa sobre o que o modelo não consegue fazer sozinho, e os modelos melhoram. Remova componentes e meça. Alguma camada aqui provavelmente já é desnecessária.

O que mudou depois de abril

Atualização, setembro de 2026. O repositório foi renomeado de claude-code-config para codex-claude-code-config, porque os mesmos princípios, hooks e skills agora também guiam o Codex e sessões mistas de Claude e Codex, e o nome antigo já não descrevia o projeto. A URL antiga ainda redireciona. Em 23 de setembro de 2026 ele tinha 30 princípios, 58 skills, 35 arquivos de regras e 73 scripts em hooks/, com 150 estrelas e 24 forks no GitHub.

Os números nas seções acima (9 arquivos de regras, 78 arquivos de memória, 16 skills, 37 artigos, 582 linhas) descrevem minha configuração em 12 de abril. Eram verdadeiros naquele dia, e eu os deixei como estavam.

Por onde começar

Cole isto em uma conversa do Claude Code:

https://github.com/AnastasiyaW/codex-claude-code-config - study it, pick what fits my work and set up my Claude Code

Comece pequeno: defesa contra ataques à cadeia de suprimentos (uma linha no .npmrc), orquestração determinística (testes por scripts) e raciocínio estruturado (um formato para depuração). Adicione o resto quando uma falha pedir. Tudo está sob licença MIT.

A página do projeto neste site é codex-claude-code-config. A biblioteca de referência que cresceu ao lado dele é descrita em 785 artigos para agentes, não para humanos, e por que confio mais nos handoffs do que no próprio histórico de sessões do app desktop está em 45 MB de sessões do Claude Code que você nunca olha.