Fase 04 · Contexto persistente
CLAUDE.md, AGENTS.md e Rules
Escrever o contexto que a IA carrega sempre: quem ela é no seu projeto, quais regras segue, como o sistema funciona.
4.1 "Quem você é" — o contexto sempre presente
Arquivos como CLAUDE.md, AGENTS.md e as rules do editor são carregados em toda interação. Eles carregam:
- Regras e convenções do projeto
- Como o agente deve trabalhar
- Contexto sobre arquitetura e decisões de design
- Padrões obrigatórios
Pense em um employee handbook: o que todo agente precisa saber desde o início.
Exemplos corretos
- "Always use TypeScript strict mode"
- "API calls through services layer"
- "Never use
anytype" - "Errors must be logged to Sentry"
Não coloque aqui
- "How to deploy" → isso é Skill
- "Steps to debug API" → isso é Skill
- "Connect to database" → isso é MCP
4.2 Onde cada ferramenta guarda isso
| Ferramenta | Arquivo | Escopo |
|---|---|---|
| Claude Code | CLAUDE.md | Global (~/.claude) e por projeto |
| Padrão aberto (Cursor, Codex, etc.) | AGENTS.md | Raiz do repositório |
| Cursor (rules) | .cursor/rules/*.mdc | Sempre carregadas ou sob demanda por glob |
O conteúdo é o mesmo; mantenha uma fonte de verdade e referencie nos demais quando o time usa mais de uma ferramenta.
4.3 Context is king — FAZ e NÃO FAZ
Faz
- Descreva o contexto do projeto de forma simples e objetiva
- Explique a arquitetura e a estrutura de pastas
- Defina convenções claras de nomeação, commits e eventos
- Inclua exemplos reais de código, eventos e testes
- Mantenha o arquivo curto (1 a 2 páginas)
- Atualize sempre que houver mudanças importantes
Não faz
- Colocar teoria demais ou conceitos abstratos
- Copiar documentação gigante do sistema
- Incluir regras que ninguém segue na prática
- Deixar informações desatualizadas ou confusas
- Usar termos vagos como "mantenha qualidade"
- Criar regras para cada detalhe minúsculo
4.4 Template mínimo
# CLAUDE.md (ou AGENTS.md)
## Projeto
API de previdência em NestJS + PostgreSQL. Monorepo com
apps/api, apps/workers e libs/shared.
## Arquitetura
- Módulos NestJS por domínio (billing, contracts, users)
- Chamadas externas SEMPRE via services em libs/shared/integrations
- Eventos de domínio via RabbitMQ (padrão em docs/events.md)
## Convenções
- TypeScript strict; proibido `any`
- Commits: imperativo curto ("Add X"), um assunto por commit
- Testes unitários com Jest ao lado do arquivo (*.spec.ts)
- Erros de integração logados no Sentry com contexto do contrato
## Como trabalhar
- Tarefas não triviais: apresente plano antes de editar
- Nunca rode migrations sem confirmar
- Rode `pnpm test` antes de declarar concluídoChecklist da fase
Marque cada item ao concluir. O progresso fica salvo neste navegador.