FAQ
Perguntas frequentes
Respostas curtas ao que as pessoas mais perguntam sobre o Deep Work Plan, cada uma com um link para a página que aprofunda o tema.
01
O que é o Deep Work Plan
O que o Deep Work Plan realmente faz?
O Deep Work Plan transforma um repositório em um ambiente estruturado no qual um agente de código pode executar trabalhos longos com confiabilidade. Ele é instalado como uma skill de agente, faz o onboarding do repositório uma única vez (um índice `AGENTS.md`, uma árvore `docs/`, um kit `.agents/` de skills e comandos, uma área de saída `.dwp/` ignorada pelo git) e, a partir daí, qualquer objetivo se torna um plano: tarefas atômicas, cada uma com critérios de aceitação e um gate de validação, executadas uma por vez, comitadas à medida que passam e retomáveis do disco por qualquer agente. O plano se encerra com um Final Review que audita a segurança e valida o estado final. A metodologia é licenciada sob MIT e funciona com qualquer agente de código que leia um repositório.
Para quem é?
Desenvolvedores e equipes que entregam trabalho real e de várias etapas a agentes de código e querem que ele seja concluído. Encaixa-se quando uma tarefa atravessa mais de uma sessão, mais de uma família de arquivos ou mais de um agente; quando um colega precisa poder continuar de onde um agente parou; ou quando "concluído" precisa significar "validado", e não "o agente disse que sim". Uma correção de uma linha não precisa de um plano, e a metodologia diz isso: sua regra de rigor proporcional recomenda, em vez disso, um objetivo com critérios e gate definidos inline.
Qual é a diferença entre um plano Lite e um Full?
Uma escolha de representação, não uma troca de rigor. Os planos são Lite por padrão: um README compacto com registros de tarefas ancorados que já é executável, não um rascunho parcial. Se você pede um plano Full desde o início, o `create` escreve os arquivos de tarefa Full diretamente; e expande um plano para Full quando o detalhe das instruções, as dependências ou os contratos de uma tarefa deixam de caber em um registro compacto e revisável. A promoção posterior conserva cada tarefa concluída. Ambos os formatos carregam os mesmos critérios de aceitação, gates de validação, evidências e o Final Review obrigatório.
É uma ferramenta, um framework ou uma metodologia?
Uma metodologia empacotada como uma skill instalável. Não há servidor, conta, formato proprietário nem runtime além do agente de código que você já usa. O que é instalado são instruções que o agente lê, um pequeno conjunto de scripts de shell para detecção de contexto e verificação de conformidade, e as convenções que o seu repositório adota. Tudo o que o plano produz é Markdown e JSON no seu repositório, legível sem nenhuma ferramenta.
Com quais agentes de código ele funciona?
Com qualquer agente que leia arquivos do repositório. Claude Code e OpenAI Codex possuem testes comportamentais de execução e handoffs bidirecionais; Cursor, GitHub Copilot, Google Gemini CLI, OpenCode, Windsurf, Cline e Antigravity possuem adaptadores com testes de instalação verificados. A metodologia separa testes comportamentais de cobertura de instalação e nunca os confunde.
Como uso?
Três passos. Primeiro, instale a skill Deep Work Plan no seu agente de código — o caminho mais rápido é `npx --yes skills add https://github.com/DailybotHQ/deepworkplan-skill/tree/v7.9.0 --skill deepworkplan -y` (ou clone o repositório da skill e execute `./setup.sh`). Segundo, faça o onboarding do repositório uma vez para que o agente adapte `AGENTS.md`, `docs/`, o kit `.agents/` e uma área `.dwp/` ignorada pelo git ao seu stack: aponte para https://deepworkplan.com/init.md, ou execute `/deepworkplan-onboard`. Terceiro, planeje e execute o trabalho com os comandos enxutos: `/dwp-create <goal>` constrói um plano; `/dwp-execute` executa tarefa por tarefa em cada gate; `/dwp-refine` edita um plano em andamento (escopo, tarefas, ou promover um plano Lite para Full); `/dwp-resume` continua após uma interrupção; `/dwp-status` informa o progresso sem executar; `/dwp-verify` produz um relatório objetivo de conformidade; `/dwp-upgrade` move uma skill instalada para uma versão mais recente sem tocar nos planos existentes. Agentes que interceptam `/` costumam usar `#` em vez disso (por exemplo `#dwp-execute`). O endpoint de adoção e o início rápido seguem o mesmo caminho com mais detalhes.
O que exatamente é instalado, e onde?
A skill do agente é instalada onde quer que o seu agente carregue skills de projeto ou de usuário. O onboarding então adapta o próprio repositório: cria ou reconcilia `AGENTS.md`, `docs/`, `.agents/` e a área `.dwp/` ignorada pelo git. A skill ensina o método ao agente; o repositório mantém o contexto, o kit e a evidência do plano que os outros agentes precisam para continuar.
O Deep Work Plan exige Git?
O Git é recomendado para repositórios porque seu histórico faz parte da superfície de recuperação e revisão, mas a metodologia também pode rodar em um workspace de agente sem um repositório Git. Nesse caso, a camada de estado legível por máquina, incluindo os checkpoints e registros de gate em `state.json`, é obrigatória para que a recuperação não dependa de uma transcrição de chat.
Qual é a diferença entre uma skill, um plano e uma especificação de produto?
Uma skill descreve como um agente executa um procedimento repetível. Um plano DWP descreve uma mudança concreta por meio de escopo, critérios de aceitação, gates de validação e evidências. Uma especificação de produto descreve o comportamento atual do produto e evolui por meio de deltas após a implementação; skills e planos também são especificações, mas descrevem procedimentos e mudanças em vez de manter esse contrato canônico do produto.
02
Como um plano é executado
Como os gates de validação são implementados? Eles exigem aprovação humana?
São asserções executáveis que o próprio agente roda. A aprovação humana enquadra a execução: uma pessoa aprova o plano antes da execução e revisa o diff final na hora do pull request; o que fica entre as duas pontas é autônomo. Cada tarefa nomeia comandos concretos, normalmente o próprio gate de qualidade do repositório, selecionados a partir da superfície tocada pela tarefa: os testes do comportamento alterado e dos seus consumidores, ampliando para a suíte completa quando a mudança é compartilhada ou não pode ser delimitada. Uma tarefa é marcada como concluída somente quando esses comandos terminam com sucesso, e tarefas que alteram comportamento devem estender os testes. Em caso de falha, o agente primeiro repara o que está dentro do escopo da própria tarefa e roda o gate de novo; uma falha que não pode ser reparada nesse escopo deixa a tarefa marcada como bloqueada e para a execução.
Como o plano evita ficar desatualizado quando as pessoas alteram o código entre execuções?
Em três frentes. As tarefas são escritas como comportamento, não como edições: um critério de aceitação diz o que o sistema deve fazer, então um arquivo renomeado ou uma implementação trocada não o invalida. Cada gate é reexecutado contra o repositório como ele está agora, então uma premissa quebrada falha ruidosamente na execução seguinte em vez de desviar em silêncio, e essa falha é o sinal para refinar. E manter a documentação em sincronia faz parte do trabalho: uma tarefa que altera comportamento também atualiza os docs e o kit voltado a agentes que o descrevem, dentro do seu próprio gate. Cada execução deve deixar o repositório mais pronto para agentes do que o encontrou.
Posso alterar o plano no meio da execução sem perder o trabalho concluído?
Sim; refinar um plano parcialmente executado é um movimento de primeira classe. As definições das tarefas e o estado de execução são mantidos separados: o plano é uma checklist em disco mais um pequeno arquivo de estado, então o que foi feito permanece registrado de forma independente do texto das tarefas. Quando uma tarefa se revela errada, o agente a marca como bloqueada e para, em vez de seguir empurrando. Você então edita, reordena, divide ou descarta as tarefas que ainda não rodaram, enquanto as tarefas concluídas permanecem concluídas. Retomar reconstrói o estado a partir do disco e do repositório real e reexecuta os gates que importam, então nada que tenha mudado por baixo passa despercebido.
Ele continua verificando o trabalho contra o plano, ou o plano é algo feito só no início?
O plano é uma verificação contínua. O agente trabalha uma pequena tarefa por vez e precisa validar antes de seguir, então ele pode desviar um passo, não três. Cada tarefa carrega critérios de aceitação mais os comandos exatos que os comprovam, e o progresso é escrito no repositório à medida que avança, com um status por tarefa, então o desvio fica visível para você, para a próxima sessão e para o próximo agente. Um plano não termina até que tudo valide, incluindo o Final Review. A ressalva honesta: a metodologia não consegue impedir que um agente escreva um critério de aceitação fraco desde o início; ela torna o desvio ruidoso em vez de silencioso.
O plano é gerado uma vez e mantido à mão, ou evolui com o código?
Nem um nem outro. Ele é gerado uma vez a partir de um objetivo e depois mantido como parte do trabalho. O plano deliberadamente não é reescrito a partir de diffs de código, porque uma especificação que persegue o código se torna um espelho atrasado, que é o desvio que a metodologia existe para eliminar. Ele evolui de propósito: os gates são reexecutados contra o repositório atual, um gate que falha dispara um refinamento, e o agente executa esse refinamento durante a execução enquanto você aprova no início e revisa no fim. Documentação e testes evoluem junto com o código por construção, porque atualizá-los está dentro do gate de cada tarefa.
O que acontece se a sessão morrer no meio do caminho?
O progresso vive no disco, não no chat. As caixas de seleção do README, o log de cada tarefa, um índice de trabalho delimitado e um arquivo de estado legível por máquina são atualizados em cada fronteira de tarefa, e o arquivo de estado registra um checkpoint antes de qualquer pausa planejada. Uma sessão nova, ou um agente diferente, lê esse índice compacto, o reconcilia com o repositório e o histórico do git e continua na primeira tarefa incompleta sem refazer o trabalho terminado. Até mesmo uma criação de plano interrompida é recuperável: a identidade do plano e a lista de tarefas pretendida são escritas antes de qualquer arquivo de tarefa, então um plano criado pela metade pode ser concluído ou descartado em vez de adivinhado.
O que é o Final Review?
A única tarefa de encerramento obrigatória de todo plano. Em ordem: um passe de segurança sobre o conjunto completo de mudanças acumuladas do plano, incluindo uma revisão local obrigatória do diff pela skill AI Diff Reviewer, com achados críticos bloqueando a conclusão até serem corrigidos ou explicitamente aceitos; a validação do estado final, ou seja, as suítes completas aplicáveis de testes, lint, verificação de tipos e formatação do repositório sobre o código final; e uma reconciliação das decisões de skills que cada tarefa registrou. O agente então relata entregáveis, evidências e limitações, e oferece um Relatório Executivo uma única vez, gerando-o somente se você pedir.
O que acontece quando um gate de validação falha?
Um gate que falha é primeiro um sinal de reparo: o agente corrige o que está dentro do escopo da própria tarefa e roda o gate de novo. Uma falha que excede esse escopo deixa a tarefa registrada como bloqueada, e o agente para antes de declarar conclusão. Você pode inspecionar a evidência, corrigir o código ou refinar a tarefa e então retomar; um comando que falha é um sinal para resolver a divergência, não uma permissão para enfraquecer o gate.
O que acontece quando o verificador de conformidade não consegue executar suas verificações?
Ele diz isso com todas as letras. O verificador encerra com código de saída 2 e um veredito `UNVERIFIED` explícito — nunca imprime uma aprovação que não tenha verificado de verdade. Quando o ambiente não tem um intérprete capaz ou uma verificação não pode rodar, o resultado honesto é «não verificado», não «conforme»; um resultado verde sempre significa que cada verificação foi executada e passou. A mesma disciplina percorre toda a metodologia: nenhum fluxo enfraquece ou forja um gate para declarar a conclusão do trabalho.
Um plano pode rodar sem supervisão durante a noite ou em CI?
Sim, quando o plano foi aprovado com antecedência, carrega a camada de estado exigida e dá ao agente uma autoridade limitada. Uma execução sem supervisão deve parar e registrar um bloqueio quando a realidade diverge, um gate falha fora do escopo de reparo planejado, ou uma nova aprovação ou credencial é necessária.
03
Múltiplos agentes e v7
Vários agentes podem trabalhar em um plano em paralelo e como isso é mantido seguro?
Sim, sob regras explícitas. Um plano v7 pode marcar uma tarefa como `parallel_safe` quando sua superfície afetada não se sobrepõe à de uma irmã e sua saída é delimitada, e somente um contrato que conceda `agent_delegation` permite que essa tarefa vá para outro agente de código — headless em seu próprio worktree do git (agentkit) ou em outro painel do Herdr (Herdr). Um delegado de escrita trabalha apenas em seu próprio worktree, a sessão pai permanece como a única escritora do diário do plano e um delegado nunca delega adiante.
O resultado de um subagente delegado é confiado automaticamente?
Não. O resultado de um delegado é registrado como `asserted` até que o plano pai integre o trabalho e seu próprio executor de gates rode o gate da tarefa, que é a única coisa que registra evidência `observed`. Uma delegação concluída nunca encerra um critério por si só, portanto a delegação expande o alcance sem reduzir o rigor para a conclusão.
O que acontece quando um agente atinge limites de uso, tokens ou taxa durante o plano?
Cada agente verifica sua própria capacidade nos limites das tarefas. Com margem restante, continua; quando a capacidade diminui, conclui apenas a tarefa que pode finalizar; quando é crítica, atinge um ponto seguro, grava um pequeno pacote de transição (`dwp-handoff-v1`: o que foi feito, verificado e não verificado, e os próximos passos), notifica o líder e para. O líder inicia um sucessor em outra conta, que aceita o pacote e retoma o plano, reexecutando cada gate que o pacote lista como não verificado. Se o próprio líder esgotar sua capacidade, passa a liderança para um sucessor; as mudanças de liderança carregam uma época crescente para que apenas um líder atue por vez.
Quando um agente autônomo para para consultar um humano?
O DWP define uma taxonomia estrita de escalonamento em sete classes (AGENT_PROTOCOL §7.5): C1 ações não aprovadas, C2 barreiras de autenticação/consentimento, C3 ambiguidade irredutível, C4 gates que falham sem correção permitida, C5 operações destrutivas, C6 alterações de licença e C7 capacidade esgotada. O progresso rotineiro segue autônomo.
Como a conclusão da tarefa é comprovada além da afirmação narrativa do agente?
Uma tarefa é concluída apenas quando as evidências registradas satisfazem cada um de seus critérios de aceitação. O contrato de resultados é endereçado por conteúdo e imutável após o início da execução, cada evento é anexado ao diário do plano e somente o executor de gates registra evidências `observed`. Um critério que necessita de julgamento humano é encerrado apenas por meio de uma aprovação humana registrada com um marcador de autoridade explícito; o recibo é recalculado a partir dos registros, nunca escrito à mão. A Revisão Final então executa a etapa de segurança e a validação completa no estado final.
Os planos v6 continuam sendo executados sob a v7?
Sim. Os contratos de planos declaram explicitamente sua geração de esquema (`plan-contract/v6.json` vs `plan-contract/v7.json`). Um plano nunca migra de geração no meio da execução. Os planos v6 existentes retêm sua estrutura, estado e semântica de diário, continuando normalmente sob as ferramentas da v7.
04
Como ele se compara
Um plano pode abranger vários repositórios?
Sim — o arquétipo de hub orquestrador existe exatamente para isso. Um repositório hub mantém o plano que coordena, e cada repositório filho executa o próprio plano dentro da sua própria área `.dwp/` isolada, de modo que um filho nunca escreve no estado de planos do hub. A completude do filho é lida do estado de nível superior do próprio plano de cada um, não por busca de strings dentro dele, e o hub registra onde está antes de navegar para qualquer lugar. Cada filho continua um repositório DWP comum, que também pode ser pilotado sozinho.
Como ele difere de ferramentas orientadas a especificação como Spec Kit, OpenSpec ou Kiro?
Elas resolvem problemas adjacentes. As ferramentas orientadas a especificação são excelentes em capturar o que deve mudar: especificações, requisitos e propostas de mudança em um formato repetível. O Deep Work Plan trata de como um agente executa por horas sem desviar: o harness integrado pelo onboarding, gates de validação por tarefa selecionados a partir da superfície tocada, estado retomável em disco, um Final Review obrigatório com passe de segurança e um verificador de conformidade para o próprio repositório. Os dois podem ser combinados, com uma especificação ou proposta de mudança alimentando um plano. A página de comparação dispõe as capacidades lado a lado, nos termos de cada ferramenta.
Como ele difere de ferramentas de fluxo de trabalho para agentes como BMAD, Superpowers, Get Shit Done ou Gentle-AI?
Frameworks de fluxo de trabalho para agentes como BMAD, Superpowers e Get Shit Done trazem estilos de trabalho fortes: papéis, princípios, passos de teste primeiro, hábitos de verificação. O Gentle-AI fica em uma categoria vizinha como configurador de ecossistema de agentes: equipa os agentes de codificação que você já usa com memória persistente entre sessões (Engram), skills selecionadas, personas, servidores MCP, Spec-Driven Development opcional e revisão opcional baseada em evidências (Receipt-Driven Development), escrevendo nos diretórios de configuração de cada agente. O Deep Work Plan difere de ambos: ele se concentra no que permanece no repositório e no que pode ser verificado — um harness que qualquer agente lê sem contexto prévio, arquivos de tarefa com critérios de aceitação e gates, estado que sobrevive a uma sessão, um verificador de conformidade com um código de saída amigável a CI e uma medição publicada de quantos bytes de instrução cada fluxo carrega. Ele é independente de ferramenta por construção e não acrescenta serviço, provedor nem segredo ao ciclo principal. As camadas podem coexistir: os frameworks e o Gentle-AI moldam como o agente trabalha; o Deep Work Plan torna o trabalho longo durável e verificável dentro do repositório. A página de comparação mostra onde cada abordagem é integrada, opcional ou está fora do escopo.
Por que não simplesmente usar o modo de planejamento nativo do meu agente?
Os modos de planejamento nativos são úteis, e o Deep Work Plan se apoia no mesmo substrato, a convenção `AGENTS.md` e o padrão aberto Agent Skills. A diferença é onde o plano vive e o que o reforça. Planos nativos geralmente vivem fora do repositório e expiram com a sessão; o Deep Work Plan escreve o plano, o seu estado e as suas evidências no repositório, então outro agente ou um colega pode continuá-lo, e cada tarefa carrega um gate executável e um log registrado. Você continua usando o modo de planejamento do seu agente para pensar; a metodologia acrescenta o loop de execução duradouro e verificável.
05
Adotando
O que o onboarding escreve no meu repositório e ele toca em arquivos existentes?
O onboarding é não destrutivo: ele detecta um `AGENTS.md`, `docs/`, `.agents/` ou `CLAUDE.md` existente, reconcilia em vez de sobrescrever e pergunta antes de substituir qualquer coisa. Ele escreve o índice `AGENTS.md` com comandos reais, uma árvore `docs/` fundamentada, docs por módulo, o kit `.agents/` com comandos enxutos `dwp-*`, uma área de saída `.dwp/` ignorada pelo git, um mapa de testes verificado e a revisão local de código obrigatória (a skill AI Diff Reviewer mais uma extensão de revisão adaptada ao repositório). Ele então executa uma autoverificação e o verificador de conformidade, para que você veja o que foi produzido. Um repositório integrado sob um padrão anterior recebe uma atualização direcionada do harness que reconcilia apenas o que falta ou está desatualizado.
Como faço o upgrade da skill em um repositório já integrado?
São dois upgrades diferentes, e o fluxo os mantém separados. O harness do repositório — `AGENTS.md`, `docs/`, o kit `.agents/` — é reconciliado reexecutando o onboarding, que preenche apenas o que falta ou está desatualizado. A skill em si avança com `/dwp-upgrade`: uma verificação somente leitura da última versão publicada, a instalação da tag exata que você aceitou, verificada, e depois o onboarding novamente como uma passada nova. O fluxo é condicionado a consentimento explícito do início ao fim, as adaptações locais são comparadas e preservadas em vez de sobrescritas, e `.dwp/` nunca é migrado — os planos existentes mantêm a forma registrada e continuam rodando.
Posso usar a metodologia principal sem instalar add-ons?
Sim. Os add-ons são camadas opcionais e um repositório sem nenhum deles é totalmente conforme com o DWP. Devcontainers, relatórios do Dailybot, atualizações de dependências, suporte a sistema de design e revisão opcional em CI só são oferecidos quando fazem sentido para o seu repositório e você os aceita explicitamente.
E se meu repositório ainda não tiver testes nem linting?
O DWP não trata a ausência de um toolchain como um passe livre. Durante o onboarding, o agente propõe uma configuração de validação adequada ao stack, registra os comandos na documentação do repositório e os usa como alvo para os futuros gates; a proposta permanece visível para você revisar.
Quanto custa e como a eficiência é medida?
A metodologia e a skill são licenciadas sob MIT e gratuitas; não há serviço, chave de API nem telemetria nos fluxos centrais. A eficiência é relatada como o número de bytes de instrução que cada fluxo carrega na entrada — seu pacote de entrada no início de uma sessão —, publicado ao lado de caminhos de ponta a ponta nomeados que somam o que os próprios gatilhos do fluxo carregam quando o trabalho real continua (por exemplo, um resume que segue para execute costuma carregar várias vezes seu pacote de entrada). Nenhum dos dois números limita uma sessão: uma execução real também lê os próprios arquivos do repositório, a saída das ferramentas e os arquivos de trabalho do plano, nada disso contado por este registro. Ambos os números são medidos por um script comitado junto com a skill, remedido em cada linha de base de lançamento e publicado em um registro de avaliação, com aumentos relatados com a mesma franqueza das reduções. Ela não é relatada como porcentagens de tokens ou economias de custo, porque um inventário de bytes não estabelece essas coisas. Uma avaliação pública com agentes novos já foi executada sob um protocolo congelado: os mesmos dois recursos construídos a partir de clones limpos sem harness, com a versão maior anterior e com a atual. Ela constatou que os agentes em uma árvore com harness leram menos bytes nas duas tarefas, e que as sessões de recurso da versão atual consumiram menos entrada e saída de modelo do que as da versão maior anterior nas duas tarefas — conforme reportado pelo harness, em uma única carga de trabalho. Ela também constatou os limites honestos: o onboarding é um custo único que só se paga quando os fluxos são usados, a direção líquida de tokens por carga de trabalho foi mista, não se reivindica vantagem de tempo de relógio, e um agente novo não entra nos fluxos sozinho — os fluxos são comandos que você ou o agente invocam.
Ainda tem uma pergunta?
Ainda tem uma pergunta?
Abra uma discussão ou uma issue no GitHub. Perguntas que surgem com frequência são acrescentadas a esta página.