Um projeto começa simples, com um CLAUDE.md que guarda convenções, comandos de teste e limites de edição para o agente. Depois entram regras de revisão, política de Git, padrão de Markdown, documentação de domínio e instruções de segurança, até que usar imports no CLAUDE.md vira uma decisão de manutenção.

O problema não é ter referência escrita, mas manter várias versões da mesma instrução e esperar que o agente descubra qual delas vale. Quando um arquivo diz uma coisa e outro repete a regra com pequenas diferenças, a revisão cria ruído para humano e IA ao mesmo tempo.

Eu usaria imports no CLAUDE.md quando já existe uma fonte de verdade clara em outro arquivo e faz sentido que o Claude Code leia essa mesma referência no início da sessão. A documentação oficial do Claude Code explica que arquivos importados são expandidos e carregados junto com a memória que os referencia.

Aqui na Promovaweb, eu olho para esse recurso como uma ferramenta de manutenção editorial e técnica. O import ajuda a reduzir duplicação, melhora a revisão e deixa a origem da regra mais explícita, mas não substitui critério sobre escopo, tamanho da memória e separação entre regra permanente, regra por caminho e procedimento recorrente.

Direto ao ponto

Use imports no CLAUDE.md quando uma regra persistente já vive em outro arquivo e você quer evitar cópia manual. Não use import como promessa de reduzir tokens, porque o conteúdo importado também entra no cenário de inicialização; se a regra vale só para uma pasta, avalie .claude/rules/, e se a instrução descreve um fluxo repetível, transforme em skill.

O import organiza a fonte, não some com a referência

O erro mais comum é tratar import como atalho invisível, como se o conteúdo deixasse de existir para o agente. Quando o CLAUDE.md referencia outro arquivo, o Claude Code expande esse conteúdo e o coloca na memória carregada para a sessão.

Isso muda bastante a decisão, porque importar um arquivo enorme pode deixar o CLAUDE.md mais legível para quem abre o repositório sem reduzir automaticamente o conteúdo recebido pelo agente. A melhoria é de manutenção, não de custo automático de referência.

Mesmo assim, essa melhoria é importante porque um arquivo principal menor facilita revisão, onboarding técnico e leitura do que realmente é regra global. O import deixa claro que determinado bloco vive em outro lugar porque aquele outro lugar é a fonte mantida.

Eu gosto desse critério porque ele evita transformar o arquivo de memória em um depósito de tudo que já foi decidido. Quando tudo entra no mesmo documento, regra essencial, referência de domínio, anotação temporária e procedimento de validação começam a disputar o mesmo espaço.

Quando vale importar um arquivo

Import faz sentido quando o arquivo importado já tem vida própria no projeto. Um README bem mantido, uma política de revisão, um guia de Git, um padrão de Markdown ou um documento de domínio podem ser bons candidatos, desde que o conteúdo realmente precise orientar o agente em toda sessão.

O sinal principal aparece quando pessoas já revisam aquele arquivo como fonte de verdade e o agente pode ler a mesma fonte. A pessoa corrige a regra em um lugar e o CLAUDE.md continua apontando para ela, em vez de carregar uma versão antiga copiada meses atrás.

Eu evitaria import quando o material é provisório, sensível, experimental ou específico demais para aparecer em toda sessão. Uma investigação pontual, uma hipótese de arquitetura ainda não aprovada ou uma preferência individual não deveria virar referência global do projeto só porque é fácil referenciar o arquivo.

Também vale olhar para o tamanho antes de importar qualquer referência extensa. Se o arquivo importado tem muitas seções que o agente raramente usa, talvez ele precise ser dividido antes.

Quando .claude/rules/ é uma escolha melhor

Uma regra que só vale para determinado caminho não precisa ficar carregada o tempo inteiro. Se a instrução orienta componentes de interface, rotas de API, testes de integração ou documentação de um módulo específico, .claude/rules/ tende a ser uma alternativa mais limpa.

Esse modelo ajuda quando a referência depende do arquivo trabalhado e precisa aparecer perto do recorte certo. A chance de uma instrução global interferir em tarefa sem relação diminui.

O import no CLAUDE.md funciona melhor para regra persistente e transversal, enquanto a regra por caminho funciona melhor para convenção localizada. Misturar os dois papéis costuma gerar memória pesada e pouco clara.

No Co-work da IA Makers, esse tipo de separação aparece bastante em projetos guiados por agentes. A pessoa começa querendo colocar tudo no CLAUDE.md porque parece mais seguro, mas depois percebe que segurança de referência vem de escopo bem definido.

Quando transformar instrução em skill

Uma instrução vira skill quando já não funciona como regra isolada e começa a descrever um procedimento. Se existe entrada, sequência de leitura, critérios de execução, validação, arquivos de saída e checklist final, o melhor lugar provavelmente não é o CLAUDE.md.

Imports ajudam a reaproveitar texto, enquanto skills ajudam a executar trabalho recorrente com método. Essa diferença importa porque uma skill pode carregar referência específica no momento certo e orientar a tarefa sem inflar a memória permanente do projeto.

