Cada bug vira uma regra

Este é o quarto de cinco posts da série sobre os bastidores do Olha o Bichim!. No anterior, eu mostrei como a especificação vira código. Agora, as regras que orientam os agentes.

Um agente de IA não tem memória de uma sessão pra outra. Cada vez que eu abro o Claude Code, ele começa do zero, como um desenvolvedor novo no primeiro dia de trabalho. Então, tudo o que ele precisa saber sobre o projeto tem que estar escrito em algum lugar que ele leia toda vez, e esse lugar são os arquivos CLAUDE.md.

As regras da casa

No começo era um arquivo só, na raiz do repositório. Com o tempo, ele inchou e, em agosto, foi dividido por contexto: o da raiz tem o projeto, a stack, os comandos de build e o checklist de publicação; o de lib/ tem as regras de Dart, banco de dados e sincronização; o de lib/presentation/ tem as regras de interface; e os de ios/ e android/, as particularidades de cada plataforma. O agente carrega o arquivo da pasta em que está mexendo, então só lê o que interessa.

Os arquivos AGENTS.md e GEMINI.md só apontam para o CLAUDE.md, então existe uma única fonte de verdade pra qualquer ferramenta de IA. E existe uma meta-regra: nunca inchar o arquivo da raiz, regra nova vai pra pasta certa. Ah, e todos são escritos em inglês e em estilo "caveman", frases telegráficas, sem enchimento, o que economiza tokens e deixa a regra direta.

Além disso, existe um protocolo de comportamento do agente, carregado em toda sessão, sem exceção. As regras dele são: nenhuma mudança de código sem skill; pensar antes de codar; simplicidade primeiro; mudanças cirúrgicas; definir critério de sucesso; motor do jogo puro e com TDD; revisão em paralelo; e verificar depois de cada implementador. As regras de pensar antes, simplicidade, mudanças cirúrgicas e critério de sucesso vieram quase palavra por palavra das diretrizes derivadas das observações do Andrej Karpathy sobre os erros típicos de LLMs ao programar, empacotadas no plugin andrej-karpathy-skills.

Cada bug vira uma regra

O que eu acho mais bonito nesse processo é que quase todas as regras de lib/, ios/ e android/ nasceram de um bug real. Alguns exemplos:

• O app travava pra sempre na tela de abertura, mas só em iPhones 14 a 17 e só no dia seguinte a jogar. A causa? Uma imagem WebP anexada a uma notificação local, que o iOS rejeita, gerando uma exceção antes mesmo do app iniciar. Regra: anexo de notificação no iOS deve ser JPEG, GIF ou PNG.
• A Apple rejeitou o app três vezes, pela Guideline 2.1, por causa do mesmo botão "Confirmar", que parecia travado. Ele esperava a gravação no servidor antes de sair da tela. Regra: botão principal nunca espera o servidor antes de navegar.
• Jogadores empatados sumiam do pódio do ranking, porque a posição era indexada pelo rank, que se repete em empates. Regra: a posição vem da ordem, nunca do rank.
• Uma compra confirmada nunca era creditada se o jogador saísse da loja no meio do processo. Regra: a entrega da compra fica num listener permanente, com um registro que evita entregar duas vezes.

Basicamente, os CLAUDE.md são a memória institucional do projeto. O próximo agente, ou eu daqui a seis meses, não vai cometer o mesmo erro, porque ele está escrito ali. E as regras são tratadas como código: versionadas, revisadas, refatoradas e podadas quando atrapalham. Por exemplo, existia uma regra que forçava um modelo específico pros subagentes, e ela foi removida quando ficou claro que a própria skill escolhia melhor.

Ponytail, o sênior preguiçoso

A outra peça do quebra-cabeça é uma skill chamada Ponytail, do Dietrich Gebert, também de código aberto. A descrição dela é ótima: "Você conhece ele. Rabo de cavalo comprido. Óculos ovais. Está na empresa há mais tempo que o controle de versão. Você mostra cinquenta linhas; ele olha, não diz nada, e troca por uma." E o lema: o melhor código é o código que nunca foi escrito.

Na prática, ela dá ao agente uma escada, e ele para no primeiro degrau que resolve o problema por completo: isso precisa existir? Já existe no código? A biblioteca padrão resolve? Um recurso nativo da plataforma resolve? Uma dependência já instalada resolve? Cabe numa linha legível? Só então, o mínimo que funciona, com um teste se tiver lógica.

O exemplo do próprio autor é bem didático: "adicione um seletor de data". Sem a skill, o agente escreveu 335 linhas, um calendário feito à mão. Com a skill, 10 linhas, reaproveitando o campo de texto do projeto com type="date", porque o navegador já traz o calendário.

Mas a parte que mais importa é o que ela nunca corta: validação nas fronteiras de confiança, tratamento de erro que evita perda de dados, segurança, acessibilidade e qualquer coisa que o usuário pediu. E toda resposta termina dizendo o que foi pulado ou não verificado e qual o risco. O código fica pequeno porque só tem o necessário, não porque alguém tentou economizar caracteres.

Pelos números do benchmark do autor, com o Opus 5.5 em 39 tarefas, foram 53% menos linhas, 41% menos tempo e 26% menos custo, e a lógica arriscada entregue com teste subiu de 68% para 98%. São números do próprio autor, então servem como indicação, não como estudo independente, mas batem com o que eu vi no dia a dia.

A lei e o hábito

O curioso é que o protocolo do repositório já tinha praticamente as mesmas ideias antes de eu instalar o Ponytail.

"Isso precisa existir?" é o "simplicidade primeiro". "Mantenha a estrutura que o código já tem" são as mudanças cirúrgicas. "Código preguiçoso sem verificação está inacabado" é o critério de sucesso com TDD. "Busque todos os chamadores e corrija a causa raiz" é a regra de depuração sistemática.

Então, por que ter as duas coisas? Porque o CLAUDE.md diz o que é bom desenvolvimento neste projeto, e o Ponytail dá ao agente um procedimento pra chegar lá. Uma é a lei, a outra é o hábito. E elas se encaixam com o Superpowers assim: o brainstorming decide o que construir, o Ponytail e as regras decidem quanto código escrever pra isso, e os revisores conferem se o que foi escrito é o que a especificação pediu, nem mais, nem menos.

No último post da série, eu saio um pouco da parte técnica e falo do produto: ouvir quem joga, inclusive as crianças, a maratona com a Apple e por que saber tirar também é design.