Dicas para escrever Especificações para a IA

Neste artigo veremos algumas dicas de como escrever especificações para a IA.

A IA nem sempre pergunta sobre uma premissa ausente — ela preenche a lacuna com um padrão de seu treinamento. A seguir vou apresentar algumas dicas e um checklist que evitam que sua especificação estrague o resultado.

O fracasso da inteligência artificial ao gerar códigos ruins geralmente não é culpa do modelo em si, mas sim de especificações (specs) falhas, ambíguas ou incompletas.

Um estudo empírico controlado (When Prompts Go Wrong, arXiv:2507.20439) comprovou que descrições de tarefas contraditórias ou vagas reduzem a precisão do código gerado por IA em 20% a 40%. Em contrapartida, fornecer uma especificação precisa — detalhando escopo, restrições e critérios de aceitação — com o exato mesmo modelo, produz resultados totalmente diferentes e superiores.

A IA não tira dúvidas; ela adivinha. Ao contrário de um desenvolvedor sênior que questiona pontos ambíguos, a IA preenche lacunas com base em padrões estatísticos. O resultado disso é um código que funciona perfeitamente na teoria, mas que entrega algo totalmente diferente do que você precisava.

A qualidade da especificação é a única alavanca sob seu controle, e não a capacidade da IA. Uma boa especificação evita que o modelo adivinhe o comportamento esperado ao definir claramente cinco pontos cruciais:

Resultados (Outcomes): O que o sistema deve alcançar (e não como codificar).
Escopo e Não-escopo (Non-goals): O que a IA deve e, explicitamente, o que NÃO deve fazer. Restrições: Definição de stack, versões, limites e convenções do repositório.
Critérios de Aceitação: Condições de sucesso binárias e testáveis para validação rápida.
Casos de Borda e Falha: Regras para cenários de erro, já que o "caminho feliz" é minoria em produção.

Dicas para escrever especificações que a IA entende

Dica 1 - Foque no Resultado, Esqueça o Código!

Em vez de tentar explicar para a IA como programar, foque em explicar o que o sistema precisa entregar e como você vai testar se deu certo.

Se você começar a enfiar pseudo-código ou detalhes de implementação (como loops e estruturas específicas) no meio da especificação, você vai estragar o brinquedo. Isso confunde a IA, fazendo com que ela ative os padrões errados e misture o objetivo com o caminho.

Mas atenção: Isso não significa que você está proibido de guiar o código. Quando for realmente pertinente — como exigir que ela siga uma arquitetura específica (ex: Clean Architecture ou DDD), aplique um padrão de design ou respeite restrições de performance —, essas diretrizes devem, sim, constar na especificação. A regra é: guie a engenharia e a estrutura quando necessário, mas não tente microgerenciar cada linha de lógica.

A regra de ouro é simples: Seu papel principal é ser o Arquiteto que desenha a planta, dita as regras do jogo e define o objetivo. Deixe que a IA faça o papel do Empreiteiro que vai carregar o piano e codificar dentro dos limites que você estabeleceu.

Dica 2 — Diga o que o sistema FAZ e o que ele NÃO FAZ de jeito nenhum!

Na hora de passar a tarefa para a IA, deixar claro o que está fora do escopo (os famosos non-goals) é tão importante quanto dizer o que deve ser feito.

Se você não colocar uma cerca invisível no projeto, a IA vai se comportar como aquele prestador de serviço empolgado, mas sem contrato: vai começar a criar funcionalidades extras que ninguém pediu só "porque parecia uma boa ideia". E na cabeça dela, faz sentido! Só que não está alinhado com o que você quer.

O pulo do gato: Uma simples frase como “Não mude a estrutura do banco de dados e não adicione paginação agora” te economiza horas limpando um código gigante que veio cheio de "brindes" que você não queria.

O resumo da ópera: Defina os limites do campo de jogo. Dizer o que não fazer evita que a IA seja zelosa demais e estrague o que já está funcionando.

Dica 3 — Crie Critérios de Aceitação que dão para testar de verdade!

Esse aqui é o coração de qualquer especificação que preste. O seu critério de aceitação precisa ser preto no branco: ou funciona ou não funciona. Papo furado como "o sistema deve ser rápido" ou "a tela precisa ficar bonita" não serve para nada na hora de guiar uma IA.

