.agent/agents/refatorar/workflows/refatorar-modulo.md

type	name	description	scope	updatedAt
workflow	refatorar-modulo	Fluxo completo de refatoração de um módulo, do diagnóstico à verificação	local	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:

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