Plan define a estratégia de implementação do projeto. É o roteiro de ordem de construção: define as fases, milestones, ordem de execução, dependências estruturais entre entregas, prioridades e sequência lógica. Evita desenvolvimento de perfumaria antes da base crítica.
Fase: 6 — Planejamento
Pré-requisito: Todos os documentos de Design e Operação aprovados (até Docs/deploy.md)
Template: Templates/Full/plan.md ou Templates/Quick/plan.md
Artefato oficial: Docs/plan.md
Próximo artefato: Docs/tasks.md
Quando criar ou revisar
- Ao finalizar a fase de Design e antes de iniciar o desenvolvimento ativo (execução)
- Quando o escopo mudar exigindo a criação de novas fases ou alteração da prioridade majoritária
- Se uma dependência técnica nova for descoberta, bloqueando uma milestone agendada
Full vs Quick
| Situação | Template |
|---|---|
| Projeto novo inteiro, do zero (Front + Back + Infra), várias sprints | Templates/Full/plan.md |
| Micro-projeto, refatoração de área ou hot-fix estruturado | Templates/Quick/plan.md |
| Descoberta de dependências de API bloqueando o Frontend drasticamente | Migrar para Full |
Estrutura — Plan Full
O template Full possui 17 seções rigorosas. A seguir, a estrutura exata exigida pelo framework, uma a uma.
1. Identificação
Nome do projeto:
Versão do documento:
Status: [rascunho | revisando | aprovado]
Documentos base: Docs/project.md, Docs/user-stories.md, Docs/pages.md, Docs/flow.md, Docs/entities.md, Docs/architecture.md, Docs/contract.yaml e Docs/deploy.md
Data de criação:
Última atualização:2. Objetivo do Documento
Cobre: fases de implementação, milestones, ordem macro de execução, dependências entre entregas, prioridades, critérios de conclusão por fase e sequência recomendada para Dev e AI.
Não cobre: tarefas atômicas detalhadas, status operacional diário, contrato de API em profundidade, arquitetura detalhada de baixo nível e controle fino de bloqueios em tempo real.
3. Estratégia Geral de Implementação
Resumo da estratégia:
Estratégia escolhida: [MVP primeiro | incremental | por módulos | por jornadas | por risco | por dependência estrutural | híbrida]
Justificativa da estratégia:
Princípios de implementação:
- construir primeiro o que destrava o restante
- priorizar fluxos críticos
- entregar verticalmente quando possível
- evitar começar por detalhe cosmético4. Premissas de Execução
Premissas assumidas para o plano atual:
- [premissa 1]
- [premissa 2]
Condições consideradas verdadeiras neste momento:
- [condição 1]
Limitações que afetam o plano:
- [limitação 1]5. Estratégia de Priorização
Critérios usados para priorizar: [valor para o usuário, dependência técnica, risco]
O que entra primeiro:
- [item 1]
O que pode ficar para depois:
- [item 1]
O que não deve ser antecipado sem necessidade:
- [item 1]6. Visão Geral das Fases
Fase 1 — [nome]
Objetivo: [descreva]
Entregas principais: [entrega 1]
Por que essa fase vem agora: [explique]
Fase 2 — [nome]
Objetivo: [descreva]
Entregas principais: [entrega 1]
Por que essa fase depende da anterior: [explique]7. Fases Detalhadas do Plano
Aqui o plano é detalhado com base nas fases listadas acima.
FASE-01 — Fundação Estrutural
Objetivo da fase:
Escopo da fase:
- [item 1]
Entregas esperadas:
- [entrega 1]
Dependências de entrada:
- [dependência 1]
Documentos mais relevantes nesta fase:
- Docs/stack.md, Docs/architecture.md
Riscos principais:
- [risco]
Critério de conclusão da fase:
- [critério 1]
Observações:8. Milestones
M1 — [nome do milestone]
Objetivo: [descreva]
Entregas associadas:
- [entrega 1]
Fases relacionadas:
- FASE-01
Critério para considerar concluído:
- [critério 1]9. Dependências Entre Entregas
Dependências estruturais:
- [entrega 1] depende de [entrega 2]
Dependências funcionais:
- [história 1] depende de [história 2]
Dependências operacionais:
- [deploy] depende de [pipeline]
Dependências externas:
- [dependência externa 1]10. Sequência Recomendada de Construção
Ordem macro recomendada:
1. base estrutural
2. contratos principais
3. fluxos críticos
4. implementação do MVP
Ordem sugerida por área:
- [área 1]
O que deve ser implementado cedo para destravar o restante:
- [item 1]
O que deve ser deixado para o final:
- [item 1]11. Riscos de Execução
Riscos principais do plano:
- [risco 1]
Possíveis bloqueios:
- [bloqueio 1]
Mitigações previstas:
- [mitigação 1]12. Critérios Gerais de Pronto
Para considerar uma entrega pronta:
- documentação-fonte respeitada
- validação funcional realizada
Para considerar uma fase pronta:
- entregas críticas concluídas
- dependências para a próxima fase destravadas
Para considerar o plano avançando corretamente:
- sem violação grave de prioridade13. Relação com Docs/tasks.md
Função deste plano em relação ao Docs/tasks.md:
- Plan define estratégia e ordem macro, Tasks detalha execução atômica
Como tasks devem nascer deste plano:
- cada fase gera grupos de tasks
Regras importantes:
- task não deve contradizer o plano14. Relação com Docs/control.md
Função deste plano em relação ao Docs/control.md:
- [explique]
Quando o plano deve ser revisado a partir do Docs/control.md:
- atraso relevante
- bloqueio estrutural15. Diretrizes de Implementação
O que Dev e AI devem respeitar obrigatoriamente:
- seguir a ordem lógica do plano
- refletir dependências reais nas tasks
O que deve ser evitado:
- misturar escopo futuro com MVP sem critério
O que exige atualização deste documento:
- mudança de fase / milestone16. Síntese Operacional para Dev e AI
16.1 Estratégia geral
16.2 Fases mais importantes
16.3 O que precisa ser construído primeiro
16.4 O que não deve ser antecipado
16.5 O que ainda está indefinido17. Aprovação
Status de aprovação: [pendente / aprovado / revisando]
Aprovado por: [preencher]
Data de aprovação: [dd/mm/aaaa]
Observações finais: [preencher]Prompt para gerar com agente
Atue como ExecutionAgent.
Objetivo: criar Docs/plan.md estipulando as ordens de implementação da base.
Carregue contexto base:
- Docs/architecture.md
- Docs/contract.yaml
- Templates/Full/plan.md
Preencha rigorosamente as 17 seções do template Full, isoladamente. Não una nem resuma as seções numeradas de 1 a 17.
Seção 5: Priorize firmemente itens fundacionais antes do frontend gráfico detalhado.
Seção 7 e 8: Traceje no mínimo de 3 a 4 fases lógicas interligadas de desenvolvimento definindo Entregáveis concretos.
Seção 10: Insira um roadmap numerado e explicativo das dependências.Definição de pronto
O plan.md está pronto e apto a pular para o próximo nível (tasks.md) quando:
- Todas as 17 seções da governança oficial foram dissecadas e explicitadas, número a número.
- A Seção 7 estabeleceu explicitamente o critério de finalização de cada uma de suas Fases.
- Milestones conectam logicamente a Seção 8.
- "O que Não Antecipar" (nas Seções 5 e 16.4) resguarda claramente a equipe de focar em layout inútil perante APIs não terminadas.
Atenção
Entrar no detalhamento de tarefas atômicas isoladas (ex: "Criar botão confirmar em azul") dentro do plan.md hiper-extende este documento de forma errônea. O Plan traça Fases e Linhas Mestres. Quem detalha código atômico é sempre Docs/tasks.md.
Erros comuns
| Erro | Correção |
|---|---|
| Juntar seções do template | Liste todas as 17 seções individualmente para não perder foco no preenchimento correto. |
| Colocar tarefas atômicas detalhadas no plano | Mantenha em alto nível de fase e milestones. Tarefas atômicas nascem em Docs/tasks.md. |
| Fases que estouram sem nenhum critério tangível | Vincule nas Fases um evento concreto para fechamento (Seção 7). |
| Descumprir regras de prioridades lógicas | Criar Fases de interface ignorando que os contratos de API devem ser o passo estrutural prévio. |
| Negligenciar Riscos e Mitigações | A Seção 11 e 4 exigem lidar com a premissa de risco; não finja que não existem desafios técnicos. |
Relação com outros artefatos
(Todos os Docs de Design anteriores)
↓
Docs/plan.md — Ordena em tempo e hierarquia as construções mapeadas pela arquitetura.
↓
Docs/tasks.md — Deriva do plan.md as tarefas atômicas atreladas a exatas e específicas "Fases" descritas.