Eu separaria assim: CLAUDE.md guarda comportamento geral, limites e comandos essenciais; imports apontam para fontes persistentes que precisam continuar como referência; .claude/rules/ cuida de regra por caminho; skills documentam fluxos com começo, meio, validação e entrega. Essa divisão evita que todo tipo de instrução dispute o mesmo arquivo.

Essa divisão também melhora revisão humana, porque cada arquivo passa a ter uma função mais fácil de auditar. Quando alguém abre uma skill, espera encontrar um procedimento; quando abre o CLAUDE.md, espera entender comportamento geral; quando abre uma rule por caminho, espera uma convenção localizada.

Como evitar conflito entre instruções

Conflito de instrução normalmente nasce de manutenção fraca, não do recurso de import em si. O risco aparece quando o CLAUDE.md define uma regra e o arquivo importado repete a mesma regra com outra redação, outro limite ou outra exceção.

Antes de importar, eu revisaria três pontos: qual arquivo é a fonte de verdade, qual parte do conteúdo realmente precisa entrar na memória e quem vai manter esse arquivo quando a regra mudar. Sem essas respostas, o import só formaliza uma duplicação que já estava ruim.

Também é importante nomear arquivos pelo papel, não pela conveniência, para que a pessoa revisora entenda a intenção antes de editar. regras-markdown.md, politica-git.md ou arquitetura-dominio.md dizem mais ao revisor do que nomes genéricos como extra.md ou notas.md.

Se o projeto já tem posts, documentos e skills próximos, o import deve respeitar essa arquitetura. O artigo sobre como organizar CLAUDE.md em projetos com hierarquia aprofunda a separação entre memória global, referência do projeto e instruções mais específicas.

Imports ajudam na manutenção do projeto com IA

O ganho mais prático de imports aparece na manutenção, porque cada ajuste de regra deixa de exigir uma busca por cópias espalhadas. Você preserva uma referência única e deixa o CLAUDE.md declarar que aquela regra vem dali.

Isso conversa com o post sobre como atualizar CLAUDE.md em tarefas longas com IA, especialmente quando o projeto precisa separar aprendizado provisório de regra estável. Nem toda descoberta de uma tarefa longa merece entrar na memória global, porque algumas descobertas viram issue, outras viram PR, outras viram regra por caminho e poucas viram memória permanente.

O import é útil justamente quando essa decisão já foi tomada e a regra está estável. Antes disso, o risco é transformar todo aprendizado provisório em instrução persistente.

Esse é o tipo de rotina que eu costumo puxar para a revisão: regra rastreável, fonte verificável e manutenção com dono claro. Sem esse cuidado, import vira apenas mais uma forma elegante de duplicar confusão.

Para quem trabalha com Claude Code, esse cuidado evita que o agente receba referência contraditório antes de tocar no repositório. E para quem está estruturando projetos com IA, a Formação IA Makers aprofunda essa disciplina de referência, Git, revisão e documentação de trabalho técnico.

Critérios frequentes

Imports não reduzem tokens de forma automática, porque deixam o CLAUDE.md mais organizado para manutenção, mas os arquivos importados são expandidos e carregados no cenário de inicialização. Se a intenção é reduzir memória carregada, o caminho é revisar o que precisa ser global, dividir regras por escopo e mover procedimentos recorrentes para skills.

Import faz sentido quando o outro arquivo já é a fonte de verdade e continuará sendo revisado diretamente. Copiar texto só parece rápido no começo, porque cada atualização posterior exige lembrar onde a regra foi repetida.

Import inclui uma referência dentro do CLAUDE.md e carrega esse conteúdo junto da memória, enquanto .claude/rules/ serve melhor quando a regra tem escopo por caminho ou por parte do projeto. Na prática, import é bom para regra persistente compartilhada e rule por caminho é melhor para convenção localizada.

Importar o README pode valer quando ele está atualizado, tem instruções realmente úteis para o agente e não mistura conteúdo que deveria ficar fora da sessão. Se o README é longo, comercial, incompleto ou cheio de seções que não orientam trabalho técnico, eu preferiria criar um arquivo menor e mais específico.

CLAUDE.local.md faz sentido para preferência individual, ajuste de ambiente local ou instrução que não deveria entrar no repositório. A regra compartilhada pertence ao projeto, enquanto a preferência particular pertence ao espaço local da pessoa que usa a ferramenta.

Skill é melhor do que import quando a instrução descreve uma rotina com etapas, validações e entrega. Se o agente precisa ler arquivos, produzir um artefato, rodar verificações e registrar resultado, skill é mais adequada que import, e o post sobre quando criar skill para agente de código detalha esse critério.

Antes de modularizar, revise a função de cada arquivo

Imports no CLAUDE.md são úteis quando protegem a fonte de verdade e deixam a manutenção mais simples. Eles ficam ruins quando viram disfarce para excesso de regra, documentação vencida ou referência que deveria aparecer apenas em tarefas específicas.

Na Promovaweb, eu começaria revisando a função de cada arquivo: memória global, regra localizada, referência humana, procedimento recorrente ou preferência local. Depois disso, o import vira uma decisão simples, porque entra quando ajuda o agente e a pessoa revisora a lerem a mesma fonte, com menos duplicação e menos conflito.