101 lines
6.2 KiB
Markdown
101 lines
6.2 KiB
Markdown
---
|
||
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/<modulo>/` | 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/<modulo>/` | 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** | `<base_projeto>/memorias-ia/` | Agentes de IA / Auditoria | Registros de sessões da IA, otimizações executadas, histórico de decisões arquiteturais e relatórios de aprimoramento contínuo. |
|
||
|
||
> ℹ️ **Estrutura da Wiki VitePress (`../../wiki`)**:
|
||
> - `../../wiki/<modulo>/` $\rightarrow$ Aplicação VitePress voltada ao **acesso dos usuários e clientes**.
|
||
> - `../../wiki/dev/<modulo>/` $\rightarrow$ Seção VitePress de **acesso interno da equipe de desenvolvimento e arquitetura**.
|
||
|
||
> 🧩 **Polimorfismo do `.agent` e Personalização por Projeto**:
|
||
> O repositório `.agent` é **polimórfico e genérico**, sendo compartilhado entre múltiplos projetos do ecossistema. Toda personalização de cada projeto reside em:
|
||
> - `./memorias-ia/` (na raiz do projeto pai): Registros de ações, sessões e decisões da IA.
|
||
> - `../../wiki/<modulo>/`: Documentação do módulo com acesso dos usuários (VitePress).
|
||
> - `../../wiki/dev/<modulo>/`: 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/<modulo>/` (Pilar 3).
|
||
- É componente técnico, arquitetura, serviço ou fila? $\rightarrow$ Criar/atualizar documentação em `../../wiki/dev/<modulo>/` (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 `<base_projeto>/memorias-ia/` (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 `<base_projeto>/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/<modulo>/`.
|
||
- Gravou registros de ações da IA em pastas despadronizadas fora de `<base_projeto>/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`
|