---
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 em `.regras-negocio.md` se refatoração foi significativa
- Informar `@documentacao` sobre mudanças estruturais

**Formato do commit:**
```
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`)