Como escrever um bom CLAUDE.md para o repositório da empresa

Como escrever um bom CLAUDE.md para o repositório da empresa

Para escrever um bom CLAUDE.md, registre apenas o que o Claude Code não consegue descobrir sozinho lendo o código: como rodar, testar e validar o projeto, convenções que fogem do padrão, limites do que não deve ser tocado e onde encontrar o restante. Mantenha o arquivo curto, em linguagem direta, com um responsável definido e revisão feita como em qualquer outro arquivo do repositório.

Principais pontos

• O CLAUDE.md é contexto para o agente, não documentação do projeto. Ele deve conter o mínimo que muda o comportamento do agente.
• Entram comandos de build e teste, convenções não óbvias, limites de segurança e ponteiros para documentos mais longos.
• Ficam de fora segredos, dados pessoais, descrições do que o código já mostra, regras genéricas de boa conduta e textos que envelhecem rápido.
• Instrução no arquivo orienta, mas não garante. Regras que não podem falhar pertencem a permissões e hooks, não a um parágrafo de texto.
• Um arquivo bom tem dono, passa por revisão em pull request e perde linhas com a mesma frequência com que ganha.

O que é o CLAUDE.md e por que o tamanho importa

O CLAUDE.md é um arquivo de texto na raiz do repositório que o Claude Code lê no início de uma sessão e mantém no contexto de trabalho. Pela documentação oficial da ferramenta, também é possível ter arquivos em subpastas e um arquivo pessoal fora do repositório, o que ajuda a separar regras da empresa, regras de um módulo e preferências individuais. Confira na documentação da versão que sua equipe usa como essa hierarquia é carregada, porque o comportamento exato pode mudar.

O ponto central é que tudo o que está no arquivo ocupa espaço na janela de contexto de toda sessão. A própria Anthropic descreve o contexto como um recurso finito, e que o objetivo é reunir o menor conjunto de informações de alto sinal que leve ao resultado desejado. Está na engenharia de contexto para agentes. Na prática, um CLAUDE.md inchado tem dois custos: gasta atenção do modelo com o que não importa e dilui as poucas regras que realmente importam.

Pense no arquivo como a página que você entregaria a um desenvolvente experiente no primeiro dia: ele sabe programar, mas não sabe como esta empresa trabalha.

O que entra no arquivo

Um bom critério para cada linha: se eu remover isto, o agente erra ou perde tempo? Se a resposta for não, a linha não precisa estar ali. Costumam passar nesse teste os itens abaixo.

• Comandos exatos para instalar dependências, subir o ambiente, rodar todos os testes, rodar um teste isolado, formatar e verificar tipos. O agente adivinha mal quando o projeto usa scripts próprios.
• Definição de pronto: o que precisa passar antes de considerar uma tarefa concluída (testes, lint, migração aplicada, changelog atualizado).
• Convenções que não aparecem no código: padrão de nomes de branch e de commit, como tratar erros, onde ficam os helpers compartilhados, qual biblioteca usar no lugar de outra que parece equivalente.
• Decisões de arquitetura que o agente tende a desfazer sem querer, com o motivo em uma frase. Exemplo: não acessar o banco direto pelos controllers, porque a camada de serviço aplica as regras de permissão.
• Zonas de cuidado: diretórios gerados, arquivos de migração já aplicados, código legado que não deve ser refatorado sem pedido explícito.
• Limites de segurança em linguagem operacional: nunca ler ou imprimir arquivos de credenciais, nunca executar comandos contra o ambiente de produção, pedir confirmação antes de apagar dados.
• Ponteiros para detalhes: em vez de copiar o guia de API, diga onde ele está e quando consultá-lo.

Observe que quase tudo é verificável. Frases como "escreva código limpo" não são, e por isso não pertencem ao arquivo.

O que não entra no arquivo

A lista do que sai costuma ser mais útil do que a do que entra, porque o erro mais comum é acumular.

• Segredos, tokens, senhas, strings de conexão e qualquer dado pessoal de clientes ou colaboradores. O arquivo vai para o controle de versão e é lido por quem tiver acesso ao repositório. Para empresas brasileiras, isso também é uma questão de LGPD, não só de higiene técnica.
• Descrição de estrutura que o agente enxerga com uma listagem de pastas. Árvores de diretórios copiadas ficam desatualizadas na primeira reorganização.
• Manual completo de arquitetura, histórico de decisões ou onboarding de pessoas. Isso vive em documentos próprios, e o CLAUDE.md só aponta para eles.
• Conselhos genéricos como "seja cuidadoso", "pense bem antes de agir" ou "siga as boas práticas". Não mudam nada e consomem atenção.
• Instruções para tarefas raras. Um procedimento de release que acontece uma vez por trimestre funciona melhor como skill carregada sob demanda. Veja Skills no Claude Code: o que são e como criar as da sua equipe.
• Regras que precisam ser cumpridas sempre. Texto é orientação, e o modelo pode ignorá-la em algum momento. O que não pode falhar deve ser imposto por ferramenta: hooks que aplicam regras antes e depois de agir e permissões e sandbox, tema de segurança no Claude Code para empresas.
• Informação que muda toda semana, como status de sprint, lista de bugs abertos ou nome de quem está de plantão.

Uma estrutura enxuta para copiar

Não existe formato obrigatório, mas uma ordem estável facilita a leitura e a revisão. Uma sugestão de seções, cada uma com poucas linhas:

• Visão do projeto: duas ou três frases sobre o que o sistema faz e para quem, só o suficiente para o agente entender o domínio.
• Comandos: instalar, rodar, testar, testar um arquivo, formatar, checar tipos.
• Fluxo de trabalho: como nomear branches, como escrever commits, o que verificar antes de abrir um pull request.
• Convenções do código: apenas o que foge do padrão da linguagem ou do framework.
• Limites: o que nunca fazer e o que exige confirmação humana.
• Onde achar mais: lista de caminhos para documentos, cada um com uma frase dizendo quando consultar.

Escreva no imperativo, com frases curtas, e prefira o positivo quando possível: "use o cliente HTTP interno em vez de chamar a biblioteca diretamente" funciona melhor do que uma proibição solta. Quando uma regra tiver motivo, dê o motivo em poucas palavras. O agente generaliza melhor quando entende a razão.

Se o repositório for um monorepo, mantenha o arquivo da raiz com o que vale para todos e coloque detalhes de cada pacote em um arquivo próprio dentro da pasta correspondente. Assim, quem trabalha na API não carrega regras do aplicativo móvel.

Como escrever, passo a passo

Este roteiro serve tanto para um repositório novo quanto para enxugar um arquivo que já cresceu demais.

• Comece pelo que a ferramenta gera. O comando de inicialização do Claude Code produz um rascunho a partir do projeto. Trate-o como ponto de partida e corte tudo o que for descrição óbvia.
• Observe uma sessão real. Peça uma tarefa típica ao agente, sem instruções extras, e anote onde ele erra: comando errado, convenção ignorada, arquivo que não deveria mexer. Cada erro recorrente vira uma linha candidata.
• Escreva a regra mais curta possível e teste. Repita a mesma tarefa com a linha adicionada. Se o comportamento não mudou, a linha não ganhou o lugar.
• Separe o que é orientação do que é imposição. Para cada limite crítico, pergunte se uma permissão ou um hook resolve melhor. Se sim, configure e deixe no arquivo apenas uma linha explicando o motivo.
• Mova o que é longo para fora. Procedimentos extensos viram skills ou documentos referenciados. O CLAUDE.md fica com o ponteiro.
• Revise em pull request. Qualquer mudança no arquivo passa por revisão, com uma pergunta simples: isto ainda é verdade e ainda é necessário?

Cenário ilustrativo: monorepo com API e painel

Cenário ilustrativo: uma empresa de software mantém um monorepo com uma API e um painel administrativo. O primeiro CLAUDE.md tinha uma árvore de pastas completa, um resumo do histórico do produto e uma lista de boas práticas gerais. Nas sessões, o agente rodava a suíte inteira de testes a cada pequena alteração, porque o comando de teste por arquivo não estava registrado, e editava arquivos de migração que já estavam aplicados.

