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:

  1. 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.

  2. 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 src/auth/"

(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 pytest tests/auth — exit 0"

(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 /goal do 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

Goal mode

QA de qualquer entrega

Prompt 5

subagente

sessão nova

"Não pare até terminar" supervisionável

Prompt 6

/goal

(use Prompt 4)

Vigiar/repetir em ritmo fixo

Prompt 7

/loop Nm

Esvaziar backlog item a item

Prompt 8

/loop dinâmico

⚠️ Goal mode por item

Endurecer qualquer goal/loop

Prompt 9