Bases de Código Prontas para Agentes: Regras Negativas, Nomes Precisos, READMEs de Diretório

Um desenvolvedor no r/ClaudeAI detalhou como adaptou sua base de código Android depois que o Claude Code repetidamente colocava novos recursos em uma classe monolítica UserManager (autenticação, sessões, perfil, analytics). A percepção principal: o agente aparece "frio" toda vez, como um novo funcionário no primeiro dia, sem memória das decisões arquiteturais. A solução foi incluir regras explícitas em um CLAUDE.md na raiz do repositório.

Três padrões que fizeram a maior diferença

1. Regras negativas superam as positivas

Em vez de "siga um bom design", o desenvolvedor escreve instruções como:

Não toque em BaseActivity – ela é compartilhada entre 12 funcionalidades e quebra silenciosamente.

O agente é otimista por padrão e segue o caminho de menor resistência. Fechar caminhos perigosos explicitamente interrompe más decisões de forma mais eficaz do que orientação vaga.

2. Nomes importam mais do que você pensa

Uma classe chamada UserSessionExpiryHandler é um contrato. Nomeá-la apenas como Handler é ruído. O agente faz correspondência de padrões com base em nomes; nomes bons reduzem a leitura de arquivos necessária. O desenvolvedor recomenda evitar sufixos genéricos e tornar o propósito explícito no nome.

3. Cada diretório tem um README listando o que NÃO pertence ali

Em vez de "esta pasta é para UI", o README diz:

Sem lógica de negócios em presentation/

Esse enquadramento negativo "parece impactar mais" o agente, prevenindo mais colocações ruins do que orientação positiva.

Regras práticas para CLAUDE.md

• Mantenha arquivos pequenos. Uma classe, uma responsabilidade.
• Crie um novo arquivo em vez de estender um antigo.
• Não produza monolítos – divida responsabilidades cedo.

O desenvolvedor relata que, após aplicar essas regras, o padrão do agente reler um arquivo de 600 linhas três vezes em uma sessão praticamente desapareceu. Eles suspeitam que o custo de tokens caiu significativamente, mas não mediram adequadamente.

Para quem é

Desenvolvedores que usam agentes de codificação com IA (Claude Code, Copilot, etc.) que desejam reduzir o desperdício de tokens e evitar que agentes tomem más decisões arquiteturais.