Voc\u00ea pede para o modelo “criar uma fun\u00e7\u00e3o que processa pagamentos com retry”, recebe um c\u00f3digo que compila, passa no teste feliz que voc\u00ea rodou manualmente e vai para o pull request. Tr\u00eas semanas depois, em produ\u00e7\u00e3o, um timeout no gateway de pagamento gera cobran\u00e7a duplicada porque o retry n\u00e3o era idempotente. Ningu\u00e9m pediu idempot\u00eancia no prompt \u2014 e o modelo, sem essa restri\u00e7\u00e3o expl\u00edcita, escolheu a implementa\u00e7\u00e3o estatisticamente mais comum nos dados de treino, que raramente \u00e9 a mais correta para o seu dom\u00ednio espec\u00edfico. O c\u00f3digo estava sintaticamente impec\u00e1vel e semanticamente incompleto. Esse \u00e9 o tipo de bug que n\u00e3o aparece em nenhum linter, porque n\u00e3o \u00e9 um erro de sintaxe: \u00e9 um erro de especifica\u00e7\u00e3o que o desenvolvedor terceirizou para um modelo sem perceber que estava fazendo isso.<\/p>\n
Esse cen\u00e1rio se repete todos os dias em equipes que j\u00e1 dominam a mec\u00e2nica de “conversar com a IA” mas nunca formalizaram como isso deveria funcionar em c\u00f3digo de produ\u00e7\u00e3o. A discuss\u00e3o p\u00fablica sobre o tema, como aponta este texto sobre o deslocamento do trabalho do desenvolvedor para a escrita de prompts<\/a>, tende a tratar o prompt como um substituto direto do c\u00f3digo. N\u00e3o \u00e9. Prompt \u00e9 especifica\u00e7\u00e3o informal, e especifica\u00e7\u00e3o informal sempre teve um custo \u2014 s\u00f3 que agora esse custo aparece como bug em produ\u00e7\u00e3o em vez de aparecer como retrabalho na fase de design. Este artigo trata prompt engineering para c\u00f3digo como o que ele realmente \u00e9: uma disciplina de especifica\u00e7\u00e3o com suas pr\u00f3prias falhas de modo, seus pr\u00f3prios trade-offs de verbosidade versus liberdade do modelo, e seus pr\u00f3prios limites estruturais que nenhuma t\u00e9cnica de prompt resolve sozinha.<\/p>\n A maioria dos desenvolvedores trata o prompt como uma pergunta em linguagem natural. Isso funciona para tarefas explorat\u00f3rias \u2014 “como funciona o algoritmo de Dijkstra” \u2014 mas falha sistematicamente para gera\u00e7\u00e3o de c\u00f3digo de produ\u00e7\u00e3o, porque c\u00f3digo de produ\u00e7\u00e3o n\u00e3o \u00e9 definido pelo que ele faz no caso feliz, e sim pelo que ele faz nos casos de borda, nas condi\u00e7\u00f5es de falha e nas restri\u00e7\u00f5es n\u00e3o funcionais que nunca aparecem no enunciado do problema.<\/p>\n Um LLM, na aus\u00eancia de restri\u00e7\u00f5es expl\u00edcitas, preenche essas lacunas com o padr\u00e3o estatisticamente mais frequente no seu corpus de treino. Isso significa que ele vai gerar tratamento de erro gen\u00e9rico, vai assumir que strings s\u00e3o UTF-8 bem formado, vai assumir que listas cabem em mem\u00f3ria, e vai assumir que a opera\u00e7\u00e3o pode ser refeita sem efeito colateral \u2014 porque essas s\u00e3o as suposi\u00e7\u00f5es mais comuns em c\u00f3digo de exemplo dispon\u00edvel publicamente. Nenhuma dessas suposi\u00e7\u00f5es \u00e9 necessariamente errada. O problema \u00e9 que elas s\u00e3o impl\u00edcitas, e decis\u00f5es impl\u00edcitas em c\u00f3digo de produ\u00e7\u00e3o s\u00e3o decis\u00f5es que ningu\u00e9m revisou.<\/p>\n \ud83d\udca1 Dica do Mestre:<\/strong> pense no prompt como a especifica\u00e7\u00e3o que voc\u00ea daria a um desenvolvedor j\u00fanior extremamente r\u00e1pido e sem contexto de neg\u00f3cio. Ele vai produzir exatamente o que voc\u00ea pediu, na leitura mais literal poss\u00edvel, e vai preencher qualquer ambiguidade com a interpreta\u00e7\u00e3o mais gen\u00e9rica. Se voc\u00ea n\u00e3o especifica idempot\u00eancia, ele n\u00e3o vai adivinhar que sua opera\u00e7\u00e3o de pagamento precisa dela.<\/p><\/blockquote>\n Uma estrutura discutida em uma thread de desenvolvedores sobre prompts para gera\u00e7\u00e3o de c\u00f3digo<\/a> prop\u00f5e uma sequ\u00eancia que vale a pena formalizar como checklist de revis\u00e3o, n\u00e3o como f\u00f3rmula r\u00edgida: definir a fun\u00e7\u00e3o que o modelo deve assumir (revisor s\u00eanior, arquiteto, implementador), a tarefa espec\u00edfica, os detalhes t\u00e9cnicos n\u00e3o negoci\u00e1veis, o contexto do sistema existente e exemplos de c\u00f3digo que j\u00e1 seguem o padr\u00e3o esperado.<\/p>\n Na pr\u00e1tica, isso significa que um prompt de produ\u00e7\u00e3o raramente cabe em uma linha. Compare:<\/p>\n A diferen\u00e7a de tamanho entre os dois prompts \u00e9 proposital. O segundo n\u00e3o \u00e9 “mais educado” \u2014 ele elimina graus de liberdade que, se deixados abertos, o modelo vai preencher com a op\u00e7\u00e3o mais gen\u00e9rica, n\u00e3o com a op\u00e7\u00e3o correta para o seu sistema.<\/p>\n Um padr\u00e3o que raramente aparece em tutoriais introdut\u00f3rios, mas que faz diferen\u00e7a mensur\u00e1vel em c\u00f3digo gerado para produ\u00e7\u00e3o, \u00e9 a restri\u00e7\u00e3o negativa \u2014 dizer explicitamente o que o modelo n\u00e3o<\/strong> deve fazer. Isso \u00e9 contraintuitivo porque a maioria dos guias de prompt foca em descrever o resultado desejado, mas um LLM treinado em bilh\u00f5es de exemplos de c\u00f3digo carrega vieses fortes para padr\u00f5es espec\u00edficos que muitas vezes s\u00e3o exatamente o que voc\u00ea quer evitar: uso de bibliotecas desatualizadas, padr\u00f5es de acesso a dados que n\u00e3o escalam, tratamento de exce\u00e7\u00e3o que engole o erro original.<\/p>\n Considere este exemplo em Python:<\/p>\n A primeira vers\u00e3o n\u00e3o est\u00e1 “errada” no sentido sint\u00e1tico \u2014 ela compila, roda, e em uma demonstra\u00e7\u00e3o ao vivo parece funcionar. Mas ela mascara falhas, perde a exce\u00e7\u00e3o original e n\u00e3o distingue item que falhou de item que nunca foi processado. Nenhuma dessas falhas aparece em um teste superficial. Elas aparecem em produ\u00e7\u00e3o, tr\u00eas meses depois, quando algu\u00e9m precisa descobrir por que 12% dos registros de um lote sumiram silenciosamente.<\/p>\n Outro erro recorrente em times que adotaram ferramentas como Cursor<\/a> ou Claude Code<\/a> \u00e9 tratar cada prompt como isolado, sem ancor\u00e1-lo nas conven\u00e7\u00f5es arquiteturais do projeto. Um modelo sem esse ancoramento vai gerar c\u00f3digo estilisticamente correto, mas arquiteturalmente inconsistente \u2014 uma camada de reposit\u00f3rio que acessa o banco diretamente em um projeto que segue rigorosamente Clean Architecture, por exemplo, ou um servi\u00e7o que lan\u00e7a exce\u00e7\u00f5es em um codebase que padronizou Result types.<\/p>\n Isso n\u00e3o \u00e9 resolvido pedindo “siga os padr\u00f5es do projeto” de forma gen\u00e9rica \u2014 essa instru\u00e7\u00e3o \u00e9 vaga o suficiente para n\u00e3o restringir nada. O que funciona \u00e9 apontar exemplos concretos do pr\u00f3prio c\u00f3digo como refer\u00eancia de padr\u00e3o:<\/p>\n Ferramentas com contexto persistente de projeto \u2014 arquivos de regras, mem\u00f3ria de sess\u00e3o, indexa\u00e7\u00e3o de codebase \u2014 reduzem parcialmente essa necessidade de repetir contexto a cada prompt, mas n\u00e3o eliminam a necessidade de voc\u00ea, desenvolvedor, decidir explicitamente qual arquivo \u00e9 a refer\u00eancia can\u00f4nica de padr\u00e3o. O modelo n\u00e3o sabe, por conta pr\u00f3pria, que Uma mudan\u00e7a de mentalidade que separa uso amador de uso profissional de IA generativa \u00e9 tratar prompts recorrentes como c\u00f3digo: versionados, revisados e reutilizados, em vez de reescritos do zero a cada sess\u00e3o. Isso \u00e9 especialmente relevante para tarefas repetitivas de gera\u00e7\u00e3o \u2014 cria\u00e7\u00e3o de endpoints CRUD, migrations, testes de unidade seguindo um padr\u00e3o espec\u00edfico.<\/p>\n Esse arquivo de prompt, mantido no reposit\u00f3rio e referenciado por conven\u00e7\u00e3o \u2014 seja via arquivo de instru\u00e7\u00f5es do Cursor, seja via \ud83d\udca1 Dica do Mestre:<\/strong> um material introdut\u00f3rio sobre boas pr\u00e1ticas de prompt, dispon\u00edvel em esta mentoria pr\u00e1tica sobre prompts claros e seguros<\/a>, refor\u00e7a um ponto que vale para times avan\u00e7ados tamb\u00e9m: comandos claros reduzem retrabalho, mas comandos claros e n\u00e3o versionados reduzem retrabalho apenas uma vez. A economia recorrente s\u00f3 existe quando o prompt vira artefato reutiliz\u00e1vel.<\/p><\/blockquote>\n Um erro de escala \u00e9 tentar resolver problemas complexos com um \u00fanico prompt gigante, esperando que o modelo produza, de uma vez, uma solu\u00e7\u00e3o completa e correta em todas as camadas \u2014 arquitetura, implementa\u00e7\u00e3o, testes e tratamento de erro. Isso funciona para tarefas pequenas e falha de forma proporcional \u00e0 complexidade da tarefa, porque a probabilidade de erro composto cresce a cada decis\u00e3o impl\u00edcita que o modelo precisa tomar sem checkpoint intermedi\u00e1rio.<\/p>\n A alternativa \u00e9 decompor a tarefa em uma cadeia de prompts com verifica\u00e7\u00e3o humana entre etapas \u2014 o que, em ferramentas de agente, se aproxima do que j\u00e1 foi discutido no contexto de como a intera\u00e7\u00e3o com IA na programa\u00e7\u00e3o est\u00e1 evoluindo de comandos isolados para fluxos estruturados<\/a>. Na pr\u00e1tica:<\/p>\n Essa decomposi\u00e7\u00e3o custa mais tempo por intera\u00e7\u00e3o, mas reduz drasticamente o volume de suposi\u00e7\u00f5es impl\u00edcitas empilhadas em uma \u00fanica resposta. \u00c9 o mesmo princ\u00edpio de engenharia de software que j\u00e1 conhecemos de outros contextos: dividir um problema grande em unidades menores e verific\u00e1veis reduz a superf\u00edcie de erro n\u00e3o detectado \u2014 s\u00f3 que aqui a unidade de trabalho \u00e9 uma etapa de prompt em vez de uma fun\u00e7\u00e3o.<\/p>\nO prompt n\u00e3o \u00e9 uma pergunta, \u00e9 um contrato incompleto por padr\u00e3o<\/h2>\n
O framework Fun\u00e7\u00e3o \u2192 Tarefa \u2192 Detalhes \u2192 Contexto \u2192 Exemplos<\/h3>\n
\/\/ Prompt fraco\n\"Crie uma fun\u00e7\u00e3o de retry para chamadas HTTP\"\n\n\/\/ Prompt com especifica\u00e7\u00e3o de contrato\n\"Implemente uma fun\u00e7\u00e3o de retry para chamadas HTTP em TypeScript com estas restri\u00e7\u00f5es:\n- M\u00e1ximo de 3 tentativas, backoff exponencial com jitter\n- Retry apenas para status 429, 502, 503, 504 e erros de timeout de rede\n- N\u00c3O fazer retry em erros 4xx exceto 429 (evitar reenviar requisi\u00e7\u00f5es inv\u00e1lidas)\n- A fun\u00e7\u00e3o deve receber um AbortSignal externo e respeit\u00e1-lo\n- Deve ser idempotente: assuma que o chamador garante idempot\u00eancia da opera\u00e7\u00e3o,\n mas documente essa premissa explicitamente no JSDoc\n- Retornar um Result em vez de lan\u00e7ar exce\u00e7\u00e3o gen\u00e9rica\n- Exemplo de assinatura esperada: retryFetch(url, options, retryConfig): Promise<Result>\"\n<\/code><\/pre>\nRestri\u00e7\u00f5es negativas valem mais que instru\u00e7\u00f5es positivas<\/h2>\n
# Prompt sem restri\u00e7\u00e3o negativa tende a gerar isto:\ndef process_batch(items):\n try:\n results = []\n for item in items:\n results.append(transform(item))\n return results\n except Exception as e:\n print(f\"Erro: {e}\")\n return []\n\n# Prompt com restri\u00e7\u00e3o negativa expl\u00edcita:\n# \"N\u00e3o capture exce\u00e7\u00f5es gen\u00e9ricas. N\u00e3o use print para logging.\n# Se um item falhar, ele deve ser reportado individualmente,\n# e o processamento dos demais itens deve continuar.\"\ndef process_batch(items: list[Item]) -> BatchResult:\n successes: list[TransformedItem] = []\n failures: list[ItemError] = []\n for item in items:\n try:\n successes.append(transform(item))\n except TransformationError as e:\n logger.warning(\"Falha ao transformar item %s: %s\", item.id, e)\n failures.append(ItemError(item_id=item.id, reason=str(e)))\n return BatchResult(successes=successes, failures=failures)\n<\/code><\/pre>\nContexto de arquitetura como parte obrigat\u00f3ria do prompt, n\u00e3o como extra<\/h3>\n
\/\/ Prompt ancorado em exemplo real do projeto\n\"Implemente o UserRepository seguindo exatamente o mesmo padr\u00e3o\nusado em OrderRepository (arquivo src\/repositories\/order-repository.ts):\n- Inje\u00e7\u00e3o de depend\u00eancia do Pool via construtor\n- M\u00e9todos retornam Either usando fp-ts\n- Erros de constraint violation do Postgres s\u00e3o mapeados para\n DuplicateEntityError, n\u00e3o propagados como PostgresError bruto\n- Toda query usa prepared statement, nunca template string\"\n<\/code><\/pre>\norder-repository.ts<\/code> \u00e9 o exemplo “certo” e n\u00e3o um c\u00f3digo legado que est\u00e1 sendo descontinuado.<\/p>\nO prompt como artefato versionado, n\u00e3o como conversa descart\u00e1vel<\/h2>\n
## prompts\/gerar-endpoint-crud.md\n\nVoc\u00ea \u00e9 um engenheiro backend s\u00eanior trabalhando neste projeto FastAPI.\n\nAo gerar um endpoint CRUD, siga SEMPRE:\n1. Schema Pydantic de entrada separado do schema de sa\u00edda (nunca reutilize o mesmo model)\n2. Valida\u00e7\u00e3o de autoriza\u00e7\u00e3o via dependency `require_permission(...)`,\n nunca inline no corpo da fun\u00e7\u00e3o\n3. Toda exce\u00e7\u00e3o de dom\u00ednio deve herdar de `DomainError` (ver `core\/errors.py`)\n e ser capturada pelo exception handler global \u2014 n\u00e3o trate erro dentro do endpoint\n4. Pagina\u00e7\u00e3o obrigat\u00f3ria em endpoints de listagem, usando `PageParams`\n j\u00e1 definido em `core\/pagination.py`\n5. NUNCA exponha o model do SQLAlchemy diretamente na resposta\n\nExemplo de refer\u00eancia completo: `api\/routes\/products.py`\n\nContexto adicional desta tarefa:\n{{contexto_especifico}}\n<\/code><\/pre>\nCLAUDE.md<\/code> no caso do Claude Code \u2014 funciona como um contrato reutiliz\u00e1vel. Ele elimina a vari\u00e2ncia entre sess\u00f5es diferentes, entre desenvolvedores diferentes e entre dias diferentes do mesmo desenvolvedor. Sem esse artefato, cada pessoa do time reinventa a especifica\u00e7\u00e3o a cada prompt, e a consist\u00eancia do c\u00f3digo gerado vira fun\u00e7\u00e3o de quem lembrou de mencionar o qu\u00ea naquele dia.<\/p>\nPrompt encadeado versus prompt monol\u00edtico: quando dividir a tarefa<\/h3>\n
Etapa 1 \u2014 Especifica\u00e7\u00e3o:\n\"Antes de gerar c\u00f3digo, liste as decis\u00f5es de design que precisam ser\ntomadas para implementar um sistema de filas com reprocessamento de\nmensagens mortas (DLQ). N\u00e3o escreva c\u00f3digo ainda.\"\n\nEtapa 2 \u2014 Revis\u00e3o humana das decis\u00f5es listadas (aqui voc\u00ea interv\u00e9m)\n\nEtapa 3 \u2014 Implementa\u00e7\u00e3o:\n\"Com base nas decis\u00f5es que confirmamos [lista revisada], implemente\no consumidor da fila em Go seguindo essas decis\u00f5es exatamente.\"\n\nEtapa 4 \u2014 Testes:\n\"Gere os testes de unidade para este consumidor, cobrindo especificamente\nos cen\u00e1rios de falha que definimos na etapa 1: mensagem malformada,\ntimeout do processamento, falha ao mover para DLQ.\"\n<\/code><\/pre>\nOnde a engenharia de prompt encontra seu limite estrutural<\/h2>\n