CLAUDE.md: configure uma vez, alinhe todas as sessões

O ganho está em reduzir a repetição do contexto inicial. Considere uma conta hipotética: quatro desenvolvedores, cada um repetindo três minutos de preparação em cinco sessões, gastam 60 minutos por semana reapresentando o contexto. Um arquivo compartilhado de instruções concentra essa preparação em um só lugar. Compare o tempo de repetição que ele elimina com o tempo necessário para mantê-lo; não há economia garantida.

O que é o CLAUDE.md?

O CLAUDE.md é um arquivo Markdown com instruções que o Claude Code lê para trabalhar no seu projeto, seguir seu fluxo pessoal ou atender às orientações da organização. Pense nele como o conjunto de orientações permanentes da equipe. Já a memória automática é o caderno de anotações que Claude mantém ao lado dele. Você cuida das orientações; Claude escreve as anotações. Os dois entram no contexto usado para tomar decisões. Guia de memória da Anthropic

A distinção que importa é o que deve continuar valendo entre sessões. Um comando de teste obrigatório pertence ao arquivo de instruções. Seu comentário de que uma explicação ficou detalhada demais pode virar uma preferência aprendida. A tarefa em andamento fica na conversa.

Essa divisão segue o guia oficial de diretórios. Você não precisa começar com uma pasta .claude cheia de arquivos. Comece pelas instruções e só acrescente outro arquivo quando ele tiver uma função clara.

Onde colocar o CLAUDE.md: projeto, usuário e organização

Em uma equipe pequena, versione um arquivo de projeto na raiz do repositório. Deixe as preferências pessoais no seu arquivo de usuário para que os colegas não as herdem sem querer.

Esses são os escopos e locais documentados. As configurações individuais não permitem excluir os arquivos gerenciados da organização, mas o texto desses arquivos continua tendo a função de orientar.

Ao iniciar, Claude carrega os arquivos de instruções do diretório de trabalho e dos diretórios acima dele. As instruções em subdiretórios são carregadas conforme ele trabalha com os arquivos desses locais. O conteúdo dos arquivos é combinado: adicionar um arquivo mais específico não apaga instruções conflitantes em outro lugar. Mantenha as orientações de usuário e de projeto coerentes entre si. Como funciona o carregamento

Um exemplo de CLAUDE.md para uma equipe pequena de produto

Registre as decisões que evitam erros recorrentes. O exemplo abaixo pressupõe um produto em TypeScript que usa pnpm e já tem os scripts lint, typecheck e test definidos. Antes de versioná-lo, substitua os comandos e caminhos por aqueles que você verificou no seu repositório.

Cada seção traz uma explicação de uma linha sobre sua finalidade. São sugestões de convenções para a equipe, não padrões definidos pela Anthropic.

# Product Team Instructions

## Product Intent
Why: Keep implementation tied to the customer problem.
- Read the task's acceptance criteria before changing code.
- Ask when missing product behavior would change the solution.

## Working Commands
Why: Make verification repeatable across teammates and sessions.
- Use pnpm for this repository; keep pnpm-lock.yaml consistent.
- Run pnpm lint and pnpm typecheck for application changes.
- Run pnpm test for behavior changes; report any checks not run.

## Change Boundaries
Why: Keep reviews small and dependencies deliberate.
- Follow nearby patterns before adding a new abstraction.
- Ask before adding a runtime dependency or changing public APIs.
- Keep unrelated cleanup out of the change.

## Data and Migrations
Why: Make data changes reviewable and reversible where possible.
- Add schema changes through the existing migration workflow.
- Describe compatibility and rollback concerns in the handoff.
- Use synthetic data in examples and tests.

## Quality
Why: Catch user-visible regressions before review.
- Add a focused regression test when fixing a behavior bug.
- Check loading, empty and error states when changing UI flows.
- State remaining uncertainty instead of calling unchecked work done.

## Project References
Why: Point to maintained decisions without copying the whole wiki.
- Read docs/product-decisions.md when product behavior is unclear.
- Read docs/release-checklist.md before preparing a release.

As referências desse exemplo são instruções comuns para consultar documentos quando forem relevantes. Crie esses documentos ou substitua os caminhos. A opção por não usar importações automáticas aqui é intencional.

Salve o arquivo, inicie uma sessão a partir do repositório e execute /context para conferir a lista de memória carregada na inicialização. Use /memory para abrir e editar o arquivo de instruções. Depois, passe uma tarefa pequena e real para Claude e observe se os comandos e limites ajudam. Como inspecionar a memória

Separe as regras por tipo de arquivo das instruções gerais

Mova uma regra para .claude/rules/ quando ela não for necessária na maioria das tarefas. Uma alteração no frontend, por exemplo, não precisa carregar todas as convenções dos handlers da API.

Crie .claude/rules/api.md com um cabeçalho paths. Um glob é um padrão de nomes de arquivo; src/api/**/*.ts seleciona os arquivos TypeScript desse diretório e dos seus subdiretórios.

