🔄 Atualizar Constantemente o Claude.md
O claude.md é carregado no início de toda conversa. Cada nova descoberta, padrão identificado, pegadinha do projeto ou convenção da equipe que não está lá representa um potencial erro repetido na próxima sessão. Mantenha-o atualizado como se fosse o manual de operação do seu projeto.
🧠 O Claude.md como Memória Persistente
Diferente da memória de uma sessão — que se perde quando você fecha — o claude.md persiste entre sessões. É o único mecanismo de aprendizado contínuo do Claude sobre o seu projeto específico.
- • Novos padrões: "Sempre usar transações no banco ao modificar mais de uma tabela"
- • Pegadinhas: "O campo `created_at` usa timezone UTC mas a API retorna local — sempre converter"
- • Skills descobertas: referência às skills criadas em .claude/skills/
- • Convenções: "Testes de integração ficam em /tests/integration, não em /src"
sem valor default. Adicione isso no claude.md para eu não
errar de novo."
Claude: [Atualiza claude.md com a regra]
# Próxima sessão: Claude já sabe essa regra automaticamente
⚠️ Cuidado com o Inchaço
O claude.md é carregado em toda conversa — cada linha é token pago. Limite prático: 150–200 linhas. Se passar disso, corte o que não é essencial, mova detalhes para arquivos separados (ver Hack 15) e mantenha apenas o que é realmente crítico para o dia a dia.
Quando Atualizar o Claude.md
Após descobrir um padrão não óbvio
Comportamento inesperado do sistema, quirks da stack, limitações de bibliotecas.
Após criar uma nova skill ou convenção de equipe
O claude.md deve mencionar as skills disponíveis e quando usá-las.
Após corrigir um erro que o Claude cometeu pela segunda vez
Se o Claude errou da mesma forma duas vezes, documente a regra correta no claude.md.
Após mudanças arquiteturais ou de processo
Nova estrutura de diretórios, novo padrão de código, nova ferramenta adotada pela equipe.
✓ O que FAZER
- ✓Atualizar após cada descoberta relevante
- ✓Manter abaixo de 200 linhas
- ✓Escrever regras no estilo de instrução direta
- ✓Incluir exemplos de casos reais do projeto
✗ O que NÃO fazer
- ✗Deixar crescer sem limite (inchaço)
- ✗Colocar documentação técnica detalhada diretamente
- ✗Escrever em estilo de README (muito descritivo)
- ✗Deixar informações desatualizadas sem remover
🗂️ Claude.md Apontando para Outros Arquivos
O claude.md não precisa conter tudo — ele precisa saber onde tudo está. Mantenha o arquivo principal enxuto e crie links para documentos separados: guias de estilo, contexto de negócio, especificações de API. O Claude acessa esses arquivos quando precisar deles, não em toda sessão.
🗺️ Claude.md como Índice, Não como Enciclopédia
A distinção é crucial: o que entra no claude.md principal são regras operacionais do dia a dia. O que vai em arquivos separados são referências detalhadas consultadas sob demanda.
- • claude.md: regras, convenções, links para documentos de referência
- • docs/style-guide.md: guia de estilo de código, padrões de nomenclatura
- • docs/business-context.md: domínio do negócio, glossário, regras de negócio
- • docs/api-reference.md: endpoints, contratos, exemplos de request/response
## Regras Operacionais
- Sempre usar transações ao modificar Orders e Payments juntos
- Campos de valor monetário sempre em centavos (inteiros)
- Nunca logar dados de cartão, nem parcialmente
## Referências
- Estilo de código: docs/style-guide.md
- Domínio de negócio: docs/business-context.md
- API completa: docs/api-reference.md
- Skills disponíveis: .claude/skills/
📊 Por que Separar em Arquivos
- Custo: guia de estilo com 300 linhas carregado em toda sessão é tokens desperdiçados
- Relevância: contexto de negócio só é necessário em tarefas de domínio, não em debugging
- Manutenção: cada documento tem sua própria vida útil e responsável
- Clareza: o claude.md principal fica legível e fácil de revisar
💡 Dica Prática
Use uma seção dedicada "## Referências" no claude.md com links relativos para os documentos separados. Quando o Claude precisar de informação detalhada, ele lê o arquivo referenciado. O prompt de sistema permanece enxuto, mas o conhecimento disponível é completo.
✓ O que FAZER
- ✓Criar seção "Referências" no claude.md
- ✓Usar links relativos (funcionam no repo)
- ✓Documentos separados por domínio (estilo, negócio, API)
- ✓Manter o claude.md principal abaixo de 200 linhas
✗ O que NÃO fazer
- ✗Copiar documentação inteira no claude.md
- ✗Criar arquivos externos sem referenciar no claude.md
- ✗Misturar regras operacionais com documentação de referência
- ✗Usar links absolutos que quebram em outros ambientes
✅ Resumo do Módulo 2.2
Próximo Módulo:
2.3 — Controle e Correção de Rota: interrompa cedo, questione resultados medíocres e use /rewind quando necessário.