86 lines
6.4 KiB
Text
86 lines
6.4 KiB
Text
---
|
||
type: structural
|
||
name: README
|
||
description: Manifesto e matriz canônica dos 6 pilares do Documentation-Driven Development (DDD)
|
||
updatedAt: "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
|
||
|
||
1. **Doc First** — Nenhum artefato novo sem documentação prévia.
|
||
2. **Doc como Contrato** — A documentação é a especificação; o código a implementa.
|
||
3. **Código Satisfaz Doc** — Se o código diverge da documentação, o código está incorreto.
|
||
4. **Sincronia Obrigatória** — Mudança no código $\rightarrow$ atualização da doc; mudança na doc $\rightarrow$ atualização no código.
|
||
5. **Localização Canônica** — Cada nível de documentação tem seu destino formal exclusivo.
|
||
6. **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 em `memorias-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 de `memorias-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.sh` e referenciados via URLs `https://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`](./templates/modulo.yml.template) |
|
||
| **Índice de Ações da IA (Pilar 6)** | `<base_projeto>/memorias-ia/historico-acoes.md` | [`historico-acoes.md.template`](./templates/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`](./templates/sessao-memoria.md.template) |
|
||
| **Domínio do Módulo (Pilar 3 e 4)** | `<modulo-wiki>/<modulo-id>/index.md` | [`modulo-dominio.md.template`](./templates/modulo-dominio.md.template) |
|
||
| **Regras de Negócio (Pilar 4)** | `<modulo-wiki>/dev/<modulo-id>/<servico>.regras-negocio.md` | [`regra-negocio.md.template`](./templates/regra-negocio.md.template) |
|
||
| **Decisões Arquiteturais - ADR (Pilar 4)** | `<modulo-wiki>/dev/<modulo-id>/adrs/` | [`adr.md.template`](./templates/adr.md.template) |
|
||
| **Ajuda na Tela / UI (Pilar 2)** | `*-front/src/.../{componente}.ajuda.md` | [`ajuda-tela.md.template`](./templates/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`](./templates/contrato-api.md.template) |
|
||
| **Fluxos e Telas (Pilar 3 e 4)** | `<modulo-wiki>/<modulo-id>/fluxos/` | [`fluxo-usuario.md.template`](./templates/fluxo-usuario.md.template) |
|
||
|
||
---
|
||
|
||
## Workflow DDD
|
||
|
||
1. **Receber Demanda:** Identificar os pilares impactados.
|
||
2. **Documentar Prévia:** Criar/atualizar a documentação no destino apropriado usando templates padronizados.
|
||
3. **Validar com Operador:** Apresentar a documentação preliminar para alinhamento e aprovação.
|
||
4. **Implementar:** Codificar de acordo com a documentação aprovada.
|
||
5. **Validar:** Testar e analisar para assegurar que o código satisfaz a documentação em 100%.
|
||
6. **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`
|