Tudo começou com um documento

Este é o segundo de cinco posts da série sobre os bastidores do Olha o Bichim!. No primeiro, eu contei de onde veio a ideia. Agora, como ela virou especificação.

O primeiro commit do repositório foi a configuração do projeto, e o segundo já foi um documento: docs: add Fase 1 design spec. Antes de qualquer tela, existia o CAPIVARA_2048_DESIGN.md (sim, o jogo se chamava Capivara 2048 no começo), que hoje tem umas 1.800 linhas. E logo na abertura ele diz para quem foi escrito:

"Documento de especificação para desenvolvimento. Pensado para ser alimentado em ferramentas como Claude Code para implementação iterativa."

Ou seja, desde o primeiro dia o leitor principal desse documento era uma IA. Nele estão a visão e o público, a mecânica, a regra de quando uma vida é consumida (com tabela de ação por ação), os 14 animais com suas cores, a loja, o ranking, a paleta com os códigos hexadecimais, a duração de cada animação em milissegundos, o modelo de dados, o roadmap por fases e, o mais importante, os casos de teste obrigatórios e os critérios de aceite de cada fase.

No fim, tem até um prompt pronto pra próxima fase, que termina com uma ordem bem explícita: "Não escreva código nesta etapa."

O ciclo que se repetiu umas cem vezes

Esse documento foi o ponto de partida, mas cada funcionalidade nova, cada feedback e cada bug passaram pelo mesmo ciclo:

Ideia, feedback ou bug, depois um brainstorm, que vira uma especificação escrita, que vira um plano com passos verificáveis, que é executado com TDD, revisado, verificado e só então publicado. Foram 95 especificações e 101 planos em menos de seis meses. Uma funcionalidade de um dia, como abrir a loja tocando no contador de moedas, tem especificação própria. Uma grande, como a Corrida Maluca, um evento semanal de kart entre os jogadores, teve nove especificações em uma semana, cada uma refinando a anterior.

Superpowers, o método empacotado

Eu não inventei esse ciclo, eu usei o Superpowers, um conjunto de skills de código aberto criado pelo Jesse Vincent. Uma skill é basicamente um pacote de instruções em Markdown que o agente carrega quando a tarefa casa com a descrição dela, e o Superpowers traz uma metodologia inteira: brainstorming, planos, TDD, desenvolvimento com subagentes, revisão de código, depuração sistemática e por aí vai.

O detalhe que faz diferença é que ele é bem chato, no bom sentido. Ao iniciar a sessão, o agente recebe uma regra que diz que, se houver 1% de chance de uma skill se aplicar, ele é obrigado a usá-la. E no repositório do jogo eu tornei isso lei: nenhuma mudança de código sem skill, nem mesmo um ajuste "pequeno".

A especificação é a fonte da verdade

Na prática, o que isso significa é que primeiro se escreve o que tem que acontecer e por quê, e o código vem depois, sendo julgado contra a especificação.

E a especificação começa sempre pelo problema, nunca pela solução. Algumas primeiras linhas reais:

• "A tela de Coleção é uma galeria morta."
• "Filhos de usuários jogaram e disseram simplesmente que 'não entenderam o jogo'."
• "A Apple rejeitou a submissão iOS (Guideline 5.1.1(v))…"
• "Chegar ao 2048 paga 20 moedas, e o valor é o mesmo na primeira vez e na décima."

Teve até bug cuja conclusão ficou registrada no documento de design assim: "a spec abaixo sempre foi a correta — o bug era na implementação". Quando existe uma régua escrita, a discussão sobre quem está certo acaba rápido.

Primeiro, descobrir o que você quer

Na versão 7.0 do Superpowers, a skill de brainstorming foi reescrita do zero, e a abertura dela é, a meu ver, um dos melhores diagnósticos sobre como uma IA trabalha:

"Você é muito bom em construir. Você constrói o que acredita que seu parceiro humano quer, e essa crença costuma ser mais fina do que parece."

Então, em vez de sair codando, o agente faz uma pergunta aberta por vez, sobre um momento real ("qual é o momento em que você sente falta disso?"), sem um menu de opções pra induzir a resposta. Depois, devolve o entendimento em partes, marcando o que é palpite dele como palpite, e pergunta o que está errado ou faltando. Ele também pergunta explicitamente os objetivos, os não-objetivos e os anti-objetivos, isto é, o que faria disso um fracasso mesmo funcionando tecnicamente.

E pergunta "como vai ser feito": plataforma, linguagem, bibliotecas. Isso parece óbvio, mas está nas notas de versão o motivo: uma sessão desenhou um app iOS, nunca perguntou a plataforma, e construiu um web app.

No fim disso tudo existe um portão, o HARD-GATE: nada é construído antes de o humano aprovar a especificação. E um "parece bom" pra ideia não aprova uma especificação que ainda nem foi escrita.

Builder check: alguém que só tem o papel

Essa é a parte mais esperta da versão 7.0. Depois da especificação escrita, um subagente novo, sem nenhum contexto da conversa, recebe o papel e é instruído a se comportar como quem vai construir aquilo, sem poder falar com o autor. A tarefa dele é listar onde teria que adivinhar, e onde um palpite errado faria diferença.

Cada lacuna cai em um de três baldes: já respondido pela conversa (e aí a resposta entra na especificação), menor (o agente decide e marca como "decisão minha") ou do humano (só eu sei, e a resposta muda o que é construído). As do terceiro tipo vêm numa única rodada de perguntas, a mais importante primeiro.

Funciona porque quem escreveu a especificação tem a conversa inteira na cabeça e "lê" o que não está escrito. O construtor só tem o papel, então toda pergunta que ele faz é uma lacuna real que, sem essa checagem, o implementador preencheria no chute.

Sem lacunas, a IA não decide por você

E aqui está o ponto central deste post. Diante de uma lacuna, um LLM não para e pergunta: ele preenche com a resposta mais provável, e a resposta mais provável é a média da internet, não a sua vontade. É assim que nascem aquelas decisões "próprias" da IA que contrariam o que você queria.

Perguntar o porquê, devolver o entendimento com palpites marcados, listar o que não fazer, perguntar a plataforma, marcar as decisões do agente como dele, passar o texto por um construtor sem contexto e só construir depois da aprovação, cada camada fecha um tipo de lacuna. E quando, lá na execução, o plano e o código divergem, quem decide é a especificação, não o palpite do agente.

Basicamente, é o mesmo que a gente faz com um desenvolvedor humano novo na equipe, só que escrito, versionado e sem preguiça. No próximo post eu mostro a outra metade: como uma especificação aprovada vira código, e por que, nesse processo, quem escreve nunca é quem aprova.