Dominar o CLAUDE.md

A maioria dos conselhos sobre o CLAUDE.md erra na função do ficheiro. Vais ler que ele serve para fazer o onboarding do Claude ao teu codebase. Listar a stack tecnológica. Meter os comandos principais. Esboçar a estrutura de pastas. Alguns guias até recomendam manter o ficheiro abaixo de 60 linhas.

Essa perspetiva engana-se no que o ficheiro realmente é.

Pensa no CLAUDE.md como um ficheiro de controlo que governa o comportamento do Claude. Define como o modelo funciona, como uma conversa é gerida, e como o trabalho flui entre o agente central e os seus auxiliares. Os factos sobre a tua stack pertencem a outro lado. As skills são esse outro lado. Carregam quando são relevantes, trazem exatamente o que é preciso, e saem quando o trabalho está feito.

Dois Paradigmas: Onboarding vs. Orquestração

A Abordagem Inferior: Onboarding do Projeto

A leitura convencional é que o CLAUDE.md deve "fazer o onboarding do Claude ao teu codebase." Respondes três questões para o modelo: O QUE é a stack tecnológica, PORQUÊ o projeto existe, e COMO o executar. Alguns guias recomendam manter o ficheiro todo abaixo de 60 linhas.

Várias coisas partem quando fazes assim:

Saturação de prioridades: Tudo dentro do CLAUDE.md ocupa alta prioridade na janela de contexto. O modelo trata o ficheiro inteiro como autoritário. Enfia todas as regras lá dentro e cada linha passa a competir com cada outra linha por esse mesmo lugar de topo. As tuas notas sobre React colidem com as convenções da API enquanto estás a trabalhar numa migração de base de dados. Quando tudo é alta prioridade, nada o é.

Desperdício de contexto: Um CLAUDE.md cheio de padrões React para a tua app React ainda carrega em cada sessão. Mesmo nas que o trabalho é um script de deployment ou uma alteração de schema.

Sem controlo comportamental: Listar a stack tecnológica não diz nada sobre como o Claude deve abordar um problema. Nada sobre delegar trabalho. Nada sobre gerir um trabalho em várias etapas.

Repetição entre projetos: Cada novo repositório gera um novo CLAUDE.md, e cada novo CLAUDE.md diverge do anterior. O AI acaba por agir de forma diferente de projeto para projeto.

Conhecimento estático: Os docs do projeto ficam desatualizados. Um padrão de API que escreveste há meio ano pode não ter nada a ver com como o código funciona hoje.

O onboarding enquadra o Claude como um contratado a ser briefado para o trabalho da manhã. A orquestração enquadra o Claude como um sistema em execução que precisa de ter os seus parâmetros definidos.

A Abordagem Superior: Camada de Orquestração

O CLAUDE.md deve definir:

1. Fluxos de trabalho operacionais - A sequência que o Claude segue para cada pedido
2. Estratégia de gestão de contexto - Como conservar e alocar contexto de forma eficaz
3. Padrões de delegação - Quando usar sub-agentes vs. tratar diretamente
4. Padrões de qualidade - Práticas de código, gestão de erros, requisitos de segurança
5. Protocolos de coordenação - Como gerir trabalho paralelo vs. sequencial

A tua stack, os teus padrões, as tuas convenções vivem dentro de skills que carregam dinamicamente quando são relevantes. Separar as coisas dessa forma dá-te:

• Comportamento consistente do AI em todos os projetos
• Uso eficiente de contexto - o conhecimento de domínio carrega apenas quando necessário
• Expertise portátil - as skills transferem-se entre projetos
• Conhecimento manutenível - atualiza uma skill uma vez, beneficia em todo o lado

Estruturar o Teu CLAUDE.md

Secção de Princípios Base

Começa com os comportamentos fundamentais que queres do teu AI. Estes devem aplicar-se universalmente, independentemente do projeto ou tarefa em que estás a trabalhar.

## Core Principles
 
### Skills-First Workflow
 
**EVERY user request follows this sequence:**
 
Request → Load Skills → Gather Context → Execute
 
Skills contain critical workflows and protocols not in base context.
Loading them first prevents missing key instructions.
 
