CLAUDE.md: como um arquivo de texto transforma o Claude Code em um engenheiro sênior

O problema real

Todo agente de IA começa zerado. Não sabe a arquitetura do seu projeto. Não conhece suas convenções. Não entende por que você prefere testes explícitos a mocks inteligentes. Não sabe que seu time usa feature branches e nunca commita direto na main.

Você explica isso na primeira conversa. Funciona. Na segunda conversa, explica de novo. Na terceira, desiste de explicar e aceita o output genérico.

A pergunta não é "o Claude Code é bom o suficiente?" A pergunta é: "você está dando contexto suficiente para ele ser bom?"

O que é o CLAUDE.md

CLAUDE.md é um arquivo de configuração que vive na raiz do seu repositório. Quando o Claude Code abre um projeto, ele lê esse arquivo automaticamente e carrega tudo como contexto persistente.

Pense assim: se o código-fonte é o que o projeto faz, o CLAUDE.md é como o projeto pensa.

Na prática, é onde você documenta:

• Status atual do projeto (o que está pronto, o que falta)
• Preferências de engenharia (DRY, cobertura de testes, nível de abstração)
• Protocolos de trabalho (como fazer code review, como planejar antes de codar)
• Comandos úteis (como rodar testes, migrations, dev server)
• O que não fazer (regras explícitas para evitar erros recorrentes)

O resultado: toda conversa com o Claude Code começa calibrada. Sem repetição. Sem reexplicar o óbvio.

O comando /init

Se você nunca criou um CLAUDE.md, o caminho mais rápido é rodar /init no Claude Code. Ele analisa o codebase e gera um arquivo inicial baseado no que encontra: linguagens, frameworks, estrutura de pastas, scripts existentes.

O output é um ponto de partida. Não é o destino. O valor real do CLAUDE.md vem quando você calibra ele com as decisões que só você conhece: por que o projeto é estruturado assim, quais são os tradeoffs que você aceitou, o que você espera de quem (ou do que) contribui com código.

CLAUDE.md na prática: um exemplo real

Vou mostrar o CLAUDE.md que uso no meu projeto principal. Depois, analiso seção por seção para explicar o raciocínio por trás de cada bloco.

O projeto é o sinal-lab: um monorepo Python + Next.js com API, agentes de IA, pipeline editorial, e um mapa de startups LATAM. 1970 testes Python, 998 testes frontend. O CLAUDE.md evoluiu junto com o projeto ao longo de meses.

---

# CLAUDE.md: Code Review & Plan Mode

> **Mantenha este arquivo conciso.** Cada linha compete por atenção no context window do Claude.
> Revise regularmente. Se remover uma linha não causa erros, remova.

---

## Status do Projeto (Atualizado: 2026-02-22)

**Repositório:** https://github.com/fabianocruz/sinal-lab
**Branch:** feature/startup-map (em progresso)
**Cobertura de Testes:** 1970 testes Python + 998 testes frontend (Vitest)

### Concluído:
- ✅ Estrutura inicial do projeto + repositório GitHub
- ✅ Routers da API testados (7/7 = 100%, inclui auth + waitlist)
- ✅ Pacote editorial testado (3/3 = 100%)
- ✅ Sistema de agentes documentado e testado
- ✅ Newsletter SSR dinâmica (API → frontend com paginação)
- ✅ Seed expandido (20 newsletters, 5 agents, 5 meses)
- ✅ Logout + área do usuário (UserMenu dropdown + /conta)
- ✅ Waitlist-auth unificado (form auth-aware + upgrade waitlist→active)
- ✅ Agente INDEX: pipeline de dados de startups LATAM (collectors, pipeline, scorer, persistência)
- ✅ Startup Map: /startups listing + /startup/[slug] páginas de detalhe
- ✅ API de Companies: envelope paginado, busca, filtros por tags, schema expandido (22 campos)
- ✅ SEO: JSON-LD Organization, sitemap assíncrono com páginas de empresas
- ✅ Paginação Generalizada + SearchBar com prop `basePath`

### Próximos Passos:
- Rodar testes antes de cada commit: `pytest apps/ packages/ -v && pnpm test`
- Manter branch main estável (sem commits diretos, exceto hotfixes)

