Como usar IA para transformar uma ideia em especificação técnica

Ferramentas de IA funcionam melhor quando recebem contexto, regras, restrições e critérios de aceite. Uma boa especificação transforma uma ideia solta em plano executável. Na era dos agentes de código, isso ficou ainda mais importante: o agente não apenas sugere, ele executa. Uma spec fraca faz o agente construir rápido a coisa errada, em vários arquivos, com testes que confirmam o engano.

O erro comum é pedir a um agente para construir algo a partir de uma ideia muito aberta. Ele preenche as lacunas com suposições plausíveis e entrega uma solução aparentemente completa, mas cheia de escolhas que você não fez. A especificação troca adivinhação por contexto. O artigo Prompt para desenvolvedores trata do pedido de uma tarefa; este trata do documento que organiza um trabalho inteiro, com várias tarefas, decisões e etapas.

Por que a spec ficou mais importante com agentes

No modelo de autocomplete, uma sugestão ruim era descartada em segundos. Com um agente, uma instrução ambígua vira uma mudança grande que alguém precisa entender, revisar e às vezes desfazer. O custo do mal-entendido subiu. Especificar deixou de ser burocracia e virou a forma mais barata de evitar retrabalho.

O que uma especificação para agente precisa conter

• Contexto do negócio e objetivo real da mudança.
• Contexto do código: arquivos, módulos e padrões que a mudança deve respeitar.
• Entidades, campos, regras e validações envolvidas.
• Restrições explícitas: o que não deve mudar e o que está fora de escopo.
• Critérios de aceite testáveis, que digam quando a tarefa está pronta.
• Riscos conhecidos e dados sensíveis que exigem cuidado.
• Decisões que cabem ao dono, separadas do resto, para não serem tomadas por suposição.

A fronteira do escopo é tão importante quanto o objetivo. Dizer o que não fazer evita que o agente cresça a mudança sem controle e ajuda a manter o diff revisável.

Como fizemos aqui: a spec da trilha de IA

A trilha Aprenda IA construindo software, da qual este artigo faz parte, começou como uma especificação escrita com a ajuda de um agente e aprovada antes de qualquer código. O documento fica no repositório do site e tem a estrutura acima, aplicada a um projeto de conteúdo:

• Objetivo e motivo: preencher a falta de um caminho de aprendizado, respondendo a uma reprovação anterior por conteúdo de baixo valor com artigos baseados em experiência própria.
• Critérios por artigo: pelo menos mil palavras, exemplo de código ou arquivo real, checklist final, pelo menos três links internos e uma seção com o caso real do projeto.
• Restrições técnicas descobertas antes: artigo com menos de 700 palavras não entra no sitemap, e rota nova precisa de cinco registros, senão dá 404 em produção.
• Decisões do dono, numeradas: onde a trilha fica, o que fazer com dois artigos rasos, se o app usado como caso pode ser citado pelo nome. Cada uma foi respondida, datada e riscada no próprio documento.
• Entrega em lotes: três lotes pequenos, cada um com sua migration e validação, em vez de oito artigos de uma vez.

O efeito mais visível foi na revisão. Como os critérios estavam escritos, conferir cada artigo virou uma lista de verificação, e não uma impressão. E uma restrição que faltou, a de não chamar de publicado um app que estava em teste fechado, entrou no documento assim que apareceu, e passou a valer para tudo o que veio depois.

Revise o plano antes de executar

Muitos agentes permitem separar planejamento de execução, num modo de plano ou numa etapa de proposta. Peça primeiro o plano: quais arquivos serão tocados, em que ordem e por quê. Revisar o plano custa minutos e evita um diff inteiro na direção errada. Só depois de concordar com o plano vale deixar o agente aplicar as mudanças.

O arquivo de instruções do projeto é uma spec permanente

Além da spec de cada trabalho, vale manter um arquivo de instruções que o agente lê sempre, como AGENTS.md ou CLAUDE.md na raiz do repositório. Ele guarda comandos de build e teste, convenções, decisões de arquitetura, o que evitar e como validar uma mudança. O artigo CLAUDE.md e AGENTS.md mostra o arquivo real deste site, e Como usar IA para documentar processos e sistemas trata de mantê-lo fiel ao sistema.

Critérios de aceite testáveis

Uma spec sem critério de aceite deixa a validação subjetiva. Critérios bons descrevem comportamento observável: dado um estado inicial, uma ação e um resultado esperado. Eles orientam tanto o agente quanto a revisão humana, e viram base para os testes. O artigo Como revisar código gerado por IA antes do deploy conecta esses critérios ao momento da revisão.

Erros comuns

• pedir uma feature inteira em uma frase e aceitar o que vier;
• não dizer o que está fora de escopo;
• omitir o padrão do projeto e depois reclamar da inconsistência;
• deixar o agente decidir algo que era decisão do dono;
• deixar o agente executar sem revisar o plano;
• tratar o resultado como pronto sem critério de aceite testável.

Com agentes, a spec é o volante. Escrever bem o que se quer, com contexto, limites e as decisões separadas, é o que separa produtividade real de um gerador de mudanças confusas.