Playbook de engenharia de prompts para programadores

• Assistentes de codificação com IA aumentam a produtividade dos desenvolvedores, mas a qualidade do resultado depende fortemente da engenharia de prompts
• Para obter resultados eficazes, é preciso seguir regras como contexto rico, objetivos específicos, exemplos, atribuição de papel e melhoria iterativa
• O material apresenta padrões de design de prompts e exemplos para tarefas centrais de desenvolvimento, como debugging, refatoração e implementação de novas funcionalidades
• Um bom prompt deve conter informações concretas como objetivo, linguagem, ambiente, mensagens de erro e exemplos de entrada/saída
• Trata-se de um método de criação de prompts que até engenheiros iniciantes conseguem seguir, incluindo comparação de respostas reais de IA e comentários

---

Visão geral: a importância da engenharia de prompts bem-sucedida

• Recentemente, desenvolvedores vêm usando assistentes de código com IA para acelerar o fluxo de trabalho, desde autocompletar funções e corrigir bugs até escrever módulos inteiros
• No entanto, a qualidade das respostas da IA é decisivamente determinada pela qualidade do prompt
• Bons prompts levam a soluções de código claras e criativas, enquanto prompts vagos ou pobres resultam em respostas limitadas e pouco úteis
• Este playbook organiza de forma prática métodos eficazes de criação de prompts que podem ser aplicados a tarefas cotidianas de desenvolvimento

Princípios básicos de prompts eficazes para código

• Forneça contexto rico: a IA não conhece previamente o projeto nem sua intenção, então explicite todas as informações relevantes, como linguagem, framework, bibliotecas, mensagens de erro e objetivo do código
• Apresente um objetivo ou pergunta claros: em vez de consultas vagas como “por que o código não funciona?”, descreva claramente o resultado desejado e a situação atual
• Divida tarefas complexas: em trabalhos como o desenvolvimento de funcionalidades grandes, não peça tudo de uma vez; quebre em etapas menores e avance gradualmente
• Inclua exemplos de entrada/saída ou comportamento esperado: fornecer exemplos reais de entrada, saída ou comportamento aumenta muito a compreensão da IA ("few-shot prompting")
• Use papéis (personas): atribuir funções como “revise o código como um desenvolvedor sênior de React” ou “otimize como um especialista em performance” eleva o nível da resposta da IA
• Melhore iterativamente em conversa: com base na primeira resposta da IA, faça pedidos adicionais ou solicite ajustes para chegar gradualmente ao resultado desejado
• Mantenha a consistência do código: como a IA se apoia no estilo, nos nomes e nos comentários do código, mantenha sempre consistência e clareza

Padrões de prompt para debugging

Como estruturar prompts de debugging de forma sistemática

• Descreva claramente o problema e os sintomas: forneça informações ricas, como linguagem, objetivo da funcionalidade, comportamento esperado, mensagem de erro real e trecho de código
• Peça análise passo a passo ou linha por linha: em erros lógicos ou bugs sutis, peça que a IA acompanhe variáveis linha por linha ou explique partes do código para identificar a causa
• Use código mínimo reproduzível: em vez de um código grande e complexo, extraia a menor unidade que reproduz o erro para focar o diagnóstico
• Faça perguntas diretas e pedidos de acompanhamento: solicite feedback claro e repetível, como “onde o bug ocorre?” ou “forneça o código corrigido”

Exemplo: prompt ruim vs. prompt melhorado

Exemplo de código com problema

function mapUsersById(users) {
  const userMap = {};
  for (let i = 0; i <= users.length; i++) {  
    const user = users[i];
    userMap[user.id] = user;
  }
  return userMap;
}
const result = mapUsersById([{ id: 1, name: "Alice" }]);

Prompt ruim:

“Por que a função mapUsersById não está funcionando?”

• Resposta da IA: apresenta suposições vagas como “o array pode estar vazio” ou “talvez user não tenha id”
• Sai apenas um conselho genérico devido à falta de contexto e à falta de clareza

Prompt melhorado:

“A função mapUsersById deve mapear um array de usuários por id, mas ao receber a entrada [ {id: 1, name: "Alice"} ] ocorre o erro TypeError: Cannot read property 'id' of undefined. O código é o seguinte: [incluir código]. O resultado esperado é algo como { "1": ... }. Qual é a causa desse comportamento e como corrigir?”

• Resposta da IA: aponta que a condição do loop (i <= users.length) ultrapassa o limite e faz com que undefined apareça na última iteração, propondo a correção para i < users.length
• Ao fornecer contexto específico, mensagem de erro e comportamento esperado, obtém-se uma solução precisa

Estratégias adicionais de prompts para debugging

• Pedir uma lista de possíveis causas do bug (“quais são as causas possíveis de um TypeError?”)
• Explicar diretamente a lógica do código e pedir revisão (“minha explicação está correta? encontre o problema”)
• Pedir casos de teste para situações inesperadas (“sugira apenas 2 entradas em que esta função pode falhar”)
• Atribuir o papel de revisor cuidadoso de código (“revise este código e explique os problemas e melhorias”)

Padrões de prompt para refatoração/otimização

Apresente objetivos de melhoria claros

• “Refatore” é vago; portanto, explicite objetivos concretos como legibilidade, desempenho, manutenibilidade e remoção de duplicação de código
• Forneça contexto suficiente: o código completo (ou o necessário), além do ambiente, da linguagem e da versão do framework
• Peça também uma explicação das mudanças (“mostre o código e os pontos de melhoria”)
• Use atribuição de papel para elevar a qualidade esperada, como “como especialista em TypeScript, siga as práticas mais atuais”

Exemplo: comparação de prompts para refatoração

Código original

(inclui problemas como fetch duplicado e estrutura de dados pouco eficiente)

async function getCombinedData(apiClient) {
  // Fetch list of users
  const usersResponse = await apiClient.fetch('/users');
  if (!usersResponse.ok) {
    throw new Error('Failed to fetch users');
  }
  // ... (restante omitido)
}

Prompt vago

“Refatore a função getCombinedData”

• A IA pode alterar arbitrariamente para fetch em paralelo, unificação de mensagens de erro etc. (como não há requisitos, o comportamento é imprevisível)

Prompt com objetivos específicos

“Remova duplicações, melhore o desempenho, paralelize os dois fetches, separe as mensagens de erro e melhore a combinação dos dados com uma abordagem eficiente. Inclua também comentários e explicações dos pontos de melhoria.”

• Resposta da IA: fornece uma refatoração que reflete claramente os objetivos, incluindo fetch em paralelo, separação de erros e adoção de uma estrutura map eficiente, além de explicação detalhada

Dicas adicionais para refatoração

• Fazer pedidos em etapas (“melhore a legibilidade → depois otimize o algoritmo”)
• Pedir abordagens alternativas (“implemente também em estilo funcional”)
• Solicitar código + explicação para facilitar aprendizado e uso como tutorial
• Pedir a adição de testes ao código resultante

Padrões de prompt para implementar novas funcionalidades

Conduza a geração de código passo a passo

• Primeiro apresente uma descrição de alto nível (qual funcionalidade você quer criar) e depois detalhe em etapas
• Transmita o contexto do ambiente de trabalho, como código semelhante existente, padrões do projeto e bibliotecas usadas
• Use comentários ou TODOs como prompt para conduzir diretamente o fluxo de codificação da IA na IDE
• Forneça exemplos de entrada/saída ou casos de teste para definir expectativas claras sobre o resultado
• Se o primeiro resultado ficar aquém, faça um novo pedido imediatamente, especificando melhorias concretas ou estilo de código desejado

Exemplo: criação do componente React ProductList

“Crie um componente funcional React chamado ProductList. Ele deve buscar um array de produtos em /api/products e exibi-lo em uma lista, além de filtrar sem diferenciar maiúsculas de minúsculas quando o usuário digitar o nome do produto em um campo de entrada. Também é necessário tratar carregamento e erro durante a busca.”

• Resposta da IA: inclui useState, useEffect para buscar os dados, tratamento da entrada, filtragem e interface para erro/carregamento
• Se o projeto usar hooks customizados, é possível repetir instruções adicionais como “refatore para usar o hook useProducts()”

Casos práticos para sofisticar prompts

• É possível pedir expansão gradual de funcionalidades, como “adicione ordenação: deve haver um dropdown A-Z, Z-A”
• Dividir o fluxo de implementação em etapas e usar prompts diferentes em cada uma ajuda a manter qualidade e consistência do código

Conclusão

• Para aproveitar ao máximo o potencial dos assistentes de código com IA, a criação de prompts é uma competência central
• Para escrever prompts bem-sucedidos, é preciso sempre considerar contexto específico, objetivo, exemplos, feedback iterativo e atribuição de papel para obter resultados eficazes
• O segredo do sucesso é tratar a IA como um desenvolvedor júnior ou revisor de código dentro do projeto, orientando-a detalhadamente na direção desejada e elevando gradualmente a qualidade

[GN⁺]

Comentários no Hacker News

• Pela minha experiência, acho que existem só três técnicas realmente importantes de prompt engineering

  • In Context Learning (fornecer exemplos no contexto, ou seja, abordagem one-shot ou few-shot em contraste com zero-shot)

  • Chain of Thought (instruir a pensar passo a passo)

  • Structured output (por exemplo, especificar claramente o formato de saída, como JSON)
    Também daria para incluir o Role Prompting citado neste texto
    RAG eu classifico separadamente, porque é uma forma de o modelo resumir o contexto fornecido
    No fim, o resto é basicamente um resumo de como pedir o que você quer em linguagem clara e simples

  • Em prompts, contexto é o fator mais importante
    Por exemplo, vi casos em que a conversa começa com Typescript e depois, ao fazer uma pergunta de ciência de dados, o modelo não responde direito
    Se fizer exatamente a mesma pergunta em Python, o resultado vem bem melhor
    Como os LLMs ainda têm dificuldade em transferir conhecimento entre domínios, é essencial definir um contexto adequado ao objetivo

  • Pessoalmente também acho Role prompting um método sem muito sentido
    Pode até ter sido no GPT-3, mas a maioria dos LLMs já entende o papel de "especialista"
    Acho que ficar obcecado com "prompt engineering" é uma forma de se enganar
    O negócio é transmitir os requisitos com clareza, adicionar exemplos se necessário, verificar o resultado ou o reasoning trace e, se o que saiu não for o desejado, ajustar e tentar de novo
    Se depois de algumas tentativas ainda não sair resposta, a opção é raciocinar com a minha própria cabeça em vez de depender da IA

  • Na minha opinião, o problema de muita gente é tentar "colocar tudo de uma vez em um único prompt"
    Em vez de mandar um pedido gigantesco de uma vez, sugiro dividir em vários prompts com contextos menores, conectar saídas estruturadas e bem definidas entre si
    Cada prompt fica focado no objetivo e nos exemplos, evitando sobrecarga de contexto
    Aí aquelas 3 técnicas centrais mencionadas acima acabam se aplicando naturalmente

  • Sobre a 3ª abordagem (Structured output), eu e meus colegas fizemos um estudo de caso aplicando isso na área científica
    Link do artigo

  • Só como referência, nossa equipe depende mais de fine-tuning do que de prompt engineering
    A abordagem de few-shot prompt não funcionou no nosso caso

• Eu frequentemente sinto que, quando o prompt fica longo ou complexo demais, o desempenho cognitivo do modelo piora
  Um prompt complexo pode dar a sensação de mais controle, mas na prática isso não necessariamente é uma vantagem
  Por isso, meu padrão de uso naturalmente converge para prompts bem simples e mínimos, ajustados em algumas iterações

  • Eu também comecei a adotar exatamente essa abordagem

    1. Passo só o contexto, as premissas e o objetivo estritamente necessários
    2. Vejo a resposta e ajusto o prompt inicial
       Esse jeito também é melhor em termos de custo-benefício
       Já usei agent e vi $30 irem embora enquanto a base de código ficava bagunçada ou voltava para o estado original várias vezes
       Também quero alertar que, se você deixar a IA escrever muito código no seu projeto, depois esse código não fica bem na sua cabeça e também vira algo mais difícil de manter

  • Também há evidências de que usar terminologia de especialista no prompt melhora o desempenho
    Em geral, quando as pessoas falam em linguagem cotidiana a precisão cai, mas vocabulário de áreas especializadas tende a levar a respostas mais confiáveis
    Os dados de treinamento também refletem essa distribuição

  • Tive experiência parecida
    Mas quando olho os system prompts de agentes, muitas vezes eles são absurdamente longos e complexos, então fico na dúvida
    Tenho curiosidade de saber como prompts assim realmente funcionam
    Link com exemplos de system prompts

  • Em um trabalho, um colega meu escreveu um prompt extremamente prolixo
    Durante a integração, adicionei operações CRUD e, como experimento, troquei tudo por algo bem curto, como "analise isso da perspectiva de <cargo>"
    No fim, os resultados dos dois lados foram quase iguais, e o prompt longo ainda tinha a tendência de reutilizar partes das próprias frases na saída
    O resultado em si foi bom, mas no fim o modelo (gemini 2.5) parecia extrair só a informação importante e ainda deixar partes desnecessárias vazarem para a resposta
    Ou seja, pelo menos nessa tarefa, tive a sensação de que a prolixidade não produziu nenhum efeito interessante no "modo de pensar" do modelo

  • Cheguei à mesma conclusão, mas fico me perguntando como interpretar os exemplos de prompts longos fornecidos por laboratórios de IA
    Exemplo de system prompt da Anthropic

• Acho que "prompt engineering" não existe como algo separado
  Desde quando escrever frases significativas de forma decente virou engenharia?
  Acho isso ainda pior do que "software engineering"
  Dito isso, é uma pena pensar que no futuro isso talvez vire mesmo uma profissão (prompt engineer) e passe a ser tratado como uma habilidade especial de escrever frases

  • Na verdade, "frases significativas escritas direito" variam de acordo com inúmeras variáveis
    Na prática, quando você inclui testes, manutenção, logging e versionamento, isso deixa de ser puro feeling e vira engenharia
    Estrutura como ordem específica, estilo e reformulação do problema é muito importante
    Ao lidar com famílias de modelos com muitos parâmetros, modelos baseados em API exigem checagem de compatibilidade dos prompts a cada atualização de versão
    Essas checagens e testes também fazem parte do processo de prompt engineering
    Acho que muita gente, por rejeitar a moda e o hype, acaba ignorando a essência da questão

  • Se o barista aqui da minha região colocasse "engenheiro de café" no próprio nome, talvez eu até confiasse mais

  • Isso também é efeito de consumidores modernos tão viciados em algoritmo que já estão perdendo até a capacidade de ler frases inteiras

  • Não acho que seja preciso se preocupar com vagas de "prompt engineer"

  • AI sloperators se esforçam muito para fazer o próprio trabalho parecer impressionante

• Pela minha experiência, quando o LLM não consegue resolver um problema, muitas vezes não adianta fazer qualquer tipo de "engenharia" de prompt
  No máximo, o que funciona é quebrar o problema em partes menores e deixar o modelo avançar aos poucos
  Se alguém teve a experiência oposta, gostaria de ouvir exemplos

  • Uma parte importante de usar LLM é desenvolver a noção de como decompor o problema da forma certa
    É preciso saber quando e como quebrar, e quando simplesmente delegar
    Como o artigo também mencionou, esse tipo de know-how é importante
    No futuro, também deve aumentar a quantidade de formas de organizar e comentar melhor o código para melhorar a interação com LLMs
    Os próprios LLMs também devem evoluir nessa direção e talvez consigam até sugerir maneiras de dividir o problema

  • O objetivo de prompt engineering é obter boas respostas mais rápido e no formato desejado
    No ideal, o modelo responderia sozinho, mas na prática a própria pergunta também precisa ser otimizada

• Ao escrever prompts, por hábito, ainda acho meio estranho dar instruções em linguagem natural
  Dá a sensação de que eu deveria escrever como se fossem argumentos exatos ou uma query SQL
  Também é curioso dar instruções para a ferramenta como se estivesse conversando
  Ainda assim, o fato de terem virado ferramentas que entendem instruções em linguagem natural aumentou dramaticamente a acessibilidade
  Mesmo assim, ainda acho um pouco engraçado me ver escrevendo prompts como se estivesse falando com uma pessoa

• Hoje em dia há uma quantidade enorme de guias de prompt
  Mas acho que, na prática, eles não são tão necessários
  Se você usar a ferramenta diretamente, se familiarizar e aprender como ela funciona, acaba entendendo naturalmente o que é um bom prompt

  • É parecido com a época em que o Google virou moda e havia aquela onda de FOMO
    Diziam que, se você não comprasse os livros sobre isso, ficaria para trás como um homem das cavernas, mas na prática era uma área simples que dava para aprender toda em um dia, então não valia a pena pensar tanto

  • Guias e vídeos de dicas realmente ajudam algumas pessoas
    Muita gente não tem iniciativa de melhorar por conta própria, mas só de ver um guia ou um vídeo de alguém muito bom já consegue evoluir
    Eu mesmo sempre aprendo dicas com a forma de uso de outras pessoas e com experiências da comunidade
    Só praticando sozinho há limites para esse tipo de aprendizado

  • Antigamente havia fórmulas como em "guia para escrever user stories", por exemplo: "As a [role], I want to [task] so I can [objective]"
    Tanto especialistas quanto iniciantes precisam de ajuda para transmitir requisitos com clareza
    Até desenvolvedores excelentes podem errar ou interpretar mal requisitos não estruturados

  • Também ajuda bastante observar como outras pessoas conseguem produtividade com essa ferramenta
    Dá para descobrir ideias que eu não tinha percebido
    Em vez de aprender tudo sozinho por tentativa e erro, é mais eficiente aproveitar ao menos um pouco da experiência que alguém já acumulou
    Pessoalmente, como não tenho tempo para testar tudo por conta própria, esse tipo de compartilhamento de experiência é informação muito valiosa

  • Com certeza existem truques pouco óbvios
    Por exemplo, pela minha experiência, dá para remover totalmente expressões de cortesia como "please" dos prompts

• Faz bastante tempo, no meu mestrado em computação, aprendi no curso de Science of programming um processo de verificação que apliquei bem na escrita de prompts para engenharia de dados
  Por exemplo: "dado input(...) e premissas(...), escreva código spark que satisfaça a post-condition(...)"
  Se você explicitar com clareza entrada, premissas e condição de resultado, dá para obter boas saídas de código
  Materiais de referência

  1. Science of programming, David Gries
  2. Verification of concurrent and sequential systems

• Acho exagerado levar prompt engineering tão a sério
  Hoje em dia, se você simplesmente copiar e colar código ou erro e fizer uma pergunta em linguagem simples, a maioria dos modelos já lida bem com isso
  Não sinto necessidade de escrever de forma excessivamente rebuscada

• Há alguns dias, Sergey Brin disse que, como um fato pouco mencionado na comunidade de IA, "ameaças físicas melhoram o desempenho do modelo"
  Artigo relacionado

  • Isso me fez lembrar da piada de um vibe coder profissional no YouTube “Programmers are also human”, que sempre termina comandos para LLM com ".. ou vai para a cadeia"

  • Será que foi por isso que o Google foi largando discretamente o "Don't Be Evil"?

• Chamar a escrita de prompts de "engenharia" me parece algo pouco sério demais

  • Na época em que prompt "engineering" estava na moda, ouvi uma analogia engraçada

    Chamar alguém de prompt engineer é igual ao funcionário do Subway se chamar de "sandwich artist"
    Piadas à parte, a palavra engenheiro já foi usada de forma tão ampla que quase perdeu o significado
    Link sobre Sandwich Artist

  • No fim, essa discussão se repete toda vez que aparece o tema software engineering

  • Talvez isso aconteça porque a imaginação de muita gente para no nível de pedir foto de gato em uma interface de chat
    Na prática, também existem prompts usados em APIs e fluxos de automação, então a coisa vai além disso

  • Nos EUA também existe o cargo de "sales engineer", e pela minha experiência muitas dessas pessoas não fazem a menor ideia de como funciona o produto que vendem

  • TI é o lugar onde as palavras e seus significados desaparecem
    Dá até vontade de perguntar se as palavras realmente precisam ter um significado original