Construir por partes

Antes do loop: o DEV_PLAN.md como guia

No capítulo anterior você criou o DEV_PLAN.md: um arquivo com fases numeradas, cada uma com objetivo, entregáveis e critérios de aceite. Ele é a fonte de verdade deste capítulo. Antes de escrever qualquer código, abra o arquivo e localize a primeira fase com status TODO.

O agente deve sempre ler o DEV_PLAN.md antes de começar uma fase. Quando a fase termina, você marca como DONE no arquivo. Esse estado é visível, auditável e evita que o agente repita trabalho ou pule etapas.

O loop de cada fase

Você já deve ter um DEV_PLAN.md dividido em fases. O objetivo deste capítulo é simples: mostrar o loop que você vai repetir começando pela fase 1 e seguindo fase por fase até fechar o plano inteiro.

Não é para pegar o plano inteiro e mandar implementar tudo de uma vez, nem para escolher uma fase aleatória porque parece mais fácil. Você começa na fase 1. Quando a fase 1 terminar com validação e report, volta ao DEV_PLAN.md, marca como DONE, pega a fase 2 e repete.

1. Abra o DEV_PLAN.md e foque só na fase 1 ou na próxima ainda não concluída
2. Revise e refine essa fase antes de executar
3. Peça ao agente para criar a PRD dessa fase
4. Mude a ferramenta para o modo PLAN
5. Peça um plano de execução e validação baseado nessa PRD
6. Volte para o modo normal e implemente a fase
7. Teste e valide contra a PRD
8. Gere o report da fase, marque como DONE no DEV_PLAN.md e siga para a próxima

1. Ler o DEV_PLAN.md, revisar a fase e gerar a PRD

O primeiro passo do loop é abrir o DEV_PLAN.md e pegar a fase 1. Nos ciclos seguintes, você sempre pega a próxima fase com status TODO. Antes de qualquer código, revise se essa fase está clara o suficiente. Se estiver vaga, grande demais ou sem critérios testáveis, ajuste antes de seguir.

Depois disso, peça ao agente para transformar essa fase em uma PRD específica. A PRD é o documento de execução da fase: o que entra, o que fica fora, como deve funcionar e como você vai validar. Quando a fase 1 estiver fechada, você repete exatamente o mesmo processo na fase 2, e assim por diante.

Quero executar a fase [FASE_NAME] do DEV_PLAN.md.

Se este for o primeiro ciclo, comece pela fase 1.
Se a fase 1 já estiver concluída, use a próxima fase ainda não concluída.

Antes de qualquer código, leia:
- DEV_PLAN.md
- ROADMAP.md
- AGENTS.md ou CLAUDE.md

TAREFA
Analise a fase [FASE_NAME] do DEV_PLAN.md, refine o que estiver vago e crie uma PRD para essa fase.

Crie o arquivo:
- docs/prd/[FASE_FILE].md

A PRD deve estar em inglês e precisa incluir:
- Goal
- Scope
- Out of scope
- User flow
- UI states
- Technical notes
- Acceptance criteria
- Manual validation
- Risks / open questions

REGRAS IMPORTANTES
- foque em uma única fase
- não invente escopo fora do implementation plan
- se a fase estiver grande demais, aponte isso antes de seguir
- não implemente nada ainda
- gere apenas o conteúdo final da PRD

2. Mudar para o modo PLAN

Com a PRD pronta, ainda não peça código. Primeiro, mude a ferramenta para o modo PLAN e peça um plano para executar e validar aquela fase atual.

Isso força o agente a pensar antes de agir: quais arquivos vai tocar, qual a sequência, quais riscos existem e como provar que a fase foi entregue. Você faz isso para a fase 1, depois repete para a fase 2, e assim até fechar o DEV_PLAN.md inteiro.

Agora vou executar a fase [FASE_NAME].

Estou seguindo o DEV_PLAN.md uma fase por vez.

Leia estes arquivos:
- DEV_PLAN.md
- ROADMAP.md
- AGENTS.md ou CLAUDE.md
- docs/prd/[FASE_FILE].md

Estou colocando a ferramenta em modo PLAN.

TAREFA
Crie um plano de execução e validação para implementar essa fase.

O plano deve incluir:
- sequência de implementação
- arquivos que provavelmente serão alterados
- riscos técnicos
- como validar localmente
- critérios da PRD que precisam ser conferidos ao final

REGRAS IMPORTANTES
- não implemente ainda
- mantenha o plano pequeno e executável
- use a PRD como fonte principal para esta fase
- se a PRD estiver vaga, aponte isso antes de seguir

3. Executar, testar e validar

Só depois da PRD e do plano da fase é que entra a implementação. Nesse momento, você já tem escopo, critérios e validação mais claros, o que reduz bastante a chance de escopo inventado.

O foco continua sendo uma fase só. Não misture duas fases no mesmo ciclo. Feche a atual primeiro, depois avance.

4. Gerar o report e seguir para a próxima

Quando a fase estiver implementada e validada localmente, feche o ciclo com um report. Esse report vira memória do projeto: o que foi feito, o que mudou, como foi validado e o que ficou pendente.

Depois disso, volte para o DEV_PLAN.md, marque a fase atual como DONE e abra a próxima com status TODO. É assim que você vai da fase 1 até a última fase sem perder clareza.

A fase [FASE_NAME] foi implementada e validada localmente.

Depois deste report, vou marcar essa fase como DONE no DEV_PLAN.md e seguir para a próxima fase ainda não concluída.

Use estes arquivos como contexto:
- DEV_PLAN.md
- ROADMAP.md
- AGENTS.md ou CLAUDE.md
- docs/prd/[FASE_FILE].md

TAREFA
Crie um arquivo:
- reports/[FASE_SLUG]-report.md

O report deve estar em inglês e incluir:
- resumo do que foi implementado
- arquivos criados ou alterados
- decisões técnicas tomadas
- como a fase foi validada
- critérios da PRD atendidos
- problemas encontrados e como foram resolvidos
- pendências ou limitações para a próxima fase

REGRAS IMPORTANTES
- escreva de forma objetiva
- não invente resultados que não aconteceram
- se algo da PRD não foi concluído, deixe isso explícito
- gere apenas o conteúdo final do report

git add .
git commit -m "[resuma o que foi feito neste capitulo]"
git push