Prompt Engineering para Agentes IA na IDE:

Prompt engineering pra chat é uma coisa. Prompt engineering pra agentes IA na IDE é outra completamente diferente. No chat, você explica tudo do zero. Na IDE, o agente tem contexto: lê seus arquivos, conhece a estrutura do projeto, sabe quais dependências estão instaladas.

Isso significa que o prompt na IDE precisa ser mais curto e mais preciso. Em vez de 'crie uma API REST em Node.js com Express usando TypeScript', você escreve 'crie o endpoint GET /api/users seguindo o padrão de src/app/api/products/route.ts'. A IA já sabe o resto.

Neste guia vou compartilhar as técnicas que uso diariamente no Cursor e Claude Code. São padrões testados em centenas de sessões, com exemplos prontos pra você copiar e adaptar.

Por que prompt engineering é diferente na IDE

Chat vs agente: o contexto muda tudo

Quando você usa ChatGPT ou Claude no browser, cada conversa começa do zero. Você precisa explicar a stack, mostrar o código existente, descrever a arquitetura. É trabalhoso e propenso a erro — se você esquece de mencionar um detalhe, o código gerado vai ignorar esse detalhe.

Na IDE, o agente IA lê seus arquivos. No Cursor com indexação ativa, ele conhece cada arquivo do projeto. No Claude Code, ele pode ler qualquer arquivo sob demanda. Isso muda radicalmente como você escreve o prompt.

Anatomia de um bom prompt para code gen

Um bom prompt pra gerar código na IDE tem três partes: referência (o que já existe), objetivo (o que você quer) e restrições (o que não pode). É simples assim.

A referência é o mais importante e o que a maioria dos devs ignora. Em vez de descrever o que você quer do zero, aponte pra algo que já existe. 'Crie um componente igual ao de src/components/UserCard.tsx mas pra Product'. Isso dá ao agente um exemplo concreto pra seguir.

# Prompt ruim (genérico demais)
Crie um componente de card pra mostrar produtos.

# Prompt bom (com referência e restrições)
Crie src/components/ProductCard.tsx seguindo o padrão de
src/components/UserCard.tsx. Props: name, price, imageUrl,
onAddToCart. Use shadcn/ui Card. Sem 'any' no TypeScript.

5 padrões de prompt que funcionam

Depois de usar IA na IDE por mais de um ano, identifiquei 5 padrões que funcionam consistentemente. Não são fórmulas mágicas — são estruturas que ajudam o agente a entender o que você quer.

1. Role + Task + Constraints

O padrão mais versátil. Funciona pra praticamente qualquer tarefa. Define quem o agente é, o que ele deve fazer e as regras que deve seguir.

Role: Você é um dev React senior especializado em Next.js 16 App Router.

Task: Crie a página de dashboard em src/app/dashboard/page.tsx
com 4 cards de métricas (receita, clientes, agendamentos, taxa de cancelamento)
e um gráfico de receita dos últimos 30 dias.

Constraints:
- Server Component (fetch data no servidor)
- Use shadcn/ui Card + Recharts pro gráfico
- Dados vêm de src/lib/api/metrics.ts (já existe)
- Mobile-first, 1 coluna no mobile, 2x2 no desktop
- Sem loading skeleton por enquanto, adiciono depois

2. Few-shot com exemplos de código

Quando o agente precisa seguir um padrão específico que não é óbvio. Você mostra 1-2 exemplos concretos do código existente e pede pra replicar.

Olha como os endpoints tão estruturados em src/app/api/products/route.ts.
Crie src/app/api/customers/route.ts seguindo exatamente o mesmo padrão:
- Mesma estrutura de try/catch
- Mesma validação com zod
- Mesmo formato de resposta { data, error, status }
- GET com paginação, POST com validação

3. Chain-of-thought para debugging

Pra bugs, force o agente a pensar passo a passo antes de propor solução. Isso evita que ele saia mexendo em coisas aleatórias.

Tenho um bug: quando o usuário cancela um agendamento,
o dashboard não atualiza o contador de agendamentos ativos.

Antes de propor qualquer mudança:
1. Trace o fluxo completo de cancelamento (de onde começa até onde deveria atualizar o dashboard)
2. Identifique em qual ponto o fluxo quebra
3. Explique por que o dashboard não tá sendo notificado
4. Só depois proponha a correção mínima necessária

4. Step-by-step para refactoring

Refatoração é onde mais gente erra com IA. Se você pede 'refatora isso', o agente muda tudo de uma vez e quebra metade do projeto. O truque é dividir em passos e pedir um de cada vez.

Preciso migrar src/lib/database.ts de Prisma pra Drizzle.
Faz em etapas, uma por vez. Não avance sem eu confirmar:

Etapa 1: Crie o schema Drizzle equivalente ao schema Prisma atual
Etapa 2: Crie os queries equivalentes às funções existentes
Etapa 3: Atualize os imports nos arquivos que usam database.ts
Etapa 4: Remova as dependências do Prisma do package.json

Comece pela etapa 1.

5. Specification-first para features novas

Pra features complexas, peça pro agente escrever a spec antes do código. Isso funciona especialmente bem no workflow BMAD onde o agente Arquiteto faz isso naturalmente.

Preciso implementar sistema de notificações por email.
Antes de codar qualquer coisa, escreva um mini-spec:

1. Quais eventos disparam notificação (baseado no PRD)
2. Qual serviço de email usar e por que
3. Estrutura dos templates de email
4. Como gerenciar preferências do usuário (opt-in/opt-out)
5. Estratégia de retry pra emails que falham

Depois que eu aprovar o spec, implemente.

Prompts por tipo de tarefa

Criar componente React do zero

Pra componentes, a chave é dar referência visual ou de código existente. 'Crie um componente bonito' não funciona. 'Crie um componente seguindo o padrão do UserCard com esses props' funciona muito bem.

Crie src/components/scheduling/TimeSlotPicker.tsx

Props:
- availableSlots: TimeSlot[] (type já definido em src/types/scheduling.ts)
- selectedSlot: TimeSlot | null
- onSelect: (slot: TimeSlot) => void
- date: Date

Visual: grid de botões com horários. Slot disponível em verde claro,
selecionado em verde escuro, indisponível em cinza com cursor not-allowed.

Siga o padrão de src/components/scheduling/DatePicker.tsx
pra estrutura do componente e styling com Tailwind.

Debuggar erro em produção

Pra debugging, sempre inclua o erro exato (stack trace ou mensagem) e o contexto de reprodução. Quanto mais preciso o input, mais precisa a solução.

Erro em produção:
"TypeError: Cannot read properties of undefined (reading 'id')"
em src/app/api/bookings/[id]/route.ts linha 23

Reproduzo quando: DELETE /api/bookings/abc-123 com token válido
mas o booking já foi deletado anteriormente.

O endpoint deveria retornar 404 nesse caso, não 500.
Corrija com tratamento de erro adequado.

Refatorar código legado

Refatoração precisa de escopo claro. Diga exatamente o que quer mudar e o que deve permanecer igual. Sem isso, o agente vai 'melhorar' coisas que funcionam e criar novos bugs.

Refatore src/lib/booking-logic.ts:

O que mudar:
- Extraia a validação de horários pra uma função separada
- Substitua os callbacks aninhados por async/await
- Adicione tipos TypeScript nos parâmetros (tá tudo 'any')

O que NÃO mudar:
- Lógica de cálculo de preço (funciona corretamente)
- Interface pública da função createBooking (outros arquivos dependem dela)
- Nomes das variáveis de ambiente usadas

Escrever testes automatizados

Pra testes, especifique o framework de teste, os cenários que quer cobrir e o nível de detalhe (unitário vs integração).

Escreva testes unitários pra src/lib/booking-logic.ts usando Vitest.

Cenários obrigatórios:
- Criar booking com dados válidos → retorna booking com status 'confirmed'
- Criar booking em horário já ocupado → retorna erro 'slot_unavailable'
- Criar booking no passado → retorna erro 'invalid_date'
- Cancelar booking existente → muda status pra 'cancelled'
- Cancelar booking já cancelado → retorna erro 'already_cancelled'

Use factories pra criar dados de teste. Siga o padrão
de src/lib/__tests__/auth.test.ts pra estrutura.

Erros comuns em prompts de código