---
paths:
  - "src/api/**/*.ts"
---

# API Rules
- Validate external input before passing it to application logic.
- Use the existing error response format.
- Add a focused test when changing an endpoint's behavior.

O padrão determina quando essa instrução entra no contexto. Sem paths, a regra é carregada incondicionalmente na inicialização. Dividir um arquivo longo de instruções em vários arquivos de regras, por si só, não economiza contexto: é preciso delimitar quando cada um será carregado. Regras por caminho de arquivo

Use importações para compartilhar texto sem perder de vista o custo de contexto

Uma importação como @docs/team-conventions.md dentro do CLAUDE.md traz o conteúdo desse arquivo para o contexto na inicialização. Caminhos relativos são resolvidos a partir do arquivo que contém a importação. Para que ela funcione, coloque-a fora das crases e dos blocos de código Markdown, que a mantêm como texto literal. Importações de projeto que apontam para fora do diretório de trabalho pedem aprovação. Sintaxe de importação

Importe uma convenção curta, já mantida por outra equipe, quando ela for necessária em todas as sessões. Para um checklist extenso de release, prefira uma referência simples, como no exemplo inicial. A importação reorganiza as instruções; ela não reduz o volume que Claude lê ao iniciar.

Já usa AGENTS.md? Mantenha uma única fonte de instruções

O Claude Code pode usar AGENTS.md diretamente no lugar de CLAUDE.md a partir da versão 2.1.277, quando esse suporte estiver disponível. O comportamento padrão tem uma condição importante: não pode haver CLAUDE.md, .claude/CLAUDE.md nem CLAUDE.local.md no diretório de trabalho ou nos diretórios acima dele. Os arquivos de instruções de usuário e da organização não impedem esse carregamento alternativo. Carregamento do AGENTS.md

Por isso, o CLAUDE.local.md pode causar confusão. Adicionar anotações pessoais do projeto pode mudar qual arquivo de instruções compartilhadas é carregado para você.

Se precisar dos dois arquivos, abra /config e defina a opção Project instructions como claude-md-and-agents-md. Outra saída é colocar @AGENTS.md em um CLAUDE.md no mesmo diretório; essa importação também funciona quando o suporte direto a AGENTS.md não está disponível. Evite manter duas cópias das regras da equipe. Nosso guia de configuração do AGENTS.md detalha essa escolha.

Memória do Claude Code: deixe os aprendizados na memória automática

A memória automática permite que Claude salve preferências, correções e contextos úteis do projeto entre conversas. Ele decide o que vale guardar e pode não salvar nada em uma sessão. O recurso vem ativado por padrão nas sessões locais. Memória automática

Por padrão, os arquivos ficam em ~/.claude/projects/<project>/memory/. Dentro de um mesmo repositório, worktrees e subdiretórios compartilham essa pasta de memória na sua máquina. Um worktree é outro checkout do repositório; portanto, começar a trabalhar em uma branch ali não cria um caderno de anotações independente. Esses arquivos não são compartilhados automaticamente com colegas, outras máquinas ou ambientes na nuvem. Local de armazenamento

O MEMORY.md é o índice. No início da sessão, Claude carrega suas primeiras 200 linhas ou 25KB, o que vier primeiro. Os arquivos detalhados por assunto são lidos conforme a necessidade. Esse limite vale para o carregamento inicial do índice, não para o total de memória que você pode armazenar. Como a memória automática é carregada

Use /memory como ponto de partida: ele lista os locais de memória, abre arquivos no seu editor, dá acesso à pasta de memória automática e permite ativar ou desativar o recurso. Use /context quando precisar verificar quais arquivos CLAUDE.md e de regras foram carregados na inicialização. Controles de memória

Deixe claro onde a informação deve ficar. “Lembre que eu prefiro resumos de entrega mais curtos” pede uma anotação aprendida. “Adicione nosso comando de teste obrigatório ao CLAUDE.md” pede uma instrução mantida pela equipe. Uma regra necessária para todos não deve depender de uma nota na pasta pessoal de um único desenvolvedor.

Não presuma que um subagente comum recebe esse caderno de anotações. A memória automática da conversa principal não é carregada em subagentes comuns; forks que herdam a conversa de origem são uma exceção, e subagentes podem ter sua própria memória configurada. Consulte nosso guia de subagentes do Claude Code ao dividir o trabalho entre agentes. Comportamento da memória em subagentes

Como desativar a memória automática

Escolha o controle adequado ao que você quer fazer:

• Na sua configuração de usuário: abra /memory e desative a memória automática. A opção salva autoMemoryEnabled em ~/.claude/settings.json.
• Em um projeto: defina "autoMemoryEnabled": false nas configurações dele. Use .claude/settings.json para uma configuração compartilhada do projeto ou .claude/settings.local.json para sua configuração local, que tem precedência.
• Em uma inicialização controlada pelo ambiente: defina CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Esses são os controles de desativação e os locais de configuração documentados. Desativar a memória automática mantém disponível o mecanismo separado de instruções do CLAUDE.md. Se também quiser remover as anotações antigas, examine e exclua explicitamente esses arquivos Markdown.

