Anatomia de um bom prompt de engenharia

Começa o Módulo 2 — Construção com Claude Code. No post-âncora (#12) a gente viu o que é o Claude Code e onde ele entra. Agora vamos pro detalhe que mais separa quem rende de quem se frustra: como pedir. Porque a regra de ouro da série se aplica em dobro aqui — contexto vence prompt bonito.

Por que o prompt vago falha

"Arruma o login" não diz qual login, qual bug, qual comportamento esperado. A IA preenche os buracos com suposição — e suposição vira código errado. Prompt vago não economiza tempo; ele empurra o retrabalho pra frente.

As 4 partes de um bom prompt de engenharia

1. Localização

Onde, exatamente. "No career-content.ts, no procedimento createPost" vale mais que "na parte de posts". Apontar arquivo/função/tabela tira a IA do chute.

2. Comportamento atual vs. esperado

"Hoje X acontece; eu quero Y." A diferença entre os dois é a tarefa. Sem o "esperado", a IA não sabe pra onde mirar.

3. Restrições

O que não pode mudar. "Sem alterar o schema", "mantém o padrão dos outros routers", "não mexe em dado de produção". Restrição evita a IA "consertar" o que não devia.

4. Critério de pronto

Como saber que terminou. "Deve passar no typecheck", "o filtro tem que funcionar com cluster vazio". Dá um alvo verificável.

Contexto que o nosso repo já entrega de graça

No ClubPetro o CLAUDE.md (raiz + por pacote) injeta contexto automático: arquitetura, regra de RLS obrigatório, convenções, pegadinhas (.env→prod, drift DB↔Drizzle). Isso significa que você não precisa repetir o básico — o Claude Code já entra sabendo o terreno. Seu prompt foca no específico.

Exemplo: ruim → bom

• ❌ "Cria um endpoint pra listar posts."
• ✅ "No router recruitment.content, adiciona um listDrafts espelhando o listPosts (mesmo genteProcedure, filtro por organizationId do ctx), mas só status draft, ordenado por createdAt desc. Não muda o schema."

O segundo gera código que você quase não precisa corrigir. O primeiro gera uma conversa.

⚠️ Armadilha #13: escrever um prompt longo e genérico achando que tamanho é contexto. Contexto é específico e relevante, não volume. Três frases certeiras batem três parágrafos vagos.

Próximo da série: #14 — Plan mode: planejar antes de gerar.