---
type: structural
name: README
description: Manifesto e guia para o Desenvolvimento Orientado a Documentação (DDD)
updatedAt: "2026-08-12"
---
# Documentation-Driven Development (DDD)
## Manifesto
No ecossistema Azteca, a documentação precede o código. Nenhum artefato (regra, skill, workflow, funcionalidade, API, decisão técnica) deve ser implementado sem documentação prévia. A documentação é a especificação viva.
## Princípios
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 doc, o código está errado.
4. **Sincronia Obrigatória** — Mudança no código → atualização da doc; mudança na doc → atualização no código.
5. **Templates Padronizados** — Cada tipo de documento tem seu template centralizado em `_templates/`.
6. **Co-localização** — Toda documentação de uma funcionalidade fica na pasta daquela funcionalidade.
7. **Leitura Antes de Escrita** — Antes de documentar, leia o que já existe.
## Organização — Por Funcionalidade
A `DOCUMENTACAO/` é organizada por **funcionalidade/domínio funcional** do módulo Qualifica, não por tipo de documento.
### Estrutura
```text
DOCUMENTACAO/
├── README.md ← Índice geral (público)
├── funcionalidades/ ← Subdivisão por funcionalidade
│ └── <funcionalidade>/ ← Uma pasta por funcionalidade
│ ├── especificacao.md ← Spec técnica (schemas, DDL, componentes)
│ ├── regras-negocio.md ← Regras de negócio em linguagem natural
│ ├── contratos.md ← Endpoints de API (quando aplicável)
│ └── fluxo.md ← Fluxograma detalhado (quando aplicável)
├── _transversais/ ← ADRs e decisões que cruzam funcionalidades
│ └── adr-NNN-titulo.md
└── _templates/ ← Templates (espelhados de .agent/DOCUMENTACAO/_templates/)
```
### Funcionalidades do Qualifica
| Funcionalidade | Pasta | Domínio |
| :--- | :--- | :--- |
| Avaliações | `funcionalidades/avaliacoes/` | Ciclos de avaliação, envios, análise, preenchimento |
| Empresas | `funcionalidades/empresas/` | Cadastro, painel, empreendedores, contatos |
| Formulários | `funcionalidades/formularios/` | Builder, seções, campos, respostas |
| Contratos Comerciais | `funcionalidades/contratos-comerciais/` | Gestão de contratos |
| Relatórios | `funcionalidades/relatorios/` | PDFs, histórico, documentos, eventos |
| Importador | `funcionalidades/importador/` | Importação de dados |
| Ajuda e Suporte | `funcionalidades/ajuda-suporte/` | Chamados, diagnóstico, suporte contextual |
| Validade | `funcionalidades/validade/` | Controle de validade |
### Tipos de Documento (dentro de cada funcionalidade)
| Arquivo | Template | Quando criar |
| :--- | :--- | :--- |
| `especificacao.md` | `_templates/_template-especificacao` | Sempre — é o doc mínimo de cada funcionalidade |
| `regras-negocio.md` | `_templates/_template-regras-negocio` | Quando a funcionalidade tem lógica de decisão não-trivial |
| `contratos.md` | `_templates/_template-contrato` | Quando a funcionalidade expõe endpoints de API |
| `fluxo.md` | `_templates/_template-fluxo` | Quando a funcionalidade tem ciclo de vida complexo |
### Documentação Transversal
Decisões arquiteturais (ADRs) e documentação que cruza múltiplas funcionalidades ficam em `_transversais/`, usando o template `_templates/_template-adr`.
## Workflow DDD
1. **Receber demanda**
2. **Identificar funcionalidade** — Determinar a qual funcionalidade a demanda pertence
3. **Consultar template** — Usar o template adequado de `_templates/`
4. **Documentar** — Criar/atualizar documentação na pasta da funcionalidade
5. **Revisar** — Apresentar a documentação ao operador para validação
6. **Implementar** — Codificar de acordo com a documentação aprovada
7. **Validar** — Verificar se o código satisfaz a doc 100%
8. **Sincronizar** — Atualizar a documentação se a implementação revelou ajustes
## Integração com o Ecossistema
| Artefato | Como Integra com DDD |
| :--- | :--- |
| `rules/regras-negocio-md.md` | Define formato e obrigatoriedade de documentar regras de negócio |
| `skills/documentar-decisao-tecnica` | Fornece habilidade para criar e atualizar ADRs |
| `skills/documentar-dominio-modulo` | Estrutura para levantar glossário e domínio |
| `skills/documentar-regras-negocio` | Habilidade para extrair e redigir regras |
| `rules/diagnostico-antes-correcao.md`| Diagnóstico exige leitura e alinhamento com doc antes de corrigir bugs |
## Referências
- `rules/ddd-documentacao-primeiro.md`
- `skills/documentar-decisao-tecnica`
- `skills/documentar-dominio-modulo`
- `skills/documentar-regras-negocio`