### Context Management Strategy
 
**Central AI should conserve context to extend pre-compaction capacity**:
 
- Delegate file explorations and low-lift tasks to sub-agents
- Reserve context for coordination, user communication, and strategic decisions
- For straightforward tasks with clear scope: skip heavy orchestration, execute directly
 
**Sub-agents should maximize context collection**:
 
- Sub-agent context windows are temporary
- After execution, unused capacity = wasted opportunity
- Instruct sub-agents to read all relevant files, load skills, and gather examples

Estes são os comportamentos que disparam em cada interação. Não trivia do projeto que pode ou não importar hoje.

Lógica de Roteamento e Delegação

Define quando o Claude deve tratar o trabalho diretamente versus delegar a especialistas:

### Routing Decision
 
**Direct Execution**:
 
- Simple/bounded task with clear scope
- Single-component changes
- Quick fixes and trivial modifications
 
**Sub-Agent Delegation**:
 
- Complex/multi-phase implementations
- Tasks requiring specialized domain expertise
- Work that benefits from isolated context
 
**Lead Orchestrator**:
 
- Ambiguous requirements needing research
- Architectural decisions with wide impact
- Multi-day features requiring session management

Com o roteamento escrito, o Claude toma decisões reais sobre quem faz o quê. Nada de fazer tudo sozinho. Nada de delegar trabalho por delegar.

Protocolos Operacionais

Define como o Claude deve coordenar trabalho, especialmente quando o paralelismo é possível:

## Operational Protocols
 
### Agent Coordination
 
**Parallel** (REQUIRED when applicable):
 
- Multiple Task tool invocations in single message
- Independent tasks execute simultaneously
- Bash commands run in parallel
 
**Sequential** (ENFORCE for dependencies):
 
- Database → API → Frontend
- Research → Planning → Implementation
- Implementation → Testing → Security
 
### Quality Self-Checks
 
Before finalizing code, verify:
 
- All inputs have validation
- Authentication/authorization checks exist
- All external calls have error handling
- Import paths verified against existing codebase examples

Padrões e Práticas de Código

Inclui princípios universais de código que devem governar todo o trabalho:

## Coding Best Practices
 
**Priority Order** (when trade-offs arise):
Correctness > Maintainability > Performance > Brevity
 
### Task Complexity Assessment
 
Before starting, classify:
 
- **Trivial** (single file, obvious fix) → execute directly
- **Moderate** (2-5 files, clear scope) → brief planning then execute
- **Complex** (architectural impact, ambiguous requirements) → full research first
 
Match effort to complexity. Don't over-engineer trivial tasks or under-plan complex ones.
 
### Integration Safety
 
Before modifying any feature:
 
- Identify all downstream consumers using codebase search
- Validate changes against all consumers
- Test integration points to prevent breakage

O Diretório de Regras: Instruções Modulares

A partir do Claude Code v2.0.64, tens outra opção para organizar instruções: o diretório .claude/rules/. As regras resolvem o problema de saturação ao deixar-te espalhar instruções de alta prioridade por ficheiros com um âmbito restrito.

Insight-chave da Anthropic: Um ficheiro de regras ocupa a mesma alta prioridade que um ficheiro CLAUDE.md. O que muda é que podes apontar essa prioridade com um padrão de caminho. A regra só ativa enquanto os ficheiros correspondentes estão em âmbito.

Quando as Regras Vencem o CLAUDE.md

As regras valem a pena no momento em que as tuas instruções têm limites de domínio:

.claude/rules/
├── api-guidelines.md     # Only relevant for API work
├── react-patterns.md     # Only relevant for frontend
├── testing-rules.md      # Only relevant for test files
└── security-rules.md     # Only relevant for auth/payment code

Cada ficheiro vive na memória do projeto. A diferença é que podes fixar uma regra a um padrão de ficheiro:

---
paths: src/api/**/*.ts
---
 
# API Development Rules
 
- All endpoints must validate input with Zod
- Return consistent error shapes

Essa regra só dispara quando o Claude toca num ficheiro de API. No frontend, as tuas convenções de API ficam em silêncio.

