CLAUDE.md: O Manual de Instruções do Seu Assistente de Código

Você contratou um desenvolvedor senior. Ele é brilhante, conhece dezenas de linguagens, aprende rápido e trabalha 24 horas. Mas ele não conhece seu projeto. Não sabe suas convenções. Não entende por que vocês fazem certas coisas de um jeito específico.

O CLAUDE.md e a carta de boas-vindas que você escreve para esse desenvolvedor.

O Que E o CLAUDE.md

O CLAUDE.md e um arquivo markdown que o Claude Code le automaticamente no inicio de cada sessão. Funciona como a memoria de longo prazo do agente — as instruções que ele sempre deve seguir, independente do que você pedir no momento.

Pense assim: o prompt que você digita e a tarefa do dia. O CLAUDE.md e o onboarding do funcionario.

Onde o Claude procura o arquivo:

CLAUDE.md na raiz do projeto (mais comum)
.claude/CLAUDE.md (organização alternativa)
~/.claude/CLAUDE.md (instruções globais para todos os projetos)
CLAUDE.local.md (pessoal, deve estar no .gitignore)

A hierarquia e respeitada. Instruções globais são carregadas primeiro, depois as do projeto, depois as locais. O mais específico prevalece.

A Estrutura WHY-WHAT-HOW

Um CLAUDE.md eficiente responde três perguntas:

WHY — Por Que Este Projeto Existe

Claude trabalha melhor quando entende o propósito. Não precisa ser longo.

## Proposito

Sistema de gestão de crédito corporativo para o mercado brasileiro.
Foco: empresas de medio porte com faturamento entre R$10M e R$500M.
Diferencial: integração nativa com Receita Federal e Serasa.

O “por que” ajuda Claude a tomar decisões quando as instruções não cobrem um caso específico.

WHAT — O Que Existe Aqui

Mapa do territorio. Claude precisa saber onde encontrar as coisas.

## Estrutura do Projeto

src/ ├── domain/ # Logica de negocio (DDD) │ ├── credit/ # Análise de crédito │ └── customer/ # Gestão de clientes ├── infra/ # Implementacoes tecnicas │ ├── database/ # Repositories (Postgres) │ └── external/ # APIs externas (Serasa, RF) └── api/ # Controllers e rotas


**Tecnologias principais:**
- Node.js 20 + TypeScript 5.3
- PostgreSQL 15 com Prisma ORM
- Jest para testes, Vitest para unitarios rapidos

Dica: Use referência file:line ao inves de copiar código. Claude pode ler os arquivos diretamente.

Veja exemplo de repository em `src/infra/database/CustomerRepository.ts:15-45`

HOW — Como Fazer as Coisas

Comandos, convenções, fluxos. O que Claude precisa para executar.

## Comandos

```bash
npm run dev          # Servidor de desenvolvimento
npm run test         # Todos os testes
npm run test:watch   # Testes em modo watch
npm run lint         # ESLint + Prettier check
npm run db:migrate   # Aplicar migracoes pendentes

Convencoes

Commits: Conventional Commits em português
- feat: adiciona validação de CNPJ
- fix: corrige cálculo de score de crédito
Branches: feature/, fix/, refactor/
PRs: Sempre com descricao e checklist de testes

Verificacao

Antes de considerar qualquer tarefa completa:

npm run lint passa sem erros
npm run test passa
Mudancas estão cobertas por testes


## Melhores Praticas

### 1. Seja Conciso

O limite recomendado e **300 linhas**. O ideal e **menos de 60**. LLMs seguem de forma confiavel entre 150-200 instruções. Apos isso, a aderencia cai.

**Ruim:**
```markdown
## Regras de Código

Sempre use const ao inves de let quando a variavel não for reatribuida.
Sempre use arrow functions para callbacks.
Sempre use template literals ao inves de concatenacao.
Sempre use destructuring quando possível.
Sempre use optional chaining quando acessar propriedades aninhadas.
... (mais 50 regras)

Bom:

## Estilo de Código

Seguimos o preset `@victorino/eslint-config`. Não repita regras do linter aqui.

2. Não Use Como Linter

CLAUDE.md e para o que não pode ser verificado automaticamente. Regras de formatacao devem estar no ESLint, Prettier, ou equivalente.

Use CLAUDE.md para:

Decisoes arquiteturais
Convencoes de negocio
Fluxos de trabalho
Contexto que máquinas não inferem

Não use para:

Regras de indentacao
Ordem de imports
Espacamento
Qualquer coisa que uma ferramenta deterministica valida

3. Progressive Disclosure

Nem tudo precisa estar no CLAUDE.md. Referencie documentacao externa.

## Documentacao

- Arquitetura: `/docs/architecture.md`
- API: `/docs/api.md`
- Deployment: `/docs/deploy.md`

Consulte esses arquivos quando precisar de detalhes específicos.

Claude le os arquivos sob demanda. Você mantem o CLAUDE.md enxuto.

4. Itere Constantemente

Trate o CLAUDE.md como código vivo. Toda vez que Claude erra de forma recorrente, pergunte: “Isso deveria estar no CLAUDE.md?”

Ciclo de melhoria:

Claude comete erro
Você corrige manualmente
Você identifica se e erro recorrente
Você adiciona instrução ao CLAUDE.md
Repete

Algumas equipes pedem ao proprio Claude: “O que deveria estar no CLAUDE.md que teria evitado esse erro?“

5. Use Marcadores de Contexto

Organize com headings claros. Claude processa melhor informação estruturada.

## PROIBIDO

- Nunca commite arquivos `.env`
- Nunca faca push direto para `main`
- Nunca altere migracoes ja aplicadas em producao

## OBRIGATÓRIO

- Todo endpoint deve ter teste de integração
- Todo handler de erro deve logar contexto
- Toda feature deve ter feature flag

Comandos Essenciais

/init — Criação Automatica

No terminal, dentro do projeto:

claude

Depois digite:

/init

Claude analisa seu projeto e gera um CLAUDE.md inicial. Revise e ajuste — o gerado e ponto de partida, não destino final.

/permissions — Gerenciamento de Acesso

/permissions

Controla o que Claude pode fazer sem pedir permissao. Útil para:

Permitir execução automatica de testes
Permitir formatacao automatica
Restringir acesso a pastas sensíveis

/clear — Limpar Contexto

/clear

Quando a conversa fica longa ou confusa, limpa o historico. Claude rele o CLAUDE.md e comeca fresco.

# — Instruções Ad-Hoc

Durante a sessão, você pode adicionar instruções temporarias:

# Estou refatorando o modulo de pagamentos.
# Prefira composicao sobre heranca.
# Mantenha compatibilidade com a API v1.

Essas instruções duram ate o final da sessão ou ate você usar /clear.

Extended Thinking (Atualizado Janeiro 2026)

Importante: A partir de janeiro de 2026, ultrathink foi descontinuado. O budget de thinking agora é máximo por padrão.

O que mudou

Antes, você precisava usar palavras-chave para ativar níveis de raciocínio:

Palavra	Status
`think`	Ainda funciona, mas desnecessário
`think hard`	Ainda funciona, mas desnecessário
`ultrathink`	Descontinuado - não faz mais nada

Comportamento atual

O Claude Code agora usa automaticamente o budget máximo de thinking (31.999 tokens) para todas as solicitações. Você não precisa mais de palavras mágicas.

Dica avançada

Para tarefas extremamente complexas, você pode dobrar o budget de thinking com uma variável de ambiente:

MAX_THINKING_TOKENS=63999 claude

Isso desbloqueia 2x o budget padrão nos modelos Opus 4.5 e Sonnet 4.

No CLAUDE.md

Você não precisa mais configurar modos de raciocínio. Remova instruções antigas sobre ultrathink dos seus arquivos CLAUDE.md.

Workflows Recomendados

Explore, Plan, Code, Commit

O fluxo mais eficiente com Claude Code:

1. Explore

Análise a estrutura atual do modulo de autenticacao.
Quais dependencias existem? Quais padroes são usados?

2. Plan

Preciso adicionar autenticacao por SAML.
Crie um plano detalhado antes de implementar.
Não escreva código ainda.

3. Code

Implemente o plano. Comece pelo adapter de SAML.

4. Commit

Revise as mudancas e crie commits semanticos.

TDD com Claude

Claude e excelente para TDD:

Quero implementar validação de CPF.
Primeiro, escreva os testes. Não implemente ainda.

Revise os testes. Depois:

Agora implemente para passar os testes.

Verificacao Cruzada

Apos implementacao complexa:

Revise criticamente sua propria implementacao.
Liste potenciais problemas, edge cases não cobertos,
e melhorias de performance.

Claude frequentemente encontra problemas que ele mesmo criou.

Multi-Claude Workflows

Para projetos grandes, considere múltiplas instancias:

Git Worktrees

# Cria worktree paralelo
git worktree add ../projeto-feature-auth feature/auth

