From b92dc7b06ea2db1c43774a37ac2c3a8dae6365ec Mon Sep 17 00:00:00 2001 From: Luiz Silva Date: Wed, 12 Aug 2026 14:01:38 -0300 Subject: [PATCH] =?UTF-8?q?docuemnta=C3=A7=C3=A3o?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- DOCUMENTACAO/INDICE | 40 ++++++++++++ DOCUMENTACAO/README | 53 ++++++++++++++++ DOCUMENTACAO/arquitetura/_template-adr | 49 +++++++++++++++ DOCUMENTACAO/contratos/_template-contrato | 70 +++++++++++++++++++++ DOCUMENTACAO/fluxos/_template-fluxo | 48 ++++++++++++++ DOCUMENTACAO/modulos/_template-modulo | 36 +++++++++++ DOCUMENTACAO/regras-negocio/_template-regra | 34 ++++++++++ README | 9 +++ agents/documentacao/agent.json | 2 +- agents/documentacao/persona | 4 ++ manifesto.json | 39 +++++++++++- rules/ddd-documentacao-primeiro.md | 52 +++++++++++++++ 12 files changed, 432 insertions(+), 4 deletions(-) create mode 100644 DOCUMENTACAO/INDICE create mode 100644 DOCUMENTACAO/README create mode 100644 DOCUMENTACAO/arquitetura/_template-adr create mode 100644 DOCUMENTACAO/contratos/_template-contrato create mode 100644 DOCUMENTACAO/fluxos/_template-fluxo create mode 100644 DOCUMENTACAO/modulos/_template-modulo create mode 100644 DOCUMENTACAO/regras-negocio/_template-regra create mode 100644 rules/ddd-documentacao-primeiro.md diff --git a/DOCUMENTACAO/INDICE b/DOCUMENTACAO/INDICE new file mode 100644 index 0000000..0604ea1 --- /dev/null +++ b/DOCUMENTACAO/INDICE @@ -0,0 +1,40 @@ +--- +type: structural +name: INDICE +description: Índice central navegável de todas as categorias de documentação +updatedAt: "2026-08-12" +--- + +# Índice de Documentação + +Este documento serve como ponto central de navegação para todas as documentações do ecossistema. Os documentos serão listados aqui conforme forem criados. + +## Arquitetura +Decisões técnicas e arquiteturais (ADRs) que impactam o sistema. +**Template**: `DOCUMENTACAO/arquitetura/_template-adr` + +- *(Nenhum documento criado ainda)* + +## Módulos +Documentação do domínio, glossário e entidades de cada módulo do sistema. +**Template**: `DOCUMENTACAO/modulos/_template-modulo` + +- *(Nenhum documento criado ainda)* + +## Regras de Negócio +Regras operacionais e de negócio extraídas do código ou definidas pelos operadores. +**Template**: `DOCUMENTACAO/regras-negocio/_template-regra` + +- *(Nenhum documento criado ainda)* + +## Contratos +Definição de contratos de API, schemas de dados e especificações de endpoints. +**Template**: `DOCUMENTACAO/contratos/_template-contrato` + +- *(Nenhum documento criado ainda)* + +## Fluxos +Mapeamento de jornadas do usuário, interações de interface e fluxos de uso do sistema. +**Template**: `DOCUMENTACAO/fluxos/_template-fluxo` + +- *(Nenhum documento criado ainda)* diff --git a/DOCUMENTACAO/README b/DOCUMENTACAO/README new file mode 100644 index 0000000..26618e0 --- /dev/null +++ b/DOCUMENTACAO/README @@ -0,0 +1,53 @@ +--- +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, módulo, 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 categoria tem seu template; nenhuma documentação é criada do zero. +6. **Leitura Antes de Escrita** — Antes de documentar, leia o que já existe. + +## Categorias de Documentação + +| Categoria | Diretório | O que documenta | Template | +| :--- | :--- | :--- | :--- | +| Arquitetura | `DOCUMENTACAO/arquitetura/` | Decisões técnicas e arquiteturais (ADRs) | `_template-adr` | +| Módulos | `DOCUMENTACAO/modulos/` | Domínio, glossário e entidades de cada módulo | `_template-modulo` | +| Regras de Negócio | `DOCUMENTACAO/regras-negocio/` | Regras extraídas do código ou definidas pelo operador | `_template-regra` | +| Contratos | `DOCUMENTACAO/contratos/` | Contratos de API, schemas, endpoints | `_template-contrato` | +| Fluxos | `DOCUMENTACAO/fluxos/` | Jornadas do usuário e fluxos de uso | `_template-fluxo` | + +## Workflow DDD +1. **Receber demanda** +2. **Documentar** (criar/atualizar documentação na categoria apropriada usando o template) +3. **Revisar** (apresentar a documentação ao operador para validação) +4. **Implementar** (codificar de acordo com a documentação aprovada) +5. **Validar** (verificar se o código satisfaz a doc 100%) +6. **Sincronizar** (atualizar a documentação se a implementação revelou ajustes necessários) + +## 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 de módulos | +| `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` diff --git a/DOCUMENTACAO/arquitetura/_template-adr b/DOCUMENTACAO/arquitetura/_template-adr new file mode 100644 index 0000000..787437b --- /dev/null +++ b/DOCUMENTACAO/arquitetura/_template-adr @@ -0,0 +1,49 @@ +--- +type: template +name: _template-adr +description: Template para Architecture Decision Records (ADRs) +updatedAt: "2026-08-12" +--- + +# ADR: + +## Data + + +## Status + + +## Autores + + +## Contexto + + +## Decisão + + +## Alternativas Consideradas + +- Alternativa 1: [...] (Motivo da rejeição: [...]) +- Alternativa 2: [...] (Motivo da rejeição: [...]) + +## Consequências + +### Positivas +- +- [...] + +### Negativas +- +- [...] + +### Neutras +- +- [...] + +## Impacto no Monorepo + + +## Referências + +- [...] diff --git a/DOCUMENTACAO/contratos/_template-contrato b/DOCUMENTACAO/contratos/_template-contrato new file mode 100644 index 0000000..0839805 --- /dev/null +++ b/DOCUMENTACAO/contratos/_template-contrato @@ -0,0 +1,70 @@ +--- +type: template +name: _template-contrato +description: Template para definição de contratos de API e schemas +updatedAt: "2026-08-12" +--- + +# Contrato: + +## Serviço + + +## Base URL +`` + +## Autenticação + + +## Endpoints + +| Método | Rota | Descrição | Auth | +| :--- | :--- | :--- | :--- | +| `GET` | `/rota/exemplo` | `` | `Sim/Não` | +| `POST` | `/rota/exemplo` | `` | `Sim/Não` | + +--- + +## Detalhamento por Endpoint + +### `` `` + + +**Request Params** +- `param1` (tipo, obrigatório?): + +**Body Schema** +```json +{ + // Exemplo de body esperado +} +``` + +**Response Schema (Sucesso)** +```json +{ + // Exemplo de resposta 200/201 +} +``` + +**Códigos de Erro** +- `400 Bad Request`: +- `404 Not Found`: + +--- + +## Schema Zod de Referência + +```typescript +// z.object({ ... }) +``` + +## Exemplos de Uso + +```bash +curl -X GET ... +``` + +## Referências + +- [...] diff --git a/DOCUMENTACAO/fluxos/_template-fluxo b/DOCUMENTACAO/fluxos/_template-fluxo new file mode 100644 index 0000000..40e6476 --- /dev/null +++ b/DOCUMENTACAO/fluxos/_template-fluxo @@ -0,0 +1,48 @@ +--- +type: template +name: _template-fluxo +description: Template para mapeamento de jornadas do usuário e fluxos de uso +updatedAt: "2026-08-12" +--- + +# Fluxo: + +## Objetivo do Fluxo + + +## Ator(es) + +- [...] + +## Pré-condições + +- [...] + +## Fluxo Principal + +1. [...] +2. [...] +3. [...] + +## Fluxos Alternativos + +- **Alternativa A** (Ocorre no passo X se a condição Y for verdadeira): + 1. [...] + 2. [...] (retorna ao passo Z do fluxo principal) + +## Tratamento de Erros + +- **Erro 1** (Falha no passo X): Ação de mitigação e mensagem de erro apresentada. + +## Regras de Negócio Aplicáveis + +- `Regra X`: [...] +- `Regra Y`: [...] + +## Telas Envolvidas + +- [...] + +## Referências + +- [...] diff --git a/DOCUMENTACAO/modulos/_template-modulo b/DOCUMENTACAO/modulos/_template-modulo new file mode 100644 index 0000000..1bdb6b5 --- /dev/null +++ b/DOCUMENTACAO/modulos/_template-modulo @@ -0,0 +1,36 @@ +--- +type: template +name: _template-modulo +description: Template para documentação de módulos e domínios +updatedAt: "2026-08-12" +--- + +# Módulo: + +## Área de Conhecimento + + +## Glossário do Módulo + +| Termo | Definição | Contexto de Uso | +| :--- | :--- | :--- | +| `` | `` | `` | +| `` | `` | `` | + +## Entidades Principais + +- **Entidade A**: . +- **Entidade B**: . + +## Legislação Aplicável + +- [...] + +## Fluxos do Domínio + +- **Fluxo Principal X**: [...] +- **Fluxo Principal Y**: [...] + +## Vocabulário de Interface + +- [...] diff --git a/DOCUMENTACAO/regras-negocio/_template-regra b/DOCUMENTACAO/regras-negocio/_template-regra new file mode 100644 index 0000000..3305c76 --- /dev/null +++ b/DOCUMENTACAO/regras-negocio/_template-regra @@ -0,0 +1,34 @@ +--- +type: template +name: _template-regra +description: Template para especificação de regras de negócio +updatedAt: "2026-08-12" +--- + +# Regra: + +## Contexto + + +## Critérios de Entrada / Identificação + +- Condição 1: [...] +- Condição 2: [...] + +## Regras de Processamento + +1. [...] +2. [...] +3. [...] + +## Casos de Revisão Manual + +- Cenário A: [...] + +## Estratégia de Fusão / Resultado + +- [...] + +## Dependências Externas + +- [...] diff --git a/README b/README index ed62663..5075682 100644 --- a/README +++ b/README @@ -11,6 +11,7 @@ Usado como **git submodule** `.agent` nos monorepos. 2. **Aprendizado contínuo** — conhecimento evolui a cada sessão via workflow `aprimorar-IA` 3. **Vendor-neutral** — arquitetura em Markdown puro, compatível com qualquer LLM 4. **Sem extensões** — artefatos de conhecimento não possuem extensão de arquivo +5. **Documentation-Driven** — documentação precede implementação; DOCUMENTACAO/ é a fonte de verdade --- @@ -19,6 +20,14 @@ Usado como **git submodule** `.agent` nos monorepos. ``` .memoria-ia/ ← armazenamento de memórias do projeto (mesmo nível do .agent, versionado pelo pai) .agent/ ← raiz do repositório (submodulo) +├── DOCUMENTACAO/ ← hub DDD — documentação precede código +│ ├── README ← manifesto DDD: princípios e workflow +│ ├── INDICE ← índice navegável de toda documentação +│ ├── arquitetura/ ← decisões técnicas (ADRs) +│ ├── modulos/ ← domínio e glossário por módulo +│ ├── regras-negocio/ ← regras de negócio documentadas +│ ├── contratos/ ← contratos de API e schemas +│ └── fluxos/ ← jornadas do usuário ├── README ← este arquivo ├── TOOLS ← ferramentas CLI recomendadas ├── manifesto.json ← inventário de todos os artefatos diff --git a/agents/documentacao/agent.json b/agents/documentacao/agent.json index 7c15d52..7ba82bc 100644 --- a/agents/documentacao/agent.json +++ b/agents/documentacao/agent.json @@ -8,7 +8,7 @@ "systemPromptSections": [ { "title": "Identidade e Escopo", - "content": "# Agente de Documentação (@documentacao)\n\n## Identidade\n\nVocê é o agente responsável por tornar o conhecimento do ecossistema Azteca acessível — para desenvolvedores, usuários finais e o próprio agente de IA. Você transforma código complexo, decisões técnicas e regras de negócio em documentação clara e utilizável.\n\n## Idioma\n\nToda sua comunicação — incluindo raciocínio interno, reflexões e respostas — **DEVE** ser em **português brasileiro (pt-BR)**. Nunca use inglês para pensar, raciocinar ou responder.\n\n## Escopo de Atuação\n\n- Todos os pacotes: `*-back`, `*-front`, `*-comuns`\n- Diretório `.agent/` (base/ herdado + local/ extensões + memory/)\n- Arquivos `.regras-negocio.md` co-localizados\n- JSDoc em funções compartilhadas\n- Guias de usuário e ajuda contextual nas telas\n- ADRs (Architecture Decision Records)\n\n## Responsabilidades\n\n1. **Diagnosticar lacunas antes de documentar** — executar a skill `diagnosticar-lacunas-documentacao` para identificar o que falta (ver `global/rules/diagnostico-antes-correcao`)\n2. Criar e manter arquivos `.regras-negocio.md` para módulos com lógica complexa\n3. Escrever JSDoc em funções e serviços compartilhados\n4. Criar guias de ajuda para usuários finais (módulo de ajuda contextual)\n5. Manter o `README` e documentação do projeto atualizada\n6. Documentar APIs internas (contratos de rotas, parâmetros, retornos)\n\n## Restrições\n\n- NUNCA documentar sem antes diagnosticar o que está ausente ou desatualizado (ver `global/rules/diagnostico-antes-correcao`)\n- NUNCA inventar, fabricar ou supor regras de negócio — documenta **exclusivamente** o que o código implementa ou o que o operador declarou\n- NUNCA descrever comportamento de API, schema ou componente sem antes **ler o código-fonte** para confirmar\n- NUNCA criar exemplos fictícios que possam ser confundidos com dados reais do sistema\n- NÃO duplica conteúdo entre artefatos — referencia via links\n- Documentação para usuário final deve usar linguagem do domínio, sem termos técnicos\n- JSDoc documenta o \"porquê\", não o \"o quê\" (que o TypeScript já expressa)\n- Quando não souber como uma funcionalidade opera, **ler o código antes de documentar** — nunca presumir\n\n## Colaborações\n\n- **Recebe código para documentar de:** `@back`, `@front`\n- **Recebe decisões arquiteturais de:** `@arquiteto`\n- **Fornece docs para:** `@comercial` (argumentos sobre features)\n- **Atualiza artefatos com:** regras e padrões definidos em qualquer conversa\n\n## Tom e Estilo\n\n- Claro, preciso e orientado ao leitor-alvo\n- Para usuários: linguagem do domínio, sem TI\n- Para desenvolvedores: técnico, com exemplos de código\n- Para o agente de IA: estruturado, sem ambiguidade\n\n\n## Checklist de documentação completa\n\n- [ ] Módulos com lógica complexa têm `.regras-negocio.md`?\n- [ ] Funções compartilhadas têm JSDoc?\n- [ ] ADRs registram decisões de alto impacto?\n- [ ] Ajuda contextual usa vocabulário do domínio?\n- [ ] Referências cruzadas entre artefatos são válidas?\n\n## Memória Persistente\n\nO ecossistema adota uma arquitetura de memória em duas camadas:\n\n- **Memórias do Projeto ()**: Armazena decisões de negócio, contexto do produto, especificações funcionais e ADRs na raiz do projeto pai (versionado pelo repositório pai).\n- **Evoluções da IA ()**: Armazena registros de sessões , otimizações dos agentes e melhorias da arquitetura multiagente (versionado pelo submódulo ).\n\n### Regras de Operação\n- Gravar memórias de projeto em (na raiz do pai).\n- Gravar evoluções da IA em (no submódulo).\n- Toda memória deve ser um arquivo Markdown em com frontmatter (, , , , ).\n" + "content": "# Agente de Documentação (@documentacao)\n\n## Identidade\n\nVocê é o agente responsável por tornar o conhecimento do ecossistema Azteca acessível — para desenvolvedores, usuários finais e o próprio agente de IA. Você transforma código complexo, decisões técnicas e regras de negócio em documentação clara e utilizável.\n\n## Idioma\n\nToda sua comunicação — incluindo raciocínio interno, reflexões e respostas — **DEVE** ser em **português brasileiro (pt-BR)**. Nunca use inglês para pensar, raciocinar ou responder.\n\n## Escopo de Atuação\n\n- `DOCUMENTACAO/` — hub central de documentação DDD\n- Todos os pacotes: `*-back`, `*-front`, `*-comuns`\n- Diretório `.agent/` (base/ herdado + local/ extensões + memory/)\n- Arquivos `.regras-negocio.md` co-localizados\n- JSDoc em funções compartilhadas\n- Guias de usuário e ajuda contextual nas telas\n- ADRs (Architecture Decision Records)\n\n## Responsabilidades\n\n0. **Aplicar Documentation-Driven Development** — garantir que toda implementação tenha documentação prévia em `DOCUMENTACAO/` usando templates padronizados (ver `rules/ddd-documentacao-primeiro`)\n1. **Diagnosticar lacunas antes de documentar** — executar a skill `diagnosticar-lacunas-documentacao` para identificar o que falta (ver `global/rules/diagnostico-antes-correcao`)\n2. Criar e manter arquivos `.regras-negocio.md` para módulos com lógica complexa\n3. Escrever JSDoc em funções e serviços compartilhados\n4. Criar guias de ajuda para usuários finais (módulo de ajuda contextual)\n5. Manter o `README` e documentação do projeto atualizada\n6. Documentar APIs internas (contratos de rotas, parâmetros, retornos)\n\n## Restrições\n\n- NUNCA permitir implementação de artefato novo sem documentação prévia em DOCUMENTACAO/ (ver rules/ddd-documentacao-primeiro)\n- NUNCA documentar sem antes diagnosticar o que está ausente ou desatualizado (ver `global/rules/diagnostico-antes-correcao`)\n- NUNCA inventar, fabricar ou supor regras de negócio — documenta **exclusivamente** o que o código implementa ou o que o operador declarou\n- NUNCA descrever comportamento de API, schema ou componente sem antes **ler o código-fonte** para confirmar\n- NUNCA criar exemplos fictícios que possam ser confundidos com dados reais do sistema\n- NÃO duplica conteúdo entre artefatos — referencia via links\n- Documentação para usuário final deve usar linguagem do domínio, sem termos técnicos\n- JSDoc documenta o \"porquê\", não o \"o quê\" (que o TypeScript já expressa)\n- Quando não souber como uma funcionalidade opera, **ler o código antes de documentar** — nunca presumir\n\n## Colaborações\n\n- **Mantém hub DDD:** DOCUMENTACAO/ — fonte de verdade para todos os agentes\n- **Recebe código para documentar de:** `@back`, `@front`\n- **Recebe decisões arquiteturais de:** `@arquiteto`\n- **Fornece docs para:** `@comercial` (argumentos sobre features)\n- **Atualiza artefatos com:** regras e padrões definidos em qualquer conversa\n\n## Tom e Estilo\n\n- Claro, preciso e orientado ao leitor-alvo\n- Para usuários: linguagem do domínio, sem TI\n- Para desenvolvedores: técnico, com exemplos de código\n- Para o agente de IA: estruturado, sem ambiguidade\n\n\n## Checklist de documentação completa\n\n- [ ] Módulos com lógica complexa têm `.regras-negocio.md`?\n- [ ] Funções compartilhadas têm JSDoc?\n- [ ] ADRs registram decisões de alto impacto?\n- [ ] Ajuda contextual usa vocabulário do domínio?\n- [ ] Referências cruzadas entre artefatos são válidas?\n\n## Memória Persistente\n\nO ecossistema adota uma arquitetura de memória em duas camadas:\n\n- **Memórias do Projeto ()**: Armazena decisões de negócio, contexto do produto, especificações funcionais e ADRs na raiz do projeto pai (versionado pelo repositório pai).\n- **Evoluções da IA ()**: Armazena registros de sessões , otimizações dos agentes e melhorias da arquitetura multiagente (versionado pelo submódulo ).\n\n### Regras de Operação\n- Gravar memórias de projeto em (na raiz do pai).\n- Gravar evoluções da IA em (no submódulo).\n- Toda memória deve ser um arquivo Markdown em com frontmatter (, , , , ).\n" } ], "toolNames": [ diff --git a/agents/documentacao/persona b/agents/documentacao/persona index 988f03a..a95a8ca 100644 --- a/agents/documentacao/persona +++ b/agents/documentacao/persona @@ -29,6 +29,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas ## Escopo de Atuação +- `DOCUMENTACAO/` — hub central de documentação DDD - Todos os pacotes: `*-back`, `*-front`, `*-comuns` - Diretório `.agent/` (base/ herdado + local/ extensões + memory/) - Arquivos `.regras-negocio.md` co-localizados @@ -38,6 +39,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas ## Responsabilidades +0. **Aplicar Documentation-Driven Development** — garantir que toda implementação tenha documentação prévia em `DOCUMENTACAO/` usando templates padronizados (ver `rules/ddd-documentacao-primeiro`) 1. **Diagnosticar lacunas antes de documentar** — executar a skill `diagnosticar-lacunas-documentacao` para identificar o que falta (ver `global/rules/diagnostico-antes-correcao`) 2. Criar e manter arquivos `.regras-negocio.md` para módulos com lógica complexa 3. Escrever JSDoc em funções e serviços compartilhados @@ -47,6 +49,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas ## Restrições +- NUNCA permitir implementação de artefato novo sem documentação prévia em DOCUMENTACAO/ (ver rules/ddd-documentacao-primeiro) - NUNCA documentar sem antes diagnosticar o que está ausente ou desatualizado (ver `global/rules/diagnostico-antes-correcao`) - NUNCA inventar, fabricar ou supor regras de negócio — documenta **exclusivamente** o que o código implementa ou o que o operador declarou - NUNCA descrever comportamento de API, schema ou componente sem antes **ler o código-fonte** para confirmar @@ -58,6 +61,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas ## Colaborações +- **Mantém hub DDD:** DOCUMENTACAO/ — fonte de verdade para todos os agentes - **Recebe código para documentar de:** `@back`, `@front` - **Recebe decisões arquiteturais de:** `@arquiteto` - **Fornece docs para:** `@comercial` (argumentos sobre features) diff --git a/manifesto.json b/manifesto.json index 5f047f6..a839ee8 100644 --- a/manifesto.json +++ b/manifesto.json @@ -1,6 +1,6 @@ { - "versao": "3.0.0", - "atualizadoEm": "2026-08-11", + "versao": "3.1.0", + "atualizadoEm": "2026-08-12", "projeto": "e-licencie", "artefatos": { "global": { @@ -26,7 +26,8 @@ "global/rules/tsconfig-ignore-deprecations.md", "global/rules/typescript-module-resolution.md", "global/rules/typescript-sem-any.md", - "global/rules/zod-validacao-padrao.md" + "global/rules/zod-validacao-padrao.md", + "global/rules/ddd-documentacao-primeiro.md" ], "workflows": [ "global/workflows/aprimora-ia.md", @@ -45,6 +46,38 @@ "global/skills/orquestrar-agentes/SKILL.md" ] }, + "documentacao": { + "diretorio": "DOCUMENTACAO", + "manifesto": "DOCUMENTACAO/README", + "indice": "DOCUMENTACAO/INDICE", + "categorias": { + "arquitetura": { + "diretorio": "DOCUMENTACAO/arquitetura", + "template": "DOCUMENTACAO/arquitetura/_template-adr", + "descricao": "Decisões técnicas e arquiteturais (ADRs)" + }, + "modulos": { + "diretorio": "DOCUMENTACAO/modulos", + "template": "DOCUMENTACAO/modulos/_template-modulo", + "descricao": "Domínio, glossário e entidades de cada módulo" + }, + "regras-negocio": { + "diretorio": "DOCUMENTACAO/regras-negocio", + "template": "DOCUMENTACAO/regras-negocio/_template-regra", + "descricao": "Regras de negócio extraídas do código ou declaradas pelo operador" + }, + "contratos": { + "diretorio": "DOCUMENTACAO/contratos", + "template": "DOCUMENTACAO/contratos/_template-contrato", + "descricao": "Contratos de API, schemas e endpoints" + }, + "fluxos": { + "diretorio": "DOCUMENTACAO/fluxos", + "template": "DOCUMENTACAO/fluxos/_template-fluxo", + "descricao": "Jornadas do usuário e fluxos de uso" + } + } + }, "agents": { "agente": { "persona": "agents/agente/persona", diff --git a/rules/ddd-documentacao-primeiro.md b/rules/ddd-documentacao-primeiro.md new file mode 100644 index 0000000..c078938 --- /dev/null +++ b/rules/ddd-documentacao-primeiro.md @@ -0,0 +1,52 @@ +--- +type: rule +name: ddd-documentacao-primeiro +description: Regra global que exige a documentação de novos artefatos antes da implementação (Documentation-Driven Development). +scope: global +trigger: always_on +priority: alta +updatedAt: "2026-08-12" +--- + +# Regra: Documentação Obrigatória Antes da Implementação + +## Contexto +Implementar sem documentar leva ao acúmulo de conhecimento implícito, código inconsistente e perda do conhecimento institucional. Para garantir que as decisões de design, regras de negócio e fluxos estejam claros antes de qualquer código ser escrito, adotamos o Documentation-Driven Development (DDD). A documentação atua como o contrato formal do que será construído. + +## Regra +Antes de implementar qualquer novo artefato (regra, skill, workflow, módulo, endpoint de API, decisão técnica) ou realizar alterações substanciais em artefatos existentes, o agente **DEVE OBRIGATORIAMENTE** criar ou atualizar a documentação na pasta `DOCUMENTACAO/` utilizando o template apropriado da respectiva categoria. + +## Protocolo DDD + +Para toda nova demanda ou funcionalidade, siga rigorosamente os passos abaixo: + +1. **Identificar Categoria**: Analisar a demanda e determinar em qual(is) categoria(s) de documentação ela se encaixa (arquitetura, módulos, regras-negócio, contratos, fluxos). +2. **Consultar Template**: Consultar o respectivo template em `DOCUMENTACAO//_template-*`. +3. **Criar/Atualizar Documentação**: Redigir a documentação na categoria adequada usando a estrutura do template. Se a funcionalidade altera algo existente, a documentação prévia deve ser atualizada. +4. **Apresentar ao Operador**: Validar a documentação redigida com o operador (usuário humano) antes de iniciar qualquer código. +5. **Implementar**: Escrever o código de forma que ele satisfaça e implemente *exatamente* o que foi estabelecido na documentação aprovada. +6. **Validar**: Testar ou analisar o código para assegurar que ele respeita a especificação em 100%. +7. **Sincronizar**: Se durante a implementação descobrir-se que ajustes na abordagem são necessários, a documentação deve ser atualizada em sincronia com o código. + +## Exceções +Esta regra pode ser ignorada apenas para alterações triviais que não impactam regras de negócio, fluxos ou arquitetura, tais como: +- Correção de erros de digitação (typos) em arquivos e variáveis. +- Formatação de código ou linting. +- Ajustes simples de imports. +- Continuação de trabalho (ex: a doc já foi feita em um prompt/sessão anterior para esta mesma task). + +## Exemplos + +✅ **Correto**: +- O operador pede um novo endpoint. O agente cria `DOCUMENTACAO/contratos/novo-endpoint` detalhando a API e os schemas usando o template. Após aprovação, cria o código na API. + +❌ **Incorreto**: +- O operador pede uma nova regra de negócio complexa e o agente já cria a função ou arquivo `.ts` sem antes registrar a regra em `DOCUMENTACAO/regras-negocio/` para validação. +- O agente toma uma decisão técnica grande (ex: trocar a biblioteca de state management) e apenas implementa no código sem gerar um ADR. + +## Impacto +O código não é mais a fonte da verdade para o funcionamento esperado, mas sim a *implementação* da verdade registrada na documentação. Isso garante rastreabilidade, reduz dependência de memória implícita de sessões passadas e facilita a manutenção por humanos e outras instâncias do agente. + +## Referências +- `DOCUMENTACAO/README` (Manifesto DDD) +- Skills relacionadas: `documentar-decisao-tecnica`, `documentar-dominio-modulo`, `documentar-regras-negocio`