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
21
global/skills/doc/SKILL.md
Normal file
21
global/skills/doc/SKILL.md
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
---
|
||||
name: doc
|
||||
description: Alias rápido para /documentacao - acionar o Agente de Documentação & Memória
|
||||
scope: global
|
||||
updatedAt: "2026-09-01"
|
||||
---
|
||||
|
||||
# Skill: /doc (Alias para /documentacao)
|
||||
|
||||
Atalho rápido para o **Agente de Documentação & Memória** cobrindo os 6 pilares canônicos:
|
||||
|
||||
> ⚡ **Modo Padrão Sem Parâmetros:** Se executado apenas como `/doc`, documenta e sincroniza 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 a documentação completa e exemplos, consulte [`skills/documentacao/SKILL.md`](file:///home/luiz/Arquivos/DEV/Industria/SIGMA2026/.agent/skills/documentacao/SKILL.md).
|
||||
69
global/skills/documentacao/SKILL.md
Normal file
69
global/skills/documentacao/SKILL.md
Normal file
|
|
@ -0,0 +1,69 @@
|
|||
---
|
||||
name: documentacao
|
||||
description: Acionar o Agente de Documentação & Memória para documentar o contexto da conversa ou gerar artefatos nos 6 pilares canônicos
|
||||
scope: global
|
||||
updatedAt: "2026-09-01"
|
||||
---
|
||||
|
||||
# Skill / Workflow: /documentacao
|
||||
|
||||
Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualizar ou auditar a documentação nos **6 pilares canônicos** do Documentation-Driven Development (DDD).
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Modo Contextual Padrão (Sem Argumentos)
|
||||
|
||||
> **Ao executar `/documentacao` (ou `/doc`) sem nenhum parâmetro**, o agente analisa automaticamente todo o histórico do chat, decisões tomadas e arquivos alterados na sessão, gerando e sincronizando a documentação nos pilares afetados:
|
||||
|
||||
1. **Pilar 1 (Código-Fonte):** Insere comentários JSDoc de aplicação prática nos arquivos alterados (`rules/jsdoc-padrao.md`).
|
||||
2. **Pilar 2 (Ajuda UI):** Gera `{componente}.ajuda.md` para modais e telas criados/modificados (`skills/adicionar-ajuda`).
|
||||
3. **Pilar 3 (Wiki do Usuário):** Atualiza tutoriais e manuais em `../../wiki/<modulo>/` (aplicação VitePress com acesso dos usuários).
|
||||
4. **Pilar 4 (Wiki de Desenvolvimento):** Documenta regras de negócio (`{modulo}.regras-negocio.md`), modelos e ADRs em `../../wiki/dev/<modulo>/` (aplicação VitePress com acesso interno dev).
|
||||
5. **Pilar 5 (Rota IA):** Assegura que novos schemas e rotas estejam refletidos na rota `/llm.md`.
|
||||
6. **Pilar 6 (Memória IA):** Registra o relatório completo da sessão em `<base_projeto>/memorias-ia/`.
|
||||
|
||||
---
|
||||
|
||||
## 🏛️ Os 6 Pilares Canônicos
|
||||
|
||||
| Pilar | Destino / Padrão | Público | Conteúdo Obrigatório |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **1. Código-Fonte** | `.ts`, `.vue`, `.js` | Desenvolvedores / IA | JSDoc e comentários claros quanto à aplicação prática e contexto de negócio. |
|
||||
| **2. Ajuda na Tela** | `*-front/.../{componente}.ajuda.md` | Usuários da UI | Ajuda contextual co-localizada: para `modalX.vue` $\rightarrow$ `modalX.ajuda.md`. |
|
||||
| **3. Wiki do Usuário** | `../../wiki/<modulo>/` | Usuários / Clientes | Aplicação VitePress com acesso dos usuários (manuais, tutoriais e fluxos). |
|
||||
| **4. Wiki de Desenvolvimento** | `../../wiki/dev/<modulo>/` | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno dev: regras de negócio (`{modulo}.regras-negocio.md`), arquitetura e ADRs (`adrs/`). |
|
||||
| **5. Integração de IA** | Rota Backend `/llm.md` | Agentes de IA / LLMs | Catálogo de schemas Zod, enums e contratos para consumo por LLMs. |
|
||||
| **6. Memória da IA** | `<base_projeto>/memorias-ia/` | Agentes de IA / Auditoria | 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,9 +1,9 @@
|
|||
---
|
||||
name: documentar-decisao-tecnica
|
||||
scope: global
|
||||
updatedAt: "2026-06-01"
|
||||
updatedAt: "2026-09-01"
|
||||
description: >
|
||||
Guia operacional para registrar decisões técnicas e arquiteturais como ADRs (Architecture Decision Records).
|
||||
Guia operacional para registrar decisões técnicas e arquiteturais como ADRs (Architecture Decision Records) na Wiki de Desenvolvimento (../../wiki/dev/<modulo>/adrs/).
|
||||
---
|
||||
|
||||
# Skill: Documentar Decisão Técnica (ADR)
|
||||
|
|
@ -17,23 +17,23 @@ O objetivo é garantir que **nenhuma decisão fique apenas na cabeça** ou perdi
|
|||
## Quando usar
|
||||
|
||||
- Nova dependência adicionada ao monorepo
|
||||
- Mudança de padrão arquitetural (ex: de REST para GraphQL)
|
||||
- Escolha de ferramenta ou lib entre alternativas
|
||||
- Decisão de breaking change
|
||||
- Migração de tecnologia
|
||||
- Mudança de padrão arquitetural (ex: de REST para GraphQL, uso de BullMQ, schemas Zod)
|
||||
- Escolha de ferramenta ou biblioteca entre alternativas
|
||||
- Decisão de breaking change de contrato
|
||||
- Migração de tecnologia ou banco de dados
|
||||
- Mudança de estratégia de deploy ou CI/CD
|
||||
- Qualquer decisão que alguém pode questionar daqui 3 meses
|
||||
- Qualquer decisão técnica relevante para o time ou para a IA
|
||||
|
||||
---
|
||||
|
||||
## PASSO 1 — Criar o Diretório de ADRs (se não existir)
|
||||
## PASSO 1 — Localizar o Diretório de ADRs
|
||||
|
||||
Convenção de diretório: `../../wiki/dev/<modulo>/adrs/` (na Wiki de Desenvolvimento) ou `.agent/DOCUMENTACAO/arquitetura/`.
|
||||
|
||||
```bash
|
||||
mkdir -p .docs/adrs
|
||||
mkdir -p ../../wiki/dev/<modulo>/adrs
|
||||
```
|
||||
|
||||
Convenção de diretório: `.docs/adrs/` na raiz do monorepo.
|
||||
|
||||
---
|
||||
|
||||
## PASSO 2 — Criar o Arquivo ADR
|
||||
|
|
@ -110,10 +110,10 @@ Após criar o ADR, avaliar se a decisão deve gerar:
|
|||
|
||||
| A decisão... | Ação |
|
||||
|-------------|------|
|
||||
| Cria uma **restrição** permanente (ex: "nunca usar lib X") | Criar/atualizar uma **Rule** em `.agent/local/rules/` |
|
||||
| Define um **processo** repetível (ex: "para migrar, faça X, Y, Z") | Criar/atualizar um **Workflow** em `.agent/local/workflows/` |
|
||||
| Refina um **padrão operacional** (ex: "queries agora usam pool separado") | Atualizar a **Skill** correspondente em `.agent/local/skills/` |
|
||||
| Não gera artefato adicional | Apenas o ADR é suficiente |
|
||||
| Cria uma **restrição** permanente (ex: "nunca usar lib X") | Criar/atualizar uma **Rule** em `.agent/rules/` |
|
||||
| Define um **processo** repetível (ex: "para migrar, faça X, Y, Z") | Criar/atualizar um **Workflow** em `.agent/workflows/` |
|
||||
| Refina um **padrão operacional** (ex: "queries agora usam pool separado") | Atualizar a **Skill** correspondente em `.agent/skills/` |
|
||||
| Registra histórico de ação da IA | Gravar na memória em `<base_projeto>/memorias-ia/` |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -152,10 +152,14 @@ Antes de considerar completo:
|
|||
- [ ] As consequências (positivas e negativas) estão claras?
|
||||
- [ ] Os pacotes impactados estão listados?
|
||||
- [ ] O status está definido (proposto/aceito)?
|
||||
- [ ] A decisão gerou rules/workflows/skills quando aplicável?
|
||||
- [ ] O ADR foi salvo em `../../wiki/dev/<modulo>/adrs/` ou `.agent/DOCUMENTACAO/arquitetura/`?
|
||||
- [ ] A decisão foi registrada na memória em `<base_projeto>/memorias-ia/`?
|
||||
- [ ] Alguém de fora do contexto entenderia este ADR?
|
||||
|
||||
---
|
||||
|
||||
## Referências
|
||||
|
||||
- Workflow: `global/workflows/aprimorar-IA` (seção de classificação de artefatos)
|
||||
- Workflow: `global/workflows/otimizar-codigos`
|
||||
- Rule: `rules/ddd-documentacao-primeiro.md`
|
||||
- Workflow: `global/workflows/aprimora-ia.md`
|
||||
- Wiki de Desenvolvimento: `../../wiki/dev/<modulo>/adrs/`
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
---
|
||||
name: documentar-decisao-tecnica
|
||||
scope: global
|
||||
updatedAt: "2026-06-01"
|
||||
updatedAt: "2026-09-01"
|
||||
description: >
|
||||
Guia operacional para registrar decisões técnicas e arquiteturais como ADRs (Architecture Decision Records).
|
||||
Guia operacional para registrar decisões técnicas e arquiteturais como ADRs (Architecture Decision Records) na Wiki de Desenvolvimento (../../wiki/dev/<modulo>/adrs/).
|
||||
---
|
||||
|
||||
# Skill: Documentar Decisão Técnica (ADR)
|
||||
|
|
@ -17,23 +17,23 @@ O objetivo é garantir que **nenhuma decisão fique apenas na cabeça** ou perdi
|
|||
## Quando usar
|
||||
|
||||
- Nova dependência adicionada ao monorepo
|
||||
- Mudança de padrão arquitetural (ex: de REST para GraphQL)
|
||||
- Escolha de ferramenta ou lib entre alternativas
|
||||
- Decisão de breaking change
|
||||
- Migração de tecnologia
|
||||
- Mudança de padrão arquitetural (ex: de REST para GraphQL, uso de BullMQ, schemas Zod)
|
||||
- Escolha de ferramenta ou biblioteca entre alternativas
|
||||
- Decisão de breaking change de contrato
|
||||
- Migração de tecnologia ou banco de dados
|
||||
- Mudança de estratégia de deploy ou CI/CD
|
||||
- Qualquer decisão que alguém pode questionar daqui 3 meses
|
||||
- Qualquer decisão técnica relevante para o time ou para a IA
|
||||
|
||||
---
|
||||
|
||||
## PASSO 1 — Criar o Diretório de ADRs (se não existir)
|
||||
## PASSO 1 — Localizar o Diretório de ADRs
|
||||
|
||||
Convenção de diretório: `../../wiki/dev/<modulo>/adrs/` (na Wiki de Desenvolvimento) ou `.agent/DOCUMENTACAO/arquitetura/`.
|
||||
|
||||
```bash
|
||||
mkdir -p .docs/adrs
|
||||
mkdir -p ../../wiki/dev/<modulo>/adrs
|
||||
```
|
||||
|
||||
Convenção de diretório: `.docs/adrs/` na raiz do monorepo.
|
||||
|
||||
---
|
||||
|
||||
## PASSO 2 — Criar o Arquivo ADR
|
||||
|
|
@ -110,10 +110,10 @@ Após criar o ADR, avaliar se a decisão deve gerar:
|
|||
|
||||
| A decisão... | Ação |
|
||||
|-------------|------|
|
||||
| Cria uma **restrição** permanente (ex: "nunca usar lib X") | Criar/atualizar uma **Rule** em `.agent/local/rules/` |
|
||||
| Define um **processo** repetível (ex: "para migrar, faça X, Y, Z") | Criar/atualizar um **Workflow** em `.agent/local/workflows/` |
|
||||
| Refina um **padrão operacional** (ex: "queries agora usam pool separado") | Atualizar a **Skill** correspondente em `.agent/local/skills/` |
|
||||
| Não gera artefato adicional | Apenas o ADR é suficiente |
|
||||
| Cria uma **restrição** permanente (ex: "nunca usar lib X") | Criar/atualizar uma **Rule** em `.agent/rules/` |
|
||||
| Define um **processo** repetível (ex: "para migrar, faça X, Y, Z") | Criar/atualizar um **Workflow** em `.agent/workflows/` |
|
||||
| Refina um **padrão operacional** (ex: "queries agora usam pool separado") | Atualizar a **Skill** correspondente em `.agent/skills/` |
|
||||
| Registra histórico de ação da IA | Gravar na memória em `<base_projeto>/memorias-ia/` |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -152,10 +152,14 @@ Antes de considerar completo:
|
|||
- [ ] As consequências (positivas e negativas) estão claras?
|
||||
- [ ] Os pacotes impactados estão listados?
|
||||
- [ ] O status está definido (proposto/aceito)?
|
||||
- [ ] A decisão gerou rules/workflows/skills quando aplicável?
|
||||
- [ ] O ADR foi salvo em `../../wiki/dev/<modulo>/adrs/` ou `.agent/DOCUMENTACAO/arquitetura/`?
|
||||
- [ ] A decisão foi registrada na memória em `<base_projeto>/memorias-ia/`?
|
||||
- [ ] Alguém de fora do contexto entenderia este ADR?
|
||||
|
||||
---
|
||||
|
||||
## Referências
|
||||
|
||||
- Workflow: `global/workflows/aprimorar-IA` (seção de classificação de artefatos)
|
||||
- Workflow: `global/workflows/otimizar-codigos`
|
||||
- Rule: `rules/ddd-documentacao-primeiro.md`
|
||||
- Workflow: `global/workflows/aprimora-ia.md`
|
||||
- Wiki de Desenvolvimento: `../../wiki/dev/<modulo>/adrs/`
|
||||
|
|
|
|||
|
|
@ -1,18 +1,19 @@
|
|||
---
|
||||
name: documentar-dominio-modulo
|
||||
scope: global
|
||||
updatedAt: "2026-06-01"
|
||||
updatedAt: "2026-09-01"
|
||||
description: >
|
||||
Guia para documentar o domínio científico/técnico de cada módulo SaaS,
|
||||
garantindo que o agente compreenda a terminologia e as regras do domínio
|
||||
ao gerar código, texto e interface.
|
||||
Guia para documentar o domínio científico/técnico de cada módulo nas wikis
|
||||
de usuário (../../wiki/<modulo>/) e de desenvolvimento (../../wiki/dev/<modulo>/).
|
||||
---
|
||||
|
||||
# Skill: Documentar Domínio de um Módulo
|
||||
|
||||
Use esta skill ao iniciar um novo módulo SaaS ou ao perceber que o agente não conhece o vocabulário e as regras do domínio que o módulo aborda.
|
||||
|
||||
Cada módulo opera em uma disciplina diferente da ciência/gestão ambiental (licenciamento, gases de efeito estufa, resíduos, projetos, etc.). O agente precisa de uma **base factual do domínio** para gerar labels, mensagens, regras de negócio e textos comerciais corretos.
|
||||
Cada módulo opera em uma disciplina diferente da ciência/gestão ambiental (licenciamento, efluentes, bombeamento, resíduos, projetos, etc.). O repositório `../../wiki` é uma **aplicação VitePress**, onde a base factual do domínio é estruturada em dois níveis de acesso:
|
||||
1. **Wiki do Usuário (`../../wiki/<modulo>/`):** Aplicação VitePress com **acesso dos usuários e clientes** (linguagem funcional, conceitos, glossário, fluxos e manuais operacionais).
|
||||
2. **Wiki de Desenvolvimento (`../../wiki/dev/<modulo>/`):** Aplicação VitePress com **acesso interno exclusivo da equipe de desenvolvimento e arquitetura** (arquitetura técnica, diagramas, modelos de banco, regras de negócio e ADRs).
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -20,112 +21,82 @@ Cada módulo opera em uma disciplina diferente da ciência/gestão ambiental (li
|
|||
|
||||
Determinar qual área da ciência/gestão o módulo aborda:
|
||||
|
||||
| Exemplo de módulo | Domínio |
|
||||
|---|---|
|
||||
| Licenciamento | Licenciamento ambiental (LP, LI, LO, condicionantes) |
|
||||
| GEE | Gases de Efeito Estufa (inventário, emissões, fatores) |
|
||||
| Resíduos | Gestão de resíduos sólidos (PGRS, MTR, classificação) |
|
||||
| Outorga | Outorga de uso de recursos hídricos |
|
||||
| Flora/Fauna | Monitoramento de biodiversidade |
|
||||
| Projetos | Gestão de projetos ambientais e consultorias |
|
||||
| Exemplo de módulo | Domínio | Destino Usuário | Destino Dev |
|
||||
|---|---|---|---|
|
||||
| SIGMA | Monitoramento ambiental (efluentes, piezometria, bombeamento) | `../../wiki/e-licencie.sigma/` | `../../wiki/dev/e-licencie.sigma/` |
|
||||
| Licenciamento | Gestão de licenças (LP, LI, LO, condicionantes) | `../../wiki/e-licencie/` | `../../wiki/dev/e-licencie/` |
|
||||
| Resíduos | Gestão de resíduos sólidos (PGRS, MTR, MTR-e) | `../../wiki/e-licencie.residuos/` | `../../wiki/dev/e-licencie.residuos/` |
|
||||
| Qualificação | Qualificação e conformidade de fornecedores | `../../wiki/e-licencie.qualifica/` | `../../wiki/dev/e-licencie.qualifica/` |
|
||||
|
||||
---
|
||||
|
||||
## PASSO 2 — Criar o Arquivo de Domínio
|
||||
## PASSO 2 — Criar Documentação na Wiki do Usuário (`../../wiki/<modulo>/`)
|
||||
|
||||
Criar documento no arquivo `.regras-negocio.md` do módulo:
|
||||
Estruturar o guia do usuário e conceitos de negócio em linguagem clara e acessível:
|
||||
|
||||
```markdown
|
||||
# Domínio: <Nome do Módulo>
|
||||
# [Nome do Módulo] — Guia do Usuário
|
||||
|
||||
## Área de Conhecimento
|
||||
Breve descrição da disciplina (1-3 linhas).
|
||||
|
||||
## Glossário do Módulo
|
||||
## Visão Geral
|
||||
Breve descrição do propósito do módulo para o gestor e operador.
|
||||
|
||||
## Glossário do Domínio
|
||||
| Termo | Definição | Sigla |
|
||||
|---|---|---|
|
||||
| Licença Prévia | Autorização para planejamento do empreendimento | LP |
|
||||
| Licença de Instalação | Autorização para início das obras | LI |
|
||||
| ... | ... | ... |
|
||||
| Ponto de Monitoramento | Local físico onde são coletadas amostras | PM |
|
||||
| Parâmetro Ambiental | Variável físico-química monitorada (ex: DBO, DQO) | — |
|
||||
|
||||
## Entidades Principais
|
||||
|
||||
Lista das entidades de negócio do módulo com descrição e relações:
|
||||
|
||||
- **Empreendimento**: unidade física onde ocorre a atividade potencialmente poluidora
|
||||
- **Licença**: autorização ambiental vinculada a um empreendimento
|
||||
- **Condicionante**: obrigação imposta pelo órgão ambiental na licença
|
||||
- ...
|
||||
|
||||
## Legislação Aplicável
|
||||
|
||||
| Norma | Descrição | Relevância |
|
||||
|---|---|---|
|
||||
| Lei 6.938/1981 | Política Nacional do Meio Ambiente | Base legal do licenciamento |
|
||||
| Resolução CONAMA 237/1997 | Regulamenta o licenciamento ambiental | Tipos de licença, prazos |
|
||||
| ... | ... | ... |
|
||||
|
||||
## Regras de citação legal
|
||||
- Formato: "Resolução CONAMA nº 237/1997, art. 8º, inciso I"
|
||||
- Toda sigla na primeira ocorrência com nome por extenso
|
||||
- Legislação federal > estadual > municipal (hierarquia)
|
||||
|
||||
## Fluxos do Domínio
|
||||
|
||||
Descrever os processos-chave que o módulo implementa:
|
||||
|
||||
1. Solicitação de licença → Análise técnica → Emissão → Monitoramento
|
||||
2. Cadastro de condicionante → Acompanhamento de prazo → Cumprimento
|
||||
|
||||
## Vocabulário de Interface
|
||||
|
||||
Termos que devem ser usados em labels, botões e mensagens:
|
||||
|
||||
| Contexto | ❌ Genérico | ✅ Correto para o módulo |
|
||||
|---|---|---|
|
||||
| Campo de nome | "Nome" | "Razão Social do Empreendedor" |
|
||||
| Status | "Ativo/Inativo" | "Vigente/Vencida/Suspensa" |
|
||||
| Ação principal | "Criar novo" | "Solicitar nova licença" |
|
||||
| Lista vazia | "Nenhum registro" | "Nenhuma licença cadastrada" |
|
||||
## Fluxos Operacionais do Usuário
|
||||
1. Cadastro de pontos de monitoramento.
|
||||
2. Lançamento e importação de medições.
|
||||
3. Emissão de relatórios e acompanhamento de conformidade.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PASSO 3 — Validar com o Operador
|
||||
## PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (`../../wiki/dev/<modulo>/`)
|
||||
|
||||
Antes de consolidar:
|
||||
Estruturar a especificação técnica, modelos de banco e arquitetura:
|
||||
|
||||
- [ ] Os termos do glossário estão corretos para o contexto do módulo?
|
||||
- [ ] As entidades cobrem os conceitos centrais?
|
||||
- [ ] A legislação listada é a principal (não exaustiva)?
|
||||
- [ ] O vocabulário de interface reflete como o usuário fala no dia a dia?
|
||||
```markdown
|
||||
# [Nome do Módulo] — Arquitetura e Engenharia
|
||||
|
||||
## Modelo de Dados e Entidades
|
||||
- **Tabelas principais:** `sigma_pontos`, `sigma_medicoes`, `sigma_parametros`
|
||||
- **Schemas Zod canônicos:** `zPontoCriar`, `zMedicaoRegistrar` em `*-comuns`
|
||||
|
||||
## Processamento Assíncrono e Filas (BullMQ)
|
||||
- **Fila `calcular_agenda`:** Recalcula status e prazos de monitoramento.
|
||||
|
||||
## Rotas e Integração de IA
|
||||
- **Rota `/llm.md`:** Disponibiliza catálogo dinâmico de endpoints e contratos.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PASSO 4 — Conectar com as Rules
|
||||
## PASSO 4 — Conectar com Código e UI
|
||||
|
||||
Após documentar o domínio:
|
||||
|
||||
1. Verificar se labels e mensagens no código usam o vocabulário definido (rule `mensagens-usuario`)
|
||||
2. Verificar se schemas Zod têm mensagens de erro no idioma do domínio (rule `zod-validacao-padrao`)
|
||||
3. Verificar se os arquivos `.ajuda.md` usam termos do glossário (workflow `adicionar-ajuda.md`)
|
||||
4. Verificar se textos comerciais citam a legislação corretamente (workflow `comercial`)
|
||||
1. Verificar se mensagens e labels na UI seguem o vocabulário definido (rule `mensagens-usuario`).
|
||||
2. Verificar se componentes e modais Vue possuem `modalX.ajuda.md` co-localizado (skill `adicionar-ajuda`).
|
||||
3. Garantir que funções centrais e serviços possuem comentários claros de aplicação (rule `jsdoc-padrao`).
|
||||
4. Assegurar que regras com 3+ critérios possuam `.regras-negocio.md` co-localizado (rule `regras-negocio-md`).
|
||||
|
||||
---
|
||||
|
||||
## Checklist Final
|
||||
|
||||
- [ ] Arquivo `.regras-negocio.md` do módulo criado e validado?
|
||||
- [ ] Glossário com pelo menos os 10 termos centrais do módulo?
|
||||
- [ ] Entidades principais listadas com descrição?
|
||||
- [ ] Legislação base documentada com formato de citação?
|
||||
- [ ] Vocabulário de interface definido (labels, status, ações, empty states)?
|
||||
- [ ] Operador validou a terminologia?
|
||||
- [ ] Documentação de usuário criada/atualizada em `../../wiki/<modulo>/`?
|
||||
- [ ] Documentação técnica criada/atualizada em `../../wiki/dev/<modulo>/`?
|
||||
- [ ] Glossário com os termos centrais do domínio documentado?
|
||||
- [ ] Regras e entidades técnicas alinhadas com os schemas Zod do `*-comuns`?
|
||||
- [ ] Rota `/llm.md` no backend reflete o módulo?
|
||||
|
||||
---
|
||||
|
||||
## Referências
|
||||
|
||||
- Rule: `global/rules/mensagens-usuario`
|
||||
- Rule: `global/rules/regras-negocio-md`
|
||||
- Workflow: `agents/comercial/workflows/comercial`
|
||||
- Workflow: `agents/front/workflows/adicionar-ajuda`
|
||||
- Rule: `rules/ddd-documentacao-primeiro.md`
|
||||
- Rule: `rules/jsdoc-padrao.md`
|
||||
- Rule: `rules/regras-negocio-md.md`
|
||||
- Skill: `skills/adicionar-ajuda/SKILL.md`
|
||||
|
||||
|
|
|
|||
|
|
@ -1,18 +1,19 @@
|
|||
---
|
||||
name: documentar-dominio-modulo
|
||||
scope: global
|
||||
updatedAt: "2026-06-01"
|
||||
updatedAt: "2026-09-01"
|
||||
description: >
|
||||
Guia para documentar o domínio científico/técnico de cada módulo SaaS,
|
||||
garantindo que o agente compreenda a terminologia e as regras do domínio
|
||||
ao gerar código, texto e interface.
|
||||
Guia para documentar o domínio científico/técnico de cada módulo nas wikis
|
||||
de usuário (../../wiki/<modulo>/) e de desenvolvimento (../../wiki/dev/<modulo>/).
|
||||
---
|
||||
|
||||
# Skill: Documentar Domínio de um Módulo
|
||||
|
||||
Use esta skill ao iniciar um novo módulo SaaS ou ao perceber que o agente não conhece o vocabulário e as regras do domínio que o módulo aborda.
|
||||
|
||||
Cada módulo opera em uma disciplina diferente da ciência/gestão ambiental (licenciamento, gases de efeito estufa, resíduos, projetos, etc.). O agente precisa de uma **base factual do domínio** para gerar labels, mensagens, regras de negócio e textos comerciais corretos.
|
||||
Cada módulo opera em uma disciplina diferente da ciência/gestão ambiental (licenciamento, efluentes, bombeamento, resíduos, projetos, etc.). O repositório `../../wiki` é uma **aplicação VitePress**, onde a base factual do domínio é estruturada em dois níveis de acesso:
|
||||
1. **Wiki do Usuário (`../../wiki/<modulo>/`):** Aplicação VitePress com **acesso dos usuários e clientes** (linguagem funcional, conceitos, glossário, fluxos e manuais operacionais).
|
||||
2. **Wiki de Desenvolvimento (`../../wiki/dev/<modulo>/`):** Aplicação VitePress com **acesso interno exclusivo da equipe de desenvolvimento e arquitetura** (arquitetura técnica, diagramas, modelos de banco, regras de negócio e ADRs).
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -20,112 +21,82 @@ Cada módulo opera em uma disciplina diferente da ciência/gestão ambiental (li
|
|||
|
||||
Determinar qual área da ciência/gestão o módulo aborda:
|
||||
|
||||
| Exemplo de módulo | Domínio |
|
||||
|---|---|
|
||||
| Licenciamento | Licenciamento ambiental (LP, LI, LO, condicionantes) |
|
||||
| GEE | Gases de Efeito Estufa (inventário, emissões, fatores) |
|
||||
| Resíduos | Gestão de resíduos sólidos (PGRS, MTR, classificação) |
|
||||
| Outorga | Outorga de uso de recursos hídricos |
|
||||
| Flora/Fauna | Monitoramento de biodiversidade |
|
||||
| Projetos | Gestão de projetos ambientais e consultorias |
|
||||
| Exemplo de módulo | Domínio | Destino Usuário | Destino Dev |
|
||||
|---|---|---|---|
|
||||
| SIGMA | Monitoramento ambiental (efluentes, piezometria, bombeamento) | `../../wiki/e-licencie.sigma/` | `../../wiki/dev/e-licencie.sigma/` |
|
||||
| Licenciamento | Gestão de licenças (LP, LI, LO, condicionantes) | `../../wiki/e-licencie/` | `../../wiki/dev/e-licencie/` |
|
||||
| Resíduos | Gestão de resíduos sólidos (PGRS, MTR, MTR-e) | `../../wiki/e-licencie.residuos/` | `../../wiki/dev/e-licencie.residuos/` |
|
||||
| Qualificação | Qualificação e conformidade de fornecedores | `../../wiki/e-licencie.qualifica/` | `../../wiki/dev/e-licencie.qualifica/` |
|
||||
|
||||
---
|
||||
|
||||
## PASSO 2 — Criar o Arquivo de Domínio
|
||||
## PASSO 2 — Criar Documentação na Wiki do Usuário (`../../wiki/<modulo>/`)
|
||||
|
||||
Criar documento no arquivo `.regras-negocio.md` do módulo:
|
||||
Estruturar o guia do usuário e conceitos de negócio em linguagem clara e acessível:
|
||||
|
||||
```markdown
|
||||
# Domínio: <Nome do Módulo>
|
||||
# [Nome do Módulo] — Guia do Usuário
|
||||
|
||||
## Área de Conhecimento
|
||||
Breve descrição da disciplina (1-3 linhas).
|
||||
|
||||
## Glossário do Módulo
|
||||
## Visão Geral
|
||||
Breve descrição do propósito do módulo para o gestor e operador.
|
||||
|
||||
## Glossário do Domínio
|
||||
| Termo | Definição | Sigla |
|
||||
|---|---|---|
|
||||
| Licença Prévia | Autorização para planejamento do empreendimento | LP |
|
||||
| Licença de Instalação | Autorização para início das obras | LI |
|
||||
| ... | ... | ... |
|
||||
| Ponto de Monitoramento | Local físico onde são coletadas amostras | PM |
|
||||
| Parâmetro Ambiental | Variável físico-química monitorada (ex: DBO, DQO) | — |
|
||||
|
||||
## Entidades Principais
|
||||
|
||||
Lista das entidades de negócio do módulo com descrição e relações:
|
||||
|
||||
- **Empreendimento**: unidade física onde ocorre a atividade potencialmente poluidora
|
||||
- **Licença**: autorização ambiental vinculada a um empreendimento
|
||||
- **Condicionante**: obrigação imposta pelo órgão ambiental na licença
|
||||
- ...
|
||||
|
||||
## Legislação Aplicável
|
||||
|
||||
| Norma | Descrição | Relevância |
|
||||
|---|---|---|
|
||||
| Lei 6.938/1981 | Política Nacional do Meio Ambiente | Base legal do licenciamento |
|
||||
| Resolução CONAMA 237/1997 | Regulamenta o licenciamento ambiental | Tipos de licença, prazos |
|
||||
| ... | ... | ... |
|
||||
|
||||
## Regras de citação legal
|
||||
- Formato: "Resolução CONAMA nº 237/1997, art. 8º, inciso I"
|
||||
- Toda sigla na primeira ocorrência com nome por extenso
|
||||
- Legislação federal > estadual > municipal (hierarquia)
|
||||
|
||||
## Fluxos do Domínio
|
||||
|
||||
Descrever os processos-chave que o módulo implementa:
|
||||
|
||||
1. Solicitação de licença → Análise técnica → Emissão → Monitoramento
|
||||
2. Cadastro de condicionante → Acompanhamento de prazo → Cumprimento
|
||||
|
||||
## Vocabulário de Interface
|
||||
|
||||
Termos que devem ser usados em labels, botões e mensagens:
|
||||
|
||||
| Contexto | ❌ Genérico | ✅ Correto para o módulo |
|
||||
|---|---|---|
|
||||
| Campo de nome | "Nome" | "Razão Social do Empreendedor" |
|
||||
| Status | "Ativo/Inativo" | "Vigente/Vencida/Suspensa" |
|
||||
| Ação principal | "Criar novo" | "Solicitar nova licença" |
|
||||
| Lista vazia | "Nenhum registro" | "Nenhuma licença cadastrada" |
|
||||
## Fluxos Operacionais do Usuário
|
||||
1. Cadastro de pontos de monitoramento.
|
||||
2. Lançamento e importação de medições.
|
||||
3. Emissão de relatórios e acompanhamento de conformidade.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PASSO 3 — Validar com o Operador
|
||||
## PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (`../../wiki/dev/<modulo>/`)
|
||||
|
||||
Antes de consolidar:
|
||||
Estruturar a especificação técnica, modelos de banco e arquitetura:
|
||||
|
||||
- [ ] Os termos do glossário estão corretos para o contexto do módulo?
|
||||
- [ ] As entidades cobrem os conceitos centrais?
|
||||
- [ ] A legislação listada é a principal (não exaustiva)?
|
||||
- [ ] O vocabulário de interface reflete como o usuário fala no dia a dia?
|
||||
```markdown
|
||||
# [Nome do Módulo] — Arquitetura e Engenharia
|
||||
|
||||
## Modelo de Dados e Entidades
|
||||
- **Tabelas principais:** `sigma_pontos`, `sigma_medicoes`, `sigma_parametros`
|
||||
- **Schemas Zod canônicos:** `zPontoCriar`, `zMedicaoRegistrar` em `*-comuns`
|
||||
|
||||
## Processamento Assíncrono e Filas (BullMQ)
|
||||
- **Fila `calcular_agenda`:** Recalcula status e prazos de monitoramento.
|
||||
|
||||
## Rotas e Integração de IA
|
||||
- **Rota `/llm.md`:** Disponibiliza catálogo dinâmico de endpoints e contratos.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PASSO 4 — Conectar com as Rules
|
||||
## PASSO 4 — Conectar com Código e UI
|
||||
|
||||
Após documentar o domínio:
|
||||
|
||||
1. Verificar se labels e mensagens no código usam o vocabulário definido (rule `mensagens-usuario`)
|
||||
2. Verificar se schemas Zod têm mensagens de erro no idioma do domínio (rule `zod-validacao-padrao`)
|
||||
3. Verificar se os arquivos `.ajuda.md` usam termos do glossário (workflow `adicionar-ajuda.md`)
|
||||
4. Verificar se textos comerciais citam a legislação corretamente (workflow `comercial`)
|
||||
1. Verificar se mensagens e labels na UI seguem o vocabulário definido (rule `mensagens-usuario`).
|
||||
2. Verificar se componentes e modais Vue possuem `modalX.ajuda.md` co-localizado (skill `adicionar-ajuda`).
|
||||
3. Garantir que funções centrais e serviços possuem comentários claros de aplicação (rule `jsdoc-padrao`).
|
||||
4. Assegurar que regras com 3+ critérios possuam `.regras-negocio.md` co-localizado (rule `regras-negocio-md`).
|
||||
|
||||
---
|
||||
|
||||
## Checklist Final
|
||||
|
||||
- [ ] Arquivo `.regras-negocio.md` do módulo criado e validado?
|
||||
- [ ] Glossário com pelo menos os 10 termos centrais do módulo?
|
||||
- [ ] Entidades principais listadas com descrição?
|
||||
- [ ] Legislação base documentada com formato de citação?
|
||||
- [ ] Vocabulário de interface definido (labels, status, ações, empty states)?
|
||||
- [ ] Operador validou a terminologia?
|
||||
- [ ] Documentação de usuário criada/atualizada em `../../wiki/<modulo>/`?
|
||||
- [ ] Documentação técnica criada/atualizada em `../../wiki/dev/<modulo>/`?
|
||||
- [ ] Glossário com os termos centrais do domínio documentado?
|
||||
- [ ] Regras e entidades técnicas alinhadas com os schemas Zod do `*-comuns`?
|
||||
- [ ] Rota `/llm.md` no backend reflete o módulo?
|
||||
|
||||
---
|
||||
|
||||
## Referências
|
||||
|
||||
- Rule: `global/rules/mensagens-usuario`
|
||||
- Rule: `global/rules/regras-negocio-md`
|
||||
- Workflow: `agents/comercial/workflows/comercial`
|
||||
- Workflow: `agents/front/workflows/adicionar-ajuda`
|
||||
- Rule: `rules/ddd-documentacao-primeiro.md`
|
||||
- Rule: `rules/jsdoc-padrao.md`
|
||||
- Rule: `rules/regras-negocio-md.md`
|
||||
- Skill: `skills/adicionar-ajuda/SKILL.md`
|
||||
|
||||
|
|
|
|||
|
|
@ -1,212 +1,105 @@
|
|||
---
|
||||
name: documentar-regras-negocio
|
||||
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"
|
||||
description: >
|
||||
Guia operacional para criar, preencher e manter arquivos {modulo}.regras-negocio.md
|
||||
co-localizados com módulos TypeScript de lógica de negócio complexa.
|
||||
updatedAt: "2026-09-01"
|
||||
---
|
||||
|
||||
# Skill: Documentar Regras de Negócio em Módulos
|
||||
# Workflow / Skill: Documentar Regras de Negócio de um Módulo
|
||||
|
||||
Use esta skill sempre que um módulo TypeScript contiver lógica de decisão não-trivial
|
||||
que precise ser rastreável por produto, suporte e desenvolvimento sem exigir leitura de código.
|
||||
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>/`.
|
||||
|
||||
---
|
||||
|
||||
## Quando usar esta skill
|
||||
[1] Ler o módulo TypeScript completamente
|
||||
|
||||
- Módulo com 3+ critérios de decisão distintos
|
||||
- Lógica de eleição/priorização entre registros
|
||||
- Processamento que pode resultar em revisão manual
|
||||
- Worker/CRON consumindo dados com estratégias diferenciadas por tipo
|
||||
- Importador automático com regras de aceite/rejeição
|
||||
Identificar e anotar:
|
||||
|
||||
- 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 BullMQ, e-mails, serviços)
|
||||
|
||||
---
|
||||
|
||||
## PASSO 1 — Identificar o escopo das regras
|
||||
[2] Verificar se já existe a documentação de regras na Wiki de Desenvolvimento
|
||||
|
||||
Antes de escrever o `.md`, percorrer o módulo e identificar:
|
||||
|
||||
| Categoria | O que procurar |
|
||||
|---|---|
|
||||
| **Critérios de entrada** | Filtros de query (excluido, vencimento, etc.) |
|
||||
| **Critérios de bloqueio** | Condições que bloqueiam o fluxo automático |
|
||||
| **Estratégia por tipo de dado** | Concatenação vs. primeiro-não-nulo vs. outros |
|
||||
| **Eleição de principal** | Regras de prioridade entre registros |
|
||||
| **Estado contraditório** | Combinações de campos mutuamente exclusivas |
|
||||
| **Dependências externas** | Tabelas, filas, serviços tocados |
|
||||
|
||||
---
|
||||
|
||||
## PASSO 2 — Criar o arquivo
|
||||
|
||||
Nomenclatura: `{nome-do-modulo-sem-underline-inicial}.regras-negocio.md`
|
||||
|
||||
Localizar **na mesma pasta** do arquivo TypeScript:
|
||||
|
||||
```
|
||||
modulo/
|
||||
_meuModulo.ts
|
||||
meu-modulo.regras-negocio.md ← co-localizado
|
||||
```bash
|
||||
ls ../../wiki/dev/<modulo>/*regras-negocio*.md 2>/dev/null
|
||||
```
|
||||
|
||||
Se o módulo for arquivo isolado (não pasta):
|
||||
```
|
||||
CRONS/
|
||||
_cron_nome.ts
|
||||
_cron_nome.regras-negocio.md ← mesmo diretório
|
||||
```
|
||||
- **Existe** → ler e identificar o que está desatualizado → ir para o passo [4]
|
||||
- **Não existe** → ir para o passo [3]
|
||||
|
||||
---
|
||||
|
||||
## PASSO 3 — Preencher com o template
|
||||
[3] Criar o arquivo de regras na Wiki de Desenvolvimento
|
||||
|
||||
```markdown
|
||||
# Regras de Negócio — [Nome Legível do Módulo]
|
||||
**Localização:** `../../wiki/dev/<modulo>/{nome-do-modulo}.regras-negocio.md` (ou `../../wiki/dev/<modulo>/regras-negocio/`).
|
||||
|
||||
Módulo: `_arquivo.ts`
|
||||
Localização: `caminho/relativo/ao/workspace`
|
||||
Preencher com a estrutura padrão:
|
||||
- Contexto operacional
|
||||
- Critérios de Entrada
|
||||
- Regras de Processamento (numeradas em ordem estrita)
|
||||
- Casos de Revisão Manual
|
||||
- Estratégia de Saída / Persistência de Campos
|
||||
- Dependências Externas (tabelas, filas, CRONs)
|
||||
|
||||
---
|
||||
|
||||
## Contexto
|
||||
[4] Adicionar ou verificar a referência no `.ts`
|
||||
|
||||
[Por que este módulo existe. Qual problema de negócio resolve.
|
||||
Inclua o cenário que levou à sua criação — ex: "O sistema pode gerar duplicatas
|
||||
por importações simultâneas..."]
|
||||
|
||||
---
|
||||
|
||||
## Critérios de Entrada
|
||||
|
||||
[O que aciona o módulo. Filtros aplicados na query de identificação.
|
||||
Ex: `excluido = false`, mesmo `(codigo_origem, vencimento)`, etc.]
|
||||
|
||||
---
|
||||
|
||||
## Regras de Processamento
|
||||
|
||||
[Numeradas em ordem de avaliação. Cada regra deve incluir:
|
||||
- Condição de ativação
|
||||
- O que acontece quando ativada
|
||||
- Se bloqueia ou direciona]
|
||||
|
||||
### Regra 1 — [Nome]
|
||||
...
|
||||
|
||||
### Regra 2 — [Nome]
|
||||
...
|
||||
|
||||
---
|
||||
|
||||
## Casos de Revisão Manual
|
||||
|
||||
[Quando o fluxo automático não pode prosseguir.
|
||||
Liste as condições que enviam para revisão manual.
|
||||
Se aplicável: como o caso é reportado (e-mail, log, fila de revisão).]
|
||||
|
||||
> **`null` é neutro** quando aplicável: descrever aqui se a lógica usa null como ausência neutra.
|
||||
|
||||
---
|
||||
|
||||
## Estratégia de Saída / Fusão de Campos
|
||||
|
||||
[Como os dados são combinados ou qual resultado é produzido.
|
||||
Usar tabela para clareza:]
|
||||
|
||||
| Campo | Estratégia |
|
||||
|---|---|
|
||||
| `campo_textual` | Concatenação sem repetição |
|
||||
| `campo_data` | Primeiro valor não-nulo vence |
|
||||
| `campo_booleano` | Primeiro valor não-nulo vence |
|
||||
|
||||
---
|
||||
|
||||
## Dependências Externas
|
||||
|
||||
[Tabelas lidas/escritas, filas disparadas, serviços externos.
|
||||
Incluir colunas de relacionamento quando relevante.]
|
||||
|
||||
- Tabelas de negócio: `tabela_a`, `tabela_b`
|
||||
- Relacionamentos re-apontados: `tabela_c` via `(codigo_origem, tabela_origem)`
|
||||
- Filas: nenhuma / `nome-da-fila`
|
||||
- E-mails: nenhum / destinatários e gatilho
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PASSO 4 — Adicionar referência no módulo TypeScript
|
||||
|
||||
Na **primeira linha útil** do arquivo `.ts` (após shebang ou licença, se houver):
|
||||
Garantir que a primeira linha útil do arquivo TypeScript seja:
|
||||
|
||||
```typescript
|
||||
// Regras de negócio: ver {modulo}.regras-negocio.md
|
||||
|
||||
import { ... } from "..."
|
||||
// Regras de negócio: ver ../../wiki/dev/<modulo>/{modulo}.regras-negocio.md
|
||||
```
|
||||
|
||||
Se já existia e está correto → sem mudança necessária.
|
||||
|
||||
---
|
||||
|
||||
## PASSO 5 — Limpar JSDoc duplicados
|
||||
[5] Estruturar JSDoc com aplicação prática e referência ao `.regras-negocio.md`
|
||||
|
||||
Percorrer os JSDoc do módulo e:
|
||||
Percorrer cada função do módulo:
|
||||
|
||||
| Se encontrar | Ação |
|
||||
|---|---|
|
||||
| JSDoc listando as regras de negócio | Substituir por referência ao `.md` |
|
||||
| JSDoc descrevendo critérios de bloqueio | Simplificar para "ver `.md`" |
|
||||
| JSDoc com listas de condições | Manter apenas `@param` e `@returns` |
|
||||
| Comentário inline explicando uma regra | Manter — comentários de linha são aceitáveis |
|
||||
- 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.
|
||||
|
||||
Exemplo de simplificação:
|
||||
---
|
||||
|
||||
```typescript
|
||||
// ❌ Antes — JSDoc duplicando as regras
|
||||
/**
|
||||
* Retorna false quando:
|
||||
* - vencimentos divergentes
|
||||
* - executada com datas distintas e não-nulas
|
||||
* - vencimento_prorrogado distintos
|
||||
* - estado contraditório: nao_executada=true + executada!=null
|
||||
*/
|
||||
[6] Verificar consistência — código ↔ `.regras-negocio.md`
|
||||
|
||||
// ✅ Depois — referência ao .md
|
||||
/**
|
||||
* Verifica se o grupo pode ser fundido e elege o registro principal.
|
||||
* Critérios de bloqueio e regras de eleição: ver regras-negocio.md
|
||||
*
|
||||
* @param execs - Registros do grupo, ordenados do mais antigo para o mais recente
|
||||
* @returns Código do eleito, ou `undefined` quando o grupo vai para revisão manual
|
||||
*/
|
||||
Para cada regra listada no `.regras-negocio.md`:
|
||||
|
||||
- [ ] Existe `if` correspondente no 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
|
||||
|
||||
---
|
||||
|
||||
[7] Validar tipagem
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
npx tsc --noEmit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PASSO 6 — Verificar consistência código ↔ `.md`
|
||||
|
||||
Percorrer cada regra listada no `.md` e verificar que há código correspondente:
|
||||
|
||||
- [ ] Cada critério de bloqueio tem um `if (...) return undefined / return retornoVazio`
|
||||
- [ ] Cada estratégia de campo tem implementação em `fundirCampos` ou equivalente
|
||||
- [ ] A ordem de avaliação no código bate com a ordem no `.md`
|
||||
- [ ] Campos exclusivos de certas tabelas estão guardados pelo `if (tabela === ...)`
|
||||
- [ ] queries têm `orderBy` quando a posição dos resultados tem significado (ver skill `consultar-banco-knex`)
|
||||
Zero erros = concluído.
|
||||
|
||||
---
|
||||
|
||||
## Checklist Final
|
||||
[8] Sincronizar com a Wiki de Desenvolvimento e Memórias
|
||||
|
||||
- [ ] Arquivo `.md` criado co-localizado com o módulo
|
||||
- [ ] Referência `// Regras de negócio: ver ...` na primeira linha do `.ts`
|
||||
- [ ] JSDoc simplificados — sem duplicar conteúdo do `.md`
|
||||
- [ ] Todas as regras do `.md` têm implementação correspondente no código
|
||||
- [ ] Código e `.md` estão consistentes (separadores, campos, condições)
|
||||
- [ ] `tsc --noEmit` passa sem erros após qualquer mudança de código
|
||||
Se o módulo introduziu ou alterou arquitetura ou regras consolidadas do módulo:
|
||||
|
||||
---
|
||||
|
||||
## Referências
|
||||
|
||||
- Rule: `global/rules/regras-negocio-md`
|
||||
- Workflow: `global/workflows/documentar-regras-negocio`
|
||||
- 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/`.
|
||||
|
|
|
|||
|
|
@ -1,212 +1,105 @@
|
|||
---
|
||||
name: documentar-regras-negocio
|
||||
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"
|
||||
description: >
|
||||
Guia operacional para criar, preencher e manter arquivos {modulo}.regras-negocio.md
|
||||
co-localizados com módulos TypeScript de lógica de negócio complexa.
|
||||
updatedAt: "2026-09-01"
|
||||
---
|
||||
|
||||
# Skill: Documentar Regras de Negócio em Módulos
|
||||
# Workflow / Skill: Documentar Regras de Negócio de um Módulo
|
||||
|
||||
Use esta skill sempre que um módulo TypeScript contiver lógica de decisão não-trivial
|
||||
que precise ser rastreável por produto, suporte e desenvolvimento sem exigir leitura de código.
|
||||
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>/`.
|
||||
|
||||
---
|
||||
|
||||
## Quando usar esta skill
|
||||
[1] Ler o módulo TypeScript completamente
|
||||
|
||||
- Módulo com 3+ critérios de decisão distintos
|
||||
- Lógica de eleição/priorização entre registros
|
||||
- Processamento que pode resultar em revisão manual
|
||||
- Worker/CRON consumindo dados com estratégias diferenciadas por tipo
|
||||
- Importador automático com regras de aceite/rejeição
|
||||
Identificar e anotar:
|
||||
|
||||
- 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 BullMQ, e-mails, serviços)
|
||||
|
||||
---
|
||||
|
||||
## PASSO 1 — Identificar o escopo das regras
|
||||
[2] Verificar se já existe a documentação de regras na Wiki de Desenvolvimento
|
||||
|
||||
Antes de escrever o `.md`, percorrer o módulo e identificar:
|
||||
|
||||
| Categoria | O que procurar |
|
||||
|---|---|
|
||||
| **Critérios de entrada** | Filtros de query (excluido, vencimento, etc.) |
|
||||
| **Critérios de bloqueio** | Condições que bloqueiam o fluxo automático |
|
||||
| **Estratégia por tipo de dado** | Concatenação vs. primeiro-não-nulo vs. outros |
|
||||
| **Eleição de principal** | Regras de prioridade entre registros |
|
||||
| **Estado contraditório** | Combinações de campos mutuamente exclusivas |
|
||||
| **Dependências externas** | Tabelas, filas, serviços tocados |
|
||||
|
||||
---
|
||||
|
||||
## PASSO 2 — Criar o arquivo
|
||||
|
||||
Nomenclatura: `{nome-do-modulo-sem-underline-inicial}.regras-negocio.md`
|
||||
|
||||
Localizar **na mesma pasta** do arquivo TypeScript:
|
||||
|
||||
```
|
||||
modulo/
|
||||
_meuModulo.ts
|
||||
meu-modulo.regras-negocio.md ← co-localizado
|
||||
```bash
|
||||
ls ../../wiki/dev/<modulo>/*regras-negocio*.md 2>/dev/null
|
||||
```
|
||||
|
||||
Se o módulo for arquivo isolado (não pasta):
|
||||
```
|
||||
CRONS/
|
||||
_cron_nome.ts
|
||||
_cron_nome.regras-negocio.md ← mesmo diretório
|
||||
```
|
||||
- **Existe** → ler e identificar o que está desatualizado → ir para o passo [4]
|
||||
- **Não existe** → ir para o passo [3]
|
||||
|
||||
---
|
||||
|
||||
## PASSO 3 — Preencher com o template
|
||||
[3] Criar o arquivo de regras na Wiki de Desenvolvimento
|
||||
|
||||
```markdown
|
||||
# Regras de Negócio — [Nome Legível do Módulo]
|
||||
**Localização:** `../../wiki/dev/<modulo>/{nome-do-modulo}.regras-negocio.md` (ou `../../wiki/dev/<modulo>/regras-negocio/`).
|
||||
|
||||
Módulo: `_arquivo.ts`
|
||||
Localização: `caminho/relativo/ao/workspace`
|
||||
Preencher com a estrutura padrão:
|
||||
- Contexto operacional
|
||||
- Critérios de Entrada
|
||||
- Regras de Processamento (numeradas em ordem estrita)
|
||||
- Casos de Revisão Manual
|
||||
- Estratégia de Saída / Persistência de Campos
|
||||
- Dependências Externas (tabelas, filas, CRONs)
|
||||
|
||||
---
|
||||
|
||||
## Contexto
|
||||
[4] Adicionar ou verificar a referência no `.ts`
|
||||
|
||||
[Por que este módulo existe. Qual problema de negócio resolve.
|
||||
Inclua o cenário que levou à sua criação — ex: "O sistema pode gerar duplicatas
|
||||
por importações simultâneas..."]
|
||||
|
||||
---
|
||||
|
||||
## Critérios de Entrada
|
||||
|
||||
[O que aciona o módulo. Filtros aplicados na query de identificação.
|
||||
Ex: `excluido = false`, mesmo `(codigo_origem, vencimento)`, etc.]
|
||||
|
||||
---
|
||||
|
||||
## Regras de Processamento
|
||||
|
||||
[Numeradas em ordem de avaliação. Cada regra deve incluir:
|
||||
- Condição de ativação
|
||||
- O que acontece quando ativada
|
||||
- Se bloqueia ou direciona]
|
||||
|
||||
### Regra 1 — [Nome]
|
||||
...
|
||||
|
||||
### Regra 2 — [Nome]
|
||||
...
|
||||
|
||||
---
|
||||
|
||||
## Casos de Revisão Manual
|
||||
|
||||
[Quando o fluxo automático não pode prosseguir.
|
||||
Liste as condições que enviam para revisão manual.
|
||||
Se aplicável: como o caso é reportado (e-mail, log, fila de revisão).]
|
||||
|
||||
> **`null` é neutro** quando aplicável: descrever aqui se a lógica usa null como ausência neutra.
|
||||
|
||||
---
|
||||
|
||||
## Estratégia de Saída / Fusão de Campos
|
||||
|
||||
[Como os dados são combinados ou qual resultado é produzido.
|
||||
Usar tabela para clareza:]
|
||||
|
||||
| Campo | Estratégia |
|
||||
|---|---|
|
||||
| `campo_textual` | Concatenação sem repetição |
|
||||
| `campo_data` | Primeiro valor não-nulo vence |
|
||||
| `campo_booleano` | Primeiro valor não-nulo vence |
|
||||
|
||||
---
|
||||
|
||||
## Dependências Externas
|
||||
|
||||
[Tabelas lidas/escritas, filas disparadas, serviços externos.
|
||||
Incluir colunas de relacionamento quando relevante.]
|
||||
|
||||
- Tabelas de negócio: `tabela_a`, `tabela_b`
|
||||
- Relacionamentos re-apontados: `tabela_c` via `(codigo_origem, tabela_origem)`
|
||||
- Filas: nenhuma / `nome-da-fila`
|
||||
- E-mails: nenhum / destinatários e gatilho
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PASSO 4 — Adicionar referência no módulo TypeScript
|
||||
|
||||
Na **primeira linha útil** do arquivo `.ts` (após shebang ou licença, se houver):
|
||||
Garantir que a primeira linha útil do arquivo TypeScript seja:
|
||||
|
||||
```typescript
|
||||
// Regras de negócio: ver {modulo}.regras-negocio.md
|
||||
|
||||
import { ... } from "..."
|
||||
// Regras de negócio: ver ../../wiki/dev/<modulo>/{modulo}.regras-negocio.md
|
||||
```
|
||||
|
||||
Se já existia e está correto → sem mudança necessária.
|
||||
|
||||
---
|
||||
|
||||
## PASSO 5 — Limpar JSDoc duplicados
|
||||
[5] Estruturar JSDoc com aplicação prática e referência ao `.regras-negocio.md`
|
||||
|
||||
Percorrer os JSDoc do módulo e:
|
||||
Percorrer cada função do módulo:
|
||||
|
||||
| Se encontrar | Ação |
|
||||
|---|---|
|
||||
| JSDoc listando as regras de negócio | Substituir por referência ao `.md` |
|
||||
| JSDoc descrevendo critérios de bloqueio | Simplificar para "ver `.md`" |
|
||||
| JSDoc com listas de condições | Manter apenas `@param` e `@returns` |
|
||||
| Comentário inline explicando uma regra | Manter — comentários de linha são aceitáveis |
|
||||
- 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.
|
||||
|
||||
Exemplo de simplificação:
|
||||
---
|
||||
|
||||
```typescript
|
||||
// ❌ Antes — JSDoc duplicando as regras
|
||||
/**
|
||||
* Retorna false quando:
|
||||
* - vencimentos divergentes
|
||||
* - executada com datas distintas e não-nulas
|
||||
* - vencimento_prorrogado distintos
|
||||
* - estado contraditório: nao_executada=true + executada!=null
|
||||
*/
|
||||
[6] Verificar consistência — código ↔ `.regras-negocio.md`
|
||||
|
||||
// ✅ Depois — referência ao .md
|
||||
/**
|
||||
* Verifica se o grupo pode ser fundido e elege o registro principal.
|
||||
* Critérios de bloqueio e regras de eleição: ver regras-negocio.md
|
||||
*
|
||||
* @param execs - Registros do grupo, ordenados do mais antigo para o mais recente
|
||||
* @returns Código do eleito, ou `undefined` quando o grupo vai para revisão manual
|
||||
*/
|
||||
Para cada regra listada no `.regras-negocio.md`:
|
||||
|
||||
- [ ] Existe `if` correspondente no 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
|
||||
|
||||
---
|
||||
|
||||
[7] Validar tipagem
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
npx tsc --noEmit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PASSO 6 — Verificar consistência código ↔ `.md`
|
||||
|
||||
Percorrer cada regra listada no `.md` e verificar que há código correspondente:
|
||||
|
||||
- [ ] Cada critério de bloqueio tem um `if (...) return undefined / return retornoVazio`
|
||||
- [ ] Cada estratégia de campo tem implementação em `fundirCampos` ou equivalente
|
||||
- [ ] A ordem de avaliação no código bate com a ordem no `.md`
|
||||
- [ ] Campos exclusivos de certas tabelas estão guardados pelo `if (tabela === ...)`
|
||||
- [ ] queries têm `orderBy` quando a posição dos resultados tem significado (ver skill `consultar-banco-knex`)
|
||||
Zero erros = concluído.
|
||||
|
||||
---
|
||||
|
||||
## Checklist Final
|
||||
[8] Sincronizar com a Wiki de Desenvolvimento e Memórias
|
||||
|
||||
- [ ] Arquivo `.md` criado co-localizado com o módulo
|
||||
- [ ] Referência `// Regras de negócio: ver ...` na primeira linha do `.ts`
|
||||
- [ ] JSDoc simplificados — sem duplicar conteúdo do `.md`
|
||||
- [ ] Todas as regras do `.md` têm implementação correspondente no código
|
||||
- [ ] Código e `.md` estão consistentes (separadores, campos, condições)
|
||||
- [ ] `tsc --noEmit` passa sem erros após qualquer mudança de código
|
||||
Se o módulo introduziu ou alterou arquitetura ou regras consolidadas do módulo:
|
||||
|
||||
---
|
||||
|
||||
## Referências
|
||||
|
||||
- Rule: `global/rules/regras-negocio-md`
|
||||
- Workflow: `global/workflows/documentar-regras-negocio`
|
||||
- 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