# Em um terminal
cd ../projeto-feature-auth && claude

# Em outro terminal (projeto principal)
claude

Dois Claudes trabalhando em paralelo, isolados por branches.

Verificacao por Pares

Apos Claude A terminar uma feature:

# No Claude B
Revise o PR #123. Identifique problemas de:
- Segurança
- Performance
- Manutencao
- Cobertura de testes

Dois agentes, perspectivas diferentes.

Exemplos de CLAUDE.md

Projeto Node.js/TypeScript

# Projeto CreditFlow

Sistema de análise de crédito para PMEs brasileiras.

## Stack

- Node.js 20, TypeScript 5.3
- PostgreSQL 15, Prisma ORM
- Express.js, Jest

## Estrutura

src/domain/ # Logica de negocio src/infra/ # Implementacoes src/api/ # HTTP layer


## Comandos

```bash
npm run dev     # Dev server (porta 3000)
npm run test    # Testes
npm run lint    # Verificacao

Convencoes

Commits: Conventional Commits em PT-BR
Testes: Todo código em domain/ precisa de teste
Erros: Use classes de erro customizadas em src/domain/errors/

Verificacao

Antes de finalizar qualquer tarefa:

npm run lint passa
npm run test passa
Mudancas tem cobertura de teste


### Projeto Python/FastAPI

```markdown
# API de Processamento de NFe

Serviço de extração e validação de Notas Fiscais Eletrônicas.

## Stack

- Python 3.11, FastAPI
- PostgreSQL, SQLAlchemy
- Pytest, Ruff

## Ambiente

```bash
source .venv/bin/activate
uvicorn app.main:app --reload

Estrutura

app/
├── domain/     # Entidades e regras
├── services/   # Casos de uso
├── api/        # Rotas FastAPI
└── infra/      # DB, External APIs

Convencoes

Type hints obrigatorios
Docstrings em português para funções publicas
Pydantic para validação de entrada

PROIBIDO

Não use print() para debug (use logging)
Não commite .env
Não faca queries SQL diretas (use SQLAlchemy)


## Erros Comuns

### 1. CLAUDE.md Muito Longo

Se passou de 300 linhas, está errado. Mova detalhes para documentacao separada.

### 2. Repetir Regras do Linter

Se o ESLint ja valida, não precisa estar no CLAUDE.md.

### 3. Instruções Vagas

**Ruim:** "Escreva código limpo"
**Bom:** "Funções com mais de 20 linhas devem ser divididas"

### 4. Não Atualizar

CLAUDE.md desatualizado e é pior que nenhum. Mantenha sincronizado com o projeto.

### 5. Ignorar o .local

Use `CLAUDE.local.md` para preferencias pessoais:

```markdown
# CLAUDE.local.md (no .gitignore)

Sou o Thiago. Prefiro:
- Explicacoes detalhadas
- Commits em português
- Foco em performance

Conclusao

O CLAUDE.md é a ponte entre a inteligência genérica do modelo e o conhecimento específico do seu projeto. Bem escrito, transforma Claude de um assistente genérico em um membro da equipe que conhece suas convenções.

Comece simples. Itere sempre. O CLAUDE.md perfeito não existe — existe o CLAUDE.md que evolui com seu projeto.

No Victorino Group, usamos Claude Code extensivamente para acelerar entregas sem sacrificar qualidade. Se você quer implementar agentes de IA com governanca no seu time, vamos conversar.

O Que E o CLAUDE.md

A Estrutura WHY-WHAT-HOW

WHY — Por Que Este Projeto Existe

WHAT — O Que Existe Aqui

HOW — Como Fazer as Coisas

Convencoes

Verificacao

2. Não Use Como Linter

3. Progressive Disclosure

4. Itere Constantemente

5. Use Marcadores de Contexto

Comandos Essenciais

/init — Criação Automatica

/permissions — Gerenciamento de Acesso

/clear — Limpar Contexto

# — Instruções Ad-Hoc

Extended Thinking (Atualizado Janeiro 2026)

O que mudou

Comportamento atual

Dica avançada

No CLAUDE.md

Workflows Recomendados

Explore, Plan, Code, Commit

TDD com Claude

Verificacao Cruzada

Multi-Claude Workflows

Git Worktrees

Verificacao por Pares

Exemplos de CLAUDE.md

Projeto Node.js/TypeScript

Convencoes

Verificacao

Estrutura

Convencoes

PROIBIDO

Conclusao

Se isso faz sentido, vamos conversar