Regras e imports: organizando projetos maiores

Regras que carregam só quando importam

Em projetos grandes, colocar tudo no CLAUDE.md principal estoura o tamanho recomendado e enche o contexto de coisas que nem sempre importam. A primeira solução são as regras por tipo de arquivo. Você cria arquivos de instruções numa pasta de regras do projeto, cada um sobre um tema, e pode amarrar cada regra a um padrão de arquivos. Assim, uma regra sobre a parte de interface só entra no contexto quando o agente trabalha com arquivos de interface; uma regra sobre a parte de banco de dados só entra quando ele toca no banco. O essencial fica sempre visivel, e o específico aparece só na hora certa.

A lógica e economizar contexto e reduzir ruido. Uma regra de estilo de testes não precisa ocupar espaço enquanto o agente mexe numa tela; ela só faz sentido quando ele abre um arquivo de teste. Ao amarrar a regra a um padrão, como os arquivos que terminam em determinada extensão ou vivem numa certa pasta, você garante que a instrução chega exatamente quando e útil e some quando não é. Regras sem padrão definido, por outro lado, carregam sempre, com a mesma prioridade do CLAUDE.md, e servem para o que vale para o projeto todo mas você quer manter em arquivo separado por organização.

Imports: quebrar o conteúdo em pedacos

A segunda ferramenta são os imports. Dentro do CLAUDE.md, você pode referenciar outro arquivo escrevendo o simbolo de arroba antes do caminho dele, e o Claude Code traz o conteúdo desse arquivo para o contexto no início da sessão. Isso ajuda a organizar: em vez de um CLAUDE.md gigante, você mantem um principal enxuto que importa arquivos menores, como um de convencoes de git ou um de padrões de código. Um detalhe importante: o import traz o conteúdo para o contexto de qualquer forma, então ele organiza, mas não reduz o tamanho total carregado como as regras por caminho fazem.

# Instruções do projeto

Veja @README.md para a visao geral do projeto.

## Fluxo de trabalho
- convencoes de git em @docs/git.md

Exemplo de imports no CLAUDE.md: o conteúdo referenciado entra no contexto no início da sessão.

Um cuidado com imports: para mencionar um caminho no texto sem importar o arquivo, envolva-o em crase, o sinal de código em Markdown. Assim o Claude Code entende que é só uma citacao, e não um pedido para trazer o conteúdo. Sem esse cuidado, uma simples menção a um arquivo poderia carregar coisas que você não queria. E os imports podem referenciar outros imports, em cadeia, até um certo limite de profundidade, o que permite montar uma estrutura organizada de instruções sem transformar o CLAUDE.md principal num monstro.

CLAUDE.md, regra ou skill: qual usar

Com três ferramentas na mesa, o CLAUDE.md, as regras e as skills, vale um mapa de quando usar cada uma. O CLAUDE.md e para fatos permanentes e transversais, que valem para o projeto inteiro em toda sessão. As regras por caminho são para instruções que só valem para uma parte do projeto e que você quer carregar só quando o agente toca ali. E as skills, que tem um módulo próprio mais a frente, são para procedimentos de vários passos que nem sempre precisam estar no contexto e são acionados sob demanda, quando você chama ou quando o agente percebe que são relevantes.

Escolher a ferramenta certa e o que mantem projetos grandes gerenciaveis sem afogar o agente em contexto. Um erro comum e empilhar tudo no CLAUDE.md até ele virar um calhamaco que o agente mais ignora do que segue. Distribuir o conteúdo, o permanente no CLAUDE.md, o específico nas regras, o procedimental nas skills, mantem cada instrução afiada e carregada só quando faz diferença. Com isso, você fecha a parte de memória que você escreve. A última aula do módulo mostra o outro lado: a memória que o próprio Claude Code escreve sozinho.