Um bom prompt para um agente de código com IA diz quatro coisas: o que você quer, por onde começar, o que não pode mudar e como saber que funcionou. A maioria dos resultados ruins vem de deixar uma dessas de fora, não das palavras erradas. O agente consegue ler o seu código, rodar comandos e editar arquivos, então o papel do prompt é apontar esse trabalho na direção certa e dar a ele uma linha de chegada.
Este guia mostra prompts ruins e bons lado a lado e depois fala de contexto, planos, divisão do trabalho, verificação e onde guardar os prompts que você reutiliza. Os exemplos usam Claude Code e Codex CLI, mas os hábitos valem para o Gemini CLI e qualquer outro agente de código.
Por que escrever prompts para um agente é diferente de um chatbot
Um chatbot só tem a sua mensagem. Um agente de código tem o seu repositório inteiro, um shell e um ciclo: lê arquivos, faz uma mudança, roda algo, olha o resultado e tenta de novo. Isso muda o que um prompt precisa fazer:
- Você não precisa colar código. Aponte os arquivos e deixe o agente ler.
- Você precisa definir limites. Um agente que pode editar qualquer coisa pode editar coisas que você não queria.
- Você precisa de uma regra de parada. Sem ela, o agente decide sozinho quando o trabalho está bom o suficiente, e o critério dele pode não ser o seu.
Cada arquivo extra que o agente lê também enche a janela de contexto dele. Um prompt focado mantém o agente focado e a sessão mais barata.
Prompt ruim vs. prompt bom
Esta é uma primeira tentativa típica:
fix the login bugO agente precisa adivinhar qual bug, onde ele está e o que significa “corrigido”. Ele pode mudar o arquivo errado, reescrever uma função que estava boa ou “corrigir” o sintoma capturando o erro.
Este é o mesmo pedido escrito para um agente:
Users with an email that has uppercase letters can't log in: the API returns
401 even with the right password. Signup stores emails as typed; login looks
them up as typed too, so "Ana@x.com" and "ana@x.com" don't match.
Start in src/auth/login.ts and src/auth/signup.ts.
Normalize emails to lowercase on both signup and login. Don't change the
database schema in this task, and don't touch the session code.
Done when: a new test in tests/auth.test.ts logs in with "Ana@X.com" after
signing up with "ana@x.com", and `pnpm test` passes. Show me the diff.É mais longo, mas cada linha poupa um chute do agente. Veja o que cada parte faz:
| Parte | Exemplo | Por que ajuda |
|---|---|---|
| Sintoma | “retorna 401 mesmo com a senha certa” | O agente sabe o que reproduzir |
| Causa, se você souber | “guarda os e-mails como foram digitados” | Pula uma busca longa |
| Arquivos de partida | src/auth/login.ts | Menos leitura, menos chutes errados |
| Restrições | “não mude o schema do banco de dados” | Mantém a mudança pequena e segura |
| Critérios de conclusão | um teste com nome e o pnpm test | Uma linha de chegada que o agente consegue verificar |
Nem sempre você sabe a causa. Tudo bem: diga isso e peça ao agente para encontrá-la antes de corrigir. “Descubra por que X acontece e explique antes de mudar qualquer coisa” já é um prompt forte por si só.
Dê contexto, não redações
O contexto mais útil é concreto e verificável. Em ordem aproximada de valor:
- Caminhos de arquivos e símbolos.
src/billing/invoice.ts,calculateTax(). No Claude Code e no Codex, você pode digitar@para escolher um arquivo e anexá-lo. - Saída de erro. Cole o stack trace exato ou a saída do teste que falhou, não um resumo.
- Restrições. Bibliotecas que você usa ou não, pastas para deixar em paz, APIs que precisam continuar compatíveis.
- Exemplos no código. “Siga o padrão de
src/routes/users.ts” é melhor que um parágrafo descrevendo o padrão. - O porquê. Uma frase sobre o objetivo para o usuário ajuda o agente a fazer escolhas razoáveis que você não detalhou.
O que deixar de fora: a longa história do projeto, suas opiniões sobre código não relacionado e instruções que valem para toda tarefa. Essas últimas pertencem a um arquivo do projeto, como veremos abaixo.
Capturas de tela ajudam em trabalho de interface. Claude Code e Codex aceitam imagens; o Codex também aceita codex --image path/to/file.png na linha de comando.
Peça um plano primeiro
Para qualquer coisa maior que uma correção pequena, separe pensar de fazer. Peça ao agente para ler o código e propor um plano, revise e depois deixe-o implementar.
- Claude Code: pressione Shift+Tab até a barra de status mostrar o plan mode, digite
/planantes de um prompt avulso ou comece comclaude --permission-mode plan. No plan mode, o Claude lê e propõe, mas não edita. O post sobre o plan mode do Claude Code traz os detalhes. - Codex CLI: o
/planpede ao Codex para planejar antes de implementar. Você também pode iniciar uma sessão somente leitura com/permissionsem Read Only. - Qualquer agente: diga com palavras: “Não edite nada ainda. Leia os arquivos relevantes e me dê um plano numerado com os arquivos que você vai mudar.”
Um prompt de planejamento que funciona bem:
We need to add CSV export to the reports page.
Don't write code yet. Read src/reports/ and the existing PDF export in
src/export/pdf.ts, then give me:
1. the files you will add or change,
2. how the CSV is built and streamed,
3. what you'll test,
4. anything you're unsure about.Ler o plano leva um minuto e pega os erros caros: a pasta errada, uma dependência nova que você não quer, uma migration que você não esperava. Se o plano estiver errado, corrija em palavras simples (“use o helper toRows() que já existe em vez de um parser novo”) e peça um plano revisado.
Divida tarefas grandes em etapas
Os agentes se saem melhor em tarefas que você conseguiria revisar de uma vez. Um prompt como “crie o sistema de cobrança” produz um diff grande, difícil de conferir e difícil de desfazer. Divida:
Step 1 of 4: add the Invoice model and migration only.
No API routes or UI yet. Run the migration on the dev database and the
model tests, then stop and show me the diff.Depois, a etapa 2 é a API, a 3 é a interface e a 4 são os e-mails. Depois de cada etapa, você revisa, faz o commit e começa a próxima. Dois hábitos fazem isso funcionar:
- Commit entre as etapas. Um commit limpo é um checkpoint. Se a etapa 3 der errado, você volta para o fim da etapa 2 em vez de desembaraçar um diff misturado. Desfazer mudanças do Claude Code lista as opções.
- Contexto novo para trabalho não relacionado. Use
/clearno Claude Code ou/newno Codex ao mudar de assunto. Contexto antigo custa tokens e puxa o agente de volta para a tarefa anterior.
Etapas independentes também podem rodar em paralelo, cada agente no próprio git worktree para que um não sobrescreva os arquivos do outro.
Diga ao agente como verificar
“Faça funcionar” deixa o agente decidir o que significa funcionar. Uma instrução de verificação devolve essa decisão a você. As boas são comandos com um resultado claro:
Done when:
- `pnpm test tests/export.test.ts` passes, including a new test for an
empty report,
- `pnpm typecheck` has no errors,
- GET /reports/42/export.csv returns a header row and one row per entry.
Paste the command output at the end.Alguns padrões que elevam o nível:
- Teste primeiro. “Escreva um teste que reproduza o bug, rode e me mostre que ele falha. Depois corrija o código até passar.” Isso prova que o teste realmente cobre o bug. Mais em escrever testes unitários com IA.
- Peça evidências, não afirmações. “Cole a saída” é mais difícil de fingir que “confirme que funciona”.
- Diga o que não pode quebrar. “Os testes existentes em
tests/auth/precisam continuar passando.” - Proíba os atalhos. “Não pule nem apague testes, e não adicione casts
anypara calar erros de tipo.” Agentes pressionados a fazer uma verificação passar às vezes seguem esses caminhos.
Depois leia o diff. Um segundo modelo revisando a mudança pega muita coisa; veja code review com IA.
Prompts que dão errado, e como corrigir
| Prompt | O que costuma acontecer | Melhor |
|---|---|---|
| “Limpe este arquivo” | Reescrita grande, funções renomeadas, imports quebrados em outros lugares | “Extraia o parsing de parse.ts para uma função própria; mantenha a API pública igual” |
| “Adicione testes” | Testes rasos que confirmam que o código faz o que faz | “Adicione testes para entrada vazia, um arquivo de 10 MB e um cabeçalho malformado; cada um deve falhar se eu remover a verificação da linha 40” |
| “Deixe mais rápido” | Micro-otimizações aleatórias | “O endpoint /search leva 2 s para 10 mil linhas. Faça o profiling, me diga onde o tempo é gasto e depois proponha uma correção” |
| “Use boas práticas” | O que o modelo achar melhor desta vez | Nomeie a prática: “use o repository pattern de src/db/users.ts” |
| Uma lista de dez correções sem relação | Metade feita, contexto cheio no item seis | Uma tarefa por prompt, ou dez tarefas numa fila |
Torne os prompts reutilizáveis
Se você digita a mesma instrução em toda sessão, tire-a dos seus prompts.
Regras do projeto: CLAUDE.md, AGENTS.md, GEMINI.md
Cada agente lê um arquivo de instruções do projeto no início da sessão: CLAUDE.md para o Claude Code, AGENTS.md para o Codex (e vários outros agentes), GEMINI.md para o Gemini CLI. Coloque ali comandos e convenções, de forma curta e específica:
## Commands
- Test: pnpm test (run before saying a task is done)
- Typecheck: pnpm typecheck
## Rules
- Don't edit files in src/generated.
- Don't add dependencies without asking.
- New API routes need a test in tests/routes/.Agora “rode os testes antes de dizer que terminou” faz parte de todo prompt sem você digitar. O /init no Claude Code, no Codex e no Gemini CLI gera um primeiro rascunho. CLAUDE.md e AGENTS.md explica como manter um único conjunto de regras para vários agentes.
Fluxos repetidos: skills e comandos personalizados
Para uma tarefa que você repete de vez em quando, como um release, uma migration ou um checklist de revisão, escreva uma vez como skill ou comando personalizado e chame pelo nome.
O Claude Code usa skills: uma pasta com um arquivo SKILL.md, em .claude/skills/<name>/ para o projeto ou ~/.claude/skills/<name>/ para você. O nome da pasta vira um comando, e o $ARGUMENTS recebe o que você digitar depois dele:
---
name: fix-issue
description: Use when the user asks to fix a GitHub issue by number.
---
Fix GitHub issue $ARGUMENTS.
1. Read the issue with `gh issue view $ARGUMENTS`.
2. Write a failing test that reproduces it.
3. Fix the code until the test passes, then run `pnpm test`.
4. Summarize the change in two sentences.Agora o /fix-issue 123 roda o prompt inteiro. Os arquivos Markdown antigos em .claude/commands/ continuam funcionando do mesmo jeito, mas a documentação da Anthropic recomenda skills para trabalho novo, porque uma pasta de skill também pode guardar scripts e arquivos de referência. O Claude também carrega uma skill sozinho quando o seu pedido combina com a descrição dela. Mais em skills do Claude Code.
O Codex lê skills de .agents/skills num projeto e de ~/.codex/skills para você, no mesmo formato SKILL.md.
O Gemini CLI usa comandos personalizados em TOML em .gemini/commands/ (projeto) ou ~/.gemini/commands/ (usuário). O {{args}} é substituído pelo que você digitar depois do comando, e subpastas viram namespaces, então git/commit.toml é /git:commit:
description = "Fix a GitHub issue by number"
prompt = """
Fix GitHub issue {{args}}. Write a failing test first,
then fix the code and run the test suite.
"""Uma boa regra prática: regras que sempre valem vão no arquivo do projeto, fluxos que você usa às vezes vão em skills, e o prompt em si só carrega o que é específico da tarefa de hoje.
Um modelo de prompt para copiar
Goal: <one sentence, user-facing>
Context: <symptom, error output, what you already know>
Start in: <files or folders>
Constraints: <what must not change, libraries to use or avoid>
Plan first: <yes/no — if yes, don't edit until I approve>
Done when: <commands that must pass, behaviour to show>
Report: <diff, command output, open questions>Nem toda linha é necessária toda vez. Para corrigir um erro de digitação, “Goal” basta. Para um recurso novo, preencha todas.
Prompts para agentes no AgentVera
O AgentVera é um app desktop para macOS, Windows e Linux que roda Claude Code, Codex, Gemini CLI e outros agentes de CLI lado a lado em terminais reais. Os prompts são os mesmos; alguns recursos assumem as partes repetitivas:
- Verify: os critérios de conclusão que você escreve na mensagem são extraídos como critérios de aceite. Quando o agente termina o turno, um verificador separado lê o diff, roda os comandos de teste permitidos e marca cada critério como aprovado ou reprovado, com evidências. Ele não consegue editar arquivos. O Verify está nos planos Pro e Team.
- Code review: quando um turno termina, um segundo modelo Claude revisa o que o agente escreveu, e os apontamentos podem voltar direto para o agente.
- Send to agent: envie um erro do terminal, um diff, um log ou uma linha de código para um agente com ⌘⇧L em vez de copiar e colar no prompt.
- Skill gallery: crie, edite, ative e desative skills do Claude Code e do Codex numa só lista, e instale skills compartilhadas depois de uma varredura de segurança.
- Workspace: uma grade de agentes por projeto, para você dar a cada etapa dividida o próprio agente e worktree.
Baixe o AgentVera e experimente o seu próximo prompt com esses recursos.
Conclusão
Escreva prompts como um ticket para um colega competente que acabou de chegar: o objetivo, onde procurar, o que deixar em paz e como você vai avaliar o resultado. Peça um plano quando a tarefa for grande, divida em etapas que você consiga revisar e sempre dê um comando que prove que terminou. Mova o que você repete para o CLAUDE.md, o AGENTS.md ou uma skill. Os mesmos hábitos importam ainda mais quando o agente mexe num banco de dados; escrever SQL e migrations com IA aplica esses hábitos a schemas e migrations.