.agent/global/rules/regras-negocio-md

---
type: rule
name: regras-negocio-md
description: Arquivo {modulo}.regras-negocio.md obrigatório para módulos com lógica complexa
scope: global
trigger: always_on
updatedAt: "2026-06-01"
---

# Regra: Arquivo `{modulo}.regras-negocio.md` Obrigatório para Módulos com Lógica Complexa

> **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.

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.

## Regra

**Todo módulo com lógica de negócio não-trivial DEVE ter um arquivo `{modulo}.regras-negocio.md` co-localizado.**

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

O módulo TypeScript deve conter, na primeira linha do arquivo, a referência:

```typescript
// Regras de negócio: ver {modulo}.regras-negocio.md
```

O arquivo `.md` é a **fonte de verdade**. Os JSDoc do código devem referenciar o `.md`, não duplicá-lo.

## Estrutura Obrigatória do Arquivo

```markdown
# Regras de Negócio — [Nome do Módulo]

Módulo: `_arquivo.ts`
Localização: `caminho/relativo/ao/arquivo`

---

## Contexto
Por que este módulo existe, qual problema 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.

## 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.

## Dependências Externas
Tabelas, filas, serviços externos tocados pelo módulo.
```

## Exemplos

✅ **Correto** — referência no topo do módulo, regras no `.md`:
```typescript
// Regras de negócio: ver juntar_execucoes.regras-negocio.md

import { ... } from "..."

export const compilarJuntarExecucoes = async (...) => {
  // implementação conforme regras-negocio.md
}
```

❌ **Errado** — regras embutidas no código como comentário de bloco:
```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

## 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`