Pare de deixar o Claude escrever código fora do contexto: um arquivo melhora a precisão da IA em 10%

Quando você usa o Claude Code para alterar um projeto existente, às vezes ele entende a stack como se fosse outra: em um projeto React aparece sintaxe de Vue; a documentação diz TypeScript, mas o resultado vem cheio de JavaScript. CLAUDE.md é o arquivo de configuração colocado na raiz do projeto justamente para resolver esse tipo de desalinhamento de contexto.

Eu já apanhei disso em um backend Node: o Claude reescreveu um middleware baseado em Koa como se fosse Express, e a cadeia inteira parou de funcionar. Nos testes da Anthropic, um CLAUDE.md bem configurado costuma elevar a precisão de codificação em 5%-10%. As 7 práticas abaixo nasceram depois desses tropeços, e cada uma traz um exemplo que dá para adaptar direto.

O que é CLAUDE.md, afinal

Resumindo, CLAUDE.md é um arquivo Markdown na raiz do projeto criado para orientar o Claude Code a entender seu projeto. Ele lembra um .editorconfig ou um README.md, mas com uma função mais específica: dizer à IA como ela deve ajudar você a escrever código.
O mecanismo é direto: quando você usa o Claude Code dentro do projeto, ele lê esse arquivo automaticamente. Embora a documentação oficial diga que o carregamento é automático, a experiência da comunidade mostra que é melhor usar o comando /init para reforçar isso uma vez e garantir que a IA entendeu a configuração. O conteúdo do arquivo entra na memória de contexto da IA e influencia toda geração de código e todas as sugestões posteriores.
Aqui existe uma característica importante: o Claude Code suporta configuração em camadas.

project-root/
├── CLAUDE.md              # configuração global, comum ao projeto inteiro
├── frontend/
│   └── .claude/
│       └── CLAUDE.md     # configuração específica do frontend
└── backend/
    └── .claude/
        └── CLAUDE.md     # configuração específica do backend

Isso significa que você pode definir regras gerais na raiz e sobrescrever regras específicas nos submódulos. Por exemplo: frontend com React, backend com Node.js, cada um mantendo sua própria configuração.

Quatro princípios centrais

Antes de escrever o CLAUDE.md, guarde estes quatro princípios. No começo eu não dei atenção a isso, escrevi um arquivo de configuração épico com mais de 300 linhas, e o Claude acabou se saindo pior.

1. Simplicidade: a regra das 100 linhas

Para ser bem honesto, essa foi uma lição que eu só aprendi pagando o preço. CLAUDE.md não é README e não precisa virar um tratado.
Por que manter curto? Tecnicamente, mesmo que a janela de contexto do Claude seja grande, o CLAUDE.md consome sua cota de tokens. Quanto mais longo o arquivo, menos tokens sobram para analisar o código real. Segundo a pesquisa da Arize AI, arquivos de configuração com até 100 linhas têm o melhor resultado.
❌ Exemplo ruim (longo e repetitivo):

# Visão geral do projeto
Este é um projeto frontend baseado em React. Usamos React para construir a interface do usuário.
React é uma biblioteca JavaScript criada pelo Facebook... (aqui seriam omitidas 200 palavras sobre React)
# Stack técnica
Nossa stack técnica inclui os seguintes itens:
- React - este é nosso framework de UI, na versão 18.2...
- TypeScript - usamos para verificação de tipos...

✅ Exemplo correto (curto e direto):

# Stack técnica
- React 18.2 (Hooks primeiro, evitar Class Components)
- TypeScript (modo estrito)
- TailwindCSS (utilities primeiro)
# Padrões de código
- Componentes funcionais + Hooks customizados
- Desestruturação de Props
- Preferir const, evitar let

Percebe a diferença? A segunda versão usa poucas linhas e entrega a mesma informação útil, até mais.

2. Especificidade: fale claro, sem regra vaga

Esse princípio parece simples, mas é fácil escorregar.
❌ Exemplo ruim (vago):

# Estilo de código
- Manter o código simples
- Usar boas práticas
- Prestar atenção à otimização de desempenho

Isso é quase o mesmo que não escrever nada. O que é “simples”? O que são “boas práticas”? A IA não consegue executar isso.
✅ Exemplo correto (concreto e executável):

# Estilo de código
- Uma função não deve passar de 50 linhas; se passar, divida
- Toda chamada de API deve incluir tratamento de erro e estado de loading
- Toda renderização de lista deve ter atributo key, usando ID em vez de index
- Evitar ternários aninhados; usar if/else ou early return

Agora a IA sabe o que deve fazer. Cada regra é clara, verificável e executável.

