otimização do agent para docuemntação
This commit is contained in:
parent
1a25edc274
commit
890eddc464
60 changed files with 1807 additions and 1435 deletions
|
|
@ -1,40 +1,52 @@
|
|||
---
|
||||
type: structural
|
||||
name: INDICE
|
||||
description: Índice central navegável de todas as categorias de documentação
|
||||
updatedAt: "2026-08-12"
|
||||
description: Índice central navegável dos 6 pilares de documentação e memória do ecossistema
|
||||
updatedAt: "2026-09-01"
|
||||
---
|
||||
|
||||
# Índice de Documentação
|
||||
# Índice Geral de Documentação e Memória
|
||||
|
||||
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 mapa de navegação para os **6 pilares de documentação** do ecossistema.
|
||||
|
||||
## Arquitetura
|
||||
Decisões técnicas e arquiteturais (ADRs) que impactam o sistema.
|
||||
**Template**: `DOCUMENTACAO/arquitetura/_template-adr`
|
||||
---
|
||||
|
||||
- *(Nenhum documento criado ainda)*
|
||||
## 1. Código-Fonte (JSDoc e Comentários de Aplicação)
|
||||
Documentação interna nos arquivos `.ts`, `.vue`, `.js` com foco na aplicação prática no sistema.
|
||||
- **Regra:** `rules/jsdoc-padrao.md`
|
||||
- **Referência de regras de negócio no código:** `// Regras de negócio: ver ../../wiki/dev/<modulo>/...`
|
||||
|
||||
## Módulos
|
||||
Documentação do domínio, glossário e entidades de cada módulo do sistema.
|
||||
**Template**: `DOCUMENTACAO/modulos/_template-modulo`
|
||||
## 2. Ajuda na Tela (UI - `.ajuda.md`)
|
||||
Arquivos Markdown co-localizados nos componentes de tela e modais.
|
||||
- **Padrão:** `modalX.vue` $\rightarrow$ `modalX.ajuda.md`
|
||||
- **Skill / Workflow:** `skills/adicionar-ajuda/SKILL.md`
|
||||
|
||||
- *(Nenhum documento criado ainda)*
|
||||
## 3. Wiki do Usuário (`../../wiki/<modulo>/`)
|
||||
Aplicação VitePress voltada ao **acesso dos usuários e clientes**. Contém manuais operacionais, tutoriais e conceitos funcionais.
|
||||
- **Estrutura:** `../../wiki/<modulo>/` (ex: `../../wiki/e-licencie.sigma/`)
|
||||
- **Skill:** `skills/documentar-dominio-modulo/SKILL.md`
|
||||
|
||||
## 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`
|
||||
## 4. Wiki de Desenvolvimento (`../../wiki/dev/<modulo>/`)
|
||||
Aplicação VitePress com **acesso interno exclusivo pela equipe de desenvolvimento e arquitetura**. Contém arquitetura técnica, modelos de banco, regras de negócio detalhadas (`{modulo}.regras-negocio.md`), fluxos de filas, CRONs e ADRs.
|
||||
- **Estrutura:** `../../wiki/dev/<modulo>/` (ex: `../../wiki/dev/e-licencie.sigma/`)
|
||||
- **Regras de Negócio:** `../../wiki/dev/<modulo>/` (ver `rules/regras-negocio-md.md`)
|
||||
- **ADRs Técnicos:** `../../wiki/dev/<modulo>/adrs/` (ver `skills/documentar-decisao-tecnica/SKILL.md`)
|
||||
|
||||
- *(Nenhum documento criado ainda)*
|
||||
## 5. Rota de Integração de IA (`/llm.md`)
|
||||
Especificação dinâmica servida pelo backend para consumo por agentes e LLMs.
|
||||
- **Rota padrão:** `GET /llm.md` ou `GET /sigma/llm.md`
|
||||
|
||||
## Contratos
|
||||
Definição de contratos de API, schemas de dados e especificações de endpoints.
|
||||
**Template**: `DOCUMENTACAO/contratos/_template-contrato`
|
||||
## 6. Memória das Ações da IA (`<base_projeto>/memorias-ia/`)
|
||||
Registros de sessões, otimizações executadas e decisões de arquitetura.
|
||||
- **Diretório:** `<base_projeto>/memorias-ia/` (na raiz do projeto pai)
|
||||
- **Workflow:** `global/workflows/aprimora-ia.md`
|
||||
|
||||
- *(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`
|
||||
## Templates Padronizados (`DOCUMENTACAO/`)
|
||||
|
||||
- *(Nenhum documento criado ainda)*
|
||||
- **ADRs:** `DOCUMENTACAO/arquitetura/_template-adr`
|
||||
- **Módulos / Domínio:** `DOCUMENTACAO/modulos/_template-modulo`
|
||||
- **Regras de Negócio:** `DOCUMENTACAO/regras-negocio/_template-regra`
|
||||
- **Contratos de API:** `DOCUMENTACAO/contratos/_template-contrato`
|
||||
- **Fluxos:** `DOCUMENTACAO/fluxos/_template-fluxo`
|
||||
|
|
|
|||
|
|
@ -1,53 +1,77 @@
|
|||
---
|
||||
type: structural
|
||||
name: README
|
||||
description: Manifesto e guia para o Desenvolvimento Orientado a Documentação (DDD)
|
||||
updatedAt: "2026-08-12"
|
||||
description: Manifesto e matriz canônica dos 6 pilares do Documentation-Driven Development (DDD)
|
||||
updatedAt: "2026-09-01"
|
||||
---
|
||||
|
||||
# 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
|
||||
No ecossistema Azteca, a documentação precede o código. Nenhum artefato (regra, skill, workflow, módulo, tela, API, decisão técnica) deve ser implementado sem documentação prévia no local adequado. A documentação é a **especificação viva e o contrato formal** do sistema.
|
||||
|
||||
---
|
||||
|
||||
## Princípios Fundamentais
|
||||
|
||||
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.
|
||||
3. **Código Satisfaz Doc** — Se o código diverge da documentação, o código está incorreto.
|
||||
4. **Sincronia Obrigatória** — Mudança no código $\rightarrow$ atualização da doc; mudança na doc $\rightarrow$ atualização no código.
|
||||
5. **Localização Canônica** — Cada nível de documentação tem seu destino formal exclusivo.
|
||||
6. **Leitura Antes de Escrita** — Antes de alterar ou criar, ler o que já existe.
|
||||
|
||||
## Categorias de Documentação
|
||||
---
|
||||
|
||||
## A Matriz Canônica dos 6 Pilares
|
||||
|
||||
| Pilar | Escopo / Destino | Formato | Público | Conteúdo Obrigatório |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| **1. Código-Fonte** | `.ts`, `.vue`, `.js` | JSDoc + comentários inline | Desenvolvedores / IA | Comentários claros e coerentes quanto à aplicação prática e contexto de negócio. |
|
||||
| **2. Ajuda na Tela (UI)** | `*-front/.../{componente}.ajuda.md` | Markdown co-localizado | Usuários da UI | Para `modalX.vue`, o arquivo **DEVE** ser `modalX.ajuda.md`. Explica objetivo, botões, campos e instruções de uso. |
|
||||
| **3. Wiki do Usuário** | `../../wiki/<modulo>/` | Markdown (VitePress) | Usuários / Clientes | Aplicação VitePress voltada ao acesso dos usuários. Manuais operacionais, tutoriais de uso, conceitos de negócio e fluxos da aplicação. |
|
||||
| **4. Wiki de Desenvolvimento** | `../../wiki/dev/<modulo>/` | Markdown (VitePress) | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno exclusivo da equipe de desenvolvimento. Arquitetura técnica, modelos de banco, regras de negócio (`{modulo}.regras-negocio.md`), filas BullMQ, CRONs e ADRs. |
|
||||
| **5. Integração de IA** | Rota Backend `/llm.md` | Markdown dinâmico | Agentes de IA / LLMs | Catálogo vivo de schemas Zod, enums canônicos e contratos de API para consumo por LLMs. |
|
||||
| **6. Memória das Ações da IA** | `<base_projeto>/memorias-ia/` | Markdown com frontmatter | Agentes de IA / Auditoria | Registros de sessões, otimizações executadas, histórico de decisões arquiteturais. |
|
||||
|
||||
> ℹ️ **Arquitetura VitePress (`../../wiki`)**:
|
||||
> - `../../wiki/` é uma aplicação **VitePress**.
|
||||
> - `../../wiki/<modulo>/` representa a documentação de **acesso dos usuários e operadores**.
|
||||
> - `../../wiki/dev/<modulo>/` representa a documentação de **acesso interno pela equipe de desenvolvimento e arquitetura**.
|
||||
|
||||
---
|
||||
|
||||
## Hub Central de Templates (`DOCUMENTACAO/`)
|
||||
|
||||
| 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` |
|
||||
| **Arquitetura (ADRs)** | `DOCUMENTACAO/arquitetura/` ou `../../wiki/dev/<modulo>/adrs/` | Decisões técnicas e arquiteturais | `_template-adr` |
|
||||
| **Módulos / Domínio** | `DOCUMENTACAO/modulos/` ou `../../wiki/dev/<modulo>/` | Domínio, glossário e entidades | `_template-modulo` |
|
||||
| **Regras de Negócio** | `DOCUMENTACAO/regras-negocio/` | Regras globais ou extraídas do código | `_template-regra` |
|
||||
| **Contratos de API** | `DOCUMENTACAO/contratos/` | Contratos de rotas e endpoints | `_template-contrato` |
|
||||
| **Fluxos de Usuário** | `DOCUMENTACAO/fluxos/` | Jornadas do usuário e telas | `_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
|
||||
1. **Receber Demanda:** Identificar os pilares impactados.
|
||||
2. **Documentar Prévia:** Criar/atualizar a documentação no destino apropriado usando templates padronizados.
|
||||
3. **Validar com Operador:** Apresentar a documentação preliminar para alinhamento e aprovação.
|
||||
4. **Implementar:** Codificar de acordo com a documentação aprovada.
|
||||
5. **Validar:** Testar e analisar para assegurar que o código satisfaz a documentação em 100%.
|
||||
6. **Sincronizar & Registrar Memória:** Sincronizar ajustes finais e registrar a sessão em `<base_projeto>/memorias-ia/`.
|
||||
|
||||
| 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`
|
||||
|
||||
- Rule: `rules/ddd-documentacao-primeiro.md`
|
||||
- Rule: `rules/jsdoc-padrao.md`
|
||||
- Rule: `rules/regras-negocio-md.md`
|
||||
- Skill: `skills/adicionar-ajuda/SKILL.md`
|
||||
- Skill: `skills/documentar-dominio-modulo/SKILL.md`
|
||||
- Skill: `skills/documentar-decisao-tecnica/SKILL.md`
|
||||
- Skill: `skills/diagnosticar-lacunas-documentacao/SKILL.md`
|
||||
- Skill: `skills/aprimora-ia/SKILL.md`
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue