---
type: structural
name: README
description: Manifesto e matriz canônica dos 6 pilares do Documentation-Driven Development (DDD)
updatedAt: "2026-09-01"
---

# 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** | `../../wiki/<modulo>/` | 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. |
| **4. Wiki de Desenvolvimento** | `../../wiki/dev/<modulo>/` | 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** | `<base_projeto>/memorias-ia/` | Markdown com frontmatter | Agentes de IA / Auditoria | Registros de sessões, otimizações executadas, histórico de decisões arquiteturais. |

> ℹ️ **Arquitetura VitePress (`../../wiki`)**:
> - `../../wiki/` é uma aplicação **VitePress**.
> - `../../wiki/<modulo>/` representa a documentação de **acesso dos usuários e operadores**.
> - `../../wiki/dev/<modulo>/` representa a documentação de **acesso interno pela equipe de desenvolvimento e arquitetura**.

---

## Hub Central de Templates (`DOCUMENTACAO/`)

| Categoria | Diretório | O que documenta | Template |
| :--- | :--- | :--- | :--- |
| **Arquitetura (ADRs)** | `DOCUMENTACAO/arquitetura/` ou `../../wiki/dev/<modulo>/adrs/` | Decisões técnicas e arquiteturais | `_template-adr` |
| **Módulos / Domínio** | `DOCUMENTACAO/modulos/` ou `../../wiki/dev/<modulo>/` | Domínio, glossário e entidades | `_template-modulo` |
| **Regras de Negócio** | `DOCUMENTACAO/regras-negocio/` | Regras globais ou extraídas do código | `_template-regra` |
| **Contratos de API** | `DOCUMENTACAO/contratos/` | Contratos de rotas e endpoints | `_template-contrato` |
| **Fluxos de Usuário** | `DOCUMENTACAO/fluxos/` | Jornadas do usuário e telas | `_template-fluxo` |

---

## 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/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`