.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-10-14

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	<modulo-wiki>/<modulo-id>/	Usuários / Operadores	Aplicação VitePress com acesso dos usuários (caminho definido em modulo-wiki em modulo.yml, fallback padrão: ../wiki/). Manuais de operação completos, tutoriais de uso, conceitos de negócio e fluxos da aplicação.
4. Wiki de Desenvolvimento	<modulo-wiki>/dev/<modulo-id>/	Desenvolvedores / Arquitetos	Seçã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	<base_projeto>/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 (<modulo-wiki>, padrão: ../wiki/):

• <modulo-wiki>/<modulo-id>/ \rightarrow Aplicação VitePress voltada ao acesso dos usuários e clientes (onde <modulo-id> e <modulo-wiki> são extraídos de memorias-ia/modulo.yml, com fallback padrão para ../wiki/).
• <modulo-wiki>/dev/<modulo-id>/ \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, modulo-acesso, modulo-wiki). Sempre consultado quando precisar de IDs, rotas base, credenciais de teste, wiki ou stack.
• ./memorias-ia/: Registros individuais sessao-AAAA-MM-DD-slug.md e índice cumulativo historico-acoes.md.
• <modulo-wiki>/<modulo-id>/: Documentação do módulo com acesso dos usuários (VitePress).
• <modulo-wiki>/dev/<modulo-id>/: Documentação técnica do módulo com acesso interno dev (VitePress).

---

Armazenamento de Arquivos e Mídias da Wiki no MinIO Paiol

Para evitar o inchaço (bloat) irreversível do repositório Git da Wiki (<modulo-wiki>), arquivos binários e mídias pesadas (manuais em PDF, imagens em alta resolução, fluxogramas, diagramas, gravações em vídeo e anexos) NUNCA devem ser commitados no Git da Wiki.

Protocolo de Envio e Nomenclatura:

• Destino: Bucket público wiki no MinIO Paiol:

  https://paiol.idz.one/wiki/{modulo}/{funcionalidade/pagina}-{aleatorio}.{ext}
  

  Onde {modulo} é extraído de modulo-id em memorias-ia/modulo.yml e {aleatorio} é um sufixo alfanumérico curto (8 caracteres) para renovação de cache e prevenção de colisão.
• Envio via Utilitário CLI (Recomendado):

  ./.agent/scripts/upload-paiol-wiki.sh <caminho-do-arquivo> <slug-funcionalidade>
  

• Envio Direto via cURL:

  curl -X PUT --upload-file ./manual.pdf https://paiol.idz.one/wiki/{modulo}/{funcionalidade/pagina}-{aleatorio}.pdf
  

• Referência nos Markdowns da Wiki: Nos arquivos .md da Wiki, utilize exclusivamente as URLs públicas geradas:
  • Para imagens: ![Descrição](https://paiol.idz.one/wiki/{modulo}/{slug}-{aleatorio}.png)
  • Para manuais/documentos: [Baixar Manual (PDF)](https://paiol.idz.one/wiki/{modulo}/{slug}-{aleatorio}.pdf)

---

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 <modulo-wiki>/<modulo-id>/ (Pilar 3).
   • É componente técnico, arquitetura, serviço ou fila? \rightarrow Criar/atualizar documentação em <modulo-wiki>/dev/<modulo-id>/ (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/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 no módulo \rightarrow inseriu JSDoc claro quanto à sua aplicação prática, documentou a regra técnica em <modulo-wiki>/dev/<modulo-id>/ e o guia de uso em <modulo-wiki>/<modulo-id>/.
• 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 <modulo-wiki>/dev/<modulo-id>/.
• 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, identidade-modulo.md
• Skills: adicionar-ajuda, documentar-dominio-modulo, documentar-decisao-tecnica, diagnosticar-lacunas-documentacao