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