--- name: Refactor-Monolith description: Skill para decomposição segura de arquivos monolíticos. Análise estrutural profunda, mapeamento exaustivo de dependências, extração incremental com zero quebra de lógica. Exige entendimento completo do negócio antes de qualquer ação. --- # 🏗️ REFACTOR-MONOLITH - Decomposição Segura de Monolitos ## 🚨 PRINCÍPIO FUNDAMENTAL ``` ╔══════════════════════════════════════════════════════════════════╗ ║ NUNCA REFATORAR SEM ENTENDER 100% DA LÓGICA DE NEGÓCIO ║ ║ NUNCA EXTRAIR SEM MAPEAR 100% DAS DEPENDÊNCIAS ║ ║ NUNCA QUEBRAR O QUE FUNCIONA ║ ╚══════════════════════════════════════════════════════════════════╝ ``` **Regra de Ouro:** É melhor um monolito funcionando do que módulos quebrados. --- ## 📋 QUANDO USAR ESTA SKILL ### ✅ USAR QUANDO: - Arquivo com +500 linhas - Arquivo com +10 funções/métodos - Arquivo com múltiplas responsabilidades (UI + lógica + dados) - Arquivo difícil de manter/entender - Arquivo com funções que poderiam ser reutilizadas - Arquivo que múltiplos devs precisam mexer simultaneamente ### ❌ NÃO USAR QUANDO: - Arquivo funciona bem e não causa problemas - Refatoração apenas por "limpeza estética" - Prazo apertado sem tempo para testes - Não há entendimento completo do negócio - Sistema em produção crítica sem ambiente de teste --- ## 🔬 FASE 0: PRÉ-ANÁLISE (OBRIGATÓRIA) ### 0.1 Perguntas de Negócio (FAZER ANTES DE TUDO) ```markdown ANTES de olhar o código, entender: 1. PROPÓSITO - Qual o objetivo principal deste arquivo? - Que problema de negócio ele resolve? - Quem são os usuários das funcionalidades? 2. CRITICIDADE - Este arquivo é crítico para o sistema? - Quebrar aqui impacta faturamento/operação? - Há janela segura para mudanças? 3. HISTÓRICO - Por que ficou monolítico? (crescimento orgânico? pressa?) - Houve tentativas anteriores de refatorar? - Quais funcionalidades foram adicionadas recentemente? 4. EXPECTATIVA - Qual o resultado esperado da refatoração? - Quais módulos idealmente existiriam? - Há padrão de modularização já usado no projeto? ``` ### 0.2 Checklist de Viabilidade ```markdown □ Entendi o propósito de negócio do arquivo □ Sei quem usa cada funcionalidade □ Tenho acesso ao arquivo completo □ Posso testar após cada mudança □ Tenho rollback disponível (git) □ Não há deploy urgente pendente □ Stakeholder aprovou a refatoração ``` **Se qualquer item for NÃO → PARAR e resolver antes de continuar.** --- ## 🔍 FASE 1: ANÁLISE ESTRUTURAL PROFUNDA ### 1.1 Radiografia do Arquivo ```bash # Métricas básicas wc -l [arquivo] # Total de linhas grep -c "function\|=>" [arquivo] # Total de funções grep -c "async" [arquivo] # Funções assíncronas grep -c "export\|module.exports" [arquivo] # Exports # Complexidade grep -n "if\|else\|switch\|for\|while" [arquivo] | wc -l # Branches grep -n "try\|catch" [arquivo] | wc -l # Error handling grep -n "TODO\|FIXME\|HACK" [arquivo] # Débitos técnicos ``` ### 1.2 Mapa de Funções (DOCUMENTAR TODAS) ```markdown ## INVENTÁRIO DE FUNÇÕES - [nome-arquivo.js] | # | Função | Linha | Linhas | Responsabilidade | Dependências Internas | Chamada Por | |---|--------|-------|--------|------------------|----------------------|-------------| | 1 | init() | 15 | 45 | Inicialização | config, setupUI | main | | 2 | fetchData() | 60 | 30 | Busca API | formatResponse | init, refresh | | 3 | formatResponse() | 90 | 25 | Formata dados | - | fetchData | | ... | ... | ... | ... | ... | ... | ... | ### Legenda de Responsabilidades: - CONFIG: Configuração e constantes - INIT: Inicialização e setup - UI: Manipulação de DOM/interface - DATA: Busca e processamento de dados - CALC: Cálculos e lógica de negócio - UTIL: Utilitários genéricos - EVENT: Handlers de eventos - EXPORT: Exportação/download - CACHE: Gerenciamento de cache - VALID: Validações ``` ### 1.3 Análise de Responsabilidades ```markdown ## MATRIZ DE RESPONSABILIDADES ┌─────────────────────────────────────────────────────────────┐ │ RESPONSABILIDADE │ FUNÇÕES │ LINHAS │ % │ ├───────────────────────┼───────────────────┼────────┼───────┤ │ Configuração │ 2 │ 50 │ 5% │ │ Inicialização │ 3 │ 120 │ 12% │ │ Interface (UI) │ 8 │ 300 │ 30% │ │ Lógica de Negócio │ 5 │ 250 │ 25% │ │ Comunicação (API) │ 4 │ 150 │ 15% │ │ Utilitários │ 6 │ 80 │ 8% │ │ Event Handlers │ 4 │ 50 │ 5% │ ├───────────────────────┼───────────────────┼────────┼───────┤ │ TOTAL │ 32 │ 1000 │ 100% │ └─────────────────────────────────────────────────────────────┘ DIAGNÓSTICO: - UI (30%) + Lógica (25%) = 55% → Forte candidato a separação - Utilitários (8%) → Pode virar módulo compartilhado ``` --- ## 🕸️ FASE 2: MAPEAMENTO EXAUSTIVO DE DEPENDÊNCIAS ### 2.1 Dependências Internas (Dentro do Arquivo) ```markdown ## GRAFO DE DEPENDÊNCIAS INTERNAS funcaoA() ├── chama: funcaoB(), funcaoC() ├── usa variável: CONFIG, state └── modifica: elementoDOM funcaoB() ├── chama: funcaoD() ├── usa variável: CONFIG └── retorna para: funcaoA(), funcaoE() funcaoC() ├── chama: nenhuma ├── usa variável: state └── retorna para: funcaoA() ## VARIÁVEIS DE ESTADO COMPARTILHADAS | Variável | Tipo | Escrito por | Lido por | Crítica? | |----------|------|-------------|----------|----------| | state | object | init, fetchData | render*, calc* | SIM | | CONFIG | const | - | todos | NÃO | | currentPage | let | pagination | render | SIM | ``` ### 2.2 Dependências Externas (Fora do Arquivo) ```bash # Quem importa este arquivo? grep -r "require.*[nome-arquivo]\|import.*[nome-arquivo]" . --include="*.js" # Este arquivo importa quem? grep -n "require\|import" [arquivo] # Quais IDs/classes DOM são manipulados? grep -oE "(getElementById|querySelector)\\(['\"][^'\"]+['\"]\\)" [arquivo] # Quais rotas/endpoints são chamados? grep -oE "fetch\\(['\"][^'\"]+['\"]" [arquivo] grep -oE "/api/[^'\" ]+" [arquivo] ``` ### 2.3 Matriz de Acoplamento ```markdown ## MATRIZ DE ACOPLAMENTO │ config │ core │ ui │ utils │ EXTERNO ────────────────────┼────────┼──────┼────┼───────┼───────── config │ - │ ← │ ← │ ← │ core │ → │ - │ ←→ │ ← │ API ui │ → │ →← │ - │ ← │ DOM utils │ → │ → │ → │ - │ ────────────────────┼────────┼──────┼────┼───────┼───────── LEGENDA: → = depende de (importa/usa) ← = é dependido por (exporta para) ←→ = dependência mútua (ALERTA: difícil separar) ``` ### 2.4 Identificação de "Costuras Naturais" ```markdown ## COSTURAS PARA CORTE Uma "costura" é um ponto onde o código pode ser dividido com MÍNIMO impacto. ### COSTURAS IDENTIFICADAS: 1. ✅ COSTURA LIMPA: Funções utilitárias (linhas 800-900) - Não dependem de estado - Não acessam DOM - Funções puras - RISCO: Baixo 2. ⚠️ COSTURA MÉDIA: Configuração (linhas 1-50) - Constantes globais - Precisam ser importadas por todos módulos - RISCO: Médio (ordem de carregamento) 3. 🔴 COSTURA DIFÍCIL: UI + Core (linhas 200-600) - Dependência mútua - Estado compartilhado - RISCO: Alto (requer refatoração de estado primeiro) ### ORDEM RECOMENDADA DE EXTRAÇÃO: 1º → Utilitários (risco baixo, ganho rápido) 2º → Configuração (estabiliza imports) 3º → Separar estado em store 4º → UI (após estado isolado) 5º → Core (após UI isolado) ``` --- ## ❓ FASE 3: PERGUNTAS DE CLARIFICAÇÃO ### 3.1 Perguntas Obrigatórias ao Stakeholder ```markdown ANTES de propor estrutura de módulos, PERGUNTAR: ## SOBRE FUNCIONALIDADES 1. "A função [X] ainda é usada ou é código legado?" → Identificar dead code antes de extrair 2. "O comportamento de [Y] está correto ou há bugs conhecidos?" → Não perpetuar bugs em módulos novos 3. "Existe regra de negócio não documentada em [Z]?" → Capturar conhecimento tácito ## SOBRE PRIORIDADES 4. "Quais funções são mais críticas para o negócio?" → Priorizar estabilidade das críticas 5. "Quais partes mudam com mais frequência?" → Isolar partes voláteis 6. "Há planos de novas features que afetam este arquivo?" → Considerar evolução futura ## SOBRE RESTRIÇÕES 7. "Há restrições de performance a considerar?" → Evitar overhead de modularização excessiva 8. "Outros sistemas/equipes dependem deste código?" → Mapear consumidores externos 9. "Posso renomear funções ou há contratos fixos?" → Entender flexibilidade de interface ``` ### 3.2 Análise Lógica x Código ```markdown ## CHECKLIST: LÓGICA DE NEGÓCIO Para CADA função identificada, validar: □ Entendo O QUE esta função faz (propósito) □ Entendo POR QUE ela existe (regra de negócio) □ Entendo QUANDO ela é chamada (fluxo) □ Entendo QUEM depende do resultado (consumidores) □ O código reflete corretamente a lógica? □ Há edge cases tratados que não são óbvios? □ Há comentários explicando decisões de negócio? ## ALERTAS DE LÓGICA OCULTA 🚨 ATENÇÃO para: - Números mágicos sem explicação - Condicionais complexos (if dentro de if) - Try/catch que engole erros silenciosamente - Timeouts/delays sem justificativa - Ordenações específicas de operações - Validações que parecem redundantes (podem não ser) ``` --- ## 📐 FASE 4: PROPOSTA DE ARQUITETURA MODULAR ### 4.1 Template de Estrutura ```markdown ## PROPOSTA DE MODULARIZAÇÃO ### ARQUIVO ORIGINAL: `[caminho/arquivo-monolito.js]` (XXX linhas) ### ESTRUTURA PROPOSTA: ``` [pasta-modulo]/ ├── config.js # Constantes e configuração │ └── [XX linhas] - Funções: A, B │ ├── core.js # Lógica de negócio principal │ └── [XX linhas] - Funções: C, D, E │ ├── ui.js # Manipulação de interface │ └── [XX linhas] - Funções: F, G, H │ ├── api.js # Comunicação com backend │ └── [XX linhas] - Funções: I, J │ ├── utils.js # Utilitários │ └── [XX linhas] - Funções: K, L, M │ ├── events.js # Event handlers │ └── [XX linhas] - Funções: N, O │ └── index.js # Orquestrador (entry point) └── [XX linhas] - init, bindEvents ``` ### DIAGRAMA DE DEPENDÊNCIAS: ``` ┌──────────┐ │ index │ (entry point) └────┬─────┘ │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ ┌────────┐ ┌────────┐ ┌────────┐ │ core │◄────►│ ui │ │ events │ └───┬────┘ └───┬────┘ └───┬────┘ │ │ │ ▼ ▼ │ ┌────────┐ ┌────────┐ │ │ api │ │ config │◄─────────┘ └───┬────┘ └────────┘ │ ▼ ┌────────┐ │ utils │ (sem dependências internas) └────────┘ ``` ### REGRAS DE IMPORTAÇÃO: 1. `utils` → Não importa nenhum módulo interno 2. `config` → Não importa nenhum módulo interno 3. `api` → Importa apenas `utils`, `config` 4. `core` → Importa `api`, `utils`, `config` 5. `ui` → Importa `core`, `utils`, `config` 6. `events` → Importa `ui`, `core`, `config` 7. `index` → Importa todos, orquestra ``` ### 4.2 Validação da Proposta ```markdown ## CHECKLIST DE VALIDAÇÃO DA ARQUITETURA ### Princípios □ Cada módulo tem UMA responsabilidade clara □ Dependências fluem em uma direção (sem ciclos) □ Módulos podem ser testados isoladamente □ Nenhuma lógica de negócio duplicada □ Estado centralizado ou claramente distribuído ### Compatibilidade □ API pública (exports) permanece compatível □ Ordem de inicialização preservada □ Event listeners funcionam igual □ Performance não degradada ### Praticidade □ Estrutura segue padrão já usado no projeto □ Nomenclatura consistente □ Tamanho dos módulos equilibrado (não criar micro-módulos) ``` --- ## 🔧 FASE 5: EXTRAÇÃO INCREMENTAL SEGURA ### 5.1 Princípio da Extração Atômica ```markdown ╔══════════════════════════════════════════════════════════════════╗ ║ UMA FUNÇÃO POR VEZ ║ ║ UM COMMIT POR EXTRAÇÃO ║ ║ UM TESTE APÓS CADA MUDANÇA ║ ╚══════════════════════════════════════════════════════════════════╝ ``` ### 5.2 Protocolo de Extração ```markdown ## SEQUÊNCIA DE EXTRAÇÃO (para cada função) ### PASSO 1: Preparar ```bash # Criar branch git checkout -b refactor/extract-[nome-funcao] # Backup cp [arquivo-original].js [arquivo-original].js.backup ``` ### PASSO 2: Criar Módulo Destino (se não existir) ```javascript // [pasta]/[modulo-destino].js // Imports necessários (identificados na análise) // ... // Função extraída virá aqui // Export module.exports = { /* funções */ }; ``` ### PASSO 3: Copiar Função (NÃO recortar ainda) ```javascript // [pasta]/[modulo-destino].js function funcaoExtraida() { // Código COPIADO do original // Ainda não modificou o original } module.exports = { funcaoExtraida }; ``` ### PASSO 4: Testar Módulo Isolado ```bash # Verificar syntax node --check [modulo-destino].js # Teste unitário se possível node -e "const m = require('./[modulo-destino]'); console.log(m.funcaoExtraida);" ``` ### PASSO 5: Atualizar Original para Usar Módulo ```javascript // [arquivo-original].js // ADICIONAR import no topo const { funcaoExtraida } = require('./[pasta]/[modulo-destino]'); // MANTER função original COMENTADA (não deletar ainda) /* function funcaoExtraida() { // código antigo } */ // Código que chamava funcaoExtraida() continua funcionando // porque agora vem do import ``` ### PASSO 6: Testar Sistema Completo ```bash # Testar funcionalidade no browser/app # Verificar console por erros # Testar casos de uso principais ``` ### PASSO 7: Commit Atômico ```bash git add [modulo-destino].js [arquivo-original].js git commit -m "refactor: extract funcaoExtraida to [modulo] - Moved funcaoExtraida from monolith to dedicated module - Original function kept commented for safety - All tests passing" ``` ### PASSO 8: Só Depois de Validado, Remover Código Comentado ```bash # Após 1-2 dias sem problemas em produção # Remover função comentada do original git commit -m "chore: remove commented legacy funcaoExtraida" ``` ``` ### 5.3 Ordem de Extração Recomendada ```markdown ## ORDEM SEGURA DE EXTRAÇÃO NÍVEL 1 - RISCO ZERO (fazer primeiro) ├── Constantes e configuração ├── Funções utilitárias puras └── Funções sem dependências internas NÍVEL 2 - RISCO BAIXO ├── Funções de formatação ├── Funções de validação └── Helpers de cálculo NÍVEL 3 - RISCO MÉDIO ├── Funções de API/fetch ├── Funções de cache └── Event handlers simples NÍVEL 4 - RISCO ALTO (fazer por último) ├── Funções de UI que manipulam estado ├── Funções de inicialização └── Orquestradores/controllers NÍVEL 5 - NUNCA EXTRAIR SOZINHO ├── Funções com dependência circular ├── Funções que modificam estado global └── Funções com efeitos colaterais ocultos → Requer refatoração prévia do estado ``` --- ## ✅ FASE 6: VALIDAÇÃO E TESTES ### 6.1 Testes de Regressão ```markdown ## CHECKLIST DE REGRESSÃO (após cada extração) ### Funcional □ Feature principal funciona □ Features secundárias funcionam □ Edge cases funcionam □ Erros são tratados corretamente ### Performance □ Tempo de carregamento similar □ Sem memory leaks novos □ Sem requests duplicados ### Compatibilidade □ Funciona no Chrome □ Funciona no Firefox □ Funciona no Safari □ Funciona no mobile ### Multi-tenant (se aplicável) □ Dados isolados por liga_id □ Sem vazamento entre tenants ``` ### 6.2 Smoke Test Rápido ```javascript // Script de smoke test async function smokeTest() { const checks = []; // 1. Módulos carregam sem erro try { const config = require('./config'); const core = require('./core'); const ui = require('./ui'); checks.push({ name: 'Modules load', status: '✅' }); } catch (e) { checks.push({ name: 'Modules load', status: '❌', error: e.message }); } // 2. Funções existem const requiredFunctions = ['init', 'render', 'fetchData']; requiredFunctions.forEach(fn => { const exists = typeof core[fn] === 'function'; checks.push({ name: `Function ${fn}`, status: exists ? '✅' : '❌' }); }); // 3. Exports corretos // ... console.table(checks); return checks.every(c => c.status === '✅'); } ``` --- ## 🚨 FASE 7: ROLLBACK E RECUPERAÇÃO ### 7.1 Plano de Rollback ```markdown ## ROLLBACK PLAN ### Cenário 1: Bug detectado imediatamente ```bash # Reverter último commit git revert HEAD ``` ### Cenário 2: Bug detectado após múltiplas extrações ```bash # Voltar para estado antes da refatoração git log --oneline # Encontrar commit anterior git checkout [hash-commit-seguro] -- [arquivo-original].js ``` ### Cenário 3: Rollback completo ```bash # Voltar branch inteira git checkout main git branch -D refactor/[nome] # Restaurar backup cp [arquivo].js.backup [arquivo].js ``` ### Cenário 4: Produção quebrou ```bash # Deploy emergencial do backup # 1. Reverter no git # 2. Rebuild # 3. Deploy # 4. Investigar em ambiente de dev ``` ``` ### 7.2 Pontos de Verificação ```markdown ## CHECKPOINTS DE SEGURANÇA Criar checkpoint ANTES de: □ Extrair primeira função □ Extrair função crítica □ Modificar estrutura de estado □ Alterar ordem de inicialização □ Remover código comentado Checkpoint = commit + tag ```bash git commit -m "checkpoint: before extracting [funcao]" git tag checkpoint-[nome]-[data] ``` ``` --- ## 📋 TEMPLATES E CHECKLISTS ### Template: Documento de Refatoração ```markdown # REFATORAÇÃO: [Nome do Arquivo] ## Metadata - **Arquivo:** [caminho/arquivo.js] - **Linhas:** [XXX] - **Data início:** [data] - **Responsável:** [nome] - **Status:** [Em análise | Em andamento | Concluído | Pausado] ## Motivação [Por que refatorar este arquivo?] ## Análise - Funções identificadas: [X] - Responsabilidades: [lista] - Dependências externas: [lista] - Riscos identificados: [lista] ## Estrutura Proposta [Diagrama de módulos] ## Plano de Execução | # | Extração | Risco | Status | Data | |---|----------|-------|--------|------| | 1 | utils.js | Baixo | ✅ | [data] | | 2 | config.js | Baixo | ⏳ | | | ... | ... | ... | ... | | ## Validações - [ ] Testes funcionais - [ ] Testes de regressão - [ ] Review de código - [ ] Aprovação stakeholder ## Rollback [Instruções de rollback] ## Lições Aprendidas [Preencher ao final] ``` ### Checklist Master ```markdown ## CHECKLIST COMPLETO - REFATORAÇÃO DE MONOLITO ### PRÉ-REFATORAÇÃO □ Entendi 100% da lógica de negócio □ Mapeei 100% das dependências □ Identifiquei costuras naturais □ Proposta aprovada pelo stakeholder □ Tenho ambiente de teste □ Tenho plano de rollback □ Branch criada □ Backup feito ### DURANTE REFATORAÇÃO □ Extraindo uma função por vez □ Commitando após cada extração □ Testando após cada commit □ Mantendo código antigo comentado □ Documentando decisões ### PÓS-REFATORAÇÃO □ Todos testes passando □ Performance validada □ Multi-tenant validado □ Code review feito □ Documentação atualizada □ Código comentado removido □ Branch mergeada □ Tag de versão criada ### MONITORAMENTO (1 semana após) □ Sem bugs reportados □ Sem degradação de performance □ Equipe consegue manter novos módulos □ Lições aprendidas documentadas ``` --- ## 🚫 ANTI-PATTERNS (NUNCA FAZER) ### ❌ Big Bang Refactor ``` ERRADO: Refatorar tudo de uma vez, commitar no final CERTO: Uma extração por vez, um commit por extração ``` ### ❌ Refatorar Sem Entender ``` ERRADO: "Vou separar em módulos porque está grande" CERTO: "Entendi que X faz Y por causa de Z, posso extrair" ``` ### ❌ Deletar Código Imediatamente ``` ERRADO: Recortar função do original para o módulo CERTO: Copiar, testar, só depois comentar, só depois deletar ``` ### ❌ Criar Micro-Módulos ``` ERRADO: Um arquivo por função (50 arquivos de 20 linhas) CERTO: Agrupar por responsabilidade (5-8 arquivos coesos) ``` ### ❌ Ignorar Dependências Circulares ``` ERRADO: Extrair A que depende de B que depende de A CERTO: Resolver ciclo primeiro (extrair dependência comum C) ``` ### ❌ Refatorar e Adicionar Feature ``` ERRADO: "Já que estou mexendo, vou melhorar X também" CERTO: Refatoração pura, sem mudança de comportamento ``` --- ## 🎯 COMANDOS DE ATIVAÇÃO ### Iniciar Análise ``` @Refactor-Monolith analisar [caminho/arquivo.js] ``` ### Continuar de Fase Específica ``` @Refactor-Monolith fase-2 [caminho/arquivo.js] # Mapeamento @Refactor-Monolith fase-4 [caminho/arquivo.js] # Proposta @Refactor-Monolith fase-5 [caminho/arquivo.js] # Extração ``` ### Extrair Função Específica ``` @Refactor-Monolith extrair [funcao] de [origem] para [destino] ``` --- ## 📚 REFERÊNCIAS ### Princípios Aplicados - S.A.I.S (Solicitar → Analisar → Identificar → Alterar) - S.D.A (Sistema de Dependências Arquiteturais) - Antipattern (Preservar intenção original) - Preservação da Lógica (Nunca quebrar funcionalidade) ### Integração com Workflow ``` /pesquisa → identifica monolito problemático /Refactor-Monolith → planeja decomposição /spec → detalha mudanças cirúrgicas /code → implementa extrações ``` --- **STATUS:** 🏗️ REFACTOR-MONOLITH - SURGICAL DECOMPOSITION PROTOCOL **Versão:** 1.0 **Última atualização:** 2026-01-17