Em vez disso, use metas reais. Por exemplo: “O endpoint de busca precisa responder em menos de 200 ms mesmo com 10.000 registros no banco.” Pronto! Isso qualquer desenvolvedor (ou a própria IA) consegue testar e provar sem precisar adivinhar o que você queria.

A regra de ouro é curta e grossa: Se você não consegue provar que o requisito foi atendido olhando apenas para o resultado, ele ainda é só um rascunho de ideia, não uma especificação de verdade.

Por que isso importa? Critérios de aceitação bem amarrados dão um alvo certeiro para a IA acertar e, de quebra, te dão o argumento perfeito para rejeitar o código se ela começar a inventar moda e colocar coisas que ninguém pediu.

Dica 4 — Obrigue a IA a pensar no pior cenário (Erros e Casos de Borda)!

Na vida real, o "caminho feliz" (quando tudo dá certo) é a minoria das requisições que batem no servidor em produção. Só que a maioria das especificações só descreve esse mundo perfeito.

Se você não deixar explícito o que o sistema deve fazer quando a lista vier vazia, quando faltar permissão para o usuário ou quando estourar um limite, a IA vai simplesmente chutar uma solução baseada no que ela viu no treinamento. E é aí que o bicho pega.

O kit básico da especificação blindada: Para cada funcionalidade, inclua no briefing pelo menos estas três situações:

1- Um caminho de erro: O que acontece se a API falhar ou cair?
2- Um caso de borda (edge case): O que acontece se o valor for zero, negativo ou gigante?
3- Um caso de limite: O que acontece se a lista estiver vazia ou o usuário não tiver acesso?

Por que se dar a esse trabalho? São exatamente nessas três lacunas que o código costuma quebrar e derrubar o sistema logo depois do deploy. Deixar isso claro poupa o seu plantão.

Dica 5 — Entregue o Contexto e as Regras do Jogo!

A IA não tem bola de cristal e não conhece o seu repositório. Se você não disser onde ela está pisando, ela vai chutar. E no mundo do desenvolvimento, "chute" significa retrabalho.

Por isso, contextualize a IA deixando claro coisas como: a stack e as versões que você usa, as convenções de nomenclatura do seu projeto, bibliotecas que são proibidas na empresa, o formato exato que você espera na saída e os limites de desempenho.

Dica de ouro com ferramentas modernas: Você não precisa digitar tudo isso em todo santo prompt. A maioria dos agentes de IA atuais (como Claude Code, Cursor, Aider, etc.) possui recursos nativos para ler o contexto do projeto automaticamente na inicialização. Basta criar arquivos de diretrizes na raiz do seu repositório — como um


CLAUDE.md


Agents.md

— detalhando seus padrões arquiteturais, comandos de build e regras de estilo. O agente lê isso antes de começar e já joga dentro do seu padrão.

Lembre-se sempre: Contexto que falta não é um silêncio neutro; é um convite para a IA adivinhar. E quando ela adivinha, ela joga o padrão mais genérico da internet para dentro do seu código — o que quase nunca vai encaixar nas particularidades do seu ambiente ou da sua arquitetura.

O papo é reto: Tudo o que você não detalhar, o modelo vai preencher com o que ele bem entender. Economize seu tempo blindando a IA com as restrições corretas antes dela começar a digitar.

Dica 6 — Desenhe! Mostre exemplos em vez de criar uma lista infinita de regras

Ficar empilhando uma lista gigantesca de regras e exceções textuais no prompt cansa a IA e aumenta a chance de ela ignorar alguma coisa. Quer que ela entenda de verdade? Mostre como faz.

Poucos e bons exemplos de entrada e saída (input-output) ensinam o modelo muito melhor do que um manual de instruções de cem páginas. Até os próprios criadores dos modelos de IA concordam com isso: em vez de uma "lista de supermercado" cheia de regrinhas, mostre exemplos reais bem escolhidos. Para um agente de IA, um bom exemplo também vale mais que mil palavras.

O pulo do gato: Um bloco de código mostrando "é exatamente assim que uma saída correta deve se parecer" destrói qualquer ambiguidade muito mais rápido do que três parágrafos tentando descrever a mesma estrutura.

O resumo: Não gaste saliva (ou tokens) filosofando sobre o formato. Monte um exemplo prático do dado entrando e do código/JSON saindo, e deixe o poder de associação da IA fazer o resto do trabalho.

Dica 7 — Adapte o tamanho do prompt à bronca que a IA vai resolver!

Vamos ser bem sinceros: aquele debate eterno sobre o prompt ideal ser "curto" ou "longo" é pura perda de tempo. Quem te vender uma regra mágica e absoluta sobre isso está te enganando.

Quem defende o prompt curto diz que a IA tem um "orçamento de atenção" limitado e que escrever uma especificação de cem linhas só para exibir uma data na tela é um antipadrão bizarro. (E eles estão certos!).

Quem defende o prompt longo se apoia em estudos que provam que descrições completas — cheias de restrições, entradas/saídas e casos de borda — aumentam brutalmente a precisão do código gerado. Tirou uma linha, a IA já erra. (E eles também estão certos!).

A saída inteligente: Não escolha um lado; use o bom senso e equilibre o nível de detalhe com a complexidade da tarefa.

Vai centralizar uma div ou criar um componente simples? Mantenha curto e direto.

Vai implementar um fluxo de OAuth completo com token refresh e tratamento de expiração? Detalhe minuciosamente.

O que realmente importa não é a quantidade de linhas que você escreve, mas sim garantir que a IA entenda o recado por múltiplos canais. Reforce a mesma ideia combinando uma boa descrição, uma restrição clara e um exemplo prático.

Chega de teoria! As regras fazem todo sentido no papel, mas agora vamos ver como isso funciona na prática comparando a mesma função descrita de um jeito ruim e de um jeito profissional.

A Mesma Função, Duas Especificações

Vamos pegar uma tarefa real do dia a dia: Criar um endpoint em ASP.NET Core Minimal APIs para exportar dados.

Veja a versão "preguiçosa" que a gente mais encontra por aí:

"Cria um endpoint aí no ASP.NET Core para exportar a tabela de logs em CSV. Faz funcionar bem e rápido."

Se você ler isso com os olhos de uma IA (que não vai te fazer perguntas para tirar dúvidas), o cenário é um desastre:

Qual o delimitador e o encoding do CSV? Não especificado.
Quais colunas mapear do banco via Entity Framework Core? Desconhecido.
O que acontece se não houver logs no período? Indefinido.
Como fica a segurança e a autorização (Identity/JWT)? Não resolvida.
E se a tabela tiver 500 mil registros? Vai dar um ToListAsync() e estourar a memória do servidor com um OutofMemoryException? Palpite de qualquer um.

A IA vai fechar cada uma dessas lacunas adivinhando. E, estatisticamente, ela vai errar o que você queria.

Agora, veja a mesma tarefa, escrita fechando as lacunas com precisão cirúrgica:

Resultado: O endpoint GET /api/logs/export expõe o download de um arquivo CSV com logs de erro do sistema.

Escopo: Apenas logs com LogLevel = "Error". Colunas: Id, Timestamp, Message, Exception.

Não-objetivos: Não exportar logs de Information ou Warning. Não alterar o esquema do banco de dados.

Restrições e Contexto: .NET 8/9; uso de StreamWriter com IAsyncEnumerable (rendimento via EF Core com AsNoTracking()) para evitar carregar tudo na memória; delimitador de ponto e vírgula (;); encoding UTF-8 com BOM; acesso restrito via Policy [Authorize(Roles = "Admin")].

Critérios de Aceitação:

Para 5 logs de erro encontrados, retorna o arquivo com cabeçalho + 5 linhas de dados (Status 200).

Se não houver logs de erro, retorna um arquivo CSV vazio contendo apenas o cabeçalho (Status 200).

Requisição sem token JWT válido ou sem a role "Admin" retorna Status 403 (Forbidden) sem processar os dados.

O consumo de memória do servidor deve ser constante (via streaming), sem dar spike mesmo ao exportar 100.000 registros.

Exemplo de saída:

Id;Timestamp;Message;Exception
1024;2026-06-30T17:00:00Z;Failed to process payment;System.TimeoutException...

Repare que a segunda versão não é absurdamente mais longa — ela só é precisa onde a primeira foi omissa.

O foco foi no resultado e na arquitetura correta (streaming via IAsyncEnumerable), sem tentar microgerenciar o loop dentro do código.

