--- type: rule name: ddd-documentacao-primeiro description: Regra global de Documentation-Driven Development (DDD) definindo os 6 pilares de documentação e memória no ecossistema. scope: global trigger: always_on priority: alta updatedAt: "2026-09-01" --- # Regra: Documentação Obrigatória Antes da Implementação (DDD) ## Contexto Implementar sem documentar leva ao acúmulo de conhecimento implícito, código inconsistente e perda de governança. Para garantir que as decisões de arquitetura, regras de negócio, interfaces e integrações estejam claras antes de qualquer código ser escrito, adotamos o **Documentation-Driven Development (DDD)**. A documentação é a **especificação viva e o contrato formal** do que é construído. --- ## Os 6 Pilares Canônicos de Documentação e Memória Todo desenvolvimento e manutenção no ecossistema deve obrigatoriamente respeitar a estrutura dos 6 pilares: | Pilar | Destino / Padrão | Público | Conteúdo Obrigatório | | :--- | :--- | :--- | :--- | | **1. Código-Fonte** | `.ts`, `.vue`, `.js` | Desenvolvedores / IA | Comentários claros e coerentes quanto à sua aplicação prática, contexto e raciocínio de negócio (JSDoc no topo de funções, serviços e rotas). | | **2. Ajuda na Tela (UI)** | `*-front/src/.../{componente}.ajuda.md` | Usuários da UI | Ajuda contextual co-localizada: para `modalX.vue`, o arquivo de ajuda **DEVE** ser `modalX.ajuda.md`. Detalha objetivo, botões, campos e instruções de uso. | | **3. Wiki do Usuário** | `/../wiki//` | Usuários / Operadores | Aplicação VitePress com acesso dos usuários. Manuais de operação completos, tutoriais de uso, conceitos de negócio e fluxos da aplicação. | | **4. Wiki de Desenvolvimento** | `/../wiki/dev//` | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno exclusivo da equipe de desenvolvimento. Arquitetura técnica detalhada, modelos de banco, regras de negócio (`{modulo}.regras-negocio.md`), fluxos de filas (BullMQ), CRONs e ADRs. | | **5. Integração de IA** | Rota de Backend `/llm.md` | Agentes de IA / LLMs | Documentação gerada/servida dinamicamente contendo schemas Zod, enums canônicos, endpoints e contratos para consumo por LLMs. | | **6. Memória das Ações da IA e Identidade** | `/memorias-ia/` | Agentes de IA / Auditoria | `modulo.yml` (identidade), índice central `historico-acoes.md` (`Data \| Memória / Ação \| Arquivo Memoria \| Citações no Código-Fonte`) e sessões individuais `sessao-AAAA-MM-DD-slug.md`. | > ℹ️ **Estrutura da Wiki VitePress (`/../wiki`)**: > - `/../wiki//` $\rightarrow$ Aplicação VitePress voltada ao **acesso dos usuários e clientes** (onde `` é o ID do módulo em `memorias-ia/modulo.yml`). > - `/../wiki/dev//` $\rightarrow$ Seção VitePress de **acesso interno da equipe de desenvolvimento e arquitetura**. > 🧩 **Polimorfismo do `.agent` e Identidade do Projeto**: > O repositório `.agent` é **polimórfico e genérico**, sendo compartilhado entre múltiplos projetos do ecossistema. Toda personalização e identidade de cada projeto reside em: > - `./memorias-ia/modulo.yml` (na raiz do projeto pai): **Identificador mandatório** (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`). Sempre consultado quando precisar de IDs, rotas base ou stack. > - `./memorias-ia/`: Registros individuais `sessao-AAAA-MM-DD-slug.md` e índice cumulativo `historico-acoes.md`. > - `/../wiki//`: Documentação do módulo com acesso dos usuários (VitePress). > - `/../wiki/dev//`: Documentação técnica do módulo com acesso interno dev (VitePress). --- ## Protocolo DDD Para toda nova demanda, módulo ou funcionalidade, execute os passos abaixo: 1. **Identificar os Pilares Impactados**: - É alteração de código? $\rightarrow$ Planejar comentários contextuais claros (Pilar 1). - É tela/modal com ajuda ao usuário? $\rightarrow$ Criar/atualizar `modalX.ajuda.md` co-localizado (Pilar 2). - É funcionalidade com impacto no usuário final? $\rightarrow$ Criar/atualizar documentação em `/../wiki//` (Pilar 3). - É componente técnico, arquitetura, serviço ou fila? $\rightarrow$ Criar/atualizar documentação em `/../wiki/dev//` (Pilar 4). - É endpoint, schema ou contrato de API? $\rightarrow$ Assegurar reflexão na rota `/llm.md` (Pilar 5). - É ação estruturante ou otimização de IA? $\rightarrow$ Registrar memória em `/memorias-ia/sessao-AAAA-MM-DD-slug.md` e indexar em `historico-acoes.md` (Pilar 6). 2. **Documentar Antes de Codar**: - Redigir a documentação preliminar nos respectivos destinos e templates antes de iniciar a implementação. 3. **Apresentar ao Operador**: - Validar as especificações e regras com o operador antes de codificar. 4. **Implementar**: - Escrever o código de forma que satisfaça estritamente a documentação validada. 5. **Validar e Sincronizar**: - Se a implementação revelar necessidade de ajustes de design, atualizar a documentação imediatamente para manter 100% de sincronismo. --- ## Exceções A etapa de documentação prévia pode ser simplificada apenas para: - Correção de typos pontuais. - Formatação ou linting sem alteração de lógica. - Ajustes triviais de imports. --- ## Exemplos ✅ **Correto**: - Criou um novo modal `ModalParametros.vue` $\rightarrow$ criou `ModalParametros.ajuda.md` na mesma pasta explicando campos e botões para o usuário. - Criou um serviço de cálculo de efluentes $\rightarrow$ inseriu JSDoc claro quanto à sua aplicação prática, documentou a regra técnica em `/../wiki/dev/e-licencie.sigma/` e o guia de uso em `/../wiki/e-licencie.sigma/`. - Criou endpoints novos no backend $\rightarrow$ rota `/llm.md` atualizada automaticamente via gerador de contratos. - Realizou otimização no ecossistema de agentes $\rightarrow$ registrou relatório em `/memorias-ia/`. ❌ **Incorreto**: - Criou `modalX.vue` e colocou ajuda em formato desconhecido ou fora da pasta do componente. - Implementou código sem comentários ou com JSDoc que apenas repete os tipos sem explicar a aplicação real no sistema. - Criou regras técnicas complexas sem atualizar `/../wiki/dev//`. - Gravou registros de ações da IA em pastas despadronizadas fora de `/memorias-ia/`. --- ## Referências - `DOCUMENTACAO/README` (Manifesto DDD e matriz de documentação) - Rules: `jsdoc-padrao.md`, `regras-negocio-md.md`, `autonomia-agente.md` - Skills: `adicionar-ajuda`, `documentar-dominio-modulo`, `documentar-decisao-tecnica`, `diagnosticar-lacunas-documentacao`