3. Iteração: não tenha medo de mudar, atualize sempre

Já vi desenvolvedor escrever o CLAUDE.md no início do projeto e depois passar meio ano sem tocar nele. O projeto migrou de Vue 2 para Vue 3, mas o arquivo ainda dizia “usar Options API”.
Atualize rápido com a tecla #: este é um dos truques de que mais gosto. No Claude Code, pressionar # permite referenciar e editar rapidamente o CLAUDE.md. Quando você notar que o comportamento da IA não está alinhado, mude a configuração na hora. Não deixe para depois.
Cenário real: na semana passada eu estava em um projeto em que o Claude insistia em gerar código com axios, mas a equipe já tinha padronizado fetch + um wrapper próprio. Apertei # e adicionei a seguinte linha ao CLAUDE.md:

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

# Requisições HTTP
- Usar sempre o fetch encapsulado em `src/utils/request.ts`
- É proibido usar axios ou fetch nativo diretamente

Depois de salvar, o Claude não repetiu mais esse erro.

4. Compartilhamento em equipe: coloque no versionamento

Muita gente ignora este ponto. O CLAUDE.md precisa entrar no repositório Git, com a mesma importância de um .gitignore.
Por quê? Porque sua configuração representa o consenso de código da equipe. Se cada pessoa tiver uma versão local diferente do CLAUDE.md, a IA vai gerar um estilo de código para uma pessoa e outro estilo para outra. Aí vira bagunça.

# Não ignore CLAUDE.md no .gitignore
# ❌ Errado
*.md
# ✅ Certo
*.md
!CLAUDE.md
!README.md

Também vale revisar mudanças no CLAUDE.md durante o Code Review. Se alguém alterou a configuração, a equipe inteira deve saber.

"O arquivo de configuração deve ser conciso e específico; até 100 linhas costuma gerar o melhor resultado. Cada regra precisa ser executável e verificável."

Os 5 módulos que precisam estar no arquivo

Esta é a configuração mínima viável que eu recomendo. Sem esses módulos, o CLAUDE.md quase não tem utilidade.

1. Declaração da stack técnica

Liste claramente os frameworks, bibliotecas e versões que você usa. Essa é a base.

# Stack técnica
**Frontend**
- Next.js 14 (App Router)
- React 18 (priorizar Server Components)
- TypeScript 5.2
- Tailwind CSS 3.4
**Backend**
- Node.js 20 LTS
- Express 4.18
- Prisma ORM
- PostgreSQL 15

Repare que incluí os números de versão. Sem versão, o Claude pode gerar código com APIs antigas. Por exemplo, o roteamento no Next.js 13 e no 14 é bem diferente; deixar a versão implícita é arriscado.

2. Estrutura do projeto

Diga à IA como seus arquivos são organizados. Só assim ela consegue colocar o código no lugar certo.

# Estrutura do projeto
src/
├── app/              # rotas de página do Next.js
├── components/       # componentes de UI reutilizáveis
│   ├── ui/          # componentes base (Button, Input)
│   └── features/    # componentes de negócio (UserCard, OrderList)
├── lib/             # funções utilitárias e hooks
├── services/        # camada de chamadas de API
└── types/           # definições de tipos TypeScript
# Nomenclatura de arquivos
- Componentes: PascalCase (UserProfile.tsx)
- Funções utilitárias: camelCase (formatDate.ts)
- Constantes: UPPER_SNAKE_CASE (API_BASE_URL)

Com isso, o Claude sabe que um novo componente de cartão de usuário deve ir para components/features/UserCard.tsx, não para um lugar aleatório.

3. Comandos frequentes

Essa parte costuma ser esquecida, mas é muito útil.

# Comandos de desenvolvimento
npm run dev          # iniciar servidor de desenvolvimento (localhost:3000)
npm run build        # build de produção
npm run test         # rodar testes Jest
npm run lint         # checagem ESLint
npm run type-check   # checagem de tipos TypeScript
# Banco de dados
npx prisma studio    # abrir GUI do banco de dados
npx prisma migrate dev  # rodar migrações do banco

Por que escrever isso? Porque às vezes o Claude precisa validar código ou rodar testes. Mostrar os comandos corretos evita muitos problemas.

4. Padrões de estilo de código

Aqui está a parte mais importante. Escreva de forma específica.

# Padrões de código
## Componentes React
- Usar componentes funcionais + Hooks; Class Components são proibidos
- Definir tipos de Props acima do componente, usando interface em vez de type
- Ordem interna do componente: definição de Props → função do componente → export
## Gerenciamento de estado
- Estado local: useState/useReducer
- Estado de servidor: TanStack Query
- Estado global: Zustand (evitar Context)
## Tratamento de erro
- Chamadas de API precisam de try-catch
- Erros visíveis ao usuário devem usar toast
- Em desenvolvimento, console.error; em produção, reportar ao Sentry

5. Fluxo de trabalho e limites

Diga à IA o que ela pode e o que não pode fazer.

# Fluxo de trabalho
- Desenvolvimento de nova funcionalidade: escrever tipos → escrever componente → escrever testes
- Correção de bug: escrever teste de reprodução → corrigir código → verificar testes
# Limites
- ❌ Não modificar `/prisma/schema.prisma` (precisa de revisão da equipe)
- ❌ Não instalar novas dependências (discutir no review do package.json)
- ❌ Não modificar `/lib/auth/*` (lógica de autenticação sensível)
- ✅ Pode modificar livremente código de negócio em `/components` e `/app`

Isso impede a IA de tentar ajudar e acabar quebrando uma parte crítica do projeto.

7 técnicas práticas para dobrar o efeito

Técnica 1: use SHOULD/MUST para marcar prioridade

Nem todas as regras têm a mesma importância. Use palavras-chave para separar prioridades.

# Prioridade das regras
**MUST (obrigatório)**
- MUST usar TypeScript em modo estrito
- MUST adicionar tratamento de erro a todas as APIs
**SHOULD (recomendado)**
- SHOULD manter componentes abaixo de 200 linhas
- SHOULD extrair lógica repetida para Hooks customizados
**COULD (opcional)**
- COULD adicionar comentários JSDoc

Essa técnica vem do estilo de documentação de RFC. Depois de usar isso, notei que o Claude obedece com muito mais rigor às regras marcadas como “MUST”.

Técnica 2: use bem o comando /init

Embora a documentação oficial diga que o CLAUDE.md é carregado automaticamente, eu recomendo muito rodar /init sempre que abrir o projeto.

Você: /init
Claude: configuração do projeto carregada; stack atual: React 18 + TypeScript...

É como dar uma atualizada na memória da IA. Principalmente logo depois de alterar o CLAUDE.md, /init faz a mudança valer imediatamente.

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

Técnica 3: exemplos de código valem mais que mil palavras

Em vez de só descrever a regra, mostre um exemplo.
❌ Descrição apenas em texto:

- Funções de API precisam incluir definição de tipos, tratamento de erro e estado de loading

✅ Com exemplo de código:

