"Kit de agents e CLAUDE.md: o que é a peça da semana 1 e por que ela existe"

"Eu simplesmente não consigo, parece que fica algo remendado, como se fosse uma pintura com 3 estilos diferentes."

Quem escreveu foi um brasileiro num fórum de tecnologia, sobre o próprio app depois de semanas pedindo coisas pra IA. Em outra conversa do mesmo tipo, alguém escreveu: "às vezes eu também penso que o problema sou [eu]".

Não é. E dá pra explicar de onde vêm os três estilos.

Cada conversa pinta de um jeito porque cada conversa começa do zero

A documentação do Claude Code, a ferramenta de programar da Anthropic que roda na pasta do seu projeto, diz isso logo na primeira linha da página sobre memória: cada sessão começa com a janela de contexto limpa. Contexto é tudo que a IA tem na cabeça durante a conversa. Fechou a conversa, foi embora.

Na segunda você explica que o valor é em real e que o login não se toca. Na quarta, numa conversa nova, ela não sabe nada disso e faz do jeito dela. Na sexta, de um terceiro jeito. Três estilos.

O problema não é você pedir mal. É que as regras do projeto moram na sua cabeça e na conversa, e a IA não lê nenhum dos dois amanhã.

A versão mínima, pra fazer hoje

Existe um lugar que ela lê toda vez. No Claude Code, é um arquivo de texto chamado CLAUDE.md, na pasta raiz do projeto. A documentação diz que ele é lido "no começo de toda conversa". No Lovable, o equivalente é o campo Knowledge nas configurações do projeto (mostrei onde fica aqui).

O que vai dentro decide se ele funciona. A versão que eu recomendo tem quatro blocos, nesta ordem:

# NUNCA (não negociável)
- Nunca apagar dado do banco de produção.
- Nunca mexer no login sem eu pedir com essa palavra.

# O que não se toca sem pedido explícito
- Cálculo do total do pedido (arquivo: total.ts)
- Tela de pagamento

# Como provar que terminou
- Rodar o teste e colar a saída. Não escrever "pronto" sem ela.

# Palavras do meu negócio
- "Cliente" é quem compra. "Usuário" é quem trabalha na loja.
- Valor sempre em real, com vírgula.

O exemplo é inventado, pra mostrar o formato. Três regras pra escrever o seu:

• O "nunca" vem primeiro. O que não pode acontecer é mais importante do que o jeito de fazer.
• Curto. A documentação pede menos de 200 linhas e avisa que arquivo inchado faz a IA ignorar as regras que importam. Pra cada linha: "se eu tirar isto, ela erra?". Se não, corta.
• Concreto. "Escreva código limpo" não muda nada. "Valor com vírgula" muda.

Escreve hoje, com as três coisas que você mais repetiu na semana.

O que muda com o kit completo

A documentação diz uma coisa que pouca gente lê: esse arquivo é tratado como contexto, não como configuração obrigatória. É conselho. Quase sempre ela segue. A vez que não segue é a do banco de produção.

O kit da Mentoria Dono do App é o que eu uso nos meus projetos, e existe pra fechar a distância entre conselho e garantia. São três peças:

1. O CLAUDE.md com a regra de ouro no topo. O do Kallos, meu app em produção, abre com "NUNCA TESTAR EM PRODUÇÃO, NUNCA APAGAR DADOS". O do kit nasce com o mesmo topo, mas curto: o meu passou de 900 linhas em dois anos de cicatriz, e o seu não precisa começar assim.

2. Travas que bloqueiam de verdade. Em inglês, hooks: pequenos programas que rodam sozinhos antes de cada ação da IA. Pela documentação, a instrução escrita é "consultiva" e o hook é "determinístico": acontece sempre, sem depender de ela lembrar. A trava de produção, por exemplo, nega o comando que tenta escrever no banco onde estão seus clientes. Nega, não pergunta. Regra escrita é cultura; trava é o que segura quando a cultura falha.

3. Agents de contexto limpo. Agent, aqui, é um assistente separado, com instrução própria e conversa própria. A documentação descreve assim: cada um "roda na sua própria janela de contexto, com instrução própria e acesso restrito a ferramentas". O valor disso pra quem não programa: quem escreveu a mudança não é quem confere. O revisor recebe só o que mudou e o critério, sem a conversa que produziu aquilo, e por isso tropeça onde um estranho tropeçaria. Tem um que revisa antes de publicar, um que procura a tela que parece pronta e não faz nada por trás, e um que lê a descrição do seu negócio e pergunta, em português, de quem é cada dado.

Junto vêm três atalhos: /comecar monta o projeto do jeito certo, /quebrou transforma "deu erro" em diagnóstico antes do conserto, e /afinar ajusta tudo ao vocabulário do seu app.

O que o kit não faz

Ele não decide de quem é cada dado nem escreve as regras de quem pode ler o quê. Isso é a fase Estruture, trabalho seu, com alguém conferindo. O kit faz a IA respeitar o desenho do app depois que ele existe; não desenha por você.

E ele pressupõe o código numa pasta sua, na sua máquina. Se o app ainda mora só no Lovable, a versão mínima cabe no Knowledge.

Por que é semana 1

Porque tudo que vem depois depende dele. Na mentoria, nenhuma outra ferramenta roda num projeto sem o CLAUDE.md com a regra de ouro e sem ponto de retorno marcado: é o primeiro portão, e é um dos quatro que nunca saem. Você não pode conferir se a IA respeitou uma regra que nunca foi escrita.

A pintura com três estilos não se conserta pintando por cima. Ela para quando existe um lugar onde as regras moram, uma trava no que não pode quebrar e um segundo par de olhos que não viu a conversa. O arquivo de hoje é a primeira dessas coisas. As outras duas, e a ordem em que entram no seu projeto, são o começo do caminho.

Fontes

• Claude Code Docs, "How Claude remembers your project" (cada sessão começa com contexto limpo; CLAUDE.md lido no começo de toda sessão; tratado como contexto, não configuração obrigatória; menos de 200 linhas): https://code.claude.com/docs/en/memory
• Claude Code Docs, "Best practices for Claude Code" (arquivo inchado faz ignorar instruções; "se eu tirar isto, ela erra?"; CLAUDE.md consultivo, hooks determinísticos): https://code.claude.com/docs/en/best-practices
• Claude Code Docs, "Create custom subagents" (cada agent roda na própria janela de contexto, com instrução própria e ferramentas restritas): https://code.claude.com/docs/en/sub-agents