docuemntação

rules/ddd-documentacao-primeiro.md

@@ -0,0 +1,52 @@
+---
+type: rule
+name: ddd-documentacao-primeiro
+description: Regra global que exige a documentação de novos artefatos antes da implementação (Documentation-Driven Development).
+scope: global
+trigger: always_on
+priority: alta
+updatedAt: "2026-08-12"
+---
+
+# Regra: Documentação Obrigatória Antes da Implementação
+
+## Contexto
+Implementar sem documentar leva ao acúmulo de conhecimento implícito, código inconsistente e perda do conhecimento institucional. Para garantir que as decisões de design, regras de negócio e fluxos estejam claros antes de qualquer código ser escrito, adotamos o Documentation-Driven Development (DDD). A documentação atua como o contrato formal do que será construído.
+
+## Regra
+Antes de implementar qualquer novo artefato (regra, skill, workflow, módulo, endpoint de API, decisão técnica) ou realizar alterações substanciais em artefatos existentes, o agente **DEVE OBRIGATORIAMENTE** criar ou atualizar a documentação na pasta `DOCUMENTACAO/` utilizando o template apropriado da respectiva categoria.
+
+## Protocolo DDD
+
+Para toda nova demanda ou funcionalidade, siga rigorosamente os passos abaixo:
+
+1. **Identificar Categoria**: Analisar a demanda e determinar em qual(is) categoria(s) de documentação ela se encaixa (arquitetura, módulos, regras-negócio, contratos, fluxos).
+2. **Consultar Template**: Consultar o respectivo template em `DOCUMENTACAO/<categoria>/_template-*`.
+3. **Criar/Atualizar Documentação**: Redigir a documentação na categoria adequada usando a estrutura do template. Se a funcionalidade altera algo existente, a documentação prévia deve ser atualizada.
+4. **Apresentar ao Operador**: Validar a documentação redigida com o operador (usuário humano) antes de iniciar qualquer código.
+5. **Implementar**: Escrever o código de forma que ele satisfaça e implemente *exatamente* o que foi estabelecido na documentação aprovada.
+6. **Validar**: Testar ou analisar o código para assegurar que ele respeita a especificação em 100%.
+7. **Sincronizar**: Se durante a implementação descobrir-se que ajustes na abordagem são necessários, a documentação deve ser atualizada em sincronia com o código.
+
+## Exceções
+Esta regra pode ser ignorada apenas para alterações triviais que não impactam regras de negócio, fluxos ou arquitetura, tais como:
+- Correção de erros de digitação (typos) em arquivos e variáveis.
+- Formatação de código ou linting.
+- Ajustes simples de imports.
+- Continuação de trabalho (ex: a doc já foi feita em um prompt/sessão anterior para esta mesma task).
+
+## Exemplos
+
+✅ **Correto**:
+- O operador pede um novo endpoint. O agente cria `DOCUMENTACAO/contratos/novo-endpoint` detalhando a API e os schemas usando o template. Após aprovação, cria o código na API.
+
+❌ **Incorreto**:
+- O operador pede uma nova regra de negócio complexa e o agente já cria a função ou arquivo `.ts` sem antes registrar a regra em `DOCUMENTACAO/regras-negocio/` para validação.
+- O agente toma uma decisão técnica grande (ex: trocar a biblioteca de state management) e apenas implementa no código sem gerar um ADR.
+
+## Impacto
+O código não é mais a fonte da verdade para o funcionamento esperado, mas sim a *implementação* da verdade registrada na documentação. Isso garante rastreabilidade, reduz dependência de memória implícita de sessões passadas e facilita a manutenção por humanos e outras instâncias do agente.
+
+## Referências
+- `DOCUMENTACAO/README` (Manifesto DDD)
+- Skills relacionadas: `documentar-decisao-tecnica`, `documentar-dominio-modulo`, `documentar-regras-negocio`