.agent/rules/ddd-documentacao-primeiro.md

type	name	description	scope	trigger	priority	updatedAt
rule	ddd-documentacao-primeiro	Regra global de Documentation-Driven Development (DDD) definindo os 6 pilares de documentação e memória no ecossistema.	global	always_on	alta	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