@maestro-ai/cli 1.0.0

package/content/workflows/mcp-refactor.md

@@ -0,0 +1,600 @@
+---
+description: Refatoração estruturada de código (Análise → Testes → Refactor → Validação)
+---
+
+# /mcp-refactor - Refatoração MCP
+
+$ARGUMENTS
+
+---
+
+## Objetivo
+
+Refatorar código de forma segura e estruturada usando fluxo de 5 fases do MCP Maestro, com testes de caracterização e validação contínua.
+
+---
+
+## Quando Usar
+
+- Melhorar qualidade de código sem mudar comportamento
+- Reduzir complexidade ou débito técnico
+- Preparar código para nova feature
+- Migrar para novo padrão ou arquitetura
+
+**NÃO usar para:**
+- Adicionar funcionalidade → Use `/mcp-feature`
+- Corrigir bugs → Use `/mcp-debug`
+
+---
+
+## Fluxo de 5 Fases
+
+```
+1. Análise de Código Atual
+   ↓
+2. Testes de Caracterização
+   ↓
+3. Refatoração Incremental
+   ↓
+4. Validação
+   ↓
+5. Deploy
+```
+
+**Princípio:** Nunca refatorar sem testes!
+
+---
+
+## Execução
+
+### Passo 1: Coleta de Informações
+
+**Perguntar ao usuário:**
+
+```markdown
+🔧 **Refatoração de Código**
+
+1. Qual área deseja refatorar?
+   [Exemplo: Serviço de autenticação, Controllers de API, etc]
+
+2. Qual o motivo da refatoração?
+   - **complexidade**: Código difícil de entender
+   - **duplicacao**: Código repetido
+   - **performance**: Lento ou ineficiente
+   - **manutencao**: Difícil de manter/estender
+   - **migracao**: Mudança de padrão/arquitetura
+
+   Escolha: [complexidade/duplicacao/performance/manutencao/migracao]
+
+3. (Opcional) Arquivos principais:
+   [Lista de arquivos a refatorar]
+```
+
+---
+
+### Passo 2: Iniciar Fluxo de Refatoração
+
+```typescript
+await mcp_maestro_refatorar({
+  area: "[área fornecida]",
+  motivo: "[motivo]"
+});
+```
+
+**MCP cria contexto e retorna:**
+
+```json
+{
+  "refactor_id": "REF-001",
+  "fases": [
+    "Análise",
+    "Testes de Caracterização",
+    "Refatoração",
+    "Validação",
+    "Deploy"
+  ],
+  "fase_atual": 1,
+  "estrategia": "[incremental/big-bang]"
+}
+```
+
+---
+
+### Passo 3: Fase 1 - Análise de Código Atual
+
+**Apresentar:**
+
+```markdown
+✅ **Fluxo de Refatoração Iniciado** (REF-001)
+
+---
+
+🎯 **Fase 1/5: Análise de Código Atual**
+🤖 **Especialista:** Exploração de Codebase
+
+## Mapeamento da Área
+
+**Arquivos Identificados:**
+- `[arquivo1.ts]` - [responsabilidade]
+- `[arquivo2.ts]` - [responsabilidade]
+- `[arquivo3.ts]` - [responsabilidade]
+
+**Métricas de Código:**
+- Complexidade Ciclomática: [valor]
+- Linhas de código: [count]
+- Duplicação: [percentual]%
+- Cobertura de testes: [percentual]%
+
+---
+
+## Problemas Identificados
+
+1. **[Problema 1]**
+   - Arquivo: `[caminho]`
+   - Evidência: [trecho de código]
+   - Impacto: [alto/médio/baixo]
+
+2. **[Problema 2]**
+   - ...
+
+---
+
+## Estratégia Recomendada
+
+${estrategia === 'incremental' ? `
+✅ **Refatoração Incremental** (Recomendado)
+
+Motivo: [área grande/crítica, fazer passo a passo]
+
+Etapas:
+1. [Passo 1]
+2. [Passo 2]
+3. [Passo 3]
+` : `
+⚡ **Big Bang Refactor**
+
+Motivo: [área pequena, pode fazer de uma vez]
+
+Refatorar tudo e validar.
+`}
+
+Prosseguir? (S/N)
+```
+
+---
+
+### Passo 4: Fase 2 - Testes de Caracterização
+
+> [!IMPORTANT]
+> **REGRA DE OURO:** Nunca refatorar sem testes!
+
+```markdown
+🎯 **Fase 2/5: Testes de Caracterização**
+
+## O que são Testes de Caracterização?
+
+Testes que capturam o **comportamento atual** do código.
+Não testam se está "correto", mas sim "preservam" o comportamento.
+
+---
+
+## Testes Criados
+
+### 1. Teste de comportamento principal
+
+```[linguagem]
+describe('[ComponenteAtual]', () => {
+  it('should preserve current behavior for [scenario]', () => {
+    // Arrange
+    const input = [value];
+    
+    // Act
+    const result = funcaoAtual(input);
+    
+    // Assert
+    expect(result).toEqual([valor_atual]);
+  });
+});
+```
+
+### 2. Teste de edge cases
+
+[Mais testes...]
+
+---
+
+## Cobertura
+
+- **Antes:** [percentual]%
+- **Depois dos testes de caracterização:** [percentual]%
+- **Meta:** 80%+ antes de refatorar
+
+✅ Todos os testes passando
+
+Pronto para refatorar com segurança!
+```
+
+---
+
+### Passo 5: Fase 3 - Refatoração Incremental
+
+```markdown
+🎯 **Fase 3/5: Refatoração Incremental**
+
+## Estratégia: Passos Pequenos
+
+${estrategia === 'incremental' ? `
+### Passo 1 de 3: [Nome do passo]
+
+**Antes:**
+```[linguagem]
+[código antigo]
+```
+
+**Depois:**
+```[linguagem]
+[código refatorado]
+```
+
+**Mudanças:**
+- [O que mudou]
+- [Por que melhorou]
+
+**Validação:**
+- ✅ Todos os testes passam
+- ✅ Comportamento preservado
+- ✅ Lint OK
+
+---
+
+### Passo 2 de 3: [Nome do passo]
+
+[...]
+
+` : `
+### Refatoração Completa
+
+**Antes:**
+[código antigo]
+
+**Depois:**
+[código refatorado]
+
+**Mudanças:**
+- [lista de mudanças]
+`}
+
+---
+
+## Padrões Aplicados
+
+${motivo === 'complexidade' ? `
+- Extract Method
+- Replace Conditional with Polymorphism
+- Simplify Complex Expressions
+` : motivo === 'duplicacao' ? `
+- Extract Function
+- Extract Class
+- Pull Up Method
+` : motivo === 'performance' ? `
+- Memoization
+- Lazy Loading
+- Algorithm Optimization
+` : `
+- [Padrões específicos]
+`}
+
+---
+
+## Validação Contínua
+
+Após cada passo:
+```bash
+npm test              # Testes passam?
+npm run lint          # Lint OK?
+git commit -m "..."   # Commit pequeno
+```
+
+---
+
+**Status:** [X/Y] passos completados
+
+Continuar para próximo passo? (S/N)
+```
+
+---
+
+### Passo 6: Fase 4 - Validação
+
+```markdown
+🎯 **Fase 4/5: Validação**
+
+## Checklist de Qualidade
+
+### Funcional
+- [x] Todos os testes passam ✅
+- [x] Comportamento preservado ✅
+- [x] Edge cases cobertos ✅
+
+### Qualidade de Código
+- [x] Complexidade reduzida: [antes] → [depois] ✅
+- [x] Duplicação removida: [%antes] → [%depois] ✅
+- [x] Lint sem warnings ✅
+- [x] Code review aprovado ✅
+
+### Performance (se aplicável)
+- [x] Benchmarks: [antes] → [depois] ✅
+- [x] Sem regressão de performance ✅
+
+---
+
+## Comparação Antes/Depois
+
+| Métrica | Antes | Depois | Melhoria |
+|---------|-------|--------|----------|
+| Linhas de código | [N] | [M] | [%] |
+| Complexidade | [N] | [M] | [%] |
+| Duplicação | [N]% | [M]% | [%] |
+| Cobertura | [N]% | [M]% | [%] |
+
+---
+
+✅ **Refatoração Validada**
+
+Pronto para deploy!
+```
+
+---
+
+### Passo 7: Fase 5 - Deploy
+
+```markdown
+🎯 **Fase 5/5: Deploy**
+
+## Estratégia de Deploy
+
+${estrategia === 'incremental' ? `
+✅ **Deploy Incremental** (Recomendado)
+
+1. Deploy de cada passo separadamente
+2. Monitorar métricas após cada deploy
+3. Rollback fácil se necessário
+
+Deploys:
+- ✅ Passo 1 → Prod (2026-01-20)
+- ✅ Passo 2 → Prod (2026-01-21)
+- 🔄 Passo 3 → Staging (testando)
+` : `
+⚡ **Deploy Único**
+
+Refatoração completa em um deploy.
+
+Checklist:
+- [ ] Testes passando em staging
+- [ ] Performance validada
+- [ ] Rollback plan pronto
+`}
+
+---
+
+## Monitoramento Pós-Deploy
+
+Métricas a observar por 24-48h:
+- Error rate
+- Response time
+- CPU/Memory usage
+- User behavior (se frontend)
+
+---
+
+Use: `/deploy production`
+```
+
+---
+
+## Exemplos de Uso
+
+### Exemplo 1: Refatorar Serviço Complexo
+
+```
+User: /mcp-refactor
+
+AI: Qual área deseja refatorar?
+
+User: Serviço de autenticação
+
+AI: Qual o motivo?
+
+User: complexidade
+
+AI: ✅ Fluxo iniciado (REF-001)
+    
+    🎯 Fase 1: Análise
+    
+    Arquivos:
+    - services/auth.service.ts (250 linhas, complexidade 15)
+    - utils/token.ts
+    
+    Problemas:
+    1. Método login() com 80 linhas (muito grande)
+    2. Lógica de validação duplicada 3x
+    3. Sem separação de responsabilidades
+    
+    Estratégia: Incremental (3 passos)
+    1. Extract validation logic
+    2. Split login method
+    3. Create TokenService
+    
+    Continuar?
+
+User: S
+
+AI: [Fase 2: Cria testes de caracterização]
+    
+    ✅ 12 testes criados (cobertura: 85%)
+    
+    Todos passando. Pronto para refatorar!
+
+User: /mcp-next
+
+AI: [Fase 3: Refatoração]
+    
+    Passo 1/3: Extract validation logic
+    
+    Antes:
+    ```ts
+    if (!email || !password) { ... }
+    if (!isValidEmail(email)) { ... }
+    ```
+    
+    Depois:
+    ```ts
+    const validator = new AuthValidator();
+    validator.validate({ email, password });
+    ```
+    
+    ✅ Testes passam
+    
+    Commit: "refactor: extract auth validation"
+    
+    Continuar passo 2? (S/N)
+```
+
+### Exemplo 2: Migração de Padrão
+
+```
+User: /mcp-refactor Migrar de callback para async/await
+
+AI: Motivo?
+
+User: migracao
+
+AI: ✅ Refactor initiated
+    
+    Detectei 15 funções com callbacks
+    
+    Estratégia:
+    - Criar versões async em paralelo
+    - Deprecar callbacks gradualmente
+    - Remover após migração completa
+    
+    Fase 1: Análise
+    [lista de funções]
+    
+    Fase 2: Testes
+    [testa callbacks atuais]
+    
+    Fase 3: Implementação async
+    [cria novas versões]
+    
+    Fase 4: Migração gradual
+    [troca chamadas uma por uma]
+```
+
+---
+
+## Comandos Relacionados
+
+```
+/mcp-refactor [área]        → Inicia refatoração
+/mcp-next                   → Avança entre fases/passos
+/mcp-status                 → Ver progresso da refatoração
+```
+
+---
+
+## Estratégias de Refatoração
+
+### Incremental (Recomendado)
+
+**Quando:** Código crítico, área grande, equipe grande
+
+**Vantagens:**
+- Risco menor
+- Rollback fácil
+- Review mais simples
+- Deploy contínuo
+
+### Big Bang
+
+**Quando:** Código isolado, área pequena, MVP
+
+**Vantagens:**
+- Mais rápido
+- Contexto único
+
+### Strangler Fig
+
+**Quando:** Migrar sistema legado
+
+**Passos:**
+1. Criar interface nova ao lado da antiga
+2. Redirecionar tráfego gradualmente
+3. Remover código antigo quando 100% migrado
+
+---
+
+## Padrões Comuns
+
+### Extract Method
+``` Função grande → Várias funções pequenas```
+
+### Extract Class
+```Classe god object → Várias classes especializadas```
+
+### Replace Conditional with Polymorphism
+```if/else gigante → Herança/interfaces```
+
+### Introduce Parameter Object
+```Muitos parâmetros → Objeto de configuração```
+
+---
+
+## Regras Críticas
+
+### ✅ SEMPRE:
+
+1. Criar testes ANTES de refatorar
+2. Commits pequenos e frequentes
+3. Validar após cada passo
+4. Preservar comportamento (sem features novas)
+5. Code review antes de merge
+
+### ❌ NUNCA:
+
+1. Refatorar sem testes
+2. Misturar refactor com nova feature
+3. Refatorar código que não entende
+4. Fazer mudanças grandes de uma vez
+5. Deploy sem validação
+
+---
+
+## Troubleshooting
+
+### Testes Quebram Durante Refatoração
+
+**Causa:** Comportamento mudou acidentalmente
+
+**Solução:**
+
+```
+1. Reverter último commit: git reset --hard HEAD~1
+2. Fazer mudança menor
+3. Validar testes
+
+
+4. Continuar
+```
+
+### Refatoração Muito Grande
+
+**Causa:** Scope creep
+
+**Solução:**
+
+```
+1. Parar refatoração atual
+2. Quebrar em múltiplos REF-XXX
+3. Fazer um por vez
+```