Depois de revisar centenas de prompts (meus e de outros devs), os erros se repetem. Aqui estão os mais comuns e como corrigir.

O pior erro, de longe, é pedir tudo de uma vez. Uma feature por prompt, uma feature por sessão. Se o prompt tem mais de 3 parágrafos, provavelmente tá acumulando tarefas que deveriam ser separadas.

Como melhorar prompts iterativamente

Ninguém escreve o prompt perfeito de primeira. O processo é iterativo: você escreve, vê o resultado, ajusta e repete. O truque é ajustar de forma inteligente em vez de reescrever tudo.

Eu mantenho um arquivo prompt-library.md em cada projeto com os prompts que funcionaram bem. Quando preciso fazer algo similar, copio o prompt e adapto. Economia de tempo enorme.

Outra técnica que funciona: depois que o agente gera código, peça pra ele avaliar o próprio output. 'Revise o código que você acabou de gerar. Tem algum edge case não tratado? Alguma inconsistência com os padrões do projeto?' O agente pega coisas que ele mesmo deixou passar.

Banco de prompts prontos para copiar

Aqui vai uma coleção de prompts que uso regularmente. Copie, adapte pro seu projeto e use como ponto de partida.

Prompt: criar API endpoint

Crie src/app/api/[recurso]/route.ts seguindo o padrão de
src/app/api/products/route.ts.

GET: lista com paginação (page, limit como query params)
POST: cria novo com validação Zod

Schema Zod pra validação: [descreva os campos]
Tabela no Supabase: [nome da tabela]
Relações: [se houver]

Prompt: criar página com formulário

Crie src/app/[rota]/page.tsx com formulário usando:
- react-hook-form + zod pra validação
- shadcn/ui pra componentes de form
- Server Action pra submit

Campos: [liste os campos e tipos]
Validações: [liste as regras]
Após submit: [o que acontece - redirect, toast, etc]

Siga o layout de src/app/settings/page.tsx como referência.

Prompt: code review por IA

Revise [arquivo ou diff] focando em:
1. Bugs potenciais e edge cases não tratados
2. Problemas de performance (N+1 queries, re-renders, etc)
3. Problemas de segurança (XSS, SQL injection, dados expostos)
4. Inconsistências com os padrões do projeto
5. Sugestões de melhoria (priorize por impacto)

Não sugira mudanças estéticas ou de estilo — só coisas que afetam
funcionalidade, performance ou segurança.

Prompt: migrar dependência

Migre [lib antiga] pra [lib nova] em todo o projeto.

Antes de mudar código:
1. Liste todos os arquivos que importam [lib antiga]
2. Mapeie cada uso pra equivalente na [lib nova]
3. Identifique casos sem equivalente direto

Depois que eu aprovar o plano, execute a migração
arquivo por arquivo, commitando cada um.

FAQ

Prompt engineering vai ficar obsoleto com IAs mais inteligentes?

Parcialmente. IAs melhores vão precisar de menos instrução pra tarefas simples. Mas pra tarefas complexas com requisitos específicos, saber comunicar claramente o que você quer sempre vai ser uma vantagem. O que muda é o nível de detalhe necessário, não a habilidade em si.

Qual o tamanho ideal de um prompt pra código?

Pra tarefas simples: 2-4 linhas. Pra tarefas médias: 5-15 linhas. Pra tarefas complexas: 15-30 linhas. Se passou de 30 linhas, provavelmente você tá acumulando tarefas que deveriam ser separadas. Prompt mais longo não é prompt melhor — o ideal é ser preciso.

Vale a pena usar prompts em inglês mesmo sendo dev brasileiro?

Pra prompts técnicos, tanto faz. Os modelos de 2026 entendem português tão bem quanto inglês pra coding. A diferença de qualidade no código gerado é praticamente zero. Use a língua que te faz pensar mais rápido.

Como lidar quando o agente ignora as restrições do prompt?

Acontece. Quando o agente ignora uma restrição, repita ela de forma mais explícita no próximo prompt: 'Você ignorou a restrição X. Refaça seguindo estritamente essa regra.' Se continuar ignorando, pode ser que a restrição conflite com outra instrução — revise o prompt como um todo.