# Prompts para agentes de código com IA: como escrever URL: https://agentvera.dev/pt/blog/prompts-for-ai-coding-agents/ · Publicado: 2026-10-27 Como escrever prompts para agentes de código com IA: exemplos ruins e bons, arquivos e restrições, pedir um plano, dividir tarefas, verificação e prompts reutilizáveis. **Resumo:** - Um bom prompt para um agente de código diz o objetivo, os arquivos por onde começar, as restrições e como verificar o resultado. Prompts vagos geram código vago. - Para qualquer coisa maior que uma correção pequena, peça um plano antes, divida o trabalho em etapas que você consiga revisar e diga ao agente qual comando prova que terminou. - Regras que você repete vão no CLAUDE.md, AGENTS.md ou GEMINI.md; fluxos que você repete viram skills ou comandos personalizados, para que cada prompt possa ser curto. **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](/pt/glossary/coding-agent/ "O que é um 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](/pt/glossary/context-window/ "O que é uma 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: ```text fix the login bug ``` O 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: ```text 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: 1. **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. 2. **Saída de erro.** Cole o stack trace exato ou a saída do teste que falhou, não um resumo. 3. **Restrições.** Bibliotecas que você usa ou não, pastas para deixar em paz, APIs que precisam continuar compatíveis. 4. **Exemplos no código.** “Siga o padrão de `src/routes/users.ts`” é melhor que um parágrafo descrevendo o padrão. 5. **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 `/plan` antes de um prompt avulso ou comece com `claude --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](/pt/blog/claude-code-plan-mode/ "Plan mode do Claude Code") traz os detalhes. - **Codex CLI:** o `/plan` pede ao Codex para planejar antes de implementar. Você também pode iniciar uma sessão somente leitura com `/permissions` em 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: ```text 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: ```text 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](/pt/blog/undo-claude-code-changes/ "Desfazer mudanças do Claude Code") lista as opções. - **Contexto novo para trabalho não relacionado.** Use `/clear` no Claude Code ou `/new` no 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](/pt/blog/git-worktree-parallel-agents/ "Git worktrees para agentes em paralelo") 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: ```text 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](/pt/blog/write-unit-tests-with-ai/ "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 `any` para 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](/pt/blog/ai-code-review/ "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: ```markdown ## 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](/pt/blog/claude-md-agents-md/ "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//` para o projeto ou `~/.claude/skills//` para você. O nome da pasta vira um comando, e o `$ARGUMENTS` recebe o que você digitar depois dele: ```markdown --- 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](/pt/blog/claude-code-skills/ "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`: ```toml 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 ```text Goal: Context: Start in: Constraints: Plan first: Done when: Report: ``` 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](/pt/features/verify/ "Verify do AgentVera"):** 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](/pt/features/code-review/ "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](/pt/features/send-to-agent/ "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](/pt/features/skill-gallery/ "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](/pt/features/workspace/ "Workspace"):** uma grade de agentes por projeto, para você dar a cada etapa dividida o próprio agente e worktree. [Baixe o AgentVera](/pt/download/ "Baixar 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](/pt/blog/write-sql-with-ai/ "Escrever SQL com IA") aplica esses hábitos a schemas e migrations. ## Perguntas frequentes **Qual deve ser o tamanho de um prompt para um agente de código?** O necessário para dizer o objetivo, os arquivos de partida, as restrições e os critérios de conclusão, e nada mais. Para uma correção pequena, são duas ou três linhas. Para um recurso, geralmente um parágrafo curto e uma lista. Contexto que vale para toda tarefa fica no CLAUDE.md ou AGENTS.md, não em cada prompt. **Devo pedir um plano ao agente antes de ele escrever código?** Sim, para qualquer coisa que mexa em mais de dois arquivos ou que você não consiga descrever com precisão. No Claude Code, use o plan mode (Shift+Tab ou /plan); no Codex, use /plan. Leia o plano, corrija e depois deixe o agente implementar. Para uma correção de uma linha, um plano é desperdício. **Truques de prompt como “você é um engenheiro sênior” ajudam agentes de código?** Bem menos do que informação concreta. Uma linha de papel custa pouco, mas o agente ganha muito mais com o arquivo por onde começar, o comando que roda os testes e o comportamento que você espera. Gaste as palavras com fatos sobre a tarefa. **Onde guardo os prompts que uso várias vezes?** Regras do projeto vão no CLAUDE.md (Claude Code), AGENTS.md (Codex e outros agentes) ou GEMINI.md (Gemini CLI). Fluxos repetidos viram skills: .claude/skills//SKILL.md no Claude Code, .agents/skills no Codex. O Gemini CLI usa comandos personalizados em TOML em .gemini/commands. **Como faço um agente de código parar de dizer que terminou quando não terminou?** Dê a ele uma verificação que precisa rodar, como um comando de teste, um build ou uma requisição curl, e peça para colar a saída. Peça um teste novo que falhe antes da mudança e passe depois. Em seguida, revise o diff você mesmo ou peça a um segundo agente para revisar. --- **Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito tem agentes ilimitados. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/