Arquivos CLAUDE.md são frequentemente organizados para desenvolvedores, não para modelos de IA – eis por que isso importa

Um post no r/ClaudeAI destaca um modo comum de falha em arquivos CLAUDE.md: eles são estruturados em torno do que o desenvolvedor quer documentar, não do que o modelo precisa decidir. São problemas diferentes.

A Estrutura Focada no Desenvolvedor

Exemplo de arquivo organizado para o desenvolvedor:

## Sobre o Projeto
[3 parágrafos de contexto]
## Pilha Tecnológica
[15 itens]
## Metas
[5 tópicos]
## Regras Rígidas   <- está na linha 47

O modelo lê linearmente. Quando chega às regras rígidas, já começou a construir suposições. Se uma restrição deve sobrepor essas suposições, o modelo está lutando contra a corrente.

Uma Estrutura Focada no Modelo

O post sugere um modelo mental: pergunte "o que o modelo precisa saber 3 segundos antes de fazer algo irreversível?". Coloque isso primeiro. Uma estrutura melhor:

## Regras Rígidas (leia estas primeiro)
[suas restrições reais]
## Contexto Atual
[o que está ativo agora]
## Histórico
[o resto]

O Problema do Comprimento

Um CLAUDE.md de 4000 linhas não está organizado — está arquivado. Um arquivo arquivado não é bem lido. Um arquivo organizado é lido rapidamente. Clareza supera completude, sempre. O autor pergunta: o que está nas primeiras 20 linhas do seu CLAUDE.md?