Módulo 2.3 — Reverse Prompting + Plan Mode + Definition of Done

🔄 Reverse Prompting

Antes de pedir X, pergunte: "o que você precisa saber pra fazer X bem feito?". O agente lista lacunas. Você preenche. Aí pede X. Essa inversão é a forma mais barata de aumentar a taxa de acerto na primeira tentativa.

❌ Sem reverse

você:
"cria um sistema de login pra clínica"

Agente assume tudo: stack, auth provider, password rules, MFA. Faz. Você descobre nas 10 perguntas que aparecem no review que metade da abordagem não cabe.

✅ Com reverse

você:
"vou pedir um sistema de login pra clínica. o que você precisa saber antes pra entregar bem feito?"

Agente lista 8 perguntas (auth provider, password policy, MFA, sessões, recuperação, RBAC, LGPD, locale). Você responde em 2 minutos. Aí pede.

📋 Exemplo: o que o agente devolve

Para o sistema de login da clínica, preciso saber:

1. Auth provider: Clerk? Supabase Auth? Convex Auth próprio?

2. Personas: paciente, recepção, médico — RBAC ou flat?

3. MFA: obrigatório, opcional, só para médicos?

4. Recuperação: e-mail, SMS, ambos?

5. Compliance: LGPD com consent screen explícito?

6. Idioma: pt-BR fixo ou multi-locale?

7. Sessão: tempo de expiração, refresh token?

8. Auditoria: log de login pra auditoria do plano de saúde?

📌 A regra dos 30 segundos

Reverse prompting custa 30 segundos de chat. Sem ele, a chance de você ter que reabrir o trabalho depois é alta. Em projetos novos, sempre faça. Em rotinas conhecidas, descarte.

📐 Plan Mode

Plan Mode é o modo onde o agente propõe um plano em 3–7 etapas antes de tocar em qualquer arquivo. Você lê, ajusta, aprova. Só então ele executa. Discutir abordagem em 30s evita refatorar 200 linhas depois.

🔁 O ciclo plan-approve-execute

Plan mode — exemplo de retorno

## Plano: sistema de login

[1/5] Adicionar Convex Auth ao schema
       - convex/auth.ts com 3 providers (email, Google)
       - convex/schema.ts: tabela users com role enum

[2/5] UI de login + signup
       - app/(auth)/login/page.tsx (form com Zod)
       - app/(auth)/signup/page.tsx (consent LGPD)

[3/5] Middleware de RBAC
       - middleware.ts com matcher por role
       - lib/auth-guards.ts (helpers)

[4/5] Recuperacao de senha
       - convex/passwordReset.ts (token TTL 30min)
       - app/(auth)/reset/[token]/page.tsx

[5/5] Audit log de login
       - convex/auditLog.ts (insert em cada login)

Risco: Convex Auth ainda em beta para Google.
Alternativa: Clerk (3min mais lento, mais maduro).

Aprovar para executar?

📌 O que torna um plano útil

Um bom plano lista etapas com nome de arquivo, sinaliza riscos e alternativas, termina com pergunta de aprovação. Plano vago ("vou fazer login") não vale nada — exija granularidade que permita você dizer "no passo 3, prefiro X".

✅ Definition of Done Explícita

Critério objetivo de "pronto". Sem DoD, "pronto" é subjetivo — agente para cedo demais ou tarde demais. Com DoD escrita no AGENTS.md, o critério é claro pra todo mundo, todo PR, todo agente.

📋 Template de DoD universal

☐bun build passa sem warning
☐bun lint e tsc --noEmit zero warning
☐bun test verde, com cobertura mínima do que mudou
☐Smoke test manual no browser/API conforme contexto
☐Diff revisado por humano (você ou par)
☐PR com Summary + Test plan + screenshots quando aplicável
☐Sem segredo vazado, sem console.log esquecido, sem TODO órfão

❌ "Pronto" sem DoD

Agente entrega: build quebrado, 3 warnings, sem teste, screenshot só do desktop. Você descobre revisando.

✅ "Pronto" com DoD

Agente roda checklist sozinho. Se algo falha, ele corrige. Só te chama quando todos os checks passam.

🎨 DoD para Frontend

Frontend tem armadilhas próprias: hidratação, dark mode, breakpoints, animação que quebra mobile. DoD genérica não cobre. DoD específica de frontend filtra esses bugs antes de virar PR.

AGENTS.md — seção DoD frontend

## Definition of Done — Frontend

[Build]
- bun build sem warning
- tsc --noEmit zero erro
- Bundle nao cresce > 5% (next-bundle-analyzer)