A Hierarquia de Prioridade das Instruções

Imagina como camadas. Cada camada combina um nível de prioridade com uma regra de carregamento:

CLAUDE.md contém o comportamento universal que queres a alta prioridade constante. Regras contêm as coisas específicas de domínio, e obtêm essa prioridade apenas enquanto os ficheiros certos estão abertos. Skills contêm expertise portátil a prioridade média, carregadas on-demand.

Queres a versão aprofundada, incluindo targeting de caminhos e táticas de migração? Lê o guia do Diretório de Regras.

Carregar CLAUDE.md de Diretórios Adicionais

Desde o Claude Code v2.1.20, o Claude pode puxar ficheiros CLAUDE.md de diretórios fora do teu projeto ativo. Útil para monorepos, convenções partilhadas de equipa, e configurações multi-projeto.

Como funciona:

# Enable the feature and specify additional directories
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-standards
 
# Multiple directories work too
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config ../team-rules

Com a flag ativada, o Claude puxa estes ficheiros de cada diretório extra:

• Ficheiros CLAUDE.md
• Ficheiros .claude/CLAUDE.md
• Ficheiros .claude/rules/*.md

Porque isto supera apontar verbalmente o Claude para um ficheiro:

Através de --add-dir, ficheiros CLAUDE.md externos tornam-se memória real do sistema em vez de preenchimento de conversa. Carregam sozinhos, sobrevivem a reinicios de sessão, e sentam-se dentro da hierarquia de prioridade.

Casos de uso práticos:

Monorepo com padrões partilhados:

company/
├── shared-standards/
│   └── CLAUDE.md          # Company coding guidelines
├── apps/
│   ├── web/
│   │   └── CLAUDE.md      # Web-specific rules
│   └── api/
│       └── CLAUDE.md      # API-specific rules

Do diretório web/:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../../shared-standards

Consistência cross-project: Coloca os teus padrões pessoais de desenvolvimento numa pasta central e puxa-os para qualquer projeto. Sem ficheiros copiados.

Onboarding de equipa: Novos colegas apontam para um diretório partilhado de convenções da equipa. Isso elimina o problema de "cada projeto tem um CLAUDE.md ligeiramente diferente".

Hierarquia de prioridade atualizada:

Nota: A funcionalidade só funciona quando CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 está definido. Sozinha, a flag --add-dir apenas concede acesso a ficheiros nesses diretórios. Não carrega os ficheiros CLAUDE.md dentro deles.

Sintaxe @import: Uma Alternativa Mais Simples

--add-dir entrega-te um diretório externo inteiro. Para puxar um ficheiro de cada vez, há uma opção mais leve. Os ficheiros CLAUDE.md suportam a sintaxe @caminho/para/importação para memória composável:

See @README for project overview and @package.json for available npm commands.
 
# Standards
 
- coding guidelines @docs/coding-standards.md
- git workflow @docs/git-instructions.md

Caminhos relativos e absolutos funcionam ambos. Um caminho relativo resolve a partir do ficheiro que importa, não do teu diretório de trabalho.

Como isto difere de --add-dir:

Aprovação na primeira vez: A primeira vez que o Claude Code encontra importações dentro de um projeto, aparece um diálogo de aprovação que lista cada ficheiro. É uma decisão única por projeto. Rejeita-o e o diálogo nunca mais aparece. Essas importações ficam desativadas.

Importações recursivas: Um ficheiro importado pode importar mais ficheiros, com uma profundidade máxima de 5 saltos. É assim que se constroem conjuntos de instruções em camadas:

# CLAUDE.md imports standards.md
 
@.claude/standards.md
 
# standards.md imports sub-files
 
@.claude/standards/api.md
@.claude/standards/testing.md

As importações são ignoradas dentro de spans de código markdown e blocos de código delimitados. Um exemplo de código que mencione @caminho não vai disparar acidentalmente um carregamento.

CLAUDE.local.md: Preferências Pessoais do Projeto

Para preferências que não queres na árvore partilhada da equipa, usa o CLAUDE.local.md. O ficheiro é adicionado automaticamente ao .gitignore e carrega mesmo ao lado do CLAUDE.md com a mesma prioridade.

Bons casos de uso:

• URLs do teu servidor de dev local e endpoints de sandbox
• Preferências pessoais de dados de teste
• Convenções de naming de branches que preferes
• Configurações de editor e ferramentas específicas da tua configuração

Dica para git worktree: CLAUDE.local.md só vive numa única worktree. Puxa uma importação do teu diretório home e as mesmas instruções pessoais acompanham-te em cada worktree que abres:

# CLAUDE.local.md
 
@~/.claude/my-project-instructions.md

Ver a Memória Carregada com /memory

Corre /memory para listar os ficheiros atualmente presentes no contexto do Claude, ou para abrir qualquer ficheiro de memória carregado no teu editor. Recorre a isto quando uma instrução parece estar em falta no comportamento do modelo. Recorre de novo quando quiseres provar que uma cadeia de importações e as tuas regras estão a funcionar corretamente.

Skills: Onde Vive o Conhecimento de Domínio

As skills são a outra metade da equação. O CLAUDE.md define como o Claude opera. As skills fornecem o que o Claude sabe sobre um domínio específico.

A Arquitetura das Skills

A Anthropic enquadra a distinção diretamente: "Os projetos dizem 'aqui está o que precisas de saber.' As skills dizem 'aqui está como fazer as coisas.'"

As skills usam divulgação progressiva:

1. Os metadados carregam primeiro (~100 tokens) - suficiente para saber quando a skill é relevante
2. As instruções completas carregam quando necessário (<5k tokens)
3. Os ficheiros/scripts incluídos carregam apenas quando necessário

Por causa desse design, podes ter dezenas de skills à mão sem explodir a janela de contexto. O Claude vai buscar exatamente a peça de que precisa, no momento em que precisa.

O Que Pertence às Skills

Padrões tecnológicos:

• Convenções de framework (padrões React, design de API)
• Operações de base de dados e migrações
• Estratégias de teste e utilitários

Fluxos de trabalho de domínio:

• Integrações de processamento de pagamentos
• Implementações de autenticação
• Procedimentos de deployment

Contexto específico do projeto:

• Guias de navegação no codebase
• Documentação de arquitetura
• Convenções da equipa

Exemplo: Separar as Responsabilidades

Em vez de meter isto no CLAUDE.md:

## About This Project
 
FastAPI REST API for user authentication.
Uses SQLAlchemy for database operations.
 
## Commands
 
uvicorn app.main:app --reload
pytest tests/ -v

Cria uma skill backend-api:

# Backend API Development Skill
 
## Framework
 
FastAPI with SQLAlchemy ORM, Pydantic validation.
 
## Development Commands
 
- `uvicorn app.main:app --reload` - Start dev server
- `pytest tests/ -v` - Run test suite
- `alembic upgrade head` - Apply migrations
 
## Patterns
 
[Detailed patterns, examples, conventions...]

O teu CLAUDE.md referencia o sistema de skills:

### Key Skills
 
`backend-api`, `frontend-react`, `database-ops`, `deployment`
 
Load relevant skills before beginning domain-specific work.

Agora os detalhes do backend só aparecem durante trabalho de backend. O contexto fica livre para o resto do trabalho. O ClaudeFast's Code Kit já vem com um CLAUDE.md de produção neste formato. Roteamento skills-first, uma avaliação de complexidade a 5 níveis, e otimização de contexto vêm incluídos por padrão.

O Debate do Número de Linhas

Uma perspetiva popular diz que o CLAUDE.md deve ficar abaixo de 60 linhas, porque o Claude alegadamente "ignora" qualquer coisa mais longa. Essa leitura de como o Claude lida com contexto está errada.

A realidade: A Anthropic recomenda que os ficheiros de skill fiquem abaixo de 500 linhas. Se uma skill que só carrega on-demand pode usar bem 500 linhas, um CLAUDE.md que carrega sempre pode certamente absorver 200 a 400 linhas de detalhe operacional.

A brevidade não é a coisa a otimizar. A relevância é. Sessenta linhas de trivia do projeto que não se aplica à tarefa de hoje consome mais contexto efetivo do que 300 linhas de regras operacionais universais.

O ponto ideal são 200-400 linhas de:

• Fluxos de trabalho operacionais (sempre relevantes)
• Lógica de roteamento (sempre relevante)
• Padrões de qualidade (sempre relevantes)
• Protocolos de coordenação (sempre relevantes)

Sessenta linhas de especificidades do projeto, metade das quais são peso morto em qualquer pedido, é o pior dos dois mundos.

Evolução do Framework

Bake instruções de auto-melhoria no ficheiro:

### Framework Improvement
 
**Recognize patterns that warrant updates:**
 
**Update existing skill when**:
 
- A workaround was needed for something the skill should have covered
- New library version changes established patterns
- A better approach was discovered during implementation
 
**Create new skill when**:
 
- Same domain-specific context needed across 2+ sessions
- A payment processor, API, or tool integration was figured out
- Reusable patterns emerged that will apply to future projects
 
**Action**: Prompt user with: "This [pattern/workaround/integration] seems
reusable. Should I update [skill] or create a new skill to capture this?"

O resultado é um sistema que melhora a si próprio. O Claude sinaliza os momentos que vale a pena transformar numa nova skill ou numa atualização de uma existente.

Porque Esta Abordagem Funciona

Orquestração Multi-Agente

O trabalho moderno com Claude Code apoia-se cada vez mais em sub-agentes: instâncias especializadas a executar trabalhos discretos. O teu CLAUDE.md é o que diz ao modelo central como gerir essa equipa.

Segundo a Anthropic, o Opus 4.5 foi treinado especificamente para gerir uma equipa de sub-agentes. Aproveita esse treino dentro do teu CLAUDE.md especificando:

• Quando delegar vs. tratar diretamente
• Como construir prompts de sub-agentes
• Como os resultados dos sub-agentes fluem de volta para a conversa principal

Economia de Contexto

A tua janela de contexto tem um teto. Cada byte de documentação do projeto que deitas no CLAUDE.md é um byte que não pode ser gasto no trabalho real. A orquestração é como gastas esse orçamento bem:

• CLAUDE.md: Instruções operacionais (sempre necessárias)
• Skills: Conhecimento de domínio (carregado on-demand)
• Sub-agentes: Contexto fresco para trabalho especializado

Consistência Entre Projetos

Quando o ficheiro codifica comportamento em vez de trivia do projeto, o AI comporta-se da mesma forma em cada trabalho. Roteamento, barras de qualidade, e hábitos de coordenação todos se transferem. Uma app React recebe o mesmo tratamento que uma CLI Python.

Referência Rápida

Request → Load Skills → Route Decision → Execute

Roteamento:

• Tarefa simples/delimitada → Execução direta
• Complexo/multi-fase → Delegação a sub-agente ou gestão de sessão

O CLAUDE.md Contém:

• Fluxos de trabalho operacionais
• Estratégia de gestão de contexto
• Lógica de roteamento e delegação
• Padrões de qualidade
• Protocolos de coordenação

As Skills Contêm:

• Especificidades da stack tecnológica
• Padrões de framework
• Convenções do projeto
• Fluxos de trabalho de domínio

Próximos Passos

1. Audita o teu CLAUDE.md atual: É documentação do projeto ou instruções operacionais?

2. Extrai o conhecimento de domínio para skills: Move a stack tecnológica, padrões, e convenções para fora do CLAUDE.md

3. Define os teus fluxos de trabalho operacionais: Como deve o Claude abordar cada pedido?

4. Estabelece a lógica de roteamento: Quando deve o Claude delegar vs. tratar diretamente?

5. Define padrões de qualidade: Que práticas devem governar todo o trabalho?

Lembra-te: O CLAUDE.md não é um documento que o Claude lê. É o sistema em que o Claude corre. Define o comportamento, empurra o conhecimento para as skills, e deixa o conjunto todo continuar a melhorar-se ao longo do tempo.

Queres o manual completo por cima destes princípios? Lê as nossas 5 melhores práticas de Claude Code que separam os melhores developers.