# Padrão de chamada de API
Exemplo de referência:
\`\`\`typescript
// src/services/user.ts
export async function getUser(id: string): Promise<User> {
  try {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) throw new Error('Failed to fetch user');
    return await response.json();
  } catch (error) {
    console.error('getUser error:', error);
    throw error;
  }
}
\`\`\`
Todas as funções de API seguem este padrão: retorno tipado + try-catch + log de erro

Depois que o Claude vê um exemplo, o código gerado fica muito mais próximo do que você espera.

Técnica 4: configuração em camadas, obrigatória em Monorepo

Se o seu projeto usa arquitetura Monorepo, use configuração em camadas.

monorepo-root/
├── CLAUDE.md                    # global: padrões comuns e fluxo Git
├── apps/
│   ├── web/
│   │   └── .claude/CLAUDE.md   # app Web: React + Next.js
│   └── mobile/
│       └── .claude/CLAUDE.md   # mobile: React Native
└── packages/
    └── shared/
        └── .claude/CLAUDE.md   # pacote compartilhado: biblioteca TS pura

CLAUDE.md da raiz (padrões globais):

# Padrões gerais do Monorepo
- Usar pnpm como gerenciador de pacotes
- Todas as configurações TypeScript herdam do tsconfig.json da raiz
- Mensagens de commit seguem Conventional Commits
# Fluxo de trabalho
- Antes de modificar código, rodar `pnpm install`
- Antes de commitar, rodar `pnpm run lint` em todos os pacotes

apps/web/.claude/CLAUDE.md (específico do frontend):

# Configuração específica do app Web
Herda os padrões da raiz; configurações extras:
- Stack técnica: Next.js 14 + React 18
- Estilo: Tailwind CSS
- Gerenciamento de estado: Zustand

O Claude lê primeiro a configuração da raiz e depois a configuração do subdiretório conforme o diretório de trabalho atual. Assim você não precisa repetir as regras comuns em cada subprojeto.

Técnica 5: use ❌ e ✅ para comparar

Humanos e IA aprendem bem com contraste.

# Padrão de atualização de estado
❌ Errado: modificar state diretamente
\`\`\`typescript
const [user, setUser] = useState({name: 'John', age: 30});
user.age = 31; // errado: modificou o objeto diretamente
\`\`\`
✅ Correto: usar atualização imutável
\`\`\`typescript
const [user, setUser] = useState({name: 'John', age: 30});
setUser(prev => ({...prev, age: 31}));
\`\`\`

Esse contraste deixa a regra visível de cara, e o Claude aprende com mais eficiência.

Técnica 6: registre padrões de erro comuns

Coloque no arquivo os erros que a equipe comete com frequência e deixe a IA ajudar na prevenção.

# ⚠️ Erros comuns e armadilhas
## 1. Esquecer de limpar efeitos colaterais
❌ Código problemático:
\`\`\`typescript
useEffect(() => {
  const timer = setInterval(() => {/* ... */}, 1000);
  // esqueceu de limpar!
}, []);
\`\`\`
✅ Correto:
\`\`\`typescript
useEffect(() => {
  const timer = setInterval(() => {/* ... */}, 1000);
  return () => clearInterval(timer); // limpa o timer
}, []);
\`\`\`
## 2. Dependências ausentes
Se o ESLint avisar que há dependências ausentes, não desative o aviso: adicione a dependência ou otimize com useCallback/useMemo

Com isso, o Claude passa a evitar essas armadilhas ao gerar código.

Técnica 7: crie links para a documentação detalhada

O CLAUDE.md deve ser curto, mas pode apontar para documentos mais completos.

# Documentos detalhados
- [Padrões de design de API](./docs/api-guidelines.md) - padrões para APIs RESTful
- [Guia de desenvolvimento de componentes](./docs/component-guide.md) - princípios de divisão e reutilização de componentes
- [Padrões de teste](./docs/testing.md) - requisitos de testes unitários e de integração

Assim você mantém o CLAUDE.md enxuto e ainda fornece detalhes quando necessário. O Claude pode usar esses links para obter mais contexto.

5 armadilhas mais comuns

Armadilha 1: arquivo longo demais, com tudo enfiado dentro

Esse é o erro mais comum de quem está começando. A pessoa coloca README, documentação de API e explicação de regra de negócio inteira dentro do CLAUDE.md.
Problema: consome tokens demais e dilui as informações importantes.
Solução: limite rigidamente a 100 linhas e escreva só o que a IA realmente precisa para codificar.

Armadilha 2: nunca atualizar a configuração

O projeto muda, mas o CLAUDE.md fica parado.
Problema: configuração desatualizada leva a IA a gerar código errado.
Solução: crie o hábito de atualizar o CLAUDE.md depois de toda refatoração importante e revisar mudanças de configuração no PR.

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

Armadilha 3: esquecer o versionamento

Colocar o CLAUDE.md no .gitignore ou não commitar no repositório.
Problema: cada membro da equipe trabalha com uma configuração própria, e o estilo do código fica inconsistente.
Solução: coloque no Git e revise junto com o código.

Armadilha 4: regras genéricas demais

Escrever frases vazias como “manter o código simples” ou “seguir boas práticas”.
Problema: a IA não consegue executar isso. É como não ter regra.
Solução: cada regra precisa ser específica, verificável e executável.

Armadilha 5: vazamento de informação sensível

Colocar chaves de API ou senhas de banco dentro do CLAUDE.md.
Problema: o arquivo de configuração vai para o repositório e vaza informação sensível.
Solução: descreva apenas o modo de configuração, sem valores reais.

❌ Errado
\`\`\`markdown
# Configuração do banco
DATABASE_URL=postgresql://admin:password123@localhost:5432/mydb
\`\`\`
✅ Correto
\`\`\`markdown
# Variáveis de ambiente
- DATABASE_URL: ler de .env.local; formato em .env.example
- API_KEY: obter de variável de ambiente; para desenvolvimento local, fale com @João para pegar uma chave de teste
\`\`\`

3 casos reais de projeto

Caso 1: projeto frontend em React

Esta é uma versão simplificada da configuração de um frontend de e-commerce que mantenho hoje:

# Projeto frontend de e-commerce
## Stack técnica
- Next.js 14.0 (App Router)
- React 18.2
- TypeScript 5.2
- Tailwind CSS 3.4
- Zustand (gerenciamento de estado)
- TanStack Query (estado de servidor)
## Estrutura do projeto
src/
├── app/          # rotas de página
├── components/   # componentes
│   ├── ui/      # componentes base
│   └── features/ # componentes de negócio
├── lib/         # funções utilitárias
└── services/    # chamadas de API
## Padrões de código
- Componentes: componentes funcionais + Hooks
- Estado: local com useState, global com Zustand, servidor com TanStack Query
- Estilo: utilities do Tailwind; layouts complexos viram componentes
- Tratamento de erro: chamadas de API precisam de try-catch
## Comandos
npm run dev      # servidor de desenvolvimento
npm run build    # build de produção
npm run lint     # checagem de código
## Limites
- Não modificar /lib/auth/* (lógica de autenticação)
- Não instalar novos pacotes (precisa de discussão da equipe)

Resultado: depois de usar essa configuração, os componentes gerados pelo Claude ficaram muito próximos da minha estrutura manual, economizando bastante tempo de ajuste.

Caso 2: projeto backend em Node.js

Esta é a configuração de um projeto de API em Express:

# API do sistema de pedidos
## Stack técnica
- Node.js 20 LTS
- Express 4.18
- Prisma ORM
- PostgreSQL 15
- Zod (validação de dados)
## Estrutura do projeto
src/
├── routes/       # definição de rotas
├── controllers/  # lógica de negócio
├── services/     # operações de banco de dados
├── middleware/   # middlewares
└── utils/        # funções utilitárias
## Padrões de código
- Toda API deve incluir: validação da requisição (Zod) + tratamento de erro + registro em log
- Operações de banco ficam sempre na camada services
- Controllers só lidam com requisição e resposta; não escrevem lógica de negócio
- Usar async/await, evitar callbacks
## Exemplo de API
\`\`\`typescript
// controllers/order.controller.ts
export async function createOrder(req: Request, res: Response) {
  try {
    const data = orderSchema.parse(req.body); // validação com Zod
    const order = await orderService.create(data);
    logger.info('Order created', { orderId: order.id });
    res.json({ success: true, data: order });
  } catch (error) {
    logger.error('Create order failed', error);
    res.status(500).json({ success: false, error: 'Internal error' });
  }
}
\`\`\`
## Comandos
npm run dev       # modo de desenvolvimento (nodemon)
npm run build     # compilação TypeScript
npm test          # testes Jest
npx prisma studio # GUI do banco de dados

Resultado: agora os endpoints de API gerados pelo Claude já vêm com validação Zod e tratamento de erro, e a qualidade subiu de forma visível.

Caso 3: arquitetura Monorepo

Este é um projeto Monorepo com frontend e backend:
CLAUDE.md da raiz:

# Monorepo de aplicação full-stack
## Arquitetura
- Usar pnpm workspaces
- apps/: aplicações
- packages/: pacotes compartilhados
## Padrões gerais
- TypeScript em modo estrito
- Formatação unificada com ESLint + Prettier
- Commits seguem Conventional Commits
## Comandos
pnpm install           # instalar todas as dependências
pnpm run dev           # iniciar frontend e backend juntos
pnpm run lint          # checar todos os pacotes
pnpm --filter web dev  # iniciar apenas o app web

apps/web/.claude/CLAUDE.md:

# Configuração do app Web
Herda os padrões da raiz
- Next.js 14 + React
- Porta: 3000
- Padrões detalhados no CLAUDE.md da raiz

apps/api/.claude/CLAUDE.md:

# Configuração do serviço de API
Herda os padrões da raiz
- Express + Prisma
- Porta: 4000
- Padrões detalhados no CLAUDE.md da raiz

Resultado: o Claude consegue trocar o contexto automaticamente conforme o diretório de trabalho. No diretório do frontend, gera código React; no backend, gera código Express.

Conclusão: comece hoje a otimizar seu CLAUDE.md

Depois dessas 7 técnicas, você já deve ter uma visão clara de como escrever um bom CLAUDE.md. Guarde os três pontos mais importantes:

1. Mantenha simples: até 100 linhas, só com informações necessárias
2. Seja específico: cada regra precisa ser executável e verificável
3. Atualize sempre: o projeto muda, então a configuração também precisa mudar
   Pela minha experiência, um bom CLAUDE.md pode aumentar a eficiência do trabalho com IA em pelo menos 30%. Você não precisa escrever tudo de uma vez. Comece pela declaração básica da stack e, sempre que encontrar um erro da IA, adicione uma nova regra ao CLAUDE.md.
   Abra seu projeto agora e crie ou otimize seu CLAUDE.md. Se você ainda não começou a usar o Claude Code, esse arquivo de configuração é um ótimo primeiro passo. Se já usa, mas a IA não está se comportando como deveria, teste as técnicas de hoje.
   Último lembrete: CLAUDE.md não é uma tarefa única. Ele deve crescer junto com o projeto. A cada grande refatoração, atualização de stack ou mudança de padrão, atualize esse arquivo. Para a IA entender de verdade o seu projeto, comece escrevendo bem o CLAUDE.md.