Uma revisão mensal da memória automática

Encare essa rotina como uma breve revisão editorial do que Claude levará para os próximos trabalhos. A frequência mensal é uma sugestão de hábito para a equipe, não uma exigência do produto.

1. Abra /memory e navegue pela pasta de memória automática. Leia MEMORY.md e siga suas referências até as anotações.
2. Apague o contexto que perdeu a validade. Remova prazos encerrados, planos abandonados e exceções que já não se aplicam. Confira as anotações duvidosas com base no estado atual do projeto.
3. Una as correções repetidas. Mantenha uma afirmação correta em vez de várias versões ligeiramente diferentes.
4. Transforme decisões duradouras da equipe em instruções compartilhadas. Mova uma convenção necessária para todos para o CLAUDE.md versionado ou para uma regra com escopo definido. Depois, remova a anotação pessoal redundante.
5. Enxugue o índice. Deixe referências breves em MEMORY.md e os detalhes nos arquivos por assunto. Confira tanto a contagem de linhas quanto o tamanho em bytes em relação ao limite de carregamento inicial.
6. Teste em uma sessão nova. Verifique a lista de instruções com /context e observe, na próxima tarefa real, se ainda aparecem orientações desatualizadas.

Os arquivos de memória automática são Markdown editável, e a política de retenção do histórico de conversas não faz a limpeza deles automaticamente. Alguém ainda precisa eliminar as anotações obsoletas. Edição e retenção

Cinco situações em que essa organização ajuda

Comece pelos pontos em que correções repetidas já atrasam as revisões. Os fluxos de trabalho abaixo são sugestões, ordenadas pela provável utilidade para uma equipe pequena de produto.

Duas ideias de pequenos produtos e serviços nessa área

A oportunidade mais promissora é uma auditoria das instruções do repositório. Uma equipe pequena poderia pagar por uma revisão que verificasse comandos, identificasse orientações conflitantes e propusesse um arquivo curto de instruções com regras de escopo definido. A menor entrega útil seria um pull request revisado e um checklist de auditoria que pudesse ser reutilizado. O DataForSEO estima 260 buscas mensais nos EUA por “claude project instructions”. Essa consulta ampla inclui interesse além do Claude Code; é um sinal de descoberta, não uma contagem de compradores. Um template genérico é fácil de copiar, então o valor cobrado precisaria estar na análise específica do repositório.

Um relatório local de manutenção da memória poderia ajudar equipes com muitos repositórios ativos. A primeira versão poderia sinalizar índices grandes demais, referências a arquivos por assunto que não existem e anotações possivelmente desatualizadas, deixando as edições para revisão do desenvolvedor. O DataForSEO estima 1,300 buscas mensais nos EUA por “claude code memory”. Isso indica interesse no problema, não demanda por essa ferramenta específica. A limitação é importante: a idade de um arquivo não diz se uma decisão ficou obsoleta. Deixe a avaliação do conteúdo com quem conhece o projeto.

As duas estimativas vêm de resultados de visão geral de palavras-chave em inglês dos EUA, obtidos em 11 de outubro de 2026 pela integração de pesquisa do site com o DataForSEO. São propostas de produtos, não recursos incorporados ao Claude Code. Para um único repositório pequeno, comece pelo arquivo e pela revisão mensal antes de comprar ou desenvolver qualquer uma dessas soluções.

A memória fornece contexto; o bloqueio de ações exige um controle

Escrever “nunca faça isso” no CLAUDE.md não torna uma ação impossível. O mesmo vale para a memória automática e para orientações escritas que abrangem toda a organização. Claude pode interpretar mal uma instrução vaga ou encontrar orientações contraditórias. Alerta da Anthropic

Use um hook PreToolUse, um controle executado antes de uma ação de ferramenta, quando precisar bloqueá-la independentemente da decisão de Claude. Um lembrete sobre arquivos protegidos pode explicar a intenção da equipe; o bloqueio exige um controle implementado. Nosso guia de configuração de hooks do Claude Code explica essa configuração.

Quanto ao tamanho do contexto, procure manter instruções que alguém consiga de fato cuidar. A Anthropic recomenda que cada arquivo CLAUDE.md tenha menos de 200 linhas, mas essa recomendação é separada do limite de carregamento inicial do MEMORY.md. Não aumente o arquivo inicial para cumprir uma suposta cota, nem transfira tudo para importações achando que isso reduziu o custo. Como escrever instruções eficazes

Dúvidas comuns de equipes pequenas

Para colocar em prática na segunda-feira: reúna as correções das últimas sessões, transforme as decisões recorrentes da equipe em um único CLAUDE.md revisado e teste-o em uma tarefa pequena. Inclua a revisão mensal da memória no calendário da equipe.

Se precisar de ajuda para transformar essas convenções em um fluxo de desenvolvimento confiável, conheça nosso serviço de sistemas de IA em produção.