134 lines
4.5 KiB
Markdown
134 lines
4.5 KiB
Markdown
---
|
|
type: workflow
|
|
name: refatorar-modulo
|
|
description: Fluxo completo de refatoração de um módulo, do diagnóstico à verificação
|
|
scope: local
|
|
updatedAt: "2026-06-19"
|
|
---
|
|
|
|
# Workflow: Refatorar Módulo
|
|
|
|
## Objetivo
|
|
|
|
Conduzir a refatoração de um módulo do ecossistema de forma segura, rastreável e fundamentada nos princípios do Refactoring.Guru.
|
|
|
|
## Gatilho
|
|
|
|
- Solicitação explícita de refatoração
|
|
- Módulo identificado com 3+ code smells em diagnóstico
|
|
- Preparação para nova feature que exige código limpo como pré-requisito
|
|
|
|
## Fluxo
|
|
|
|
```
|
|
┌─────────────┐ ┌───────────────┐ ┌──────────────┐
|
|
│ 1. DIAGNÓS- │───▶│ 2. SOLICITAR │───▶│ 3. PLANEJAR │
|
|
│ TICAR │ │ TESTES │ │ AÇÕES │
|
|
└─────────────┘ └───────────────┘ └──────────────┘
|
|
│
|
|
┌─────────────┐ ┌───────────────┐ ┌──────┴───────┐
|
|
│ 6. DOCUMEN- │◀───│ 5. VERIFICAR │◀───│ 4. EXECUTAR │
|
|
│ TAR │ │ TESTES │ │ REFAT. │
|
|
└─────────────┘ └───────────────┘ └──────────────┘
|
|
```
|
|
|
|
### Etapa 1: Diagnosticar
|
|
|
|
**Agente:** `@refatorar`
|
|
|
|
Executar a skill `diagnosticar-code-smells`:
|
|
- Listar code smells encontrados
|
|
- Identificar violações SOLID
|
|
- Recomendar Design Patterns aplicáveis
|
|
- Classificar por severidade (🔴 🟡 🟢)
|
|
|
|
**Saída:** Relatório de diagnóstico com plano de ação priorizado.
|
|
|
|
### Etapa 2: Solicitar Testes
|
|
|
|
**Agente:** `@refatorar` → `@testes`
|
|
|
|
Para cada trecho que será refatorado:
|
|
- Verificar se há testes cobrindo o comportamento
|
|
- Se não há: solicitar ao `@testes` criação de testes
|
|
- Aguardar confirmação de que testes passam
|
|
|
|
**Regra:** Nenhuma refatoração avança sem cobertura de testes. Sem exceções.
|
|
|
|
### Etapa 3: Planejar Ações
|
|
|
|
**Agente:** `@refatorar`
|
|
|
|
Para cada item do plano de ação:
|
|
1. Nomear a técnica de refatoração (ex: "Extract Method", "Replace Conditional with Strategy")
|
|
2. Identificar o princípio SOLID que será atendido
|
|
3. Estimar arquivos afetados
|
|
4. Definir ordem de execução (itens independentes primeiro)
|
|
|
|
**Formato:**
|
|
```markdown
|
|
| # | Técnica | Princípio | Arquivos | Dependência |
|
|
|---|---------|-----------|----------|-------------|
|
|
| 1 | Extract Method | S — SRP | servico.ts | Nenhuma |
|
|
| 2 | Strategy Pattern | O — OCP | calculador.ts, tipos.ts | Após #1 |
|
|
```
|
|
|
|
### Etapa 4: Executar Refatoração
|
|
|
|
**Agente:** `@refatorar`
|
|
|
|
Para cada item do plano, em ordem:
|
|
1. Aplicar a mudança em **passos pequenos**
|
|
2. Verificar que testes passam após cada passo
|
|
3. Não misturar refatoração com feature
|
|
|
|
**Passos típicos de uma refatoração:**
|
|
```
|
|
4.1 Extrair função/composable
|
|
4.2 Mover para arquivo adequado
|
|
4.3 Atualizar imports
|
|
4.4 Verificar testes → ✅
|
|
4.5 Próximo item
|
|
```
|
|
|
|
### Etapa 5: Verificar Testes
|
|
|
|
**Agente:** `@refatorar` + `@testes`
|
|
|
|
- Executar todos os testes do módulo
|
|
- Confirmar zero regressões
|
|
- Se algum teste falha: reverter último passo e investigar
|
|
|
|
### Etapa 6: Documentar
|
|
|
|
**Agente:** `@refatorar` → `@documentacao`
|
|
|
|
- Atualizar JSDoc se interfaces mudaram
|
|
- Registrar decisão e regras na Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`) se a refatoração foi significativa
|
|
- Informar `@documentacao` sobre mudanças estruturais
|
|
|
|
**Sugestão de texto do commit (para o operador humano):**
|
|
```
|
|
refactor(<módulo>): <técnica aplicada>
|
|
|
|
- Problema: <code smell identificado>
|
|
- Solução: <padrão/técnica aplicada>
|
|
- Princípio: <princípio SOLID atendido>
|
|
```
|
|
|
|
## Critérios de Sucesso
|
|
|
|
- [ ] Todos os code smells críticos (🔴) resolvidos
|
|
- [ ] Todos os testes passam (zero regressões)
|
|
- [ ] Nenhum arquivo acima de 250 linhas
|
|
- [ ] Nenhum `any`/`as any` introduzido
|
|
- [ ] Fronteiras de pacote respeitadas
|
|
- [ ] Decisões documentadas
|
|
|
|
## Referências
|
|
|
|
- Skill: `agents/refatorar/skills/diagnosticar-code-smells/SKILL`
|
|
- Rule: `agents/refatorar/rules/refatoracao-segura`
|
|
- Rule: `agents/refatorar/rules/solid-compliance`
|
|
- Rule: `agents/refatorar/rules/design-patterns-pragmatico`
|
|
- Workflow global: `global/workflows/codigo-limpo` (ou `global/workflows/otimizar-codigos`)
|