O Guia Definitivo do Arquivo CLAUDE.md: Como Multiplicar Sua Produtividade no Claude Code por 10

O Que É um Arquivo CLAUDE.md e Por Que Importa

Se você está usando o Claude Code sem um arquivo CLAUDE.md, está deixando a maior parte do poder dele em cima da mesa.

O CLAUDE.md é um arquivo de configuração em Markdown que o Claude Code lê automaticamente no início de cada sessão. Ele conta ao Claude sobre a arquitetura do seu projeto, padrões de código, ferramentas preferidas, padrões de teste e regras de fluxo. Em vez de repetir as mesmas instruções a cada conversa, você escreve uma vez e o Claude segue toda vez.

Pense nele como a diferença entre contratar um terceirizado que não sabe nada sobre sua empresa e um que leu seu manual de engenharia inteiro. O arquivo CLAUDE.md é esse manual.

Por Que CLAUDE.md Vence Prompting Repetido

A economia de tokens sozinha é significativa. Se você gasta 500 tokens em configuração de contexto por conversa e tem 20 conversas por dia, isso são 10.000 tokens diários — ou aproximadamente $0,15-$0,75 por dia dependendo do modelo. Em um mês, um arquivo CLAUDE.md te economiza $4,50-$22,50 em custos brutos de API enquanto produz resultados melhores.

Créditos Anthropic | Créditos AWS | Créditos Google Cloud

---

Como o Claude Code Lê Arquivos CLAUDE.md

O Claude Code procura arquivos CLAUDE.md em uma ordem específica de prioridade. Entender essa hierarquia é essencial para organizar suas instruções efetivamente.

Ordem de Carregamento de Arquivos

O Claude Code mescla todos os arquivos aplicáveis. Se seu arquivo global diz "use indentação de 2 espaços" mas seu arquivo de projeto diz "use tabs de 4 espaços," o arquivo de projeto vence para aquele projeto.

O Que Vai Onde

CLAUDE.md global (~/.claude/CLAUDE.md) — preferências que se aplicam em todo lugar:

# Preferências Globais
- Sempre use TypeScript em vez de JavaScript quando possível
- Prefira componentes funcionais em vez de componentes de classe em React
- Escreva mensagens de commit concisas com menos de 72 caracteres
- Use imports ESM, nunca require() do CommonJS

CLAUDE.md do projeto (raiz do projeto) — tudo específico desta base de código:

# Projeto: Acme Dashboard
## Tech Stack
- Next.js 15 com App Router
- TypeScript 5.x strict mode
- Tailwind CSS 4.0
- Prisma ORM com PostgreSQL
- Jest + React Testing Library para testes

## Arquitetura
- /app — rotas Next.js (apenas App Router, sem Pages Router)
- /components — componentes UI reutilizáveis
- /lib — lógica de negócio e utilitários
- /prisma — schema do banco e migrações

---

Criando Seu Primeiro Arquivo CLAUDE.md

Aqui está uma configuração passo a passo para começar com o Claude Code e um arquivo CLAUDE.md configurado adequadamente.

Passo 1: Instale o Claude Code

npm install -g @anthropic-ai/claude-code

Passo 2: Crie CLAUDE.md na Raiz do Projeto

touch CLAUDE.md

Passo 3: Adicione Configuração Básica

Comece com este template mínimo e expanda conforme necessário:

# Projeto: [Nome do Seu Projeto]

## Tech Stack
- [Linguagem/Framework]
- [Banco de Dados]
- [Bibliotecas principais]

## Padrões de Código
- [Preferência de indentação]
- [Convenções de nomenclatura]
- [Ordenação de imports]

## Regras
- Sempre escreva testes para novas funções
- Nunca commite diretamente na main
- Use mensagens de commit convencionais

Passo 4: Rode o Claude Code

claude

O Claude Code detecta e carrega seu arquivo CLAUDE.md automaticamente. Você verá uma confirmação na saída da sessão.

---

Templates CLAUDE.md: Starter, Avançado e Time

Template 1: Projeto Simples (20 Linhas)

Melhor para desenvolvedores solo, projetos paralelos e bases de código pequenas.

# Meu App

## Stack
- Python 3.12, FastAPI, SQLAlchemy, PostgreSQL
- pytest para testes

## Regras
- Use type hints em todas as assinaturas de função
- Escreva docstrings para funções públicas
- Mantenha funções com menos de 30 linhas
- Use async/await para todas as operações de banco
- Formate com black, faça lint com ruff

## Padrões
- Repository pattern para acesso a dados
- Modelos Pydantic para validação de request/response
- Injeção de dependência via FastAPI Depends()

