Skip to content
← Todos os documentos da especificação

Conformidade

Versão 1.1. 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.
  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 drafts/, 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. Os addons (devcontainer, Dailybot, dependency-upgrade, design-system) são opcionais e NÃO DEVEM (MUST NOT) ser exigidos para a conformidade.

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.
  5. O plano DEVE (MUST) incluir as três tarefas finais obrigatórias — Security Review, Skills & Agents Discovery e o Executive Report. Um achado crítico de segurança bloqueia a conclusão até que seja corrigido ou explicitamente aceito.
  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 as três tarefas finais obrigatórias presentes, incluindo a Security Review.

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.