105 lines
2.8 KiB
Markdown
105 lines
2.8 KiB
Markdown
---
|
|
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
|
|
scope: global
|
|
updatedAt: "2026-06-01"
|
|
---
|
|
|
|
# Workflow: 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.
|
|
|
|
---
|
|
|
|
[1] Ler o módulo TypeScript completamente
|
|
|
|
Identificar e anotar:
|
|
|
|
- Nome do arquivo e localização exata
|
|
- 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)
|
|
|
|
---
|
|
|
|
[2] Verificar se já existe um `.regras-negocio`
|
|
|
|
```bash
|
|
ls $(dirname <arquivo>)/*.regras-negocio.md 2>/dev/null
|
|
```
|
|
|
|
- **Existe** → ler e identificar o que está desatualizado → ir para o passo [4]
|
|
- **Não existe** → ir para o passo [3]
|
|
|
|
---
|
|
|
|
[3] Criar o arquivo `.regras-negocio`
|
|
|
|
Nomenclatura: `{nome-sem-_inicial}.regras-negocio` na mesma pasta do módulo.
|
|
|
|
Preencher com o template da skill `documentar-regras-negocio.global`:
|
|
- Contexto
|
|
- Critérios de Entrada
|
|
- Regras de Processamento (numeradas)
|
|
- Casos de Revisão Manual
|
|
- Estratégia de Saída / Fusão de Campos
|
|
- Dependências Externas
|
|
|
|
---
|
|
|
|
[4] Adicionar ou verificar a referência no `.ts`
|
|
|
|
Garantir que a primeira linha útil do arquivo TypeScript seja:
|
|
|
|
```typescript
|
|
// Regras de negócio: ver {modulo}.regras-negocio.md
|
|
```
|
|
|
|
Se já existia e está correto → sem mudança necessária.
|
|
|
|
---
|
|
|
|
[5] Simplificar JSDoc que duplicam as regras
|
|
|
|
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
|
|
|
|
---
|
|
|
|
[6] Verificar consistência — código ↔ ``
|
|
|
|
Para cada regra listada no ``:
|
|
|
|
- [ ] 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
|
|
- [ ] `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
|
|
```
|
|
|
|
Zero erros = concluído.
|
|
|
|
---
|
|
|
|
[8] Registrar no sistema de conhecimento (se regras novas)
|
|
|
|
Se o workflow revelou novos padrões de negócio relevantes ao projeto:
|
|
|
|
- Criar ou atualizar ADR via skill `documentar-decisao-tecnica`
|
|
- Verificar se alguma rule precisa ser atualizada
|