Template 2: Projeto Full-Stack Avançado (80+ Linhas)

Para aplicações em produção com múltiplos desenvolvedores e arquitetura complexa.

# Plataforma SaaS Acme

## Tech Stack
- Frontend: Next.js 15, TypeScript 5.x, Tailwind CSS 4.0
- Backend: Node.js 22, tRPC, Prisma ORM
- Banco: PostgreSQL 16, Redis 7
- Infra: Vercel (frontend), Railway (backend)
- Testes: Vitest, Playwright, MSW

## Arquitetura
Todo código segue princípios de Clean Architecture:
- /packages/web — frontend Next.js (apenas App Router)
- /packages/api — backend tRPC
- /packages/shared — tipos e utilitários compartilhados
- /packages/db — schema e cliente Prisma

## Padrões de Código
- TypeScript estrito: sem any, sem ts-ignore
- Todos os componentes devem ser funcionais com hooks
- Server Components por padrão, "use client" apenas quando necessário
- Todas as rotas de API devem ter validação de entrada com Zod
- Consultas ao banco passam pela camada de repositório, nunca SQL puro

## Requisitos de Teste
- Mínimo de 80% de cobertura para código novo
- Testes unitários para toda lógica de negócio
- Testes de integração para endpoints de API
- Testes E2E para fluxos críticos de usuário
- Use MSW para mock de API, nunca mocke fetch diretamente

## Fluxo Git
- Commits convencionais: feat:, fix:, chore:, docs:
- Todos os PRs exigem CI passando antes do merge
- Squash merge para main
- Nomenclatura de branch: feature/TICKET-123-descricao

## Regras de Segurança
- NUNCA hardcode segredos ou chaves de API
- Sempre use variáveis de ambiente para config
- Sanitize toda entrada de usuário
- Use queries parametrizadas (Prisma cuida disso)
- NUNCA exponha detalhes internos de erro para clientes

Template 3: Configuração de Time (Compartilhada via Git)

Para times que querem comportamento consistente do Claude Code entre todos os membros.

# Padrões de Engenharia do Time — Acme Corp

## Visão Geral
Este arquivo garante que o Claude Code siga os padrões de
engenharia do nosso time. Commitado no Git para que todos os engenheiros
recebam comportamento idêntico.

## Checklist de Code Review (Claude deve seguir antes de sugerir código)
1. Esta mudança tem testes?
2. Casos de erro são tratados?
3. A função está documentada?
4. Segue nossas convenções de nomenclatura?
5. Há alguma implicação de segurança?

## Convenções de Nomenclatura
- Componentes: PascalCase (UserProfile.tsx)
- Hooks: camelCase com prefixo use (useAuth.ts)
- Utils: camelCase (formatDate.ts)
- Constantes: SCREAMING_SNAKE (MAX_RETRIES)
- Tabelas de banco: snake_case (user_profiles)
- Rotas de API: kebab-case (/api/user-settings)

## Padrões Proibidos
- NÃO use console.log em código de produção (use nosso logger)
- NÃO use escapes de TypeScript (any, @ts-ignore)
- NÃO instale dependências novas sem justificativa
- NÃO modifique schema do banco sem arquivo de migração
- NÃO use exports default (use apenas named exports)

## Bibliotecas Preferidas (não sugira alternativas)
- Gerenciamento de estado: Zustand (não Redux)
- Formulários: React Hook Form + Zod (não Formik)
- Cliente HTTP: fetch nativo (não Axios)
- Manipulação de datas: date-fns (não Moment.js)
- Animação: Framer Motion (não React Spring)

---

Comparação: CLAUDE.md vs .cursorrules vs .github/copilot-instructions.md

Se você está avaliando ferramentas de codificação com IA, entender como cada uma lida com configuração é crítico.

O grande diferencial do Claude Code é o ecossistema em volta do CLAUDE.md — hooks, comandos customizados, MCP servers e suporte multi-agente o transformam de um arquivo de configuração em um framework completo de automação.

---

Hooks: Automatizando Seu Fluxo do Claude Code

Hooks são configurados em .claude/settings.json, não no próprio CLAUDE.md. Eles rodam comandos de shell automaticamente antes ou depois de eventos do Claude Code.

Estrutura de Configuração de Hook

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "echo 'File about to be modified'"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH"
      }
    ],
    "PreCommit": [
      {
        "command": "npm run lint && npm run test:changed"
      }
    ]
  }
}

Padrões de Hook Mais Úteis

Exemplos Práticos de Hook

Auto-formatar após cada edição de arquivo:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ]
  }
}

Rodar testes para arquivos modificados:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "npx vitest run --reporter=verbose --changed"
      }
    ]
  }
}

---

Slash Commands Customizados

Slash commands te deixam criar templates de prompt reutilizáveis que gatilham com um único comando /.

Como Criar Slash Commands

1. Crie um diretório .claude/commands/ no seu projeto
2. Adicione arquivos Markdown — cada arquivo vira um comando
3. Use $ARGUMENTS como placeholder para entrada dinâmica

Exemplo: .claude/commands/review.md

Revise o seguinte código procurando:
1. Vulnerabilidades de segurança
2. Issues de desempenho
3. Tratamento de erro ausente
4. Gaps de cobertura de teste

Código para revisar: $ARGUMENTS

Forneça uma classificação de severidade (baixa/média/alta/crítica) para cada achado.

Uso no Claude Code:

/project:review src/auth/login.ts

Ideias Úteis de Slash Commands

---

MCP Servers: Estendendo as Capacidades do Claude Code

MCP (Model Context Protocol) servers conectam o Claude Code a ferramentas e serviços externos. Quando configurado adequadamente, o Claude Code pode consultar bancos de dados, navegar na web, gerenciar arquivos, interagir com GitHub e muito mais — tudo de dentro da sua sessão de codificação.

Como Configurar MCP Servers

MCP servers são configurados em .claude/settings.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://localhost:5432/mydb"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

MCP Servers Mais Populares para Desenvolvedores

Referenciando MCP no CLAUDE.md

Seu CLAUDE.md pode instruir o Claude Code sobre quando e como usar MCP servers conectados:

## Ferramentas Disponíveis
- Use o MCP postgres para checar schema antes de escrever migrações
- Use o MCP github para criar PRs depois de completar feature branches
- Use o MCP memory para rastrear progresso em tarefas multi-passo

---

A Configuração Viral de 27 Agentes: Como um Engenheiro do Google Automatizou 80% do Trabalho

No começo de 2026, a thread no Twitter de um engenheiro do Google viralizou descrevendo como ele configurou 27 agentes Claude Code especializados para lidar com partes diferentes do fluxo dele. Cada agente tinha seu próprio CLAUDE.md com instruções estreitas e focadas.

O Insight Central

Em vez de uma sessão Claude Code de propósito geral tentando fazer tudo, ele decompôs o trabalho em papéis especializados. Cada agente tinha:

• Um CLAUDE.md dedicado com conhecimento específico de domínio
• Acesso a ferramentas restrito (apenas o que aquele agente precisa)
• Limites claros sobre o que deveria e não deveria tocar
• Formatos específicos de saída e padrões de qualidade

Exemplo de Decomposição de Agentes

Como Replicar Essa Configuração

Você não precisa de 27 agentes para se beneficiar desse padrão. Comece com 3-5 configurações especializadas:

1. Crie arquivos CLAUDE.md separados por papel:

.claude/agents/frontend.md
.claude/agents/backend.md
.claude/agents/testing.md

2. Inicie o Claude Code com uma configuração específica:

# Use perfis diferentes combinando contexto global + específico do agente
claude --profile frontend

3. Defina pontos claros de handoff:

Seu CLAUDE.md primário pode referenciar quando trocar de agentes:

## Fluxo de Agentes
- Mudanças de frontend: use o perfil de agente frontend
- Mudanças de API: use o perfil de agente backend
- Após qualquer mudança de código: rode o agente de teste
- Antes de fazer merge: rode o agente de revisão

Por Que Isso Funciona

A abordagem de 27 agentes funciona por causa de um princípio fundamental de produtividade com IA: contexto estreito produz melhor saída que contexto amplo. Uma sessão Claude Code carregada com 400 linhas de instruções sobre frontend, backend, DevOps, testes e documentação vai performar pior em qualquer tarefa única do que uma carregada com 50 linhas altamente relevantes.

---

Erros Comuns no CLAUDE.md (e Como Corrigir)

Erro 1: Ser Vago Demais

Ruim:

Escreva código bom que siga boas práticas.

Bom:

- Use TypeScript strict mode, sem implicit any
- Todas as funções devem ter comentários JSDoc
- Tratamento de erro: envolva operações async em try/catch
- Tamanho máximo de função: 30 linhas

Erro 2: Sobrecarregar Com Instruções

Colocar mais de 500 linhas de instruções faz o Claude Code despriorizar regras importantes. Mantenha seu CLAUDE.md focado.

Erro 3: Não Versionar o CLAUDE.md

Seu CLAUDE.md deve ser commitado no Git. Isso garante:

• Consistência no time
• Histórico de mudanças e responsabilidade
• Rollback fácil se instruções causarem issues
• Revisões de PR para mudanças de instruções

