Skip to content
Deep Work Plan está no Product Hunt hoje Vote nele
← Todos os documentos da especificação

Conformidade

Versão 1.3. Status: Estável. Este documento define o que significa um repositório ser conforme ao Deep Work Plan — ou seja, AI-first e pilotável por agentes. As palavras-chave MUST, MUST NOT, SHOULD, SHOULD NOT e MAY devem ser interpretadas conforme descrito na RFC 2119.

A conformidade existe para que “AI-first” seja uma propriedade objetiva e verificável, e não uma impressão. Um repositório atende aos critérios abaixo ou não atende. A sub-skill verify (/dwp-verify) os verifica de forma mecânica.

Um repositório conforme

Um repositório conforme ao DWP DEVE (MUST) satisfazer todos os itens a seguir. Todo artefato DEVE (MUST) ser fundamentado para o repositório — adaptado às suas linguagens, frameworks e comandos reais. Um stub genérico, um placeholder ou conteúdo copiado de outro repositório não satisfaz um critério.

  1. AGENTS.md na raiz. O repositório DEVE (MUST) conter um AGENTS.md na raiz que inclua (a) um índice da documentação, (b) as regras obrigatórias do repositório e (c) um bloco Quick Commands cujos comandos sejam reais e executáveis neste repositório. Comandos placeholder (por exemplo, npm test em um repositório que não usa npm) NÃO DEVEM (MUST NOT) aparecer. O índice NÃO DEVE (MUST NOT) vincular um arquivo de docs/ que não existe, e o arquivo DEVERIA (SHOULD) permanecer dentro de um orçamento de 150–500 linhas, movendo o detalhe para docs/ e vinculando-o, em vez de crescer sem limite.
  2. CLAUDE.md resolve para AGENTS.md. Um CLAUDE.md DEVE (MUST) existir e resolver para AGENTS.md (um symlink, ou um equivalente que garanta uma única fonte de verdade). Os dois NÃO DEVEM (MUST NOT) divergir.
  3. Uma hierarquia docs/. O repositório DEVE (MUST) conter um diretório docs/ que cubra as categorias padrão (arquitetura, padrões, testes, comandos de desenvolvimento, segurança e onboarding de agentes) com conteúdo real e específico do repositório. Módulos complexos DEVERIAM (SHOULD) ter seu próprio README.md. O guia de testes DEVE (MUST) definir uma cadeia de ferramentas real de teste, lint e type-check — ou, para um repositório que não tenha nenhuma, uma configuração concreta proposta a partir da stack durante o onboarding. Um guia de testes vazio ou “sem testes” não satisfaz este critério: sem uma forma definida de validar o comportamento, um plano não tem nenhum validation gate objetivo.
  4. Um diretório .agents/. O repositório DEVE (MUST) conter um diretório .agents/ com agents/, commands/ e skills/, além de um catálogo em .agents/docs/ que corresponda ao que está em disco. Os comandos dwp-* DEVEM (MUST) ser delegadores enxutos para a skill instalada. Um caminho .claude DEVE (MUST) resolver para .agents.
  5. Um espaço de trabalho .dwp/ ignorado pelo git. O repositório DEVE (MUST) conter um diretório .dwp/ com plans/, e .dwp/ DEVE (MUST) ser ignorado pelo git. Um espaço de rascunho tmp/ DEVERIA (SHOULD) existir e DEVERIA (SHOULD) ser ignorado pelo git.
  6. A skill da metodologia é resolvível. A skill Deep Work Plan DEVE (MUST) estar instalada ou referenciada de modo que um agente no repositório possa invocar suas sub-skills.

Um repositório é totalmente conforme com zero addons opcionais. Os addons opcionais (devcontainer, Dailybot, dependency-upgrade, design-system) NÃO DEVEM (MUST NOT) ser exigidos para a conformidade. Desde o padrão 2.3.0 a revisão local do AI Diff Reviewer (skill vendorizada + arquivo de extensão) faz parte da linha de base: sua ausência é uma falha para um repositório que declara 2.3.0 ou posterior, e um achado de versão do harness para um repositório legado. Sua superfície de CI continua opcional.

Um plano bem formado

Um Deep Work Plan em .dwp/plans/ é bem formado quando:

  1. Toda tarefa DEVE (MUST) declarar um escopo explícito, critérios de aceitação e ao menos um validation gate (um comando ou verificação que objetivamente aprova ou reprova).
  2. Toda tarefa que adiciona nova funcionalidade central ou altera o comportamento do produto DEVE (MUST) incluir cobertura de testes automatizados para esse comportamento em seus critérios de aceitação, e DEVE (MUST) executar os testes do repositório junto com suas verificações de lint e type-check em seu validation gate — não apenas o build. Os testes existentes DEVEM (MUST) permanecer verdes; uma mudança de comportamento DEVE (MUST) atualizar um teste que ela quebra, em vez de excluí-lo ou pulá-lo. Tarefas puramente de documentação, configuração ou pesquisa estão isentas de criar testes, mas ainda assim executam o gate do repositório.
  3. Toda tarefa que toca autenticação, tratamento de entradas, segredos ou configuração, superfície de rede ou dependências DEVE (MUST) carregar as expectativas de segurança dessa mudança em seus critérios de aceitação, e todo commit DEVE (MUST) estar livre de material secreto.
  4. O plano DEVE (MUST) persistir o progresso de modo que o trabalho sobreviva à interrupção e possa ser retomado por um agente diferente. Uma tarefa NÃO DEVE (MUST NOT) ser registrada como completed enquanto qualquer um de seus registros de validation gate ainda mostrar uma execução falha não resolvida, e o próprio log de conclusão de uma tarefa NÃO DEVE (MUST NOT) contradizer seu status registrado (por exemplo, uma tarefa completed cujo log ainda diga “Status: pending” é um defeito, não uma aprovação).
  5. O plano DEVE (MUST) encerrar-se com sua revisão final registrada. Um plano redigido sob esta versão DEVE (MUST) terminar com exatamente um Final Review obrigatório — o passe de segurança, a validação de estado final e a reconciliação de skills. Um plano redigido sob uma versão anterior termina com as três tarefas finais obrigatórias (Security Review, Skills & Agents Discovery, Executive Report) e continua conforme. Um achado crítico de segurança bloqueia a conclusão até que seja corrigido ou explicitamente aceito. A própria conclusão é uma transação verificada e recuperável, não uma simples troca de status: a tarefa terminal se fecha por meio de um passo de publicação protegido que valida os artefatos do plano finalizado antes de escrever o estado e deixa um recibo FINALIZATION.json verificável por máquina; uma publicação interrompida é recuperada a partir da evidência, nunca redeclarada concluída silenciosamente. Qualquer ponteiro de evidência citado por um registro de gate DEVE (MUST) resolver-se dentro da própria pasta do plano — um ponteiro pendente ou que escapa é um achado, não evidência de aprovação.
  6. As tarefas DEVERIAM (SHOULD) reancorar-se ao objetivo do plano antes de executar, para evitar a deriva ao longo de um horizonte extenso.

Verificando a conformidade

A conformidade DEVERIA (SHOULD) ser verificada de forma mecânica, e não por inspeção. Executar /dwp-verify produz um relatório de aprovado/reprovado em relação aos critérios acima: a presença e o conteúdo real do AGENTS.md, a resolução do CLAUDE.md, as categorias de docs/, a correspondência catálogo-versus-disco de .agents/, o status de gitignore de .dwp/ e tmp/ e — para um plano — que cada tarefa carrega critérios de aceitação e um validation gate, com cobertura de testes para tarefas que alteram o comportamento e a revisão final registrada presente. Ele também verifica, para um plano, que o markdown do plano e seu estado legível por máquina concordam (um README e um state.json dessincronizados é um achado, nunca uma aprovação silenciosa), que as tarefas concluídas carregam evidência de gate e de log sem contradições, e — quando um plano concluído chega até lá — que um recibo de publicação respalda a conclusão que ele declara. O verificador é consciente da versão: DEVE (MUST) aceitar como conforme um plano legado (três tarefas finais obrigatórias, sem Superfície tocada), e DEVE (MUST) rejeitar um plano que declara esta versão e é objetivamente inválido sob ela. Ele também relata uma linha de proveniência DWP standard: ausente ou desatualizada como um achado que nomeia a atualização dirigida do harness. A camada mecânica é honesta sobre seus limites: sem um intérprete capaz (Python 3.9+), encerra com saída diferente de zero e um veredito UNVERIFIED explícito, em vez de pular suas verificações — um verificador nunca reporta um resultado que não verificou.

Um repositório DEVERIA (SHOULD) ser reverificado após o onboarding e após cada plano concluído, de modo que a conformidade seja mantida, e não afirmada uma única vez.