A equipe reescreveu o arquivo em seções curtas. Saíram a árvore de pastas, o histórico e os conselhos genéricos. Entraram o comando para testar um único arquivo, a definição de pronto, uma linha dizendo que migrações aplicadas nunca são editadas (cria-se uma nova), e um ponteiro para o guia de contratos da API. Para a regra das migrações, a equipe ainda configurou uma verificação automática, deixando o texto apenas como explicação. O arquivo ficou pequeno o bastante para ser lido inteiro em uma reunião de revisão, e é isso que o torna mantível.

O exemplo é ilustrativo e não representa resultado medido de nenhum cliente.

Como manter o arquivo vivo sem virar depósito

O CLAUDE.md degrada de forma previsível: alguém adiciona uma linha depois de um erro e ninguém remove nada depois. Em alguns meses, o arquivo contradiz o código. Algumas práticas simples evitam isso.

• Defina um responsável por repositório, mesmo que a edição seja aberta a todos.
• Trate o arquivo como código: mudança entra por pull request, com descrição do problema que a linha resolve.
• Reserve uma revisão periódica curta para apagar. Cada linha precisa justificar sua presença de novo.
• Quando um erro se repetir, decida primeiro se a correção é texto, skill, permissão ou hook. Nem todo erro deve virar frase no arquivo.
• Se vários times usam a ferramenta, padronize um esqueleto comum e deixe cada time preencher o seu. O guia de adoção do Claude Code por equipes, com controle detalha esse tipo de combinação.

O método que usamos em projetos de IA se aplica bem aqui. Mapear: observar como o agente trabalha hoje e onde erra, antes de escrever qualquer regra. Limitar: decidir o que ele pode ler, executar e alterar, e impor isso por ferramenta. Pilotar: começar com um repositório e uma tarefa recorrente, com um critério de sucesso combinado, por exemplo menos retrabalho em revisão de código. Transferir: entregar o arquivo com dono, rotina de revisão e a decisão registrada de expandir para outros repositórios, ajustar ou parar. Para a ideia geral de limitar o escopo de um agente, vale a leitura de Building effective agents, da Anthropic, e de harnesses para agentes de longa duração.

Uma separação ajuda a manter honestidade técnica no próprio arquivo: o que vem da documentação oficial (como a ferramenta carrega o contexto), o que vem da experiência de implementação (o que costuma funcionar em equipes) e o que ainda é hipótese (uma regra nova que você está testando). Marque as hipóteses com um comentário curto e remova-as se o teste não mostrar efeito.

Perguntas frequentes

Quanto tempo e quantas linhas um CLAUDE.md deve ter? Não há um tamanho certo, mas o arquivo deve caber em uma leitura rápida por uma pessoa. Se você precisa rolar muito para encontrar uma regra, o agente também terá dificuldade de priorizar. Quando passar disso, mova procedimentos para skills ou documentos referenciados.

Posso colocar senhas, chaves de API ou dados de clientes no arquivo para o agente usar? Não. O arquivo vai para o controle de versão e circula entre muitas pessoas e ferramentas. Credenciais devem ficar em gerenciadores de segredos e variáveis de ambiente, com permissões que impeçam o agente de lê-las. Dados pessoais exigem atenção à LGPD e não pertencem a um arquivo de contexto.

O CLAUDE.md garante que o agente vai seguir as regras? Não. Ele é contexto que orienta o comportamento, e o modelo pode deixar de segui-lo em alguma situação. Para regras que não podem falhar, como bloquear comandos perigosos ou exigir testes antes de concluir, use permissões, sandbox e hooks, e deixe no arquivo apenas a explicação do motivo.

Devo ter um CLAUDE.md por repositório ou um só para a empresa? O ideal é um esqueleto comum entre repositórios e um arquivo próprio em cada um, com os comandos e convenções reais daquele projeto. Regras de empresa, como segurança e fluxo de revisão, podem ser replicadas a partir de um modelo, mas o conteúdo específico de cada código deve ficar junto dele para ser revisado e atualizado por quem o mantém.

Fontes

• Anthropic: Effective context engineering for AI agents
• Anthropic: Building effective agents
• Anthropic: Effective harnesses for long-running agents