Módulo 1.5 — Prompt Engineering Básico

💡 Por que o prompt importa tanto

Dois desenvolvedores, a mesma ferramenta, o mesmo modelo de IA. Um recebe código preciso que funciona na primeira tentativa. O outro recebe código genérico que precisa de 5 rodadas de correção. A diferença quase nunca é a ferramenta — é a qualidade do prompt. Prompt engineering é a habilidade central do vibe coder.

🔬 O mesmo pedido, dois resultados

Prompt vago

"crie uma função de validação"

Resultado:

Função genérica de validação de email (a IA chutou o tipo). Sem tratamento de erro. Retorna boolean sem mensagem. Não integra com o formulário existente.

Prompt específico

"crie uma função validateHabitForm(data) que recebe {name: string, frequency: 'daily'|'weekly'} e retorna {valid: boolean, errors: Record<string, string>}. Se name estiver vazio, errors.name = 'Nome obrigatório'"

Resultado:

Exatamente o que foi pedido, com tipos TypeScript corretos, integra com o formulário e tem mensagens de erro específicas.

📊 O impacto mensurável de prompts melhores

Prompts bem estruturados reduzem as rodadas de iteração em ~60% (baseado em uso real de times de desenvolvimento)
Desenvolvedores que aprendem prompt engineering reportam 2-3x mais produtividade com as mesmas ferramentas
O custo de tokens também cai — prompts precisos geram respostas mais curtas e focadas

👑 Contexto é rei — a estrutura de 4 partes

Todo prompt eficaz para código tem quatro componentes. Você não precisa de todos em todos os prompts — mas quanto mais presentes, mais preciso o resultado. A estrutura é: Contexto + Tarefa + Restrições + Resultado Esperado.

Contexto — onde estamos

O que o agente precisa saber sobre o projeto

"Estamos em um app Next.js 14 de gestão de hábitos. O componente HabitForm já existe em /components/HabitForm.tsx."

Tarefa — o que precisa ser feito

Ação específica, com verbo claro

"Adicione validação ao formulário que impeça submissão se o campo 'nome' estiver vazio."

Restrições — o que não fazer

Limites explícitos que previnem saídas indesejadas

"Não use bibliotecas externas. Não mude a estrutura atual do componente. Apenas adicione a lógica de validação."

Resultado Esperado — como fica

O comportamento final que confirma que funcionou

"O botão deve ficar desabilitado enquanto o campo estiver vazio. Mensagem 'Nome obrigatório' deve aparecer abaixo do input em text-red-400."

💡 Não precisa ser formal

Você não precisa escrever "Contexto:", "Tarefa:" como cabeçalhos. O importante é que o prompt contenha essas informações de forma natural. O agente extrai a estrutura do texto — apenas certifique-se de que tudo está lá.

📐 Especificar entrada e saída

Para funções e componentes, o nível de precisão mais eficaz é especificar exatamente o que entra e o que sai. "Faça uma função" é vago. "Função que recebe X e retorna Y" gera código que integra perfeitamente com o resto do sistema.

📋 Tipos de especificação de entrada/saída

Para funções:

"Crie uma função formatCurrency(value: number, locale: string) que retorna uma string no formato moeda (ex: R$ 1.234,56 para pt-BR)"

Para APIs:

"Crie um endpoint POST /api/habits que recebe {name: string, frequency: string} e retorna {id: string, ...habit, createdAt: string} ou {error: string} com status 400"

Para componentes:

"Crie um componente HabitCard que recebe habit: {id, name, frequency, completedToday: boolean} e chama onToggle(id) quando clicado"

✗ Prompts de função vagos

✗"faça uma função para formatar data"
✗"crie um helper para o formulário"
✗"função que verifica se o usuário tem acesso"

✓ Prompts de função precisos

✓"formatDate(date: Date) → string no formato 'dd/mm/yyyy'"
✓"validateForm(fields) → {valid: bool, errors: object}"
✓"canAccess(user: User, resource: string) → boolean"

📌 Fornecer exemplos no prompt

Exemplos são o atalho mais eficaz para resultados precisos. Quando você mostra o que quer, a IA infere o padrão e replica — mais rápido e mais fiel do que qualquer descrição verbal. Isso é chamado de few-shot prompting e é tecnicamente validado em pesquisas sobre LLMs.

📝 Few-shot prompting em prática

# Sem exemplos (zero-shot)

"Crie funções de formatação para os dados de hábitos"

# Com exemplos (few-shot) — muito mais preciso

"Crie funções de formatação seguindo o padrão abaixo:

// Exemplo existente

const formatDate = (d: Date) => d.toLocaleDateString('pt-BR')

// Crie da mesma forma:

// formatFrequency(freq: 'daily'|'weekly') → 'Diário' | 'Semanal'

// formatStreak(days: number) → '5 dias seguidos'"