[Visual]
- Smoke test Chrome 1440px (desktop)
- Smoke test 375px (iPhone 14 / mobile)
- Dark mode + light mode validados
- Sem CLS visivel (animacao de entrada estavel)

[Acessibilidade]
- Lighthouse a11y >= 90
- Foco navegavel por Tab
- aria-label nos botoes-icone

[Prova]
- Screenshot antes/depois no PR
- Gif de 5s da interacao principal (se UI nova)

📸 Os 4 viewports obrigatórios

MOBILE

📱

375px

iPhone 14

TABLET

📱

768px

iPad

DESKTOP

💻

1440px

MacBook

WIDE

🖥️

1920px

Monitor

📌 Use a skill @qa-visual

Você não precisa abrir 4 tabs e tirar screenshot manual. @qa-visual roda os 4 viewports automaticamente, gera comparação antes/depois e anexa no PR. DoD é um clique.

⚙️ DoD para Backend

Backend quebra silenciosamente em produção: query lenta, migration que não rola, race condition. DoD apertada de backend pega tudo em staging, antes de virar incidente caro.

AGENTS.md — seção DoD backend

## Definition of Done — Backend

[Testes]
- bun test verde (unit + integracao)
- Cobertura do que mudou >= 80%
- Pelo menos 1 teste de caminho de erro

[Banco]
- Migration roda em staging sem erro
- Migration eh idempotente (rodar duas vezes nao quebra)
- Rollback testado e documentado

[Performance]
- Query lenta tem index? Explain analisado
- Sem N+1 (verificar com query log)
- Endpoint < 300ms p95 em staging

[Observabilidade]
- Log estruturado (sem console.log)
- Metricas no dashboard (latencia, error rate)
- Alerta configurado se taxa de erro > 1%

[Deploy]
- Deploy de staging OK
- Smoke test de API (curl para os 3 endpoints principais)
- Variavel de ambiente documentada em .env.example

⚠️ Os 5 erros mais caros em produção

Erro	Cura na DoD
Migration não idempotente	Rodar 2x em staging antes do PR
N+1 query	Query log no smoke test
.env vazado em commit	Pre-commit hook + AGENTS.md "Não Faça"
Endpoint sem rate limit	Checklist explícita de rate limit
Erro silenciado por catch genérico	Lint rule contra catch sem rethrow

📌 Custo de bug em prod vs staging

Bug pego em staging: 30 minutos pra arrumar. Bug em produção: hotfix + comunicação + reembolso + reputação. DoD apertada custa 10 minutos a mais por PR e poupa horas no mês.

📜 Template Autoral: A Frase Única

Frase única que combina Reverse + Plan + DoD. Você cola no início de qualquer sessão e o agente já entra calibrado nos três eixos. Bônus do Master Codex — cole onde quiser.

🎁 O Template Master Codex

Antes de escrever código, faça três coisas:

(1) Reverse: liste o que precisa saber pra entregar bem feito. Pare e me pergunte.

(2) Plan: proponha um plano em 3–7 etapas com nome de arquivo, riscos e alternativas. Espere minha aprovação.

(3) DoD: ao final, rode o checklist do AGENTS.md (build, lint, test, smoke, screenshot). Só me chame quando tudo passar.

Confirma que entendeu antes de começar.

🔄 Reverse

Inverte o trabalho de descobrir lacunas. Agente declara o que precisa, você responde.

📐 Plan

Você captura erros de abordagem em 30s — antes de virar 200 linhas de código pra refatorar.

✅ DoD

Define "pronto" objetivamente. Agente para no momento certo, não cedo nem tarde.

💡 Onde colar

Cole essa frase no topo do AGENTS.md do projeto, ou na primeira mensagem de qualquer sessão. Em 1 ano de uso, vira muscle memory — você nem precisa mais colar, fala naturalmente nessa sequência. Aí o curso valeu.

✅ O que Aprendemos

✓

Reverse prompting inverte o trabalho — em vez de você adivinhar lacunas, o agente declara o que precisa saber.

✓

Plan mode evita refatorar 200 linhas depois — discute abordagem em 30s; aprova antes de executar.

✓

Definition of Done = critério objetivo de pronto — escrito no AGENTS.md, agente roda checklist sozinho.

✓

DoD frontend: 4 viewports + dark/light + screenshots — pega bugs visuais antes de virar PR.

✓

DoD backend: testes + migration idempotente + smoke de API — staging pega o que produção sofreria.

✓

Template autoral combina os 3 em uma frase — cole no AGENTS.md ou no topo da sessão. Vira muscle memory.

Próximo Módulo:

2.4 — Memória, contexto, sandbox e worktrees: a camada operacional que destrava multiagente real e protege seu projeto de acidentes caros.

← Anterior: Skills Próximo: Memória & Sandbox →