O sistema de contexto que impede o Claude de derivar

Trabalhe com um agente por mais de alguns dias e você bate no mesmo muro: ele esquece cada decisão que você tomou, e uma feature nova quebra outras três. Fiquei consertando essa mesma dor de novo e de novo, até perceber que o conserto já estava no meu repo, meio montado sem querer. Aqui está a versão real, dos meus próprios projetos, e os dois arquivos que de fato me faltavam.

Por que ele deriva

Um agente não tem memória entre sessões. Cada chat novo começa do zero. Você explica o projeto, ele toma decisões razoáveis, ele anda. Amanhã você abre outro chat e ele não lembra de nada: nem da stack, nem de por que você escolheu aquela biblioteca, nem do que não pode ser tocado. Então você explica de novo, ele chuta de novo, e aos poucos o código começa a se contradizer. A IA não é burra. Você está pedindo que ela lembre de algo que você nunca salvou em lugar nenhum.

A ideia: arquivos que viajam com o repo

O conserto não é um prompt mais longo. É um conjunto de arquivos que o agente lê antes de fazer qualquer coisa, e que ficam no repo para sempre. Outro dia, outro agente, outro colega: todo mundo começa do mesmo contexto. Aqui está mais ou menos o meu:

my-project/
├── CLAUDE.md                  # o que o projeto é e o que ele NÃO é
├── .claude/
│   ├── agent-trust-policy.md  # regras: o que o agente nunca pode fazer
│   └── settings.json          # hooks que bloqueiam comandos perigosos
├── design.md                  # design tokens (cores, tipografia)
├── code-standards.md          # convenções de código (o que me faltava)
└── docs/
    ├── architecture.md        # stack, limites, invariantes
    └── specs/
        └── 01-login.md        # uma unidade por vez

• CLAUDE.md — o que o produto é, para quem ele é, e o que está deliberadamente fora do escopo. A primeira coisa que o agente lê.
• agent-trust-policy.md — as regras de comportamento: o que o agente nunca pode fazer (deletar fora da sua área, mexer em segredos, dar push na main sem PR).
• design.md — os design tokens, para ele não inventar cores nem fontes.
• architecture.md — a stack, os limites entre camadas e as invariantes que o código nunca quebra.
• docs/specs/ — uma spec por unidade de trabalho. A peça que de fato muda as coisas.

O loop: uma unidade por vez

Aqui está a virada de chave. Você não diz ao agente "construa o dashboard". Você escreve uma spec pequena, com um objetivo, as decisões, o que não pode ser tocado, e um checklist do que precisa ser verdade para considerar pronto:

# Spec: login por email

## Goal
O usuário consegue se cadastrar e fazer login com email. Nada mais.

## Decisions
- Auth com Clerk (já instalado).
- Não mexer na navbar nem na sidebar.

## Implementation
- Criar /login e /signup com componentes do Clerk.
- Proteger todas as rotas exceto /login e /signup.

## Checklist (verificar antes de fechar)
- [ ] Rotas protegidas por padrão
- [ ] Nenhuma cor hardcoded (usar os tokens de design.md)
- [ ] npm run build passa

Aí você entrega a spec em um prompt só. O agente lê o contexto, lê a spec, e constrói contra um sistema em vez de chutar:

Leia CLAUDE.md, code-standards.md, design.md e docs/specs/01-login.md.
Marque a spec 01 como "em andamento" no rastreador de progresso.
Implemente exatamente como está escrito, nada além do escopo.

Você revisa o resultado contra o checklist. Se passa, fecha a unidade e dá push. Se algo está errado, você escreve um prompt corretivo concreto, conserta aquela coisa, e segue. Uma unidade limpa por vez, em vez de um agente solto por uma hora deixando uma pilha para você desenrolar.

O arquivo que a maioria pula: o estado

Esse é o que faz mais trabalho e o que as pessoas esquecem. Um arquivo de estado que atualiza a cada passo, e que reconstrói o contexto inteiro em um prompt só quando você volta amanhã, semana que vem, ou daqui a seis meses:

# Estado do projeto

**Fase atual:** auth
**Em andamento:** login por email (spec 01)
**Pronto:** layout base, tema escuro
**Decisões:** Clerk para auth; Postgres só para metadados
**Próximo:** dashboard do usuário

É exatamente isso que resolve o problema da falta de memória. O agente lê, entende onde o projeto está, e continua de onde você parou. Você não precisa se explicar de novo.

Os dois arquivos que me faltavam

Eu já tinha metade disso antes do vídeo: as regras do agente, o contexto do projeto, o estado. O que o vídeo me mostrou foram duas lacunas.

A primeira, code-standards.md. Sem ele, o padrão que o agente usa na função 16 não bate com a função 5. Quatro linhas economizam semanas de deriva:

# Padrões de código

- TypeScript strict. Sem `any`.
- `use client` só quando o componente precisa de interatividade.
- Sem classes de cor cruas do Tailwind: usar os tokens.
- Um componente por arquivo. Nomes em inglês.

A segunda, separar as invariantes em architecture.md: as regras que o sistema nunca viola. Coisas como "request handlers não rodam trabalho pesado de IA, isso vai para background tasks" ou "a autorização é checada em toda mutação". O agente trata elas como limites, não como sugestões.

Quando importa (e quando é exagero)

Para um conserto de um arquivo só, isso é exagero: abre o chat e faz. Mas para algo que você vai manter por semanas, com um agente indo e voltando, é a diferença entre avançar e brigar com o próprio código na terceira semana. Escrever esses arquivos é trabalho de verdade, e é por isso que as pessoas pulam para se sentir produtivas agora. O tempo que você economiza pulando é o mesmo que você perde depois, debugando um resultado que parou de fazer sentido.

O que está realmente acontecendo

O sistema não é um produto nem um prompt mágico. É que o raciocínio continua com você, e o agente ganha um contrato escrito em vez de chutar. Os arquivos são baratos. A clareza é a parte cara, e é a parte que a IA ainda não faz por você.

Agora tente isto

No seu próximo projeto, antes de pedir qualquer coisa ao agente:

• Escreva um CLAUDE.md. Três frases do que ele é, e uma lista do que ele NÃO é.
• Escreva uma spec para a primeira feature, com seu checklist.
• Crie um arquivo de estado e faça o agente atualizar a cada passo.
• Adicione code-standards.md no momento em que o agente inventar o segundo padrão diferente.