📊 Quando exemplos são essenciais

→ Estilo de código: Quando seu projeto tem convenções específicas (nomes de variáveis, estrutura de arquivos, padrão de comentários)
→ Formato de output: Quando o retorno precisa ser exatamente igual a algo que já existe (schema de banco, formato de API)
→ Componentes consistentes: Quando você quer que o novo componente siga o padrão visual e estrutural dos existentes

💡 Use @referências no Cursor

No Cursor, use @componente.tsx para incluir um arquivo existente como exemplo. "Crie um componente similar ao @HabitCard.tsx mas para metas semanais" é mais eficaz do que descrever o padrão em palavras.

✂️ Dividir problemas grandes

Nunca peça tudo de uma vez. Quanto maior e mais complexo o pedido, maior a probabilidade de a IA "alucinar" partes, gerar inconsistências entre arquivos e produzir código que funciona individualmente mas quebra quando integrado. Decompor o problema é responsabilidade do arquiteto — você.

🪓 Como decompor uma feature

Pedido monolítico (evitar):

"Crie um sistema de autenticação completo com login, registro, recuperação de senha, sessão persistente e proteção de rotas"

Dividir em:

Passo 1

"Crie a página de login com formulário (email + senha) e validação básica. Sem lógica de auth ainda."

Passo 2

"Conecte o formulário à API /api/auth/login que retorna {token, user}"

Passo 3

"Salve o token no cookie httpOnly e crie middleware de proteção de rota"

Passo 4

"Adicione a tela de registro seguindo o mesmo padrão do login"

💡 Peça o plano antes do código

Para features complexas, comece com: "Antes de escrever qualquer código, me dê um plano de como você implementaria [feature]". Revise o plano, ajuste a abordagem, e só então peça a implementação passo a passo. Isso elimina 90% dos retrabalhos.

🔁 Pedir revisão e refatoração

Uma das capacidades mais subutilizadas: usar a IA para melhorar o código que ela mesma gerou. Depois de ter algo funcionando, você pode pedir revisão de segurança, performance, legibilidade e manutenibilidade — tudo em prompts separados.

Prompts de revisão úteis

› "Revise esse código para possíveis vulnerabilidades de segurança"
› "Esse código vai escalar para 10.000 usuários simultâneos? O que melhorar?"
› "Refatore para ser mais legível, mantendo o comportamento atual"
› "O que está faltando de tratamento de erro aqui?"

Sequência recomendada

1 Faça funcionar (prompt de implementação)

2 Commite o estado funcionando

3 Peça revisão de segurança

4 Peça revisão de performance

5 Peça refatoração de legibilidade

📊 Por que separar as revisões funciona

Quando você pede segurança + performance + legibilidade em um único prompt, a IA faz tudo de forma superficial. Quando você pede um aspecto por vez, ela vai a fundo em cada dimensão. A qualidade do output melhora substancialmente com prompts focados.

❌ Os 5 erros mais comuns em prompts de código

Depois de analisar centenas de sessões de vibe coding, cinco padrões de erro aparecem repetidamente. Conhecê-los antes de cometê-los economiza horas de frustração. Cada erro tem uma correção simples e direta.

Pedir muito de uma vez

Errado:

"Crie todo o sistema de hábitos com CRUD, gráficos, notificações e auth"

Correto:

"Primeiro, apenas a tela de listagem de hábitos"

Não especificar a stack

Errado:

"crie um formulário de login"

Correto:

"com Next.js 14, TypeScript e TailwindCSS, crie..."

Feedback genérico de erro

Errado:

"não funcionou, tente de novo"

Correto:

"[erro completo do console]. Acontece quando clico em salvar."

Aceitar sem testar

O código parece correto, você aceita sem abrir o browser. O erro vai aparecer 3 features depois e será muito mais difícil de rastrear. Sempre teste imediatamente após aceitar.

Não especificar o que não mudar

Errado:

"adicione dark mode ao componente"

Correto:

"adicione dark mode. Não mude a estrutura HTML, apenas os estilos Tailwind"

✅ Resumo do Módulo 1.5

✓

O prompt é a habilidade central — mesma IA, prompt melhor, resultado muito melhor

✓

Estrutura C+T+R+E — Contexto + Tarefa + Restrições + Resultado Esperado

✓

Especifique entrada e saída para funções — não "crie uma função" mas "função que recebe X e retorna Y"

✓

Exemplos são mais eficazes que descrições — use @referências e few-shot prompting

✓

Divida problemas grandes — peça o plano primeiro, implemente passo a passo

✓

Revisões separadas têm mais profundidade — segurança, performance e legibilidade em prompts distintos

Próximo Módulo:

1.6 — 🔄 Ciclo de Desenvolvimento com IA — o workflow EPIV: Explore, Plan, Implement, Verify

← Módulo Anterior Próximo Módulo →