6.4 KiB
6.4 KiB
| type | name | description | updatedAt |
|---|---|---|---|
| structural | README | Manifesto e matriz canônica dos 6 pilares do Documentation-Driven Development (DDD) | 2026-10-14 |
Documentation-Driven Development (DDD)
Manifesto
No ecossistema Azteca, a documentação precede o código. Nenhum artefato (regra, skill, workflow, módulo, tela, API, decisão técnica) deve ser implementado sem documentação prévia no local adequado. A documentação é a especificação viva e o contrato formal do sistema.
Princípios Fundamentais
- Doc First — Nenhum artefato novo sem documentação prévia.
- Doc como Contrato — A documentação é a especificação; o código a implementa.
- Código Satisfaz Doc — Se o código diverge da documentação, o código está incorreto.
- Sincronia Obrigatória — Mudança no código
\rightarrowatualização da doc; mudança na doc\rightarrowatualização no código. - Localização Canônica — Cada nível de documentação tem seu destino formal exclusivo.
- Leitura Antes de Escrita — Antes de alterar ou criar, ler o que já existe.
A Matriz Canônica dos 6 Pilares
| Pilar | Escopo / Destino | Formato | Público | Conteúdo Obrigatório |
|---|---|---|---|---|
| 1. Código-Fonte | .ts, .vue, .js |
JSDoc + comentários inline | Desenvolvedores / IA | Comentários claros e coerentes quanto à aplicação prática e contexto de negócio. |
| 2. Ajuda na Tela (UI) | *-front/.../{componente}.ajuda.md |
Markdown co-localizado | Usuários da UI | Para modalX.vue, o arquivo DEVE ser modalX.ajuda.md. Explica objetivo, botões, campos e instruções de uso. |
| 3. Wiki do Usuário | <modulo-wiki>/<modulo-id>/ |
Markdown (VitePress) | Usuários / Clientes | Aplicação VitePress voltada ao acesso dos usuários. Manuais operacionais, tutoriais de uso, conceitos de negócio e fluxos da aplicação. Arquivos e mídias pesadas no MinIO Paiol. |
| 4. Wiki de Desenvolvimento | <modulo-wiki>/dev/<modulo-id>/ |
Markdown (VitePress) | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno exclusivo da equipe de desenvolvimento. Arquitetura técnica, modelos de banco, regras de negócio ({modulo}.regras-negocio.md), filas BullMQ, CRONs e ADRs. |
| 5. Integração de IA | Rota Backend /llm.md |
Markdown dinâmico | Agentes de IA / LLMs | Catálogo vivo de schemas Zod, enums canônicos e contratos de API para consumo por LLMs. |
| 6. Memória das Ações da IA e Identidade | <base_projeto>/memorias-ia/ |
YAML / Markdown | Agentes de IA / Auditoria | Arquivo mandatório modulo.yml (modulo-id, modulo-caminho, modulo-descricao, modulo-tipo, modulo-acesso, modulo-wiki), índice central historico-acoes.md (Data | Memória / Ação | Arquivo Memoria | Citações no Código-Fonte) e arquivos dedicados de sessão sessao-AAAA-MM-DD-slug.md. |
ℹ️ Arquitetura VitePress (
<modulo-wiki>, padrão:../wiki) e Identidade do Projeto:
<modulo-wiki>é uma aplicação VitePress cujo caminho é definido emmemorias-ia/modulo.yml(fallback padrão:../wiki/).<modulo-wiki>/<modulo-id>/representa a documentação de acesso dos usuários e operadores (onde<modulo-id>provém dememorias-ia/modulo.yml).<modulo-wiki>/dev/<modulo-id>/representa a documentação de acesso interno pela equipe de desenvolvimento e arquitetura.- O arquivo
<base_projeto>/memorias-ia/modulo.ymlé obrigatório em todos os projetos.- Mídias e Arquivos no MinIO Paiol: Imagens, manuais em PDF, gravações em vídeo e anexos pesados NUNCA devem ser commitados no Git da Wiki; devem ser enviados ao MinIO Paiol via
./.agent/scripts/upload-paiol-wiki.she referenciados via URLshttps://paiol.idz.one/wiki/....
Hub Central de Templates (DOCUMENTACAO/templates/)
Todos os modelos canônicos para instanciar a documentação nos projetos residem em DOCUMENTACAO/templates/:
| Pilar / Categoria | Destino Canônico no Projeto | Template Canônico |
|---|---|---|
| Identidade do Módulo (Pilar 6) | <base_projeto>/memorias-ia/modulo.yml |
modulo.yml.template |
| Índice de Ações da IA (Pilar 6) | <base_projeto>/memorias-ia/historico-acoes.md |
historico-acoes.md.template |
| Registro de Sessão da IA (Pilar 6) | <base_projeto>/memorias-ia/sessao-AAAA-MM-DD-slug.md |
sessao-memoria.md.template |
| Domínio do Módulo (Pilar 3 e 4) | <modulo-wiki>/<modulo-id>/index.md |
modulo-dominio.md.template |
| Regras de Negócio (Pilar 4) | <modulo-wiki>/dev/<modulo-id>/<servico>.regras-negocio.md |
regra-negocio.md.template |
| Decisões Arquiteturais - ADR (Pilar 4) | <modulo-wiki>/dev/<modulo-id>/adrs/ |
adr.md.template |
| Ajuda na Tela / UI (Pilar 2) | *-front/src/.../{componente}.ajuda.md |
ajuda-tela.md.template |
| Contratos de API (Pilar 5 e 4) | Rota /llm.md ou <modulo-wiki>/dev/<modulo-id>/contratos/ |
contrato-api.md.template |
| Fluxos e Telas (Pilar 3 e 4) | <modulo-wiki>/<modulo-id>/fluxos/ |
fluxo-usuario.md.template |
Workflow DDD
- Receber Demanda: Identificar os pilares impactados.
- Documentar Prévia: Criar/atualizar a documentação no destino apropriado usando templates padronizados.
- Validar com Operador: Apresentar a documentação preliminar para alinhamento e aprovação.
- Implementar: Codificar de acordo com a documentação aprovada.
- Validar: Testar e analisar para assegurar que o código satisfaz a documentação em 100%.
- Sincronizar & Registrar Memória: Sincronizar ajustes finais e registrar a sessão em
<base_projeto>/memorias-ia/.
Referências
- Rule:
rules/ddd-documentacao-primeiro.md - Rule:
rules/identidade-modulo.md - Rule:
rules/jsdoc-padrao.md - Rule:
rules/regras-negocio-md.md - Skill:
skills/adicionar-ajuda/SKILL.md - Skill:
skills/documentar-dominio-modulo/SKILL.md - Skill:
skills/documentar-decisao-tecnica/SKILL.md - Skill:
skills/diagnosticar-lacunas-documentacao/SKILL.md - Skill:
skills/aprimora-ia/SKILL.md