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
|
|
@ -22,11 +22,16 @@ O conhecimento do agente está organizado em **três tipos de artefatos**, cada
|
|||
|
||||
| Artefato | Diretório (herdado) | Diretório (local) | Responsabilidade |
|
||||
|----------|---------------------|-------------------|------------------|
|
||||
| **Rules** | `.agent/base/global/rules/` | `.agent/local/rules/` | Restrições e convenções que o agente **deve respeitar sempre** |
|
||||
| **Workflows** | `.agent/base/global/workflows/` | `.agent/local/workflows/` | Processos sequenciais com passos numerados para tarefas bem definidas |
|
||||
| **Skills** | `.agent/base/global/skills/` | `.agent/local/skills/` | Guias operacionais completos e reutilizáveis para tarefas complexas recorrentes |
|
||||
| **Memória do Projeto** | — | `./.memoria-ia/` | Decisões de negócio, contexto do produto, especificações e ADRs (raiz do pai, versionado pelo pai) |
|
||||
| **Evoluções da IA** | `.agent/memory/` | — | Relatórios de sessões `/aprimora-ia`, otimizações dos agentes e melhorias da IA (versionado pelo submódulo) |
|
||||
| **Rules** | `.agent/rules/` | `.agent/rules/` | Restrições e convenções que o agente **deve respeitar sempre** |
|
||||
| **Workflows** | `.agent/workflows/` | `.agent/workflows/` | Processos sequenciais com passos numerados para tarefas bem definidas |
|
||||
| **Skills** | `.agent/skills/` | `.agent/skills/` | Guias operacionais completos e reutilizáveis para tarefas complexas recorrentes |
|
||||
| **Memória das Ações da IA** | — | `<base_projeto>/memorias-ia/` | Registros de sessões, otimizações dos agentes, decisões e relatórios da IA (raiz do pai) |
|
||||
|
||||
> 🧩 **Polimorfismo do `.agent` e Personalização por Projeto**:
|
||||
> O `.agent` é polimórfico e genérico. A personalização de cada projeto específico é mantida fora do `.agent`:
|
||||
> - `./memorias-ia/` (na raiz do projeto pai): Registros de ações, sessões e decisões da IA.
|
||||
> - `../../wiki/<modulo>/`: Documentação funcional com acesso dos usuários na aplicação VitePress.
|
||||
> - `../../wiki/dev/<modulo>/`: Documentação técnica com acesso interno dev na aplicação VitePress.
|
||||
|
||||
### Diferenças entre os artefatos
|
||||
|
||||
|
|
|
|||
22
global/workflows/doc.md
Normal file
22
global/workflows/doc.md
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
---
|
||||
type: workflow
|
||||
name: doc
|
||||
description: Alias para /documentacao - acionar o Agente de Documentação & Memória
|
||||
scope: global
|
||||
updatedAt: "2026-09-01"
|
||||
---
|
||||
|
||||
# Workflow: /doc (Alias para /documentacao)
|
||||
|
||||
Atalho rápido para o **Agente de Documentação & Memória** cobrindo os 6 pilares canônicos:
|
||||
|
||||
> ⚡ **Sem Parâmetros:** Se executado apenas como `/doc`, documenta automaticamente todo o contexto e decisões da conversa atual no chat.
|
||||
|
||||
- `1. Código-Fonte` $\rightarrow$ JSDoc de aplicação prática (`rules/jsdoc-padrao.md`)
|
||||
- `2. Ajuda UI` $\rightarrow$ `modalX.ajuda.md` co-localizado com `modalX.vue`
|
||||
- `3. Wiki Usuário` $\rightarrow$ `../../wiki/<modulo>/` (VitePress com acesso dos usuários)
|
||||
- `4. Wiki Dev` $\rightarrow$ `../../wiki/dev/<modulo>/` (VitePress com acesso interno dev e regras `{modulo}.regras-negocio.md`)
|
||||
- `5. Rota IA` $\rightarrow$ Rota do backend `/llm.md`
|
||||
- `6. Memória IA` $\rightarrow$ `<base_projeto>/memorias-ia/`
|
||||
|
||||
Para ver todas as opções e sintaxes, consulte [`/documentacao`](file:///home/luiz/Arquivos/DEV/Industria/SIGMA2026/.agent/global/workflows/documentacao.md).
|
||||
75
global/workflows/documentacao.md
Normal file
75
global/workflows/documentacao.md
Normal file
|
|
@ -0,0 +1,75 @@
|
|||
---
|
||||
type: workflow
|
||||
name: documentacao
|
||||
description: Acionar o Agente de Documentação para documentar o contexto do chat ou executar comandos específicos nos 6 pilares
|
||||
scope: global
|
||||
updatedAt: "2026-09-01"
|
||||
---
|
||||
|
||||
# Workflow: /documentacao (Agente de Documentação & Memória)
|
||||
|
||||
Este workflow aciona o **Agente de Documentação** para gerar, atualizar ou auditar a documentação nos **6 pilares canônicos** do Documentation-Driven Development (DDD).
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Comportamento Padrão (Sem Instruções Adicionais)
|
||||
|
||||
> **Quando invocado como `/documentacao` (ou `/doc`) sem nenhum parâmetro**, o agente executa automaticamente a **Documentação Contextual Baseada no Chat**:
|
||||
|
||||
1. **Varredura Integral do Contexto:**
|
||||
- Analisa todo o histórico da conversa, arquivos editados (`git status`), decisões tomadas e regras implementadas.
|
||||
2. **Distribuição e Geração nos 6 Pilares:**
|
||||
- **Pilar 1 (Código-Fonte):** Insere JSDoc de aplicação prática nos arquivos alterados na sessão (`rules/jsdoc-padrao.md`).
|
||||
- **Pilar 2 (Ajuda UI):** Gera `{componente}.ajuda.md` para modais e telas criados/modificados (`skills/adicionar-ajuda`).
|
||||
- **Pilar 3 (Wiki Usuário):** Atualiza manuais em `../../wiki/<modulo>/` se houver mudanças com impacto no usuário final.
|
||||
- **Pilar 4 (Wiki Dev):** Documenta regras técnicas (`{modulo}.regras-negocio.md`) e ADRs em `../../wiki/dev/<modulo>/`.
|
||||
- **Pilar 5 (Rota IA):** Assegura que novos schemas e rotas estejam refletidos na rota `/llm.md`.
|
||||
- **Pilar 6 (Memória IA):** Registra o relatório completo da sessão em `<base_projeto>/memorias-ia/`.
|
||||
3. **Entrega de Relatório:**
|
||||
- Apresenta um resumo claro ao operador de tudo o que foi documentado com links diretos para os arquivos gerados.
|
||||
|
||||
---
|
||||
|
||||
## 🏛️ Os 6 Pilares Canônicos
|
||||
|
||||
| Pilar | Escopo / Destino | O que é gerado/auditado |
|
||||
| :--- | :--- | :--- |
|
||||
| **1. Código-Fonte** | `.ts`, `.vue`, `.js` | JSDoc e comentários claros quanto à aplicação prática (ver `rules/jsdoc-padrao.md`). |
|
||||
| **2. Ajuda na Tela** | `*-front/.../{componente}.ajuda.md` | Ajuda contextual co-localizada: para `modalX.vue` $\rightarrow$ `modalX.ajuda.md`. |
|
||||
| **3. Wiki do Usuário** | `../../wiki/<modulo>/` | Aplicação VitePress com acesso dos usuários (manuais, tutoriais e fluxos). |
|
||||
| **4. Wiki de Desenvolvimento** | `../../wiki/dev/<modulo>/` | Aplicação VitePress com acesso interno dev: regras de negócio (`{modulo}.regras-negocio.md`), modelos de banco, arquitetura e ADRs (`adrs/`). |
|
||||
| **5. Integração de IA** | Rota Backend `/llm.md` | Catálogo de schemas Zod, enums e contratos para consumo por LLMs. |
|
||||
| **6. Memória da IA** | `<base_projeto>/memorias-ia/` | Registros de sessões, otimizações executadas e decisões históricas. |
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Comandos Específicos (Com Argumentos)
|
||||
|
||||
```bash
|
||||
# Diagnosticar lacunas no módulo
|
||||
/documentacao diagnosticar
|
||||
|
||||
# Documentar JSDoc de aplicação prática em arquivo específico
|
||||
/documentacao jsdoc <caminho/arquivo.ts>
|
||||
|
||||
# Criar ajuda contextual modalX.ajuda.md para modal/tela
|
||||
/documentacao ajuda <caminho/modalX.vue>
|
||||
|
||||
# Documentar domínio na Wiki do Usuário (VitePress)
|
||||
/documentacao wiki-usuario <modulo>
|
||||
|
||||
# Documentar regras de negócio na Wiki Dev (VitePress)
|
||||
/documentacao regras <caminho/servico.ts>
|
||||
|
||||
# Criar um ADR na Wiki Dev
|
||||
/documentacao adr "<Título da Decisão>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Regras Inegociáveis
|
||||
|
||||
1. **Nunca inventar regras:** Documentar estritamente o que foi implementado no código ou declarado na conversa.
|
||||
2. **Linguagem acessível no usuário:** Sem termos técnicos de TI na Wiki do Usuário ou em `.ajuda.md`.
|
||||
3. **JSDoc de Aplicação:** Explicar a utilidade prática no sistema, não apenas repetir tipos.
|
||||
4. **Polimorfismo:** O `.agent` é genérico; personalizações ficam em `./memorias-ia/` e `../../wiki/`.
|
||||
|
|
@ -1,15 +1,13 @@
|
|||
---
|
||||
type: workflow
|
||||
name: documentar-regras-negocio
|
||||
description: Criar ou atualizar o arquivo {modulo}.regras-negocio.md co-localizado com um módulo TypeScript e garantir consistência entre código e documentação
|
||||
description: Criar ou atualizar o arquivo {modulo}.regras-negocio.md na Wiki de Desenvolvimento (../../wiki/dev/<modulo>/) e garantir consistência com o código TypeScript.
|
||||
scope: global
|
||||
updatedAt: "2026-06-01"
|
||||
updatedAt: "2026-09-01"
|
||||
---
|
||||
|
||||
# Workflow: Documentar Regras de Negócio de um Módulo
|
||||
# Workflow / Skill: Documentar Regras de Negócio de um Módulo
|
||||
|
||||
Use este workflow com `/documentar-regras-negocio.global` para criar ou atualizar o arquivo
|
||||
`{modulo}.regras-negocio` de qualquer módulo TypeScript com lógica de negócio não-trivial.
|
||||
Use este workflow para criar ou atualizar o arquivo de regras de negócio de qualquer módulo TypeScript com lógica não-trivial, armazenado na **Wiki de Desenvolvimento** em `../../wiki/dev/<modulo>/`.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -17,20 +15,20 @@ Use este workflow com `/documentar-regras-negocio.global` para criar ou atualiza
|
|||
|
||||
Identificar e anotar:
|
||||
|
||||
- Nome do arquivo e localização exata
|
||||
- Nome do arquivo e localização exata no código
|
||||
- Funções exportadas e suas responsabilidades
|
||||
- Todos os `if` que representam critérios de decisão
|
||||
- Campos lidos e gravados (especialmente JSONB e campos de status)
|
||||
- Queries de banco: tabelas acessadas, filtros aplicados, joins
|
||||
- Caminhos alternativos (revisão manual, erros, skips)
|
||||
- Dependências externas (filas, e-mails, serviços)
|
||||
- Dependências externas (filas BullMQ, e-mails, serviços)
|
||||
|
||||
---
|
||||
|
||||
[2] Verificar se já existe um `.regras-negocio`
|
||||
[2] Verificar se já existe a documentação de regras na Wiki de Desenvolvimento
|
||||
|
||||
```bash
|
||||
ls $(dirname <arquivo>)/*.regras-negocio.md 2>/dev/null
|
||||
ls ../../wiki/dev/<modulo>/*regras-negocio*.md 2>/dev/null
|
||||
```
|
||||
|
||||
- **Existe** → ler e identificar o que está desatualizado → ir para o passo [4]
|
||||
|
|
@ -38,17 +36,17 @@ ls $(dirname <arquivo>)/*.regras-negocio.md 2>/dev/null
|
|||
|
||||
---
|
||||
|
||||
[3] Criar o arquivo `.regras-negocio`
|
||||
[3] Criar o arquivo de regras na Wiki de Desenvolvimento
|
||||
|
||||
Nomenclatura: `{nome-sem-_inicial}.regras-negocio` na mesma pasta do módulo.
|
||||
**Localização:** `../../wiki/dev/<modulo>/{nome-do-modulo}.regras-negocio.md` (ou `../../wiki/dev/<modulo>/regras-negocio/`).
|
||||
|
||||
Preencher com o template da skill `documentar-regras-negocio.global`:
|
||||
- Contexto
|
||||
Preencher com a estrutura padrão:
|
||||
- Contexto operacional
|
||||
- Critérios de Entrada
|
||||
- Regras de Processamento (numeradas)
|
||||
- Regras de Processamento (numeradas em ordem estrita)
|
||||
- Casos de Revisão Manual
|
||||
- Estratégia de Saída / Fusão de Campos
|
||||
- Dependências Externas
|
||||
- Estratégia de Saída / Persistência de Campos
|
||||
- Dependências Externas (tabelas, filas, CRONs)
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -57,30 +55,31 @@ Preencher com o template da skill `documentar-regras-negocio.global`:
|
|||
Garantir que a primeira linha útil do arquivo TypeScript seja:
|
||||
|
||||
```typescript
|
||||
// Regras de negócio: ver {modulo}.regras-negocio.md
|
||||
// Regras de negócio: ver ../../wiki/dev/<modulo>/{modulo}.regras-negocio.md
|
||||
```
|
||||
|
||||
Se já existia e está correto → sem mudança necessária.
|
||||
|
||||
---
|
||||
|
||||
[5] Simplificar JSDoc que duplicam as regras
|
||||
[5] Estruturar JSDoc com aplicação prática e referência ao `.regras-negocio.md`
|
||||
|
||||
Percorrer cada função do módulo:
|
||||
|
||||
- JSDoc com lista de regras de negócio → substituir por referência ao ``
|
||||
- Manter apenas `@param` e `@returns` com informação técnica precisa
|
||||
- Comentários inline (`//`) explicando lógica pontual são aceitos → manter
|
||||
- Inserir JSDoc explicando a aplicação prática da função no sistema (rule `rules/jsdoc-padrao.md`).
|
||||
- Referenciar o arquivo `.regras-negocio.md` para a lista detalhada de regras e critérios de decisão.
|
||||
- Manter `@param` com contexto do domínio, `@returns` e `@throws`.
|
||||
- Manter comentários inline (`//`) explicando cálculos pontuais ou regras de exceção.
|
||||
|
||||
---
|
||||
|
||||
[6] Verificar consistência — código ↔ ``
|
||||
[6] Verificar consistência — código ↔ `.regras-negocio.md`
|
||||
|
||||
Para cada regra listada no ``:
|
||||
Para cada regra listada no `.regras-negocio.md`:
|
||||
|
||||
- [ ] Existe `if` correspondente no código
|
||||
- [ ] A ordem de avaliação bate entre `` e código
|
||||
- [ ] Campos com separador de concatenação batem entre `` e código
|
||||
- [ ] A ordem de avaliação bate entre `.regras-negocio.md` e código
|
||||
- [ ] Campos com separador de concatenação batem entre documentação e código
|
||||
- [ ] `null` como neutro está implementado corretamente (`!= null`)
|
||||
- [ ] Queries têm `orderBy` quando a posição dos resultados importa
|
||||
|
||||
|
|
@ -97,9 +96,10 @@ Zero erros = concluído.
|
|||
|
||||
---
|
||||
|
||||
[8] Registrar no sistema de conhecimento (se regras novas)
|
||||
[8] Sincronizar com a Wiki de Desenvolvimento e Memórias
|
||||
|
||||
Se o workflow revelou novos padrões de negócio relevantes ao projeto:
|
||||
Se o módulo introduziu ou alterou arquitetura ou regras consolidadas do módulo:
|
||||
|
||||
- Criar ou atualizar ADR via skill `documentar-decisao-tecnica`
|
||||
- Verificar se alguma rule precisa ser atualizada
|
||||
- Atualizar a especificação técnica na **Wiki de Desenvolvimento** em `../../wiki/dev/<modulo>/`.
|
||||
- Criar ou atualizar ADR em `../../wiki/dev/<modulo>/adrs/` via skill `documentar-decisao-tecnica`.
|
||||
- Registrar decisões e ações na memória em `<base_projeto>/memorias-ia/`.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue