Voc\u00ea j\u00e1 deve ter vivido essa cena: pede para o modelo “refatorar essa fun\u00e7\u00e3o para ficar mais leg\u00edvel”, recebe um c\u00f3digo que compila, passa nos olhos rapidamente, entra no PR \u2014 e tr\u00eas sprints depois descobre que a refatora\u00e7\u00e3o mudou silenciosamente o comportamento de arredondamento num\u00e9rico numa regra de neg\u00f3cio financeira. Ningu\u00e9m pediu para mudar o comportamento. Ningu\u00e9m percebeu, porque o c\u00f3digo “parecia” mais limpo. O problema n\u00e3o foi o modelo ter “alucinado”. O problema foi o prompt ter deixado espa\u00e7o para m\u00faltiplas interpreta\u00e7\u00f5es v\u00e1lidas, e o modelo escolheu uma que fazia sentido sintaticamente, mas n\u00e3o semanticamente para o seu dom\u00ednio.<\/p>\n
Esse tipo de falha \u00e9 sistem\u00e1tica, n\u00e3o aleat\u00f3ria. E ela nasce quase sempre no mesmo lugar: na forma como a instru\u00e7\u00e3o foi estruturada, n\u00e3o nas palavras escolhidas. Depois de meses testando fluxos de prompt em produ\u00e7\u00e3o com Claude<\/a> e ferramentas como Cursor<\/a>, fica claro que existe uma gram\u00e1tica subjacente que separa prompts que geram c\u00f3digo correto, test\u00e1vel e sustent\u00e1vel de prompts que geram c\u00f3digo plaus\u00edvel \u2014 que \u00e9 o tipo mais perigoso de erro, porque passa despercebido. Este artigo \u00e9 sobre essa gram\u00e1tica: os elementos estruturais que realmente movem a agulha, os limites do que prompt engineering resolve, e onde a responsabilidade volta inevitavelmente para voc\u00ea.<\/p>\n A confus\u00e3o mais comum entre desenvolvedores seniores que est\u00e3o migrando o fluxo de trabalho para modelos de linguagem \u00e9 tratar o prompt como uma pergunta em linguagem natural, quando na pr\u00e1tica ele deveria ser tratado como uma especifica\u00e7\u00e3o de contrato incompleta que voc\u00ea est\u00e1 preenchendo em tempo real. A diferen\u00e7a \u00e9 sutil, mas muda tudo.<\/p>\n Uma pergunta aceita qualquer resposta plaus\u00edvel. Um contrato define pr\u00e9-condi\u00e7\u00f5es, p\u00f3s-condi\u00e7\u00f5es, invariantes e o espa\u00e7o de comportamento aceit\u00e1vel. Quando voc\u00ea escreve “crie uma fun\u00e7\u00e3o que valida CPF”, est\u00e1 fazendo uma pergunta. Quando voc\u00ea escreve uma especifica\u00e7\u00e3o com entrada, sa\u00edda, casos de borda e comportamento em falha, est\u00e1 definindo um contrato \u2014 e \u00e9 isso que reduz drasticamente o espa\u00e7o de solu\u00e7\u00f5es que o modelo pode gerar sem violar sua inten\u00e7\u00e3o.<\/p>\n Repare que o segundo prompt n\u00e3o \u00e9 “mais educado” nem “mais detalhado” no sentido gen\u00e9rico. Ele elimina graus de liberdade espec\u00edficos que historicamente geram bugs: o caso da sequ\u00eancia repetida \u00e9 justamente o tipo de regra de neg\u00f3cio que um LLM tende a esquecer porque n\u00e3o est\u00e1 no algoritmo formal, apenas na pr\u00e1tica de mercado. Se voc\u00ea n\u00e3o especifica, o modelo n\u00e3o tem como saber que isso importa para o seu contexto.<\/p>\n \ud83d\udca1 Dica do Mestre:<\/strong> a discuss\u00e3o sobre prompts para desenvolvedores no t\u00f3pico da comunidade ChatGPTPro no Reddit<\/a> converge para um ponto recorrente entre profissionais experientes: ser espec\u00edfico e fornecer exemplo de estilo de c\u00f3digo vale mais do que qualquer f\u00f3rmula m\u00e1gica de frase. Isso confirma, na pr\u00e1tica coletiva, o que a teoria de contrato sugere \u2014 a especificidade reduz o espa\u00e7o de ambiguidade, e exemplos concretos ancoram o modelo em conven\u00e7\u00f5es que ele n\u00e3o tem como inferir sozinho.<\/p>\n<\/blockquote>\n Depois de testar varia\u00e7\u00f5es sistem\u00e1ticas de prompt em tarefas reais \u2014 desde gera\u00e7\u00e3o de endpoints REST at\u00e9 refatora\u00e7\u00e3o de pipelines de dados \u2014, quatro eixos aparecem consistentemente como os que mais influenciam a qualidade do resultado. Nenhum deles \u00e9 sobre “escolher as palavras certas”.<\/p>\n Modelos de linguagem otimizam para serem \u00fateis, e “\u00fatil” frequentemente significa “fazer mais do que foi pedido”. Isso \u00e9 desej\u00e1vel em brainstorming e catastr\u00f3fico em manuten\u00e7\u00e3o de c\u00f3digo. Se voc\u00ea pede para corrigir um bug de concorr\u00eancia numa fun\u00e7\u00e3o, e n\u00e3o delimita o escopo, \u00e9 comum o modelo “aproveitar” para renomear vari\u00e1veis, reorganizar imports, ou “melhorar” a assinatura da fun\u00e7\u00e3o \u2014 mudan\u00e7as que aumentam o diff, dificultam o code review e escondem a mudan\u00e7a real dentro de ru\u00eddo cosm\u00e9tico.<\/p>\n Esse tipo de restri\u00e7\u00e3o negativa \u00e9 subestimado. A maioria dos guias de prompt foca em dizer o que fazer; a experi\u00eancia pr\u00e1tica mostra que dizer explicitamente o que n\u00e3o fazer \u00e9 o que reduz o “escopo criativo” descontrolado que gera PRs enormes e revis\u00f5es imposs\u00edveis.<\/p>\n Conven\u00e7\u00f5es de c\u00f3digo \u2014 nomenclatura, tratamento de erro, padr\u00e3o de logging, estrutura de testes \u2014 n\u00e3o existem de forma universal. Existem no seu reposit\u00f3rio, na sua equipe, na sua cultura de engenharia. Um LLM treinado em bilh\u00f5es de linhas de c\u00f3digo p\u00fablico vai gravitar para o padr\u00e3o estatisticamente mais comum, que raramente \u00e9 o padr\u00e3o do seu time.<\/p>\n A solu\u00e7\u00e3o \u00e9 colar um exemplo real do seu pr\u00f3prio c\u00f3digo como \u00e2ncora. Isso \u00e9 mais eficaz do que qualquer descri\u00e7\u00e3o textual de “estilo”.<\/p>\n Isso resolve um problema que instru\u00e7\u00f5es textuais n\u00e3o resolvem bem: estilo \u00e9 mais f\u00e1cil de demonstrar do que de descrever. “Use error wrapping consistente” \u00e9 amb\u00edguo; um exemplo real do seu codebase n\u00e3o \u00e9.<\/p>\n Este \u00e9 o eixo mais negligenciado e o que mais separa times maduros de times que ainda tratam IA como “gerador de sugest\u00f5es”. Pedir o teste antes \u2014 ou junto \u2014 da implementa\u00e7\u00e3o muda fundamentalmente a qualidade do c\u00f3digo gerado, porque for\u00e7a o modelo a raciocinar sobre comportamento observ\u00e1vel antes de comprometer-se com uma implementa\u00e7\u00e3o espec\u00edfica.<\/p>\n Esse padr\u00e3o de duas etapas \u2014 testes primeiro, implementa\u00e7\u00e3o depois, com um ponto de aprova\u00e7\u00e3o humana no meio \u2014 \u00e9 estruturalmente parecido com TDD, e n\u00e3o por acaso funciona bem com LLMs pelo mesmo motivo que funciona com humanos: separar “o que precisa ser verdade” de “como isso ser\u00e1 implementado” evita que decis\u00f5es de implementa\u00e7\u00e3o prematuras contaminem o entendimento do problema.<\/p>\n Um erro estrutural comum \u00e9 misturar, num \u00fanico prompt, informa\u00e7\u00e3o que deveria ser persistente (arquitetura do sistema, conven\u00e7\u00f5es do projeto, stack) com informa\u00e7\u00e3o que \u00e9 espec\u00edfica daquela tarefa pontual. Isso gera dois problemas: prompts gigantescos e repetitivos, e perda de contexto quando a sess\u00e3o \u00e9 encerrada.<\/p>\n Ferramentas como Claude Code<\/a> resolvem isso parcialmente com arquivos de contexto persistente (como o Com esse contexto j\u00e1 estabelecido, o prompt da tarefa fica enxuto e espec\u00edfico, sem precisar reexplicar o mundo a cada intera\u00e7\u00e3o:<\/p>\n \u00c9 preciso ser honesto sobre o que prompt engineering n\u00e3o resolve, porque a tenta\u00e7\u00e3o de trat\u00e1-lo como bala de prata \u00e9 grande \u2014 inclusive h\u00e1 quem projete um futuro em que programar vai virar essencialmente escrever prompts at\u00e9 2030<\/a>, argumento que simplifica demais a realidade de sistemas complexos e legados.<\/p>\n Prompt bem escrito reduz a vari\u00e2ncia do resultado, mas n\u00e3o elimina a necessidade de verifica\u00e7\u00e3o. Modelos de linguagem n\u00e3o t\u00eam acesso ao estado de execu\u00e7\u00e3o real do seu sistema \u2014 eles inferem comportamento a partir de padr\u00f5es textuais. Isso significa que para bugs que dependem de estado de runtime, condi\u00e7\u00f5es de corrida sutis, comportamento espec\u00edfico de infraestrutura ou intera\u00e7\u00e3o entre servi\u00e7os distribu\u00eddos, nenhuma formula\u00e7\u00e3o de prompt substitui instrumenta\u00e7\u00e3o, logs e testes de integra\u00e7\u00e3o reais.<\/p>\n H\u00e1 tamb\u00e9m um limite estrutural na quantidade de contexto que cabe numa janela, por maior que seja. Sistemas legados com d\u00e9cadas de decis\u00f5es acumuladas \u2014 inclusive em linguagens como Delphi, ainda comuns em sistemas corporativos brasileiros de miss\u00e3o cr\u00edtica \u2014 carregam contexto impl\u00edcito que nenhum prompt, por mais bem escrito, consegue capturar sozinho sem que voc\u00ea primeiro fa\u00e7a o trabalho de explicitar essas regras em algum lugar persistente e consult\u00e1vel.<\/p>\n \ud83d\udca1 Dica do Mestre:<\/strong> a an\u00e1lise publicada no artigo “Quando programar vira prompt: o fim da era do c\u00f3digo”<\/a> descreve bem essa transi\u00e7\u00e3o de “escrever c\u00f3digo” para “dirigir a sa\u00edda” \u2014 mas dirigir a sa\u00edda de um sistema complexo exige mais rigor de especifica\u00e7\u00e3o, n\u00e3o menos. A ilus\u00e3o de que prompt simplifica o trabalho de engenharia \u00e9 exatamente o que gera c\u00f3digo plaus\u00edvel e fr\u00e1gil quando o rigor de contrato \u00e9 negligenciado.<\/p>\n<\/blockquote>\n Juntando os eixos anteriores, um fluxo que tem se mostrado consistente em projetos reais segue esta sequ\u00eancia, que trata o prompt n\u00e3o como um evento isolado, mas como uma etapa dentro de um processo de verifica\u00e7\u00e3o maior:<\/p>\n Esse fluxo \u00e9 mais lento por tarefa do que simplesmente pedir “implemente X” e aceitar o resultado. Mas o custo comparativo precisa ser medido em ciclo completo, incluindo o tempo de debugar comportamento inesperado descoberto em produ\u00e7\u00e3o \u2014 que costuma ser ordens de grandeza maior do que o tempo investido em especificar melhor de in\u00edcio.<\/p>\n Nem toda tarefa justifica esse n\u00edvel de rigor. Scripts descart\u00e1veis, prot\u00f3tipos de explora\u00e7\u00e3o, c\u00f3digo que ser\u00e1 jogado fora em horas \u2014 nesses casos, prompt de contrato completo \u00e9 over-engineering. O crit\u00e9rio pr\u00e1tico \u00e9: se o c\u00f3digo vai para produ\u00e7\u00e3o, vai ser mantido por outra pessoa, ou toca em l\u00f3gica de neg\u00f3cio sens\u00edvel, o investimento em especifica\u00e7\u00e3o se paga. Se \u00e9 explora\u00e7\u00e3o de uma hip\u00f3tese que voc\u00ea vai descartar, prompt r\u00e1pido e iterativo \u00e9 a escolha correta.<\/p>\nO prompt n\u00e3o \u00e9 uma pergunta, \u00e9 uma especifica\u00e7\u00e3o de contrato<\/h2>\n
\/\/ Prompt fraco (pergunta)\n\"Crie uma fun\u00e7\u00e3o em TypeScript para validar CPF\"\n\n\/\/ Prompt como contrato\n\"\"\"\nImplemente validarCPF(cpf: string): Resultado\n\nPr\u00e9-condi\u00e7\u00f5es:\n- cpf pode conter m\u00e1scara (pontos e tra\u00e7o) ou n\u00e3o\n- cpf pode vir com espa\u00e7os em branco nas bordas\n\nP\u00f3s-condi\u00e7\u00f5es:\n- retorna Ok(true) apenas se os d\u00edgitos verificadores forem v\u00e1lidos\n segundo o algoritmo oficial da Receita Federal\n- retorna Err(ErroValidacao.FormatoInvalido) se n\u00e3o houver 11 d\u00edgitos\n num\u00e9ricos ap\u00f3s sanitiza\u00e7\u00e3o\n- retorna Err(ErroValidacao.SequenciaRepetida) para CPFs como\n 111.111.111-11 (matematicamente v\u00e1lidos, mas inv\u00e1lidos na pr\u00e1tica)\n\nRestri\u00e7\u00f5es:\n- n\u00e3o usar bibliotecas externas\n- fun\u00e7\u00e3o pura, sem I\/O\n- cobertura de testes deve incluir: CPF v\u00e1lido com m\u00e1scara,\n CPF v\u00e1lido sem m\u00e1scara, CPF com sequ\u00eancia repetida,\n CPF com menos de 11 d\u00edgitos, string vazia, null\n\"\"\"\n<\/code><\/pre>\nOs quatro eixos que realmente movem a qualidade do c\u00f3digo gerado<\/h2>\n
1. Delimita\u00e7\u00e3o expl\u00edcita de escopo (o que N\u00c3O fazer)<\/h3>\n
Contexto: fun\u00e7\u00e3o processarFila() em Go, com race condition\nidentificada no acesso ao slice compartilhado `pendentes`.\n\nTarefa: corrija exclusivamente a race condition usando sync.Mutex\nou um canal, conforme for mais idiom\u00e1tico para este caso.\n\nRestri\u00e7\u00f5es expl\u00edcitas \u2014 N\u00c3O fa\u00e7a:\n- n\u00e3o renomeie vari\u00e1veis existentes\n- n\u00e3o altere a assinatura p\u00fablica da fun\u00e7\u00e3o\n- n\u00e3o reorganize ou remova imports n\u00e3o relacionados ao fix\n- n\u00e3o adicione logging, m\u00e9tricas ou coment\u00e1rios al\u00e9m do necess\u00e1rio\n para explicar a mudan\u00e7a de concorr\u00eancia\n\nEntregue apenas o diff m\u00ednimo necess\u00e1rio para resolver a race\ncondition, com uma linha de coment\u00e1rio explicando a escolha entre\nmutex e canal.\n<\/code><\/pre>\n2. Exemplo de estilo como \u00e2ncora, n\u00e3o como sugest\u00e3o<\/h3>\n
Aqui est\u00e1 um exemplo de como tratamos erros neste projeto:\n\nfunc BuscarPedido(id string) (*Pedido, error) {\n if id == \"\" {\n return nil, fmt.Errorf(\"buscar pedido: id vazio: %w\", ErrValidacao)\n }\n pedido, err := s.repo.FindByID(id)\n if err != nil {\n return nil, fmt.Errorf(\"buscar pedido %s: %w\", id, err)\n }\n return pedido, nil\n}\n\nSiga exatamente este padr\u00e3o de wrapping de erro (contexto + %w)\nao implementar CancelarPedido(id string) error.\n<\/code><\/pre>\n3. Especifica\u00e7\u00e3o do crit\u00e9rio de aceite antes do c\u00f3digo<\/h3>\n
Antes de implementar, escreva os casos de teste (usando pytest)\nque descrevem o comportamento esperado de calcular_frete().\nN\u00e3o implemente a fun\u00e7\u00e3o ainda \u2014 apenas os testes com asserts\ne coment\u00e1rios explicando cada caso de borda considerado.\n\nDepois que eu aprovar os testes, implemente a fun\u00e7\u00e3o para\nfaz\u00ea-los passar.\n<\/code><\/pre>\n4. Contexto de sistema versus contexto de tarefa<\/h3>\n
CLAUDE.md<\/code>), mas o princ\u00edpio vale mesmo sem tooling dedicado: separe o que \u00e9 “verdade do sistema” do que \u00e9 “pedido da tarefa”.<\/p>\n# CLAUDE.md (contexto persistente do projeto)\n\n## Stack\n- Backend: Go 1.22, PostgreSQL, sqlc para gera\u00e7\u00e3o de queries\n- Erros seguem padr\u00e3o de wrapping com %w e sentinelas em errors.go\n- Testes usam testify\/assert, n\u00e3o testify\/require, exceto em setup\n\n## Conven\u00e7\u00f5es n\u00e3o negoci\u00e1veis\n- Nenhuma query SQL inline fora de arquivos .sql processados por sqlc\n- Handlers HTTP n\u00e3o cont\u00eam l\u00f3gica de neg\u00f3cio, apenas orquestra\u00e7\u00e3o\n- Toda fun\u00e7\u00e3o p\u00fablica tem doc comment no formato padr\u00e3o Go\n<\/code><\/pre>\nImplemente o handler de cancelamento de assinatura seguindo as\nconven\u00e7\u00f5es do projeto. A l\u00f3gica de neg\u00f3cio j\u00e1 existe em\nservice.CancelarAssinatura(ctx, id) \u2014 o handler deve apenas\nvalidar o path param, chamar o servi\u00e7o e mapear erros para\nstatus HTTP conforme o padr\u00e3o j\u00e1 usado em handlers\/pedido.go.\n<\/code><\/pre>\nOnde a engenharia de prompt encontra seu limite<\/h2>\n
Um fluxo pr\u00e1tico: do prompt \u00e0 revis\u00e3o como parte do mesmo processo<\/h2>\n
1. Contexto persistente (arquitetura, conven\u00e7\u00f5es) j\u00e1 carregado\n via arquivo de projeto ou sess\u00e3o configurada.\n\n2. Prompt de tarefa com:\n - objetivo espec\u00edfico e mensur\u00e1vel\n - restri\u00e7\u00f5es expl\u00edcitas de escopo (o que n\u00e3o fazer)\n - exemplo de estilo do pr\u00f3prio c\u00f3digo, quando aplic\u00e1vel\n - crit\u00e9rio de aceite (testes) solicitado antes da implementa\u00e7\u00e3o\n\n3. Revis\u00e3o humana dos testes propostos ANTES da implementa\u00e7\u00e3o\n \u2014 este \u00e9 o ponto de maior alavancagem para pegar mal-entendidos\n de requisito antes que virem c\u00f3digo.\n\n4. Implementa\u00e7\u00e3o gerada para satisfazer os testes aprovados.\n\n5. Revis\u00e3o de diff com foco em escopo: o modelo tocou em algo\n fora do que foi pedido? Se sim, isso \u00e9 sinal de prompt\n insuficientemente restritivo, n\u00e3o de \"capricho\" do modelo.\n<\/code><\/pre>\nQuando vale a pena investir tempo na engenharia do prompt<\/h3>\n