MÓDULO 1.3

📋 Planejamento real com writing-plans

Crie planos de implementação tão detalhados que mantêm o agente no caminho por horas sem desviar.

📋6 tópicos ⏱️~30 min 🎯Intermediário 📖Teoria + Prática
1

⚖️ Plano bom vs. plano genérico

A diferença entre um plano que funciona e um que não funciona não é o tamanho — é a especificidade. Um plano genérico lista intenções. Um plano bom lista ações verificáveis com arquivos, código e critérios. O agente executa o que está escrito, não o que você quis dizer.

Plano genérico (não funciona)

  • • Criar componente de formulário
  • • Adicionar validação
  • • Conectar ao backend
  • • Testar

Plano bom (funciona)

  • • Criar src/components/LoginForm.tsx
  • • Campos: email (required, format) + senha (min 8 chars)
  • • POST para /api/auth/login, handle 401
  • • Verificar: npm test LoginForm passa

O teste do plano bom

Mostre o plano para alguém que não conhece o projeto. Se essa pessoa consegue executar cada tarefa sem fazer uma única pergunta, o plano é bom. Se precisar perguntar qualquer coisa, o plano é incompleto.

2

⏱️ Tarefas de 2-5 minutos: por quê esse tamanho?

O tamanho de 2-5 minutos por tarefa não é arbitrário. É calibrado para ser pequeno o suficiente para commitar frequentemente, mas grande o suficiente para ter resultado verificável. Tarefas maiores criam contexto longo e perda de foco. Tarefas menores criam overhead excessivo de commit.

Por que esse tamanho específico

  • →2-5 min = uma função ou um teste — unidade atômica de código
  • →Commit a cada tarefa — histórico granular, rollback fácil
  • →Verificação imediata — você sabe em 5 min se funcionou
  • →Erro precoce — bugs surgem na tarefa 3, não na 30

Exemplos de tarefas bem dimensionadas

  • ✓ Criar a função validateEmail() com testes unitários
  • ✓ Adicionar campo createdAt ao modelo User e migração
  • ✓ Implementar o endpoint POST /api/users com validação de input
  • ✗ "Implementar todo o sistema de autenticação" (muito grande)
  • ✗ "Adicionar import statement" (muito pequeno, não tem valor verificável)
3

🗂️ Caminhos de arquivo, código completo e verificação

Os três pilares de uma tarefa de plano são: o caminho exato do arquivo que será modificado, o trecho de código completo (não pseudocódigo) que deve ser escrito, e o comando ou critério que confirma que a tarefa está concluída.

Pilar 1: Caminho de arquivo

Sempre absoluto ou relativo ao root do projeto. Sem ambiguidade.

src/lib/auth/validators.ts

Pilar 2: Código completo

O trecho real, não "algo como..." ou pseudocódigo. O agente copia e adapta.

export function validateEmail(email: string): boolean {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}

Pilar 3: Critério de verificação

O comando que deve passar ou o comportamento que deve ser observável.

npm test -- --testPathPattern=validators
4

🔍 Auto-revisão inline do plano

A skill writing-plans instrui o agente a, após gerar o plano completo, fazer uma revisão inline antes de apresentá-lo. Nessa revisão, o agente verifica se cada tarefa tem os três pilares, se a sequência é lógica, e se há dependências implícitas não declaradas.

Checklist da auto-revisão

  • □Toda tarefa tem caminho de arquivo?
  • □Toda tarefa tem código real (não pseudocódigo)?
  • □Toda tarefa tem critério de verificação?
  • □A sequência respeita dependências (A deve existir antes de B)?
  • □Todos os critérios de aceitação da spec foram cobertos?
  • □Há alguma tarefa que pode ser dividida em partes menores?

Essa auto-revisão acontece antes de o agente apresentar o plano para você. É uma camada extra de qualidade que captura erros antes da sua revisão, economizando idas e vindas.

5

🔄 Iterando o plano com feedback humano

O plano não é aprovado na primeira versão — ele é iterado. Você revisa o plano, aponta o que está errado, incompleto ou mal ordenado, e o agente revisa e reapresenta. Esse ciclo continua até o plano estar pronto para execução. Corrigir agora custa segundos; corrigir depois custa horas.

V1

Agente apresenta plano inicial

↓
R1

Você aponta: "Tarefa 3 depende da 5, inverta a ordem"

↓
V2

Agente revisa e reapresenta com mudanças destacadas

↓
✓

Plano aprovado — pronto para execução

Número típico de iterações

Para features bem especificadas: 1-2 iterações. Para features complexas: 3-4. Se passar de 5 iterações, o problema provavelmente está na spec, não no plano.

6

🛠️ Prática: criar um plano para uma feature real

Use a spec aprovada do módulo anterior como input. O objetivo é criar um plano de implementação com todos os três pilares em cada tarefa, passar pela auto-revisão do agente e iterar com seu feedback até aprovação.

Roteiro do exercício

  1. 1.Abra a spec do módulo anterior e passe para o agente
  2. 2.Diga: "Crie um plano de implementação detalhado com tarefas de 2-5 minutos"
  3. 3.Aguarde a auto-revisão e o plano final
  4. 4.Verifique: todo tarefa tem os 3 pilares? A sequência é correta?
  5. 5.Forneça feedback e itere até aprovação
  6. 6.Salve o plano — ele será o input do Módulo 1.4

Critério de conclusão

O plano está pronto quando você consegue ler cada tarefa e saber exatamente o que fazer, onde fazer e como verificar — sem consultar nenhum outro documento.

Resumo do Módulo 1.3

✓Sei distinguir plano bom de plano genérico
✓Entendo por que tarefas de 2-5 minutos são a granularidade certa
✓Conheço os três pilares de uma tarefa: arquivo, código, verificação
✓Entendi como funciona a auto-revisão inline do agente
✓Pratiquei o ciclo de iteração com feedback humano
✓Tenho um plano aprovado pronto para execução
Próximo módulo: 1.4 — TDD com agente: RED-GREEN-REFACTOR
← Voltar para Trilha Próximo Módulo →