Erro 4: Ignorar a Seção de Segurança

Sempre inclua regras de segurança no seu CLAUDE.md:

## Segurança (CRÍTICO — nunca ignore)
- NUNCA hardcode chaves de API, tokens ou senhas
- NUNCA commite arquivos .env
- SEMPRE use queries parametrizadas de banco
- SEMPRE valide e sanitize entrada de usuário
- NUNCA exponha stack traces ou erros internos para usuários

Erro 5: Esquecer de Mencionar o Tech Stack

O Claude Code pode inferir seu stack a partir do código, mas declarações explícitas previnem suposições erradas:

## Stack (autoritativo — não inferir diferente)
- Runtime: Node.js 22 (NÃO Deno, NÃO Bun)
- Framework: Next.js 15 App Router (NÃO Pages Router)
- ORM: Prisma (NÃO Drizzle, NÃO TypeORM)
- Gerenciador de pacotes: pnpm (NÃO npm, NÃO yarn)

---

Boas Práticas do Claude Code: Dicas de Power User

Dica 1: Use Instruções Condicionais

## Regras Específicas de Ambiente
- Em desenvolvimento: use logging verboso, pule minificação
- Em produção: sem console.log, habilite todas as otimizações
- Em CI: rode suite completa de testes, falhe em qualquer warning

Dica 2: Defina Formatos de Saída

## Quando eu pedir um code review, responda com:
1. **Resumo** (1-2 frases)
2. **Issues encontradas** (em bullets, com severidade marcada)
3. **Correções sugeridas** (com snippets de código)
4. **Nota geral** (A/B/C/D/F)

Dica 3: Defina Limites de Dependências

## Regras de Dependência
- NUNCA instale pacotes com menos de 1.000 downloads semanais
- NUNCA instale pacotes com CVEs conhecidos
- Prefira APIs nativas do Node.js em vez de pacotes de terceiros
- Sempre cheque o impacto no tamanho do bundle antes de adicionar deps de frontend

Dica 4: Use Arquivos de Memória para Projetos Longos

## Memória
- Rastreie todas as features completadas em .claude/memory/features.md
- Logue todas as decisões arquiteturais em .claude/memory/decisions.md
- Atualize o progresso após cada sessão

Dica 5: Integre Com Seu CI/CD

Seu CLAUDE.md pode instruir o Claude Code a respeitar seu pipeline de CI:

## Antes de fazer push de qualquer código:
1. Rode `pnpm lint` — corrija todos os erros
2. Rode `pnpm test` — todos os testes devem passar
3. Rode `pnpm build` — o build deve ter sucesso
4. Cheque o tamanho do bundle — não deve exceder 250KB

---

Quanto o Claude Code Custa? (E Como Conseguir Créditos)

O Claude Code usa créditos de API, o que significa que seus custos dependem de qual modelo você usa e quanto contexto você alimenta.

Detalhamento de Custo do Claude Code

Um dia típico de Claude Code intenso usa 500K-2M tokens, custando $2-$30 dependendo da escolha de modelo. Um CLAUDE.md bem configurado reduz o uso de tokens eliminando contexto repetido.

Conseguindo Créditos Grátis para Claude Code

A melhor forma de financiar seu uso de Claude Code é por programas de créditos:

Créditos empilháveis totais: até $230.000+ entre todos os programas.

Créditos Anthropic | Créditos AWS | Créditos Google Cloud | Créditos Azure

Um único arquivo CLAUDE.md combinado com $5.000-$25.000 em créditos de startup te dá 3-6 meses de desenvolvimento intenso com Claude Code a custo zero. Veja todos os programas de créditos disponíveis em ClaimAICredits para encontrar para o que você qualifica.

---

Referência Rápida: Cheat Sheet do CLAUDE.md

---

Começando Hoje

O arquivo CLAUDE.md é a configuração de maior alavanca que você pode montar para desenvolvimento assistido por IA. Comece com o template simples deste guia, commite no seu repo e itere baseado no que funciona para seu fluxo.

Os engenheiros que estão extraindo mais valor do Claude Code não estão escrevendo melhores prompts — estão escrevendo melhores arquivos CLAUDE.md. A configuração viral de 27 agentes prova que configuração pensada vence prompting força bruta toda vez.

Se os custos de API do Claude Code estão te impedindo de experimentar configurações avançadas como fluxos multi-agente, explore os programas de créditos grátis disponíveis na ClaimAICredits. Empilhar créditos da Anthropic, AWS e Google Cloud pode te dar meses de tempo de desenvolvimento grátis para aperfeiçoar sua configuração do CLAUDE.md.