---

## Preferências de Engenharia

IMPORTANTE: use estas para guiar toda recomendação, revisão e mudança de código.

- **DRY é importante.** Aponte repetição agressivamente.
- **Código bem testado é inegociável.** Prefiro testes demais a testes de menos.
- **"Engenharia na medida":** nem sub-engenharia (frágil, gambiarra) nem super-engenharia (abstração prematura, complexidade desnecessária).
- **Cubra mais edge cases, não menos.** Cuidado > velocidade.
- **Explícito sobre esperto.** Priorize legibilidade.
- **Legibilidade sobre esperteza.** Se é difícil de seguir, simplifique.

---

## Plan Mode: Protocolo de Code Review

Revise este plano a fundo antes de fazer qualquer mudança no código. Para cada issue ou recomendação, explique os tradeoffs concretos, dê uma recomendação com opinião, e peça meu input antes de assumir uma direção.

### ANTES DE COMEÇAR

Pergunte se eu quero uma de duas opções:

1. **MUDANÇA GRANDE:** Trabalhar interativamente, uma seção por vez (Arquitetura → Qualidade de Código → Testes → Performance) com no máximo 4 issues por seção.
2. **MUDANÇA PEQUENA:** Trabalhar interativamente com UMA pergunta por seção.

### 1. Revisão de Arquitetura

Avalie:

- Design geral do sistema e fronteiras entre componentes
- Grafo de dependências e problemas de acoplamento
- Padrões de fluxo de dados e gargalos potenciais
- Características de escala e pontos únicos de falha
- Arquitetura de segurança (auth, acesso a dados, fronteiras da API)

### 2. Revisão de Qualidade de Código

Avalie:

- Organização do código e estrutura de módulos
- Violações de DRY. Seja agressivo aqui.
- Padrões de tratamento de erro e edge cases ausentes (aponte explicitamente)
- Hotspots de débito técnico
- Áreas super-engenheiradas ou sub-engenheiradas relativo às minhas preferências

### 3. Revisão de Testes

Avalie:

- Lacunas de cobertura (unitários, integração, e2e)
- Qualidade dos testes e força das assertions
- Cobertura de edge cases ausentes. Seja minucioso.
- Modos de falha e caminhos de erro não testados

### 4. Revisão de Performance

Avalie:

- Queries N+1 e padrões de acesso ao banco
- Preocupações com uso de memória
- Oportunidades de cache
- Caminhos de código lentos ou de alta complexidade

### Para Cada Issue Encontrada

Para cada issue específica (bug, smell, concern de design, ou risco):

1. **Descreva o problema concretamente**, com referência a arquivo e linha.
2. **Apresente 2–3 opções**, incluindo "não fazer nada" quando razoável.
3. **Para cada opção especifique:** esforço de implementação, risco, impacto em outro código, e custo de manutenção.
4. **Dê sua opção recomendada e porquê**, mapeada às minhas preferências acima.
5. **Então pergunte explicitamente** se eu concordo ou quero escolher outra direção antes de prosseguir.

### Regras de Interação

- NUMERE todas as issues (ex: Issue #1, Issue #2).
- Dê LETRAS para opções (ex: A, B, C).
- Ao usar AskUserQuestion, rotule claramente cada opção com o NÚMERO da issue e a LETRA da opção.
- IMPORTANTE: A opção recomendada deve ser sempre a 1ª opção.
- Não assuma minhas prioridades de prazo ou escala.
- Após cada seção, pause e peça meu feedback antes de avançar.

---

## Padrões de Workflow

### Planeje Antes de Codar

Para qualquer coisa além de mudanças triviais:

1. **Explore:** leia os arquivos relevantes, entenda o contexto. NÃO escreva código ainda.
2. **Planeje:** pense bem na abordagem. Proponha um plano com tradeoffs. Use um arquivo scratchpad (`PLAN.md`) para tarefas complexas.
3. **Implemente:** somente após eu aprovar o plano. Verifique a corretude durante a implementação.
4. **Teste:** rode os testes. Se falharem, itere até passarem.
5. **Commite:** escreva uma mensagem de commit descritiva. Atualize docs se necessário.

### Test-Driven Development (Preferência)