Os não-objetivos cortaram o risco de vir logs indesejados.
O "funciona bem" virou quatro critérios testáveis e preto no branco.
Forçamos os caminhos de erro (sem permissão) e o caso de lista vazia.
Definimos as restrições da stack (.NET, EF Core com As No Tracking, delimitador).

Isso prova a nossa tese: não é o tamanho do prompt que muda o jogo — é a quantidade de lacunas que você fecha antes da IA começar a digitar.

Claro que, mesmo uma especificação bem amarrada assim, raramente nasce 100% perfeita na primeira tentativa. O próximo passo fundamental é saber como iterar e refinar o código junto com o agente.

Como Iterar na Especificação (O Loop de Refinamento)

Uma boa especificação não nasce pronta; ela evolui em um ciclo vivo. Você escreve, a IA gera o código, os testes rodam e, se algo quebrar, você ajusta a especificação, não apenas o código.

O poder do fluxo em etapas: O estudo AlphaCodium provou que parar de usar um prompt único e passar a usar um fluxo de trabalho em várias etapas (gerar, testar, corrigir, refinar) fez a taxa de sucesso do GPT-4 saltar de 19% para 44% em testes complexos.

Para não se perder nesse processo, guarde estas três regras práticas:

1- A Especificação é Soberana
Se o código gerado e a especificação divergirem, a especificação manda. Um teste falhando geralmente não é um bug no código, mas sim um aviso de que sua especificação esqueceu de prever alguma regra ou cenário real.

2- Saiba quando NÃO escrever uma Spec
Não mate uma mosca com um canhão. Correções simples de bugs, protótipos rápidos ou tarefas direto ao ponto não precisam de uma documentação gigante. Use especificações completas para o que realmente importa: fluxos complexos, segurança (autorização), pagamentos e integridade de dados.

3- A palavra final é sempre Humana
Cuidado com a armadilha do "tá tudo verde". A IA pode dar a tarefa como concluída e fingir que os testes passaram, mesmo deixando o código incompleto. A verificação final e o carimbo de "pronto para produção" são sempre do desenvolvedor.

O resumo: Antes de jogar o projeto no colo da IA, use um checklist mental para fechar as lacunas da especificação. De resto, use o loop de testes para lapidar o resultado!

Checklist de Especificação: A Linha de Defesa Antes do Código

Passar sua especificação por um checklist rápido antes de entregar para a IA não é burocracia; é economia de tempo. Se o seu briefing não passar nesses pontos, nem mande para o agente, pois o código vai voltar errado.

Aqui está o checklist prático para você copiar, colar e usar no dia a dia:

[ ] Cada critério de aceitação assume a forma (Dado/Quando/Então — contexto -> evento -> resultado esperado) ou um equivalente.

[ ] Pelo menos um critério cobre um caminho de erro.

[ ] Pelo menos um critério cobre um caso vazio, de permissão ou de borda.

[ ] Um não-objetivo (non-goal) está explicitamente declarado — o que esta mudança NÃO faz.

[ ] Para cada critério, uma prova é definida (teste, log, captura de tela) — ANTES da implementação.

[ ] Nenhum caminho para prova significa que o critério está muito vago — volte e refine-o.

Trate Prompts e Specs como se fossem Código!

O segredo para elevar o nível da equipe é tratar a especificação com o mesmo respeito que você trata o código-fonte:

Coloque no Git: Versione suas especificações e prompts.

Faça Spec Review: Revisar o briefing antes de rodar a IA deve ser tão normal quanto fazer um Code Review.

Compartilhe Exemplos: Deixe specs boas e ruins circulando no time para servirem de norte.

A barreira é psicológica, não técnica: Um estudo da AWS mostrou que engenheiros aprenderam especificação formal em poucas semanas e começaram a caçar bugs críticos assim que o "formalismo assustador" foi traduzido para uma disciplina prática do dia a dia.

O veredito final: Escrever uma especificação animal exige exatamente a mesma precisão de pensamento que escrever um código limpo e bem arquitetado. A especificação dá trabalho pelo exato mesmo motivo que a torna tão valiosa: ela te obriga a pensar antes de digitar.

E estamos conversados..

"De sorte que somos embaixadores da parte de Cristo, como se Deus por nós rogasse. Rogamo-vos, pois, da parte de Cristo, que vos reconcilieis com Deus."
2 Coríntios 5:20

Referências:

José Carlos Macoratti