Voc\u00ea abre o chat da IA, digita “cria uma fun\u00e7\u00e3o para validar CPF” e recebe um c\u00f3digo que compila, mas que n\u00e3o trata m\u00e1scaras, n\u00e3o considera CPFs com todos os d\u00edgitos iguais, n\u00e3o segue o padr\u00e3o de nomenclatura do seu projeto e usa uma biblioteca que a sua equipe n\u00e3o aprovou. Voc\u00ea corrige, pede de novo, a IA erra em outro ponto. Cinco intera\u00e7\u00f5es depois, voc\u00ea j\u00e1 teria escrito a fun\u00e7\u00e3o sozinho \u2014 e ainda ficou com a sensa\u00e7\u00e3o de que a IA “n\u00e3o presta”.<\/p>\n
Esse cen\u00e1rio se repete com uma frequ\u00eancia inc\u00f4moda em times que adotaram ferramentas como Claude<\/a>, ChatGPT<\/a> ou assistentes integrados ao editor, como o Cursor<\/a> e o GitHub Copilot<\/a>. O problema quase nunca est\u00e1 no modelo. Est\u00e1 no prompt. Um prompt vago produz um c\u00f3digo gen\u00e9rico; um prompt bem constru\u00eddo produz um c\u00f3digo espec\u00edfico, alinhado ao seu contexto e, na maioria das vezes, correto de primeira.<\/p>\n Neste artigo vou detalhar a estrutura que uso profissionalmente para escrever prompts que geram c\u00f3digo de qualidade \u2014 com exemplos reais em diferentes linguagens, incluindo os erros mais comuns que fazem desenvolvedores desistirem da IA antes de aprender a conversar com ela corretamente.<\/p>\n Modelos de linguagem n\u00e3o leem sua mente. Eles preveem a continua\u00e7\u00e3o mais prov\u00e1vel do texto que voc\u00ea forneceu. Se o texto \u00e9 vago, a continua\u00e7\u00e3o mais prov\u00e1vel \u00e9… gen\u00e9rica. \u00c9 a mesma l\u00f3gica de perguntar a um consultor “me faz um or\u00e7amento” sem dizer o que precisa or\u00e7ar: ele vai te entregar algo plaus\u00edvel, mas raramente \u00fatil.<\/p>\n Compare estes dois prompts:<\/p>\n O segundo prompt elimina praticamente toda ambiguidade. A IA n\u00e3o precisa “adivinhar” se voc\u00ea quer suporte a dom\u00ednios internacionais, se pode usar uma lib, ou qual conven\u00e7\u00e3o de nomes seguir. Cada decis\u00e3o que voc\u00ea toma antecipadamente \u00e9 uma itera\u00e7\u00e3o de corre\u00e7\u00e3o que voc\u00ea economiza depois.<\/p>\n \ud83d\udca1 Dica do Mestre:<\/strong> o conceito de “prompt engineering” ganhou formaliza\u00e7\u00e3o acad\u00eamica com o paper “Pre-train, Prompt, and Predict”<\/a> (Liu et al., 2021), que documenta como pequenas mudan\u00e7as na formula\u00e7\u00e3o de um prompt alteram drasticamente a qualidade da sa\u00edda de modelos de linguagem.<\/p>\n<\/blockquote>\n Depois de escrever centenas de prompts para gera\u00e7\u00e3o de c\u00f3digo em projetos reais, identifiquei cinco elementos que, quando presentes, aumentam consistentemente a qualidade da resposta. Vou detalhar cada um.<\/p>\n A IA n\u00e3o sabe se voc\u00ea est\u00e1 construindo um microsservi\u00e7o em produ\u00e7\u00e3o ou um script descart\u00e1vel. Informe a linguagem, o framework, a vers\u00e3o e, se relevante, o ambiente de execu\u00e7\u00e3o.<\/p>\n Esse tipo de informa\u00e7\u00e3o evita que a IA sugira, por exemplo, um loop bloqueante s\u00edncrono em um ambiente serverless com timeout curto, ou que use uma API do Node 22 em um projeto travado na vers\u00e3o 20.<\/p>\n Dizer o que voc\u00ea quer \u00e9 importante, mas dizer o que voc\u00ea n\u00e3o<\/em> quer costuma ser ainda mais eficaz, porque elimina os “caminhos padr\u00e3o” que o modelo tende a seguir por estat\u00edstica.<\/p>\n Se seu time tem um padr\u00e3o de c\u00f3digo estabelecido, mostrar um exemplo real vale mais do que qualquer descri\u00e7\u00e3o textual. Essa t\u00e9cnica \u00e9 chamada de few-shot prompting<\/em> e \u00e9 uma das mais eficazes para manter consist\u00eancia de estilo.<\/p>\n O resultado tende a manter a mesma inje\u00e7\u00e3o de depend\u00eancia via construtor, o mesmo tratamento de erro e a mesma nomenclatura \u2014 porque voc\u00ea n\u00e3o descreveu o padr\u00e3o, voc\u00ea mostrou<\/em> o padr\u00e3o.<\/p>\n Se voc\u00ea vai colar o c\u00f3digo direto no projeto, diga isso. Se quer apenas o trecho da fun\u00e7\u00e3o sem explica\u00e7\u00f5es longas, diga isso tamb\u00e9m. Prompts que n\u00e3o especificam o formato geram respostas com texto explicativo excessivo, que exige trabalho manual de extra\u00e7\u00e3o.<\/p>\n Esse \u00e9 o elemento mais negligenciado e, na minha experi\u00eancia, o que mais reduz retrabalho. Descreva os casos de teste ou o comportamento esperado nas bordas (edge cases). Isso obriga o modelo a considerar cen\u00e1rios que normalmente ficariam de fora de uma resposta gen\u00e9rica.<\/p>\n Juntando os cinco elementos, um prompt real para o exemplo de valida\u00e7\u00e3o de e-mail ficaria assim:<\/p>\n Testei esse exato prompt no Claude<\/a> e a resposta j\u00e1 veio com os casos de borda tratados corretamente, sem necessidade de corre\u00e7\u00e3o \u2014 porque cada decis\u00e3o amb\u00edgua j\u00e1 havia sido eliminada antes da gera\u00e7\u00e3o.<\/p>\n A estrutura funciona independentemente da linguagem. Veja um exemplo em Python para gera\u00e7\u00e3o de uma fun\u00e7\u00e3o de retry:<\/p>\n E, para times que trabalham com Delphi \u2014 cen\u00e1rio comum em sistemas legados de m\u00e9dio e grande porte no Brasil \u2014 o mesmo princ\u00edpio se aplica ao gerar uma classe ou unit:<\/p>\n Notou o padr\u00e3o? A estrutura do prompt n\u00e3o muda com a linguagem. O que muda \u00e9 o vocabul\u00e1rio t\u00e9cnico espec\u00edfico de cada ecossistema \u2014 e isso voc\u00ea domina melhor do que qualquer modelo, porque \u00e9 voc\u00ea quem conhece o seu projeto.<\/p>\n Prompts como “crie um sistema de login completo” geram respostas superficiais em v\u00e1rias frentes ao mesmo tempo, em vez de uma solu\u00e7\u00e3o s\u00f3lida em uma frente espec\u00edfica. Prefira decompor: primeiro o modelo de dados, depois a valida\u00e7\u00e3o, depois a persist\u00eancia, depois a rota HTTP \u2014 cada etapa com seu pr\u00f3prio prompt, revisado antes de avan\u00e7ar para a pr\u00f3xima.<\/p>\n Se voc\u00ea j\u00e1 tem uma classe de erro customizada, um logger configurado ou um padr\u00e3o de resposta de API, diga isso no prompt. Sem essa informa\u00e7\u00e3o, a IA cria suas pr\u00f3prias abstra\u00e7\u00f5es \u2014 que depois voc\u00ea precisa substituir manualmente pelas do projeto.<\/p>\n Um prompt bem escrito reduz a chance de erro, mas n\u00e3o elimina a necessidade de revis\u00e3o. Trate a sa\u00edda da IA como o trabalho de um desenvolvedor j\u00fanior talentoso: provavelmente est\u00e1 no caminho certo, mas merece um code review antes de ir para produ\u00e7\u00e3o.<\/p>\nO problema real: prompt vago, c\u00f3digo gen\u00e9rico<\/h2>\n
Prompt vago:\n\"cria uma fun\u00e7\u00e3o para validar email\"\n\nPrompt espec\u00edfico:\n\"Escreva uma fun\u00e7\u00e3o em TypeScript chamada validateEmail que:\n- Recebe uma string e retorna um boolean\n- Usa regex compat\u00edvel com RFC 5322 simplificado\n- Rejeita strings vazias ou com espa\u00e7os\n- N\u00e3o usa bibliotecas externas\n- Inclui JSDoc explicando o comportamento\n- Segue o padr\u00e3o de nomenclatura camelCase do projeto\"\n<\/code><\/pre>\nA anatomia de um prompt de c\u00f3digo eficaz<\/h2>\n
1. Contexto: onde esse c\u00f3digo vai viver<\/h3>\n
Contexto: Projeto Node.js 20 com Express 4, usando TypeScript strict mode.\nO c\u00f3digo roda em um servidor serverless (AWS Lambda) com timeout de 10s.\n<\/code><\/pre>\n2. Restri\u00e7\u00f5es expl\u00edcitas: o que N\u00c3O fazer<\/h3>\n
Restri\u00e7\u00f5es:\n- N\u00e3o use bibliotecas externas al\u00e9m do que j\u00e1 est\u00e1 no package.json\n- N\u00e3o use \"any\" em nenhum lugar do c\u00f3digo TypeScript\n- N\u00e3o crie classes; prefira fun\u00e7\u00f5es puras\n- N\u00e3o fa\u00e7a chamadas de rede dentro da fun\u00e7\u00e3o de valida\u00e7\u00e3o\n<\/code><\/pre>\n3. Exemplos (few-shot): mostre o padr\u00e3o que voc\u00ea quer seguir<\/h3>\n
Aqui est\u00e1 um exemplo de como estruturamos nossos servi\u00e7os:\n\nclass UserService {\n constructor(private readonly repository: UserRepository) {}\n\n async findById(id: string): Promise<User | null> {\n if (!id) throw new InvalidArgumentError('id \u00e9 obrigat\u00f3rio');\n return this.repository.findById(id);\n }\n}\n\nAgora crie um OrderService seguindo exatamente esse padr\u00e3o,\ncom os m\u00e9todos findById e listByUserId.\n<\/code><\/pre>\n4. Formato de sa\u00edda: pe\u00e7a exatamente o que voc\u00ea vai usar<\/h3>\n
Formato de resposta:\n- Apenas o c\u00f3digo, sem explica\u00e7\u00f5es antes ou depois\n- Coment\u00e1rios apenas onde a l\u00f3gica n\u00e3o for \u00f3bvia\n- Se houver mais de um arquivo, use blocos separados com o\n nome do arquivo como cabe\u00e7alho\n<\/code><\/pre>\n5. Crit\u00e9rio de aceita\u00e7\u00e3o: como saber se est\u00e1 correto<\/h3>\n
Crit\u00e9rios de aceita\u00e7\u00e3o:\n- validateEmail(\"\") deve retornar false\n- validateEmail(\"a@b.co\") deve retornar true\n- validateEmail(\"usuario@dominio\") deve retornar false (sem TLD)\n- validateEmail(\" a@b.com \") deve retornar false (espa\u00e7os nas pontas)\n<\/code><\/pre>\nPrompt completo na pr\u00e1tica<\/h2>\n
Contexto: Projeto TypeScript 5.4 sem depend\u00eancias externas para valida\u00e7\u00e3o,\nexecutado no navegador (n\u00e3o pode usar m\u00f3dulos Node).\n\nTarefa: Escreva uma fun\u00e7\u00e3o chamada validateEmail que recebe uma string\ne retorna um boolean.\n\nRestri\u00e7\u00f5es:\n- N\u00e3o use bibliotecas externas\n- N\u00e3o aceite espa\u00e7os nas extremidades da string\n- N\u00e3o considere dom\u00ednios sem TLD como v\u00e1lidos\n\nCrit\u00e9rios de aceita\u00e7\u00e3o:\n- validateEmail(\"\") -> false\n- validateEmail(\"a@b.co\") -> true\n- validateEmail(\"usuario@dominio\") -> false\n- validateEmail(\" a@b.com \") -> false\n\nFormato de resposta: apenas o c\u00f3digo TypeScript, com JSDoc na fun\u00e7\u00e3o.\n<\/code><\/pre>\nAplicando o mesmo racioc\u00ednio em outras linguagens<\/h2>\n
Contexto: script Python 3.12 para chamadas HTTP usando a biblioteca requests,\nj\u00e1 presente no requirements.txt.\n\nTarefa: crie uma fun\u00e7\u00e3o retry_request que tenta uma requisi\u00e7\u00e3o HTTP\nat\u00e9 3 vezes com backoff exponencial.\n\nRestri\u00e7\u00f5es:\n- N\u00e3o use bibliotecas de retry externas (tenacity, backoff etc.)\n- Deve lan\u00e7ar a \u00faltima exce\u00e7\u00e3o capturada se todas as tentativas falharem\n- Deve logar cada tentativa usando o m\u00f3dulo logging padr\u00e3o\n\nCrit\u00e9rios de aceita\u00e7\u00e3o:\n- Se a primeira tentativa funcionar, n\u00e3o deve haver espera\n- O tempo de espera deve dobrar a cada tentativa (1s, 2s, 4s)\n- Deve funcionar com qualquer fun\u00e7\u00e3o que receba **kwargs\n\nFormato: apenas a fun\u00e7\u00e3o, com type hints e docstring no formato Google.\n<\/code><\/pre>\nContexto: projeto Delphi 12 (Object Pascal), usando o padr\u00e3o de nomenclatura\ncom prefixo T para classes e I para interfaces, seguindo Clean Code.\n\nTarefa: crie uma classe TCpfValidator com um m\u00e9todo p\u00fablico\nfunction IsValid(const ACpf: string): Boolean.\n\nRestri\u00e7\u00f5es:\n- N\u00e3o usar unit de terceiros\n- Remover m\u00e1scara antes de validar (pontos e h\u00edfen)\n- Rejeitar CPFs com todos os d\u00edgitos iguais\n\nCrit\u00e9rios de aceita\u00e7\u00e3o:\n- IsValid('') -> False\n- IsValid('111.111.111-11') -> False\n- IsValid('529.982.247-25') -> True\n\nFormato: apenas a classe completa, com interface e implementation.\n<\/code><\/pre>\nErros comuns que arru\u00ednam bons prompts<\/h2>\n
Pedir “o c\u00f3digo completo” sem definir escopo<\/h3>\n
N\u00e3o informar o que j\u00e1 existe no projeto<\/h3>\n
Aceitar a primeira resposta sem revis\u00e3o cr\u00edtica<\/h3>\n