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,120 +1,120 @@
|
|||
---
|
||||
type: rule
|
||||
name: regras-negocio-md
|
||||
description: Arquivo {modulo}.regras-negocio.md obrigatório para módulos com lógica complexa
|
||||
description: O conteúdo de regras de negócio deve ficar em ../../wiki/dev/<modulo>/.
|
||||
scope: global
|
||||
trigger: always_on
|
||||
updatedAt: "2026-06-01"
|
||||
updatedAt: "2026-09-01"
|
||||
---
|
||||
|
||||
# Regra: Arquivo `{modulo}.regras-negocio.md` Obrigatório para Módulos com Lógica Complexa
|
||||
# Regra: Conteúdo de Regras de Negócio em `../../wiki/dev/<modulo>/`
|
||||
|
||||
> **Escopo global** — aplica-se a todos os projetos do ecossistema Azteca.
|
||||
|
||||
## Contexto
|
||||
|
||||
Qualquer arquivo TypeScript que contenha lógica de negócio não-trivial — múltiplas regras de decisão, critérios de bloqueio, estratégias de processamento — deve ter suas regras documentadas em linguagem natural em um arquivo Markdown co-localizado.
|
||||
Toda lógica de negócio não-trivial — regras de decisão, critérios de bloqueio, estratégias de processamento, priorizações e fluxos de dados — deve ter seu conteúdo documentado em linguagem natural na **Wiki de Desenvolvimento** em `../../wiki/dev/<modulo>/`.
|
||||
|
||||
Isso garante que produto, suporte e desenvolvimento possam entender as regras sem precisar ler TypeScript, e que o agente de IA encontre rapidamente os critérios corretos antes de alterar qualquer código.
|
||||
> 💡 **Aplicação VitePress (`../../wiki`)**: O diretório `../../wiki` é uma aplicação VitePress na qual `../../wiki/<modulo>/` é voltado ao acesso dos **usuários**, e `../../wiki/dev/<modulo>/` é reservado ao **acesso interno exclusivo da equipe de desenvolvimento**.
|
||||
|
||||
Isso garante centralização, governança técnica e facilidade de consulta por desenvolvedores, arquitetos e agentes de IA.
|
||||
|
||||
---
|
||||
|
||||
## Regra
|
||||
|
||||
**Todo módulo com lógica de negócio não-trivial DEVE ter um arquivo `{modulo}.regras-negocio.md` co-localizado.**
|
||||
**Todo o conteúdo detalhado de regras de negócio DEVE ficar em `../../wiki/dev/<modulo>/`.**
|
||||
|
||||
Considera-se lógica não-trivial qualquer módulo que:
|
||||
- possui 3 ou mais critérios de decisão distintos
|
||||
- realiza eleição/priorização entre registros
|
||||
- aplica diferentes estratégias por tipo de dado
|
||||
- pode resultar em revisão manual (caminho alternativo ao fluxo automático)
|
||||
- é consumido por CRON, worker ou importador automático
|
||||
- Possui 3 ou mais critérios de decisão distintos
|
||||
- Realiza eleição/priorização entre registros
|
||||
- Aplica diferentes estratégias por tipo de dado
|
||||
- Pode resultar em revisão manual (caminho alternativo ao fluxo automático)
|
||||
- É consumido por CRON, worker ou importador automático
|
||||
|
||||
O módulo TypeScript deve conter, na primeira linha do arquivo, a referência:
|
||||
O módulo TypeScript deve conter, na primeira linha útil do arquivo, a referência:
|
||||
|
||||
```typescript
|
||||
// Regras de negócio: ver {modulo}.regras-negocio.md
|
||||
// Regras de negócio: ver ../../wiki/dev/<modulo>/{modulo}.regras-negocio.md
|
||||
```
|
||||
|
||||
O arquivo `.md` é a **fonte de verdade**. Os JSDoc do código devem referenciar o `.md`, não duplicá-lo.
|
||||
A documentação na **Wiki de Desenvolvimento** é a **fonte de verdade da lógica operacional**. Os comentários JSDoc no código explicam a aplicação prática da função e apontam para a wiki para o detalhamento dos critérios.
|
||||
|
||||
## Estrutura Obrigatória do Arquivo
|
||||
---
|
||||
|
||||
## Estrutura do Documento de Regras na Wiki de Desenvolvimento
|
||||
|
||||
**Localização:** `../../wiki/dev/<modulo>/` (ex.: `../../wiki/dev/e-licencie.sigma/regras-negocio/` ou `../../wiki/dev/e-licencie.sigma/{modulo}.regras-negocio.md`)
|
||||
|
||||
```markdown
|
||||
# Regras de Negócio — [Nome do Módulo]
|
||||
# Regras de Negócio — [Nome do Módulo / Serviço]
|
||||
|
||||
Módulo: `_arquivo.ts`
|
||||
Localização: `caminho/relativo/ao/arquivo`
|
||||
Módulo TypeScript: `_arquivo.ts`
|
||||
Localização no Código: `caminho/relativo/ao/arquivo`
|
||||
|
||||
---
|
||||
|
||||
## Contexto
|
||||
Por que este módulo existe, qual problema resolve.
|
||||
Por que este módulo existe, qual problema operacional resolve.
|
||||
|
||||
## Critérios de Entrada / Identificação
|
||||
O que aciona o módulo, quais dados recebe, filtros aplicados.
|
||||
|
||||
## Regras de Processamento
|
||||
As regras numeradas em ordem de avaliação.
|
||||
As regras numeradas em ordem estrita de avaliação.
|
||||
|
||||
## Casos de Revisão Manual (quando aplicável)
|
||||
Quando o processamento automático não pode prosseguir.
|
||||
|
||||
## Estratégia de Fusão / Resultado (quando aplicável)
|
||||
O que o módulo produz, como campos são combinados.
|
||||
## Estratégia de Fusão / Persistência (quando aplicável)
|
||||
O que o módulo produz, como campos são combinados ou persistidos.
|
||||
|
||||
## Dependências Externas
|
||||
Tabelas, filas, serviços externos tocados pelo módulo.
|
||||
Tabelas, filas BullMQ, rotas e serviços externos tocados pelo módulo.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exemplos
|
||||
|
||||
✅ **Correto** — referência no topo do módulo, regras no `.md`:
|
||||
✅ **Correto** — referência no topo do módulo apontando para a Wiki de Desenvolvimento:
|
||||
```typescript
|
||||
// Regras de negócio: ver juntar_execucoes.regras-negocio.md
|
||||
// Regras de negócio: ver ../../wiki/dev/e-licencie.sigma/juntar_execucoes.regras-negocio.md
|
||||
|
||||
import { ... } from "..."
|
||||
|
||||
/**
|
||||
* Consolida execuções de condicionantes com base nas datas de vencimento.
|
||||
* Aplicação: Processamento noturno de auditoria e saneamento de agenda.
|
||||
*/
|
||||
export const compilarJuntarExecucoes = async (...) => {
|
||||
// implementação conforme regras-negocio.md
|
||||
// implementação conforme a Wiki de Desenvolvimento
|
||||
}
|
||||
```
|
||||
|
||||
❌ **Errado** — regras embutidas no código como comentário de bloco:
|
||||
❌ **Errado** — regras embutidas no código como comentário gigante ou arquivos soltos fora da wiki:
|
||||
```typescript
|
||||
/**
|
||||
* Regras de negócio:
|
||||
* [x] Pode ter apenas uma execução por data de vencimento.
|
||||
* [x] Se tiver apenas uma execução consolidada → ela é a principal.
|
||||
* ...
|
||||
*/
|
||||
```
|
||||
|
||||
❌ **Errado** — JSDoc duplicando as regras em vez de referenciar o `.md`:
|
||||
```typescript
|
||||
/**
|
||||
* Retorna false quando:
|
||||
* - vencimentos divergentes
|
||||
* - executada com datas distintas
|
||||
* - vencimento_prorrogado distintos
|
||||
* ...
|
||||
*/
|
||||
```
|
||||
---
|
||||
|
||||
## Impacto
|
||||
|
||||
Sem este padrão:
|
||||
- Regras de negócio ficam implícitas no código ou em JSDoc que envelhece sem controle
|
||||
- O agente de IA precisa inferir regras do código ao invés de lê-las diretamente
|
||||
- Produto e suporte não conseguem validar o comportamento sem ajuda técnica
|
||||
- Mudanças de regra geram JSDoc desatualizado espalhado pelo código
|
||||
- Centralização de todo o conhecimento técnico e operacional na Wiki de Desenvolvimento.
|
||||
- Regras de negócio claras para humanos e IAs sem poluir o código-fonte.
|
||||
- Mudanças de regras são auditáveis e versionadas na documentação do repositório.
|
||||
|
||||
## Aplicação
|
||||
|
||||
- Módulos de CRON com lógica de auditoria/fusão
|
||||
- Importadores automáticos (ex: importação de licenças via IA)
|
||||
- Workers de processamento em lote
|
||||
- Qualquer utilitário com lógica de decisão multi-critério
|
||||
---
|
||||
|
||||
## Referências
|
||||
|
||||
- Skill: `global/skills/documentar-regras-negocio/SKILL`
|
||||
- Workflow: `global/workflows/documentar-regras-negocio`
|
||||
- Rule: `rules/ddd-documentacao-primeiro.md`
|
||||
- Rule: `rules/jsdoc-padrao.md`
|
||||
- Skill: `skills/documentar-regras-negocio/SKILL.md`
|
||||
- Workflow: `global/workflows/documentar-regras-negocio.md`
|
||||
- Wiki de Desenvolvimento: `../../wiki/dev/<modulo>/`
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue