Meu CLAUDE.md – 582 linhas. Eis o porquê

Sonia_Black ontem às 17:19 Meu CLAUDE.md – 582 linhas. Eis o porquê Média 6 min 26K Inteligência Artificial Programação * Open source * Segurança da Informação * Caso

Cada novo chat com o Claude Code começa do zero. O agente não conhece seu projeto, não se lembra do que você discutiu uma hora atrás em outra janela, não sabe que não se pode tocar em uma determinada porta neste servidor. Você explica a mesma coisa pela quinta vez e, na sexta, ele ainda vai "corrigir" uma configuração que estava funcionando normalmente.

Toda semana, no r/ClaudeAI, surge uma nova história. O agente excluiu o banco de dados de produção. O agente enviou segredos para um repositório público. O agente "otimizou" o serviço de billing e emitiu contas zeradas para os clientes. E toda vez você pensa: não quero ser essa pessoa nas manchetes.

CLAUDE.md deve resolver ambos os problemas: contexto entre as sessões e proteção contra desastres. Um CLAUDE.md típico de 5 a 10 linhas não resolve nenhum dos dois. Decidi abordar isso de forma sistemática – não um problema de cada vez, mas como uma tarefa arquitetural.

Atualmente, minha configuração tem 582 linhas, 6 camadas, e cada regra tem uma história específica por trás.

Três casos que mudaram tudo

O agente "corrigiu" um sistema em funcionamento.

Domingo à noite. O agente vê na configuração

127.0.0.1

para um serviço de armazenamento externo. Decide que a sessão anterior deixou um erro – em vez do endereço real, está localhost. Lógico, certo? Ele substitui pelo IP real. O upload quebra. Mais meia hora de debugging antes de perceber: era um SNI-proxy através de um túnel local, 127.0.0.1 era o valor correto. Sem contexto, a solução óbvia se tornou uma catástrofe.

A regra que surgiu: "não alterar configurações sem entender por que os valores atuais são assim. Se o valor parecer estranho – primeiro entender, depois agir."

fail2ban confundiu o agente com um brute-forcer.

O agente estava verificando o estado do servidor. Para cada verificação, ele abria uma nova conexão SSH. Uma dezena de conexões por minuto – fail2ban interpretou como brute-force e bloqueou o IP por meia hora. Durante esse tempo, um modelo estava sendo treinado no servidor e eu perdi o acesso a ele.

Regra: "um SSH-bridge para tudo. Um cliente por sessão. Não escrever scripts separados para check, fix, verify – combinar em um."

"Filtrar" acabou sendo "excluir".

Eu pedi para filtrar um dataset – remover imagens inadequadas. O agente interpretou literalmente: excluiu os arquivos. Não moveu, não marcou – excluiu. Os dados desapareceram.

Regra: "'filtragem' = mover ou marcar, não excluir. Antes de qualquer exclusão, certificar-se de que o usuário pediu explicitamente para excluir."

Escrever "seja cuidadoso" não funciona. É preciso um sistema.

6 camadas: como funciona

Nenhuma camada foi planejada. Cada uma surgiu após um problema específico.

Camada 1: Rules

(9 arquivos). Conjunto de regras que são carregadas dependendo da situação. O agente está escrevendo um artigo – ele não precisa de regras sobre SSH. Está debugando código – não precisa de regras sobre formatação de texto. Claude Code consegue conectar os arquivos de rules necessários dependendo da tarefa.

Camada 2: Memory

(78 arquivos). Surgiu quando o agente esqueceu a configuração do servidor pela terceira vez. Entre as sessões, ele agora se lembra: configurações de infraestrutura, decisões sobre projetos, minhas preferências, erros passados. Os arquivos são vinculados por links

[[filename]]

– 178 links cruzados, criando um grafo de conhecimento a partir de markdown comum. Parte é carregada sempre (regras básicas), o restante – por tópico.

Camada 3: Handoffs.

Surgiu quando um novo chat repetiu o beco sem saída do anterior. Ao fechar o chat, o agente registra um resumo: o que foi feito, o que NÃO funcionou (a parte mais valiosa), uma próxima ação. Aqui está um handoff real:

## Цель сессии
Color checker: CNN sweep + diffusion, первые визуальные результаты.

## Сделано
- CNN baseline: median 1.99 deg (11M params, 21 MB)
- Sweep на 5 GPU: crop128(3.17), bs16(2.04), lr3e-4(NaN)
- Diffusion training запущен: epoch 5/50, loss 0.827

## НЕ сработало
- EfficientNet-B0: hash mismatch в Docker image
- lr=3e-4: NaN после epoch 10-13, нет gradient clipping
- CNN визуально: 3 числа дают паразитные кастинги

## Следующий шаг
Inference скрипт для diffusion + visual sheets с 24 patches

O próximo chat lê 1500 tokens em vez de analisar o projeto novamente. Em 4 dias, acumulou 27 handoff’s – nenhum beco sem saída se repetiu. Funciona não apenas entre chats: tenho três assinaturas (duas de trabalho, uma pessoal), e o handoff permite começar em outra assinatura sem explicações repetidas.

Camada 4: Chronicles.

Surgiu quando, após 20 handoffs, ficou непонятно, por que o projeto chegou ao estado atual. Handoff responde "o que vem a seguir". Crônica - "como chegamos aqui". Decisões-chave, reviravoltas, becos sem saída. 3-7 linhas para cada marco.

Camada 5: Hooks.

Surgiu quando a regra "verificar links em CLAUDE.md" parou de funcionar após 20 minutos de sessão. Sobre isso - uma seção separada abaixo.

Camada 6: Skills

(16 штук). Conjuntos de conhecimentos prontos para tarefas específicas. A descrição é escrita como um gatilho para o modelo: "usar quando: GPU travou, precisa de verificação de saúde do servidor", e não "ajuda com servidores".

Regra - desejo. Hook - garantia.

Esta é a conclusão mais não óbvia do mês.

Uma regra em CLAUDE.md é uma instrução no prompt. O agente pode esquecer, reinterpretar, ignorar em uma sessão longa quando o contexto está cheio de outras coisas. A regra "verificar links antes de trabalhar" funcionou nos primeiros 10 minutos. Então o agente se empolgou com a tarefa e esqueceu.

Um Hook é um script Python que Claude Code executa automaticamente em determinados eventos. SessionStart, Stop, PreToolUse. O script não esquece, não reinterpreta. Ele é executado mecanicamente, toda vez.

Exemplo - hook que lembra de registrar um handoff antes de fechar uma sessão longa:

python
# remind_handoff.py (Stop hook, упрощённо)
age = session_age_minutes()
if age < 15:
    return  # короткая сессия, не нужно

if fresh_handoff_exists():
    return  # уже записан

# Блокируем закрытие и просим записать handoff
print(json.dumps({
    "decision": "block",
    "reason": f"Сессия {int(age)} мин, handoff не записан. "
              f"Запиши в .claude/handoffs/ перед выходом."
}))

O modelo sabe quando é hora - quando a tarefa é concluída ou o contexto está sobrecarregado. O Hook protege contra casos em que ele esqueceu.

Se algo deve acontecer garantidamente - é um hook, não uma regra.

Uma linha de configuração que salvou de um ataque supply chain

Em 31 de março de 2026, o grupo Sapphire Sleet (DPRK) comprometeu o pacote npm oficial axios (~100M de downloads por semana). Publicaram a versão 1.14.1 com código malicioso. Janela: 3 horas, das 00:21 às 03:29 UTC.

No meu

.npmrc

tinha uma linha:

min-release-age=7

Pacotes publicados há menos de 7 dias não são instalados. A maioria dos pacotes maliciosos são descobertos em 1-3 dias, 7 dias - um buffer confortável.

Não fui afetado. Uma linha na configuração.

Analogamente para Python - em

uv.toml

exclude-newer = "7 days"

Por trás da configuração - 37 papers

Muitas regras vieram não da experiência pessoal, mas de trabalhos acadêmicos.

37 arxiv papers , transformados em princípios. Aqui estão aqueles que mais mudaram meu workflow:

Proof Loop.

O agente diz "testes passaram" - você verifica, os testes não passaram. Proof Loop proíbe o agente de confirmar seu próprio trabalho. Precisamos de arquivos de prova: saída de testes, veredicto de um verificador em uma nova sessão, que não viu o processo de criação.

Fonte.

Structured Reasoning.

Em vez de um livre "bem, talvez isso, ou talvez aquilo" - um formato: o que sabemos com certeza do código e dos logs → rastreamento passo a passo → o que se segue → quais hipóteses verificamos e descartamos. Em patches reais, a precisão sobe de 78% para 93%.

Fonte.

Deterministic Orchestration.

Se a tarefa é determinística - testes, linter, formatação - ela passa por um shell-script. O modelo calcula mal, perde contadores, confunde condições em loops. O script - não.

Red Lines.

Regras comuns o agente pode interpretar "criativamente". Red Lines - proibições absolutas sem exceções. "Não excluir sem confirmação." "Não alterar configurações de produção sem entender." Cada um está ligado a um incidente. Padrão da comunidade de engenharia chinesa (红线).

Os outros princípios -

• generator-evaluator * autoresearch * multi-agent decomposition * codified context * agent security * documentation integrity e mais 7 - são descritos detalhadamente no repositório.

Números

78 arquivos de memória. 178 links cruzados. 27 handoffs em 4 dias. 96.9% de KV-cache hit rate em 83 sessões em uma semana.

O arquivo de configuração se atualiza sozinho: após cada alteração, o agente verifica se os links não estão desatualizados. O SessionStart hook valida automaticamente.

Funciona perfeitamente? Não. Durante a auditoria, foram encontrados 4 arquivos de memória que caíram fora do índice. O Documentation drift aconteceu com um sistema que deveria impedi-lo. Mas sem ele seria pior.

O que eu não sei

Não tenho certeza se todos os princípios são necessários para todos. Para a maioria dos projetos, provavelmente cinco são suficientes: Deterministic Orchestration, Structured Reasoning, Supply Chain Defense, Codified Context, Handoffs.

Não tenho certeza se 6 camadas é o mínimo. Talvez eu tenha overengineered. Mas em um mês, nenhum contexto foi perdido e nenhum beco sem saída se repetiu.

Um dos princípios (Assumption Testing) diz diretamente: cada componente codifica uma suposição sobre a incapacidade do modelo. Os modelos estão melhorando. Remova componentes e meça - talvez alguma camada não seja mais necessária.

Experimentar

Copie para o chat do Claude Code:

https://github.com/AnastasiyaW/claude-code-config - изучи, выбери что подходитдля моей работы и настрой мой Claude Code

Comece pequeno: Supply Chain Defense (uma linha em

.npmrc

) + Deterministic Orchestration (testes via scripts) + Structured Reasoning (formato de debug). Adicione conforme necessário.

Tudo sob MIT.

github.com/AnastasiyaW/claude-code-config