Seu prompt é vago porque você não sabe o que quer. Aqui está como saber.

TL;DR

• Culpa de IA é 10%, culpa de especificação é 90% — antes de pedir pra IA, defina input, output, caso de uso e o que NÃO deve acontecer.
• Escopo pequeno = prompt curto funciona; escopo grande = prompt precisa de estrutura (contexto, requisitos, restrições, formato, critério de aceitação).
• Exemplo concreto é melhor que descrição — mostrar entrada/saída esperada desambigua o que a IA deve fazer.
• Critério de rejeição diferencia — dizer “não use bibliotecas externas” é o que separa um output útil de um output genérico.
• Contexto (“por quê”) reduz alucinação — IA gera melhor quando sabe o motivo do pedido.

1. Especificação precede prompt

Antes de abrir o chat com a IA, responda quatro perguntas em qualquer caderno, post-it ou comentário de código:

• O que é input? (de onde vem, formato, exemplos)
• O que é output esperado? (formato, conteúdo, exemplo pronto)
• Qual é o caso de uso? (quando alguém chama isso? em qual fluxo?)
• Qual é o caso que NÃO deve acontecer? (o que conta como bug, não como feature?)

Se não consegue responder, não está pronto pra pedir. Está pronto pra pensar mais um pouco.

Exemplo real:

Vago: “Crie validador de email.”

Preciso: “Crie função JavaScript que valida email: aceita strings que casam com RFC 5322 simplificado, rejeita endereços de provedores descartáveis (tempmail.com, guerrillamail.com, 10minutemail.com), falha com `throw new Error(‘email inválido: ‘ + valor)` se entrada não é string ou não casa o regex, sucede retornando `true` se válido. Não use bibliotecas externas.”

A diferença é a mesma entre pedir “faz comida” e “faz um omelete com 3 ovos, sem cebola, ponto da gema mole, serve no prato branco”. A segunda especificação elimina 90% da variação.

2. Tamanho de escopo define tamanho de prompt

Pequeno escopo (validar um campo) cabe em uma frase. Prompt de duas linhas funciona.

Grande escopo (arquitetura de autenticação) precisa de estrutura explícita. Caso contrário a IA vai te entregar 4 mil palavras de generalidade.

Para escopo grande, organize em cinco seções nomeadas:

• Contexto (por que estamos fazendo isso? qual problema resolve?)
• Requisitos (o que precisa fazer?)
• Restrições (o que NÃO pode fazer? tecnologia proibida, padrão obrigatório, performance budget)
• Formato esperado (quero código production-ready, ou quero esqueleto, ou quero diagrama de arquitetura?)
• Critério de aceitação (como sabemos que está certo? testes, métricas, comportamento observável)

Essas cinco seções viraram minha segunda natureza em prompt longo. Funciona pra modelagem de schema, design de API, refatoração de classe inteira, plano de migração. A IA tem cinco âncoras pra preencher em vez de uma única pergunta em aberto.

3. Exemplo é mais claro que descrição

Descrever comportamento esperado em texto é vago. Mostrar exemplo é concreto. Concreto elimina variação.

Ruim: “Crie função que formata data.”

Bom: “Crie função que formata data no formato brasileiro longo. Entrada: string ISO `’2024-01-15’`. Saída esperada: `’15 de janeiro de 2024’`. Outro exemplo: `’2024-12-25’` → `’25 de dezembro de 2024’`. Casos de borda: data inválida → lança `Error(‘data inválida’)`.”

Com exemplos, a IA sabe exatamente o que você quer — sem ter que adivinhar formato, idioma, ordem dos componentes. Cada exemplo elimina uma pergunta. Dois a três exemplos práticos valem mais que cinco parágrafos de descrição.

Dica: sempre que possível, pegue um caso real do código que você está mexendo. Mostre entrada que veio de outro lugar do sistema, saída que outro componente consome. Contexto concreto > abstração.

4. Critério de rejeição é tão importante quanto critério de aceitação

A maioria dos prompts só diz o que quer. Não diz o que não quer.

Critério de aceitação sozinho é raso: “função retorna string formatada” — qualquer função faz isso. Critério de rejeição é o diferenciador: “não use bibliotecas externas”, “não crie variáveis de uma letra (x, y, z)”, “não use `any` do TypeScript”, “não gere testes de integração”, “não mexa no schema do banco”.

Prática concreta: adicionar uma linha “O resultado NÃO deve:” antes de pedir. Lista 2 a 4 proibições. Exemplos que uso toda semana:

• “O resultado NÃO deve usar bibliotecas externas além de X.”
• “O resultado NÃO deve alterar arquivos fora de `src/services/`.”
• “O resultado NÃO deve incluir comentários óbvios como `// loop through array`.”
• “O resultado NÃO deve gerar testes — só a implementação.”

Essas linhas cortam 50% do lixo que normalmente a IA cospe. E mais: te forçam a pensar no que você não quer, o que é metade da especificação.

5. Contexto desambigua

IA gera melhor quando sabe por quê. Não é antropomorfização — é priors. Quando a IA sabe que você está gerando testes pra uma função de validação de estoque, ela prioriza casos extremos (negativo, zero, overflow). Quando ela acha que você está gerando testes de uma API REST, ela perde tempo com serialização JSON.

Ruim: “Gere testes.”

Bom: “Gere testes unitários (não integração) pra função `validarEstoque(produto, quantidade)` em `src/domain/estoque.ts`. Focamos em casos extremos: quantidade negativa, quantidade zero, quantidade que excede estoque, produto sem SKU. NÃO precisamos testar integração com banco de dados, mocks, ou serialização. Use Jest, sem bibliotecas extras. Cobrir ≥ 90% de branches.”

Contexto reduz alucinação. Sem contexto, a IA tem que adivinhar — e a probabilidade de ela adivinhar errado em algum detalhe que vai te custar 20 minutos de debug é alta.

Inclua no prompt, sempre que relevante:

• Onde no sistema o código vai rodar
• Por que esse código existe (qual problema resolve)
• Quem vai chamar (outra função? API? usuário direto?)
• O que já existe em volta (não reinventar a roda)

Fechamento

Prompt matador começa com especificação clara do que você quer. Se especificação é vaga, prompt será vago. Culpa de IA é de 10%. Culpa de especificação é de 90%.

A boa notícia: especificação é uma skill que se aprende escrevendo prompt, não antes. O ciclo é: prompt vago → output ruim → perceber o que faltou → reescrever prompt com a especificação que deveria ter existido. Depois de umas 30 iterações, especificação passa a vir antes do prompt naturalmente. E o output da IA começa a parecer menos slot machine e mais colega de trabalho.

Próximo passo prático: da próxima vez que você for pedir algo pra IA, escreva 4 linhas antes do prompt: input, output, caso de uso, caso que NÃO deve acontecer. Se conseguir escrever essas 4 linhas em menos de 1 minuto, prompt vai sair bom. Se levar mais que isso, vale a pena abrir uma issue de especificação antes.

Leitura relacionada

• Manutenção remota é skill que ninguém ensina — porque contexto operacional também é especificação, e a maioria pula essa parte.
• O código novo que ninguém consegue manter é pior que o legado — código gerado por IA sem critério de aceitação vira esse monstro.
• Conhecimento como responsabilidade ao usar IA pra código — a outra metade: depois de especificar, revisar é sua responsabilidade.