92 lines
4.9 KiB
Text
92 lines
4.9 KiB
Text
---
|
|
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`
|