Skip to content
← Todos os capítulos

Capítulo 03

Templates de plano e de tarefa

Um Deep Work Plan é um diretório de arquivos markdown. O formato desse diretório — e de cada arquivo dentro dele — é o que torna um plano revisável tanto por humanos quanto por agentes.

Estrutura do plano

Um plano é um diretório em .dwp/plans/ chamado PLAN_001_<slug>/. Ele contém:

  • manifest.json — a identidade do plano e o ponteiro para seu contrato ativo, escrito primeiro na materialização.
  • contract.json — contrato imutável e endereçado por conteúdo de resultados (critérios de aceitação, escopo, invariantes).
  • journal.ndjson — registro de eventos de apenas anexação do ledger.
  • state.json — um instantâneo projetado a partir do journal, nunca editado manualmente.
  • README.md — visão geral do plano: objetivo, material de origem, tabela de tarefas e status.
  • PROGRESS.md — registro contínuo de execução legível por humanos.
  • 1.task_<slug>.md, 2.task_<slug>.md — arquivos individuais de tarefa em Markdown.
  • analysis_results/ — diretório para artefatos de tarefas, relatórios de análise e evidências de validação.

O pacote atual 7.x cria planos v7 por padrão, com slugs de 2–5 palavras, como os planos v6. O fluxo v5 mantido usa 2–4 palavras porque seus esquemas congelados contam o ID numérico como uma palavra. Novos planos recebem IDs numéricos monotônicos com pelo menos três dígitos (por exemplo, PLAN_001_add_payment_webhooks/). As pastas existentes sem numeração PLAN_<slug>/ continuam legíveis e nunca são renomeadas; planos existentes nunca são migrados implicitamente. Quando há planos numerados, latest resolve para o plano com o maior ID numérico.

Estrutura do arquivo de tarefa

Cada arquivo de tarefa é chamado <n>.task_<slug>.md e segue as dez seções normativas definidas pela skill instalada (consulte O loop central para a anatomia da tarefa). Cada tarefa reancora-se ao objetivo do plano antes de agir, o que impede o agente de derivar ao longo de um horizonte extenso, de várias horas.

O Final Review

Todo plano deve terminar com exatamente uma tarefa obrigatória: o Final Review. Ele encerra o plano em cinco partes ordenadas — nada do passe de segurança ou dos gates é relaxado:

  1. Passe de segurança — auditar tudo o que o plano mudou em busca de segredos, riscos de injeção e nova superfície de ataque, manter docs/SECURITY.md atualizado e executar a revisão local requerida do AI Diff Reviewer sobre o intervalo completo do plano (um revisor ausente é registrado como uma constatação de local reviewer not installed, nunca ignorado silenciosamente). Uma constatação crítica bloqueia a conclusão.
  2. Validação do estado final — a suíte completa de testes, linter e verificação de tipos do repositório é executada e passa sobre o último estado. Qualquer correção feita durante a revisão invalida os resultados afetados e exige nova execução.
  3. Reconciliação de skills — verificar se cada tarefa registrou sua disposição de skills local e reconciliar qualquer autoria necessária em analysis_results/SKILLS_CANDIDATES.md.
  4. Reconciliação de documentação — verificar a superfície tocada de cada tarefa que altera comportamento contra os documentos que a registram (docs/TESTING_GUIDE.md, documentos de arquitetura e AGENTS.md).
  5. Conclusão — os registros do plano concordam (lista de tarefas, registro de progresso e, em planos v6 e v7, o instantâneo e recibo derivados do journal); relatar entregas, evidências e limitações, e oferecer o Executive Report uma vez.

Convenções de README e PROGRESS

O README.md do plano deve conter um título (# Deep Work Plan: <name>), uma declaração de objetivo em prosa, uma seção opcional de material de origem, uma tabela de tarefas (número, nome da tarefa, caixa de status) e uma linha de status do plano no formato <n>/<total> tasks complete.

O PROGRESS.md é um registro de execução somente de adição. Cada entrada registra um carimbo de data/hora ISO 8601, o número e o nome da tarefa, o que foi feito e quaisquer desvios ou motivos de pular. Como ele apenas cresce, é um histórico confiável de como o plano realmente se desenrolou.

Títulos e referências cruzadas

Todos os títulos usam sentence case, e os documentos evitam linguagem de marketing e pontos de exclamação. Essas convenções mantêm os planos consistentes entre agentes e ao longo do tempo.