Prompt para desenvolvedores: do pedido solto à instrução com critério

Escrever prompt não é procurar frases mágicas. Para quem desenvolve software, é uma habilidade que já existe com outro nome: escrever uma boa especificação. O modelo é um executor rápido que não conhece o seu projeto, não pode fazer perguntas na hora certa e preenche com o mais provável tudo o que você deixou de dizer. Quanto mais o pedido depende do que só você sabe, mais isso precisa estar escrito.

Este é o segundo artigo da trilha Aprenda IA construindo software. O anterior, Como um LLM funciona, explica por que o modelo completa lacunas com o que é plausível. Este mostra como fechar essas lacunas.

As cinco partes de uma instrução

Um pedido que funciona costuma ter cinco partes. Nem todo pedido precisa das cinco escritas por extenso, mas vale saber qual está faltando quando o resultado vem errado.

1. Contexto: onde isso vive. Linguagem, framework, versão, como o projeto é organizado, quem vai usar.
2. Objetivo: o que precisa existir no final, dito como resultado, não como passos.
3. Restrições: o que não pode acontecer. Bibliotecas proibidas, arquivos que não devem ser tocados, regras de negócio, limites de custo.
4. Formato: como a resposta deve vir. Um arquivo, um diff, uma tabela, JSON com campos definidos, um texto de no máximo tantos parágrafos.
5. Critério de aceite: como saber que ficou certo. Testes que devem passar, comando que deve rodar sem erro, caso de borda que deve ser tratado.

O critério de aceite é a parte mais esquecida e a que mais rende. Ele transforma o pedido de algo que parece pronto em algo que pode ser verificado, e serve tanto para o modelo quanto para você na revisão.

Antes e depois: um CRUD

O pedido solto:

Faça um CRUD de clientes em Spring Boot.

O modelo vai entregar algo que compila, mas com escolhas dele: talvez outra versão do Spring, entidade sem validação, exclusão física quando o negócio exigia inativação, exceções devolvendo stack trace. Nada disso é erro do modelo; são lacunas do pedido preenchidas com o mais comum.

O mesmo pedido com critério:

Contexto: API em Java 21 e Spring Boot 3, pacotes por módulo de domínio,
JPA com MySQL e migrations Flyway. Já existe ApiExceptionHandler que
devolve erros no formato ApiErrorResponse.

Objetivo: endpoints REST para cadastrar, consultar, listar e inativar clientes.

Restrições:
- cliente nunca é apagado, só inativado (campo ativo)
- CPF ou CNPJ obrigatório e único
- sem bibliotecas novas no pom.xml
- erros de validação passam pelo ApiExceptionHandler existente

Formato: migration Flyway nova, entidade, repository, service, controller
e testes, um arquivo por vez com o caminho completo.

Critério de aceite:
- mvn test passa
- POST com documento repetido devolve 409
- GET de cliente inativo devolve 404 na rota pública

O segundo pedido é mais longo, mas não é mais difícil de escrever: são decisões que você tomaria de qualquer jeito, só que agora antes de ver o código errado, e não depois. O artigo Validação e erros em API REST detalha o tipo de restrição que vale escrever para endpoints.

Prompt de sistema: a instrução que vale para toda a conversa

Quando você integra um modelo a um produto, as instruções fixas ficam no prompt de sistema, enviado em toda chamada. O do Porto, assistente deste site, segue uma estrutura que funciona bem para assistentes: identidade, idioma, personalidade, o que pode fazer e regras obrigatórias. Um trecho real:

REGRAS OBRIGATORIAS:
1. Responda apenas sobre conteudo do RM Porto Tech, tecnologia e carreira em tecnologia.
2. Nunca invente artigo, hub, material, preco ou funcionalidade que voce nao tem certeza que existe.
...
5. Respostas curtas: no maximo 3 a 4 paragrafos curtos.
6. Se nao tiver certeza da resposta, diga que nao sabe e direcione para a pagina /contato.

Repare em dois detalhes. Primeiro, cada regra diz o que fazer, e a regra 6 diz o que fazer quando não souber, que é a saída que evita a invenção. Segundo, a regra de idioma resolve um conflito antes de ele acontecer: o site tem páginas em português e em inglês, e o mesmo assistente aparece nas duas. Sem regra, o modelo teria de adivinhar se segue o idioma da página, o da primeira mensagem ou o da última. A instrução decide: responder sempre no idioma da última mensagem do visitante. Toda ambiguidade que você consegue prever merece uma linha no prompt.

Como fizemos aqui: quando faltou uma restrição

Os artigos desta trilha foram escritos com ajuda de um agente de código, e um episódio mostra bem o custo de uma restrição não dita. O pedido era escrever sobre o app Diário do Professor, construído com agente e levado à Google Play. O texto saiu dizendo que o app estava publicado na Google Play. Não estava: estava em teste fechado, disponível só para testadores convidados.

O modelo não mentiu por malícia. Ele recebeu um contexto com Play Console, versões enviadas e revisão aprovada, e a continuação mais plausível era publicado. A correção foi acrescentar uma restrição explícita, registrada no documento da trilha: o texto diz levado à Google Play, em teste fechado, e não publicado, até o lançamento.

A lição vale para qualquer pedido: o fato que só você sabe e que muda o sentido do resultado precisa estar escrito. Status de um projeto, a versão em produção, o cliente que não pode ser citado, o número que ainda não é oficial.

O pedido curto que funciona

Nem todo pedido precisa ser longo. Num agente de código que já leu o arquivo de instruções do projeto e acompanha a conversa, um pedido curto como pode tirar do ar os dois artigos rasos e colocar o app do professor como referência funciona, porque o contexto já está lá: o agente sabe quais são os artigos, como se despublica e qual é o app. O artigo CLAUDE.md e AGENTS.md mostra como esse contexto permanente é construído.

A regra prática: o tamanho do pedido é inversamente proporcional ao contexto que o executor já tem. Numa conversa nova, sem arquivo de instruções, escreva as cinco partes. Num agente bem orientado, no meio de uma tarefa, uma frase basta.

Técnicas que ajudam de verdade

• Dar um exemplo do formato desejado. Um exemplo de saída vale mais que um parágrafo descrevendo a saída.
• Separar dados de instruções. Quando colar um documento, deixe claro onde ele começa e termina, por exemplo entre marcadores. Isso reduz a chance de o modelo tratar o conteúdo do documento como ordem.
• Pedir para listar dúvidas antes de executar. Em tarefas maiores, pedir que o modelo aponte o que está ambíguo antes de escrever código revela lacunas do seu pedido.
• Dividir tarefas grandes. Um pedido por etapa, com verificação entre elas, rende mais que uma instrução gigante.
• Dizer o que fazer, não só o que evitar. Não use bibliotecas externas funciona melhor acompanhado de use apenas o que já está no pom.xml.

Checklist

• O pedido diz onde o código vai viver: linguagem, versão, organização do projeto.
• O objetivo está escrito como resultado, não como lista de passos.
• As restrições que mudam o resultado estão explícitas, inclusive fatos que só eu sei.
• O formato da resposta está definido, com exemplo quando possível.
• Existe um critério de aceite verificável: teste, comando ou caso de borda.
• Instruções fixas de produto estão no prompt de sistema, com uma saída para quando o modelo não souber.
• O resultado passa por revisão antes de ir para produção.

O passo de revisão tem artigo próprio: Como revisar código gerado por IA antes do deploy. Na trilha, o próximo é CLAUDE.md e AGENTS.md: o arquivo que ensina o agente sobre o seu projeto.