Templates de Prompt — Catálogo Versátil (GOALS + LOOPS)
GOALS funcionam em Claude Code E Codex CLI (Claude: /goal; Codex: Goal mode). LOOPS usam apenas os comandos nativos /loop e /goal do Claude Code — Codex não tem loop; para Codex, use sempre a Categoria 1.
Como usar
Copie qualquer template daqui e monte um prompt personalizado para o seu caso. Dois jeitos:
Você preenche: troque cada
{placeholder}pelo seu valor. Não deixe nenhum placeholder genérico — um prompt que serviria para dezenas de cenários diferentes está vago demais; torne-o tão específico que só sirva para o SEU caso.O agente preenche: cole o template no Claude Code / Codex com uma linha antes: "Preencha este template para o meu caso: {descreva o caso em 2-3 frases}. Me devolva o prompt pronto e me pergunte o que estiver faltando." O agente vira o seu compositor de prompt.
As 4 regras de composição (specificity pattern) — toda versão boa de um prompt adiciona estes 4 itens sobre a versão vaga:
Adicione | Vai em | Exemplo |
|---|---|---|
(a) Localização | CONTEXT | "olhe o fluxo de auth em |
(b) Cenário / edge case | GOAL | "a falha que ocorre após timeout de sessão" |
(c) Critério de pronto binário | DONE WHEN | "rode |
(d) Constraint | CONSTRAINTS | "trate a causa raiz, não suprima o erro; sem libs novas" |
Regra de roteamento: regra que vale para o projeto INTEIRO não entra no prompt — vai para CLAUDE.md (Claude) / AGENTS.md (Codex). Prompt inflado com regra durável dilui a instrução real.
Limite duro: o que você cola no /goal do Claude Code precisa caber em 4000 caracteres (o comando rejeita acima disso). Estourou? Corte prosa, referencie arquivos em vez de colar conteúdo, ou decomponha em prompts menores numerados — e persista a fila num arquivo, não só no chat.
CATEGORIA 1 — GOALS (task-spec)
Funciona igual em Claude Code e Codex CLI. Anatomia fixa: GOAL / CONTEXT / CONSTRAINTS / DONE WHEN.
Prompt 1 — Task padrão (anatomia 4 blocos)
Para qualquer task de escopo claro: feature pequena, ajuste, refactor pontual.
GOAL: {verbo + resultado observável + cenário que importa}.
(ex.: "Adicionar flag --json ao parser, cobrindo input vazio e input malformado"
— nunca "melhorar o parser")
CONTEXT: Trabalhe em {arquivo(s)/diretório exatos}.
Leia ANTES de editar: {arquivo-exemplo} — siga esse padrão.
{se houver: erro/log/spec relevante, colado ou referenciado}
CONSTRAINTS:
- Não altere {API pública / schema / arquivos fora do escopo}.
- Não adicione dependências além das já usadas no projeto.
- Trate a causa raiz — não suprima erro, não desative teste para passar.
- {constraint específica do seu domínio}
DONE WHEN:
- {comando exato: npm test / pytest tests/x -v / npm run build} sai com exit 0.
- Rode o check e ME MOSTRE A SAÍDA — saída colada, não "feito".
Por que funciona: cada bloco elimina um modo de falha — GOAL com verbo+resultado mata o adjetivo vago; CONTEXT com verbo de leitura ("leia antes de editar") garante que o padrão é seguido, não inventado; CONSTRAINTS mata scope creep e supressão de erro; DONE WHEN com comando+exit code fecha o loop sem você ser o revisor.
Prompt 2 — Bugfix (root cause, anti-supressão)
GOAL: Corrigir o bug: {sintoma específico — o que acontece, quando, para quem}.
CONTEXT: Erro exato (não resuma, use isto):
{cole o erro/stack trace completo}
Onde olhar primeiro: {diretório/módulo}, especialmente {função/fluxo}.
Como reproduzir: {passos ou comando}.
CONSTRAINTS:
- Corrija a CAUSA RAIZ. Proibido: suprimir o erro, capturar exceção genérica,
ajustar o teste para passar, adicionar retry que mascara o problema.
- Mudança mínima: não refatore nada além do necessário para o fix.
DONE WHEN:
1. Existe um teste novo que FALHAVA antes do fix (mostre-o falhando).
2. O teste passa após o fix.
3. {suite completa: comando exato} sai com exit 0 — nenhum outro teste quebrou.
Cole o output dos 3 passos como evidência.
Por que funciona: o teste-que-falha-primeiro torna o bug reprodutível e o fix verificável; a lista explícita de táticas proibidas bloqueia as 4 formas mais comuns de reward hacking; os 3 passos numerados do DONE WHEN são binários — ou tem evidência ou não terminou.
Prompt 3 — Feature grande (interview-first → SPEC)
Use ANTES de implementar qualquer coisa com mais de ~1h de trabalho. Duas sessões obrigatórias.
SESSÃO 1 (spec — só conversa, nenhum código):
Quero construir {descrição breve}. Me entreviste em detalhe.
Pergunte sobre implementação técnica, UX, edge cases, riscos e tradeoffs.
Não pergunte o óbvio — cave nas partes difíceis que eu posso não ter considerado.
Continue até cobrirmos tudo, depois escreva a spec completa em SPEC.md contendo:
- Objetivos E não-objetivos (o que está explicitamente FORA de escopo)
- Requisitos funcionais + constraints (libs proibidas, padrões a manter)
- Arquivos e interfaces envolvidos (a spec deve ser autocontida:
quem ler SÓ a spec consegue implementar)
- Exemplos concretos de input/output
- Critérios de aceite: 1 por linha, cada um verificável por teste ou comando
- Verificação end-to-end final que PROVA que a feature funciona
SESSÃO 2 (execução — sessão NOVA, contexto limpo):
Leia SPEC.md POR INTEIRO antes de qualquer edição.
Implemente exatamente o que está na spec — nada além (não-objetivos são vetos).
DONE WHEN: todos os critérios de aceite passam + a verificação end-to-end
da spec executa com sucesso. Rode e cole o output de cada critério.
Por que funciona: a entrevista transfere a extração de requisitos para o agente (ele pergunta o que você não pensou); a spec autocontida com não-objetivos vira contrato — os não-objetivos funcionam como vetos contra scope creep; executar em sessão limpa evita que a discussão polua a implementação.
Prompt 4 — Goal mensurável (Claude /goal E Codex Goal mode)
A fórmula: ação + estado final que um avaliador externo consegue checar sem te perguntar nada.
/goal {ação no codebase}. {Condição de término: comando exato + exit code ou threshold}.
Exemplos preenchidos (note: sempre comando + critério, nunca adjetivo):
/goal Migrar src/ de JavaScript para TypeScript. `npx tsc --noEmit --strict` sai com exit 0 e o diff não contém nenhum `any` explícito.
/goal Eliminar os warnings de lint. `npm run lint` sai com exit 0.
/goal Subir a cobertura de payments/ para >= 80%. `npm run coverage` reporta >= 80% no módulo e todos os testes passam.
Regras do bloco:
Teto de 4000 caracteres no
/goaldo Claude Code e Codex.
Por que funciona: nos dois CLIs um avaliador separado re-checa a condição a cada turno — se a condição não for mensurável por comando, o avaliador não tem o que checar e o goal degrada para "opinião do modelo". A segunda perna ("sem any no diff") fecha o atalho óbvio.
Prompt 5 — Revisão adversarial (autor ≠ auditor)
Rode em subagente/sessão separada de quem implementou. Stakes altos ou entregável criativo → este prompt é obrigatório, não opcional.
Use um subagente (ou sessão nova) para revisar o diff de {feature} contra {SPEC.md / plano / critérios}.
O revisor deve verificar:
- todo requisito listado está implementado (cite requisito → arquivo:linha que o cumpre)
- os edge cases listados têm teste correspondente
- nada FORA do escopo declarado mudou (liste qualquer arquivo tocado que a spec não prevê)
Reporte GAPS DE CORREÇÃO, não preferências de estilo.
Sinalize apenas o que afeta correção ou os requisitos declarados — gap apontado
sem requisito correspondente será descartado.
Formato do veredito: APROVADO ou lista numerada de gaps com requisito + evidência.
Por que funciona: contexto fresco não herda os vieses de quem escreveu ("✅ DONE" auto-relatado já passou com claim inventado dentro, caso real). A exigência de citar requisito→arquivo:linha torna o veredito auditável; a regra "gap sem requisito é descartado" neutraliza o viés do revisor de inventar problema para parecer útil.
CATEGORIA 2 — LOOPS (comandos nativos /goal e /loop — Claude Code)
Só os comandos nativos. /goal = continue até a condição valer (avaliador separado checa a cada turno). /loop = repita um prompt em intervalo fixo ou auto-ritmado. Codex não tem equivalente — use Prompt 4.
Prompt 6 — /goal contínuo ("não pare até terminar")
Para trabalho longo de condição única, dentro da sessão, sem supervisão. O texto vai INTEIRO no /goal (teto 4000 chars).
/goal {condição binária verificável: comando + exit/threshold}. Trabalhe item a item em {fonte dos itens: lista/diretório/arquivo}: conclua e verifique UM item antes de começar o próximo. Constraints: {o que não tocar}; causa raiz sempre, nunca suprimir erro. Se travar num item: registre o bloqueio em {progress.txt} com o motivo, PULE para o próximo e liste os bloqueios no final — não invente solução, não declare concluído com bloqueio aberto.
Exemplo preenchido:
/goal `npm test` sai com exit 0 em todos os arquivos de tests/legacy/ e nenhum teste está marcado como skip. Trabalhe arquivo por arquivo: corrija, rode o teste do arquivo, só então avance. Constraints: não altere o código de produção em src/core/; causa raiz sempre. Se um teste depender de serviço externo indisponível: registre em progress.txt, pule, e liste no final — não marque skip para passar.
Por que funciona: a condição é re-checada por avaliador separado a cada turno — o agente não consegue "se dar alta". "Um item por vez" mantém cada passo verificável. O protocolo de bloqueio com arquivo de registro fecha os dois modos de falha clássicos: inventar progresso para satisfazer a condição, ou mascarar o bloqueio (skip) para o comando passar.
Prompt 7 — /loop com intervalo fixo (recorrência)
Para vigiar/repetir algo em ritmo conhecido: CI, fila, deploy, rotina de manutenção. O prompt roda DO ZERO a cada disparo.
/loop {intervalo: 5m / 30m / 1h} {prompt idempotente e autossuficiente, com os 3 ramos: estado-bom / estado-ruim / não-sei}
Exemplos preenchidos:
/loop 10m Verifique o status do CI no branch {branch} via `gh run list --branch {branch} -L 1`. Se o último run FALHOU: leia o log com `gh run view --log-failed`, corrija a causa raiz, commite e push. Se PASSOU: responda só "verde" e nada mais. Se o comando falhar ou o estado for ambíguo: reporte o que viu e NÃO aja.
/loop 1h Rode {validador: comando exato}. Se exit != 0: corrija as violações apontadas e commite com mensagem "fix: {escopo}". Se exit 0: não faça NADA (nenhum commit, nenhuma melhoria espontânea).
Regras do bloco: cada disparo nasce sem memória do anterior → todo o contexto vai NA frase; idempotente (rodar 2x seguidas no mesmo estado não pode causar dano); os 3 ramos são obrigatórios — o ramo "não-sei → não aja" evita ação destrutiva sobre estado ambíguo; o ramo "bom → não faça nada" evita melhoria espontânea não pedida a cada hora.
Prompt 8 — /loop auto-ritmado (backlog até esvaziar)
Para varrer uma lista de trabalho até acabar, deixando o agente decidir o ritmo. Omita o intervalo.
/loop Processe o PRÓXIMO item pendente de {arquivo de backlog: tasks.yaml / prd.json}.
UNIDADE: 1 item = {defina exatamente o que conta como 1 item — ex.: "1 story do prd.json com passes:false"}.
Por ciclo: implemente o item, rode {checks: comando exato}, e SÓ com exit 0 commite ({formato: feat: [ID] - título}) e marque o item como concluído no arquivo.
Item grande demais para 1 ciclo: quebre-o em sub-itens NO PRÓPRIO arquivo de backlog e conclua só o primeiro.
Item bloqueado: marque "blocked: {motivo}" no arquivo e siga para o próximo.
Encerre o loop quando não houver itens pendentes nem desbloqueáveis — diga quantos ficaram blocked.
Por que funciona: o estado vive no arquivo de backlog — qualquer humano ou script audita o progresso com grep, sem confiar no relato do modelo. A UNIDADE travada evita o caso real documentado de um lote de ~100 unidades virar 12 arquivos porque ninguém definiu o que contava como 1. A condição de saída ("sem pendentes") é um dado no arquivo, não uma opinião.
Prompt 9 — Gate de conclusão (bloco universal)
Cole no FIM de qualquer goal ou loop para endurecer o critério de término. Use o comando LITERAL do seu validador — gate parafraseado ("rode o validador") sem exit code não bloqueia nada.
## Gate de conclusão (obrigatório)
Antes de declarar conclusão:
1. Rode: {comando literal do validador — ex.: node scripts/validate-x.cjs --file out.yaml}
2. Critério: {exit 0 / score >= N / 0 erros — o número exato}.
3. Se o critério falhar: corrija e repita. Você NÃO está autorizado a concluir
com o gate falhando, nem a relaxar o critério, nem a editar o validador.
4. Somente com o gate passando: cole o OUTPUT COMPLETO do comando e então declare concluído.
A sua avaliação de "parece pronto" não substitui o gate. Evidência, não asserção.
Por que funciona: o gate não se importa se o modelo ACHA que terminou — se importa se o comando passa. As duas proibições extras (relaxar critério, editar validador) fecham as rotas de escape que um gate ingênuo deixa aberto. Exigir o output completo colado torna o fechamento auditável depois.
Checklist antes de despachar
[ ] GOAL tem verbo + resultado observável (não adjetivo vago)?
[ ] Passa no teste "dezenas de cenários" (só serve para o SEU caso)?
[ ] CONTEXT aponta arquivos específicos E manda ler ("leia antes de editar") — não só lista paths?
[ ] CONSTRAINTS declara o que NÃO fazer (incluindo anti-supressão)?
[ ] DONE WHEN é comando + exit code/threshold, com "me mostre a saída"?
[ ] Para
/goal: ≤ 4000 caracteres, contados por comando (não estimados)?[ ] Pedido grande demais? → decomponha em prompts numerados e persista a fila num arquivo.
[ ] Stakes altos / entregável criativo? → some o Prompt 5 (revisão adversarial) ao fluxo.
[ ] Multi-arquivo ou abordagem incerta? → Claude: plan mode antes; Codex: peça o plano antes.
Calibração por engine
Codex tem viés de ação: assume detalhe faltante e entrega. → Reforce CONSTRAINTS + DONE WHEN para ele não assumir errado.
Claude Code prefere explorar → planejar → codar. → Abordagem incerta ou multi-arquivo: mande planejar antes ("apresente o plano, espere meu ok").
Guia rápido: qual usar
Situação | Template | Claude Code | Codex |
|---|---|---|---|
Task pontual com escopo claro | Prompt 1 | ✅ | ✅ |
Bug reportado | Prompt 2 | ✅ | ✅ |
Feature > 1h de trabalho | Prompt 3 | ✅ | ✅ |
Objetivo longo, condição única | Prompt 4 | ✅ | ✅ Goal mode |
QA de qualquer entrega | Prompt 5 | ✅ subagente | ✅ sessão nova |
"Não pare até terminar" supervisionável | Prompt 6 | ✅ | ❌ (use Prompt 4) |
Vigiar/repetir em ritmo fixo | Prompt 7 | ✅ | ❌ |
Esvaziar backlog item a item | Prompt 8 | ✅ | ⚠️ Goal mode por item |
Endurecer qualquer goal/loop | Prompt 9 | ✅ | ✅ |
