agente documentação
This commit is contained in:
parent
b92dc7b06e
commit
5f11352ab7
11 changed files with 239 additions and 158 deletions
|
|
@ -1,40 +1,64 @@
|
|||
---
|
||||
type: structural
|
||||
name: INDICE
|
||||
description: Índice central navegável de todas as categorias de documentação
|
||||
description: Índice central navegável da documentação organizada por funcionalidade
|
||||
updatedAt: "2026-08-12"
|
||||
---
|
||||
|
||||
# Índice de Documentação
|
||||
# Índice de Documentação — Qualifica
|
||||
|
||||
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.
|
||||
Este documento serve como ponto central de navegação para toda a documentação do módulo Qualifica. A documentação é organizada por **funcionalidade**, onde cada pasta agrupa especificação técnica, regras de negócio, contratos e fluxos.
|
||||
|
||||
## Arquitetura
|
||||
Decisões técnicas e arquiteturais (ADRs) que impactam o sistema.
|
||||
**Template**: `DOCUMENTACAO/arquitetura/_template-adr`
|
||||
**Templates**: `DOCUMENTACAO/_templates/`
|
||||
**Funcionalidades**: `DOCUMENTACAO/funcionalidades/`
|
||||
|
||||
---
|
||||
|
||||
## Avaliações
|
||||
Ciclos de avaliação, envios, análise e preenchimento — funcionalidade core do sistema.
|
||||
|
||||
- `funcionalidades/avaliacoes/especificacao.md` — Spec técnica (schemas Zod, DDL, fluxos)
|
||||
- `funcionalidades/avaliacoes/regras-negocio.md` — Ciclos, prazos, envios e reenvios
|
||||
|
||||
## Empresas
|
||||
Cadastro de empresas, painel da empresa, empreendedores, empreendimentos e contatos.
|
||||
|
||||
- *(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`
|
||||
## Formulários
|
||||
Builder de formulários, seções, campos e respostas.
|
||||
|
||||
- *(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`
|
||||
## Contratos Comerciais
|
||||
Gestão de contratos comerciais.
|
||||
|
||||
- *(Nenhum documento criado ainda)*
|
||||
|
||||
## Contratos
|
||||
Definição de contratos de API, schemas de dados e especificações de endpoints.
|
||||
**Template**: `DOCUMENTACAO/contratos/_template-contrato`
|
||||
## Relatórios
|
||||
Relatórios em PDF, histórico, documentos e eventos.
|
||||
|
||||
- *(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`
|
||||
## Importador
|
||||
Importação de dados externos.
|
||||
|
||||
- *(Nenhum documento criado ainda)*
|
||||
|
||||
## Ajuda e Suporte
|
||||
Sistema de chamados, diagnóstico de ambiente e suporte contextual.
|
||||
|
||||
- `funcionalidades/ajuda-suporte/especificacao.md` — Arquitetura, componentes, fluxos e UX
|
||||
|
||||
## Validade
|
||||
Controle de validade.
|
||||
|
||||
- *(Nenhum documento criado ainda)*
|
||||
|
||||
---
|
||||
|
||||
## Transversais
|
||||
Decisões arquiteturais (ADRs) e documentação que cruza funcionalidades.
|
||||
**Template ADR**: `_templates/_template-adr`
|
||||
|
||||
- *(Nenhum documento criado ainda)*
|
||||
|
|
|
|||
|
|
@ -8,33 +8,72 @@ 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.
|
||||
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 categoria tem seu template; nenhuma documentação é criada do zero.
|
||||
6. **Leitura Antes de Escrita** — Antes de documentar, leia o que já existe.
|
||||
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.
|
||||
|
||||
## Categorias de Documentação
|
||||
## Organização — Por Funcionalidade
|
||||
|
||||
| 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` |
|
||||
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. **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)
|
||||
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
|
||||
|
||||
|
|
@ -42,7 +81,7 @@ No ecossistema Azteca, a documentação precede o código. Nenhum artefato (regr
|
|||
| :--- | :--- |
|
||||
| `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-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 |
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
type: template
|
||||
name: _template-adr
|
||||
description: Template para Architecture Decision Records (ADRs)
|
||||
description: Template para Architecture Decision Records (ADRs) — decisões transversais
|
||||
updatedAt: "2026-08-12"
|
||||
---
|
||||
|
||||
|
|
@ -31,18 +31,15 @@ updatedAt: "2026-08-12"
|
|||
|
||||
### Positivas
|
||||
- <Listar ganhos com a decisão>
|
||||
- [...]
|
||||
|
||||
### Negativas
|
||||
- <Listar desvantagens, trade-offs ou custos gerados>
|
||||
- [...]
|
||||
|
||||
### Neutras
|
||||
- <Listar impactos que não são inerentemente bons ou ruins>
|
||||
- [...]
|
||||
|
||||
## Impacto no Monorepo
|
||||
<Como essa decisão afeta a estrutura existente? Módulos afetados? Mudanças em dependências?>
|
||||
<Como essa decisão afeta a estrutura existente? Funcionalidades afetadas? Mudanças em dependências?>
|
||||
|
||||
## Referências
|
||||
<Links úteis, issues, PRs ou outras documentações que sustentem a decisão>
|
||||
|
|
@ -1,14 +1,14 @@
|
|||
---
|
||||
type: template
|
||||
name: _template-contrato
|
||||
description: Template para definição de contratos de API e schemas
|
||||
description: Template para definição de contratos de API e schemas de uma funcionalidade
|
||||
updatedAt: "2026-08-12"
|
||||
---
|
||||
|
||||
# Contrato: <PREENCHER NOME DO SERVIÇO OU DOMÍNIO>
|
||||
# Contrato de API — <PREENCHER NOME DA FUNCIONALIDADE>
|
||||
|
||||
## Serviço
|
||||
<Nome e breve descrição do serviço ou microsserviço responsável por esta API>
|
||||
<Nome e breve descrição do serviço responsável por esta API>
|
||||
|
||||
## Base URL
|
||||
`<URL base de desenvolvimento e/ou produção>`
|
||||
|
|
@ -54,17 +54,16 @@ updatedAt: "2026-08-12"
|
|||
---
|
||||
|
||||
## Schema Zod de Referência
|
||||
<Adicionar fragmento de código Zod caso o projeto utilize validação via schema>
|
||||
```typescript
|
||||
// z.object({ ... })
|
||||
```
|
||||
|
||||
## Exemplos de Uso
|
||||
<Comandos curl, snippets fetch ou scripts de exemplo>
|
||||
```bash
|
||||
curl -X GET ...
|
||||
```
|
||||
|
||||
## Referências
|
||||
<Links para outras documentações, regras de negócio ou ADRs relacionadas>
|
||||
- Especificação: `especificacao.md` (co-localizado)
|
||||
- Regras de negócio: `regras-negocio.md` (co-localizado)
|
||||
- [...]
|
||||
52
DOCUMENTACAO/_templates/_template-especificacao
Normal file
52
DOCUMENTACAO/_templates/_template-especificacao
Normal file
|
|
@ -0,0 +1,52 @@
|
|||
---
|
||||
type: template
|
||||
name: _template-especificacao
|
||||
description: Template para especificação técnica de uma funcionalidade do módulo
|
||||
updatedAt: "2026-08-12"
|
||||
---
|
||||
|
||||
# Especificação: <PREENCHER NOME DA FUNCIONALIDADE>
|
||||
|
||||
## Área de Conhecimento
|
||||
<Descrever brevemente o domínio de negócio desta funcionalidade. Qual sua responsabilidade principal dentro do módulo?>
|
||||
|
||||
## Glossário
|
||||
|
||||
| Termo | Definição | Contexto de Uso |
|
||||
| :--- | :--- | :--- |
|
||||
| `<Termo 1>` | `<Definição>` | `<Contexto>` |
|
||||
|
||||
## Entidades Principais
|
||||
<Descrever as entidades de dados que compõem esta funcionalidade>
|
||||
- **Entidade A**: <Descrição do papel e principais atributos>.
|
||||
|
||||
## Schemas Zod
|
||||
<Referenciar os schemas Zod em `qualifica-comuns/src/tabelas/` que sustentam esta funcionalidade>
|
||||
- `_entidade.ts` — <descrição>
|
||||
|
||||
## Estrutura de Dados (DDL)
|
||||
<Se aplicável, descrever a estrutura SQL das tabelas envolvidas>
|
||||
```sql
|
||||
-- DDL da tabela principal
|
||||
```
|
||||
|
||||
## Componentes de Interface
|
||||
<Listar as páginas e componentes Vue envolvidos nesta funcionalidade>
|
||||
- `PaginaX/` — <descrição>
|
||||
- `ComponenteY.vue` — <descrição>
|
||||
|
||||
## Fluxos do Domínio
|
||||
<Listar os fluxos de negócio orquestrados por esta funcionalidade, referenciando `fluxo.md` co-localizado se existir>
|
||||
- **Fluxo Principal**: [...]
|
||||
|
||||
## Legislação Aplicável
|
||||
<Listar leis, normas técnicas ou portarias que afetam esta funcionalidade, se aplicável>
|
||||
- [...]
|
||||
|
||||
## Vocabulário de Interface
|
||||
<Termos específicos que devem ser usados na UI para manter consistência com a linguagem ubíqua do domínio>
|
||||
- [...]
|
||||
|
||||
## Referências
|
||||
- Regras de negócio: `regras-negocio.md` (co-localizado)
|
||||
- [...]
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
type: template
|
||||
name: _template-fluxo
|
||||
description: Template para mapeamento de jornadas do usuário e fluxos de uso
|
||||
description: Template para mapeamento de jornadas do usuário e fluxos de uso de uma funcionalidade
|
||||
updatedAt: "2026-08-12"
|
||||
---
|
||||
|
||||
|
|
@ -11,38 +11,38 @@ updatedAt: "2026-08-12"
|
|||
<O que o usuário ou sistema deseja alcançar ao completar este fluxo?>
|
||||
|
||||
## Ator(es)
|
||||
<Quem inicia e participa do fluxo? (Ex: Cliente, Administrador, Sistema, Job em background)>
|
||||
<Quem inicia e participa do fluxo?>
|
||||
- [...]
|
||||
|
||||
## Pré-condições
|
||||
<O que precisa ser verdadeiro antes deste fluxo iniciar? (Ex: Usuário estar logado, possuir saldo, etc)>
|
||||
<O que precisa ser verdadeiro antes deste fluxo iniciar?>
|
||||
- [...]
|
||||
|
||||
## Fluxo Principal
|
||||
<O caminho feliz. O passo a passo em ordem cronológica de como o objetivo é alcançado>
|
||||
<O caminho feliz, passo a passo em ordem cronológica>
|
||||
1. [...]
|
||||
2. [...]
|
||||
3. [...]
|
||||
|
||||
## Fluxos Alternativos
|
||||
<Caminhos secundários ou desvios do fluxo principal que ainda levam a um resultado bem sucedido (ou parcial)>
|
||||
<Caminhos secundários ou desvios do fluxo principal>
|
||||
- **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
|
||||
<Como o fluxo reage a falhas, validações incorretas ou problemas de sistema>
|
||||
- **Erro 1** (Falha no passo X): Ação de mitigação e mensagem de erro apresentada.
|
||||
- **Erro 1** (Falha no passo X): Ação de mitigação e mensagem apresentada.
|
||||
|
||||
## Regras de Negócio Aplicáveis
|
||||
<Quais regras validam e controlam este fluxo? Linkar para `DOCUMENTACAO/regras-negocio/`>
|
||||
- `Regra X`: [...]
|
||||
- `Regra Y`: [...]
|
||||
<Quais regras validam e controlam este fluxo? Referenciar `regras-negocio.md` co-localizado>
|
||||
- Regra X: [...]
|
||||
|
||||
## Telas Envolvidas
|
||||
<Se aplicável, quais telas da UI compõem o fluxo>
|
||||
<Quais telas da UI compõem o fluxo?>
|
||||
- [...]
|
||||
|
||||
## Referências
|
||||
<Links para protótipos, designs, issues ou módulos relacionados>
|
||||
- Especificação: `especificacao.md` (co-localizado)
|
||||
- Regras de negócio: `regras-negocio.md` (co-localizado)
|
||||
- [...]
|
||||
43
DOCUMENTACAO/_templates/_template-regras-negocio
Normal file
43
DOCUMENTACAO/_templates/_template-regras-negocio
Normal file
|
|
@ -0,0 +1,43 @@
|
|||
---
|
||||
type: template
|
||||
name: _template-regras-negocio
|
||||
description: Template para especificação de regras de negócio de uma funcionalidade
|
||||
updatedAt: "2026-08-12"
|
||||
---
|
||||
|
||||
# Regras de Negócio — <PREENCHER NOME DA FUNCIONALIDADE>
|
||||
|
||||
Funcionalidade: `<nome da funcionalidade>`
|
||||
Localização: `DOCUMENTACAO/<funcionalidade>/`
|
||||
|
||||
---
|
||||
|
||||
## Contexto
|
||||
<Descrever em qual situação, processo ou fluxo estas regras são aplicadas. Qual o propósito de negócio?>
|
||||
|
||||
## Critérios de Entrada / Identificação
|
||||
<O que aciona estas regras? Quais dados ou condições precisam existir?>
|
||||
- Condição 1: [...]
|
||||
- Condição 2: [...]
|
||||
|
||||
## Regras de Processamento
|
||||
<Passo a passo lógico e determinístico. Como a validação ou transformação acontece?>
|
||||
1. [...]
|
||||
2. [...]
|
||||
3. [...]
|
||||
|
||||
## Casos de Revisão Manual
|
||||
<Existem exceções onde o sistema não decide automaticamente e envia para análise humana?>
|
||||
- Cenário A: [...]
|
||||
|
||||
## Estratégia de Fusão / Resultado
|
||||
<Qual é o output da execução destas regras? (ex: aprovação, recusa, alteração de status, cálculo final)>
|
||||
- [...]
|
||||
|
||||
## Dependências Externas
|
||||
<As regras dependem de integrações de terceiros, APIs, ou outras funcionalidades do sistema?>
|
||||
- [...]
|
||||
|
||||
## Referências
|
||||
- Especificação: `especificacao.md` (co-localizado)
|
||||
- [...]
|
||||
|
|
@ -1,36 +0,0 @@
|
|||
---
|
||||
type: template
|
||||
name: _template-modulo
|
||||
description: Template para documentação de módulos e domínios
|
||||
updatedAt: "2026-08-12"
|
||||
---
|
||||
|
||||
# Módulo: <PREENCHER NOME DO MÓDULO>
|
||||
|
||||
## Área de Conhecimento
|
||||
<Descrever brevemente o domínio de negócio deste módulo. Qual sua responsabilidade principal e área de atuação no ecossistema?>
|
||||
|
||||
## Glossário do Módulo
|
||||
|
||||
| Termo | Definição | Contexto de Uso |
|
||||
| :--- | :--- | :--- |
|
||||
| `<Termo 1>` | `<Definição>` | `<Contexto>` |
|
||||
| `<Termo 2>` | `<Definição>` | `<Contexto>` |
|
||||
|
||||
## Entidades Principais
|
||||
<Descrever as entidades de dados fundamentais que compõem este módulo>
|
||||
- **Entidade A**: <Descrição do papel da entidade e principais atributos>.
|
||||
- **Entidade B**: <Descrição do papel da entidade e principais atributos>.
|
||||
|
||||
## Legislação Aplicável
|
||||
<Listar leis, normas técnicas ou portarias que afetam as regras deste domínio, se aplicável>
|
||||
- [...]
|
||||
|
||||
## Fluxos do Domínio
|
||||
<Listar os fluxos de negócios centrais orquestrados por este módulo, referenciando documentos em `DOCUMENTACAO/fluxos/` se existirem>
|
||||
- **Fluxo Principal X**: [...]
|
||||
- **Fluxo Principal Y**: [...]
|
||||
|
||||
## Vocabulário de Interface
|
||||
<Termos específicos que devem ser usados na UI para manter a consistência com a linguagem ubíqua do domínio>
|
||||
- [...]
|
||||
|
|
@ -1,34 +0,0 @@
|
|||
---
|
||||
type: template
|
||||
name: _template-regra
|
||||
description: Template para especificação de regras de negócio
|
||||
updatedAt: "2026-08-12"
|
||||
---
|
||||
|
||||
# Regra: <PREENCHER NOME DA REGRA>
|
||||
|
||||
## Contexto
|
||||
<Descrever em qual situação, processo ou fluxo essa regra é aplicada. Qual o propósito de negócio dela?>
|
||||
|
||||
## Critérios de Entrada / Identificação
|
||||
<O que aciona essa regra? Quais dados ou condições precisam existir para que ela seja avaliada?>
|
||||
- Condição 1: [...]
|
||||
- Condição 2: [...]
|
||||
|
||||
## Regras de Processamento
|
||||
<Passo a passo lógico e determinístico da regra. Como a validação ou transformação acontece?>
|
||||
1. [...]
|
||||
2. [...]
|
||||
3. [...]
|
||||
|
||||
## Casos de Revisão Manual
|
||||
<Existem exceções onde o sistema não decide automaticamente e envia para análise humana? Listar os cenários.>
|
||||
- Cenário A: [...]
|
||||
|
||||
## Estratégia de Fusão / Resultado
|
||||
<Qual é o output da execução dessa regra? (ex: aprovação, recusa, alteração de status, cálculo final)>
|
||||
- [...]
|
||||
|
||||
## Dependências Externas
|
||||
<A regra depende de integrações de terceiros, APIs, ou outras regras do sistema para ser processada?>
|
||||
- [...]
|
||||
|
|
@ -50,32 +50,29 @@
|
|||
"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)"
|
||||
"organizacao": "por-funcionalidade",
|
||||
"templates": {
|
||||
"diretorio": "DOCUMENTACAO/_templates",
|
||||
"especificacao": "DOCUMENTACAO/_templates/_template-especificacao",
|
||||
"regras-negocio": "DOCUMENTACAO/_templates/_template-regras-negocio",
|
||||
"contrato": "DOCUMENTACAO/_templates/_template-contrato",
|
||||
"fluxo": "DOCUMENTACAO/_templates/_template-fluxo",
|
||||
"adr": "DOCUMENTACAO/_templates/_template-adr"
|
||||
},
|
||||
"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"
|
||||
}
|
||||
"diretorioFuncionalidades": "DOCUMENTACAO/funcionalidades",
|
||||
"funcionalidades": [
|
||||
"avaliacoes",
|
||||
"empresas",
|
||||
"formularios",
|
||||
"contratos-comerciais",
|
||||
"relatorios",
|
||||
"importador",
|
||||
"ajuda-suporte",
|
||||
"validade"
|
||||
],
|
||||
"transversais": {
|
||||
"diretorio": "DOCUMENTACAO/_transversais",
|
||||
"descricao": "Decisões arquiteturais e documentação que cruzam funcionalidades"
|
||||
}
|
||||
},
|
||||
"agents": {
|
||||
|
|
|
|||
|
|
@ -14,14 +14,14 @@ updatedAt: "2026-08-12"
|
|||
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.
|
||||
Antes de implementar qualquer novo artefato (regra, skill, workflow, funcionalidade, 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/funcionalidades/<funcionalidade>/` utilizando o template apropriado de `DOCUMENTACAO/_templates/`.
|
||||
|
||||
## 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/<categoria>/_template-*`.
|
||||
1. **Identificar Funcionalidade**: Analisar a demanda e determinar a qual funcionalidade ela pertence (avaliacoes, empresas, formularios, contratos-comerciais, relatorios, importador, ajuda-suporte, validade). Para decisões transversais, usar `DOCUMENTACAO/_transversais/`.
|
||||
2. **Consultar Template**: Consultar o respectivo template em `DOCUMENTACAO/_templates/_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.
|
||||
|
|
@ -38,10 +38,10 @@ Esta regra pode ser ignorada apenas para alterações triviais que não impactam
|
|||
## 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.
|
||||
- O operador pede um novo endpoint de avaliações. O agente cria/atualiza `DOCUMENTACAO/funcionalidades/avaliacoes/contratos.md` detalhando a API usando o template `_templates/_template-contrato`. 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 operador pede uma nova regra de negócio complexa para empresas e o agente já cria a função ou arquivo `.ts` sem antes registrar a regra em `DOCUMENTACAO/funcionalidades/empresas/regras-negocio.md` 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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue