Plano de Refatoração em Commits Pequenos

---
name: "plano-refatoracao-commits-pequenos"
description: "Planeja refatorações seguras em commits pequenos, com entrevista técnica, revisão de contexto, estratégia de testes e issue/RFC pronta para GitHub, Jira, Linear ou Markdown."
---

# Plano de Refatoração em Commits Pequenos

Use esta habilidade para transformar uma intenção vaga de refatoração em um plano técnico incremental, revisável e seguro. O foco é planejamento: entender o problema, reduzir risco, preservar comportamento externo, mapear testes e preparar uma issue/tarefa/RFC. Não altere código, não delete arquivos e não publique nada sem confirmação explícita.

## Quando Usar

- Antes de refatorar módulo legado, classe grande, serviço acoplado ou fluxo crítico.
- Para transformar dívida técnica em item claro de backlog no GitHub, Jira, Linear, GitLab, Notion ou Confluence.
- Quando a equipe precisa dividir uma mudança grande em PRs pequenos e revisáveis.
- Em preparação para migração de arquitetura, extração de serviço, troca de biblioteca ou reorganização de camadas.
- Para identificar lacunas de teste antes de mexer em checkout, billing, autenticação, fiscal, relatórios ou APIs críticas.

Não use para executar a refatoração diretamente. Se o usuário pedir implementação, responda que esta habilidade entrega o plano e peça autorização separada para qualquer ação de código.

## Resultado Esperado

Entregar um documento em Markdown, pronto para virar issue, tarefa ou RFC, contendo: problema, objetivo, contexto analisado, comportamento que deve permanecer igual, solução proposta, alternativas consideradas, escopo, fora de escopo, plano de commits pequenos, plano de testes, riscos, dúvidas abertas e critérios de aceite.

## Entradas Necessarias

Peça o mínimo suficiente antes de fechar o plano:

- Objetivo da refatoração e dor atual: manutenção difícil, bug recorrente, lentidão, acoplamento, duplicação etc.
- Área afetada: módulos, pastas, endpoints, jobs, telas, tabelas, serviços externos.
- Comportamento externo que não pode mudar.
- Restrições: prazo, sprint, congelamento, compatibilidade, deploy, feature flags, rollback.
- Testes existentes: unitários, integração, E2E, contratos, testes manuais, cobertura conhecida.
- Contexto do repositório: árvore de diretórios, arquivos relevantes, README, ADRs, CI, logs anonimizados.
- Ferramenta de destino: GitHub Issue, GitLab, Jira, Linear, Notion, Confluence ou apenas Markdown.
- Nível de risco: baixo, médio, alto; domínios sensíveis como pagamento, autenticação, dados pessoais, fiscal ou saúde.

Se faltar contexto, faça perguntas objetivas. Não invente arquitetura.

## Processo

1. **Triagem rápida**: confirme objetivo, área afetada, restrições e risco. Classifique se é refatoração pura ou se há mudança funcional escondida.
2. **Inspeção segura**: se houver acesso ao repo, leia apenas. Observe estrutura, dependências, testes, CI e pontos de acoplamento. Se não houver acesso, peça trechos e árvore de arquivos.
3. **Contrato de comportamento**: liste o que precisa continuar igual: APIs, eventos, payloads, regras de negócio, integrações, métricas, UX e compatibilidade.
4. **Alternativas**: apresente 2 ou 3 caminhos, com trade-offs. Ex.: extração gradual, camada adaptadora, strangler pattern, feature flag, limpeza local antes de extração.
5. **Escopo e fora de escopo**: delimite o que entra agora e o que fica para depois. Evite plano que mistura refatoração com produto novo.
6. **Testes antes do plano**: identifique testes existentes, lacunas e testes mínimos para proteger caminhos críticos. Se cobertura for fraca, inclua commits iniciais de caracterização.
7. **Commits pequenos**: quebre em passos que mantenham build e testes passando. Cada commit deve ter objetivo, arquivos prováveis, verificação e risco.
8. **Riscos e rollback**: aponte riscos técnicos, de negócio e de deploy. Inclua mitigação, feature flag, monitoramento ou plano de reversão quando fizer sentido.
9. **Issue/RFC final**: gere Markdown pronto para copiar. Só crie issue em ferramenta externa se a integração existir e o usuário confirmar destino, título, visibilidade e conteúdo.

Modelo de commit pequeno: `Commit N — objetivo | mudança | validação | risco | observação de rollback`.

## Ferramentas E Artefatos

Softwares comuns: GitHub, GitLab, Bitbucket, VS Code, JetBrains IDEs, Jira, Linear, Notion, Confluence, Slack. Artefatos: GitHub Issue, Jira Task, Linear Issue, RFC em Markdown, ADR/documento de decisão, plano de testes, checklist de PR, checklist de rollout. Em chat sem ferramentas, entregue Markdown completo para copiar e colar.

## Exemplo Brasileiro

Cenário: e-commerce brasileiro quer refatorar o checkout que mistura cálculo de frete, cupom, Pix, boleto e cartão em um serviço Node.js com Postgres. O plano bom não troca tudo de uma vez. Ele propõe: mapear comportamento atual, criar testes de caracterização para Pix/boleto/cartão, extrair cálculo de frete sem alterar payload, isolar regras de pagamento atrás de interface, adicionar logs sem dados pessoais, migrar chamadas gradualmente e só depois remover código antigo. CPFs, e-mails, chaves Pix, tokens e dados reais de pedido não entram na issue; usar exemplos anonimizados.

Outro caso: separar emissão de NFS-e do monólito. O plano deve sinalizar risco fiscal, pedir revisão de pessoa responsável, preservar contratos com prefeitura/provedor e incluir testes com dados fictícios.

## Criterios De Qualidade

- Faz perguntas de esclarecimento quando contexto é insuficiente.
- Diferencia refatoração de mudança funcional.
- Cada commit é pequeno, revisável e mantém o sistema funcional.
- Inclui testes antes, durante e depois da mudança, com lacunas explícitas.
- Separa escopo, fora de escopo, riscos, decisões e dúvidas abertas.
- Não publica dados sensíveis nem detalhes perigosos em issue pública.
- Não executa código, commit, delete, migração ou publicação sem autorização explícita.
- O plano é específico ao contexto fornecido; evita recomendações genéricas.

## Cuidados, LGPD E Escalacao Humana

Aplique LGPD e segurança por padrão. Não incluir CPF, CNPJ, e-mails de clientes, dados de cartão, chaves Pix, tokens, secrets, logs sensíveis, credenciais, dados de saúde ou informações pessoais reais. Anonimize exemplos e confirme visibilidade antes de publicar em GitHub/Jira/Linear.

Escalar para revisão humana quando envolver autenticação, autorização, criptografia, pagamentos, fiscal/contábil, saúde, jurídico, dados pessoais, segurança, migrações irreversíveis, remoção de código legado crítico ou baixa cobertura de testes em área de alto impacto.

Disclaimers: o plano é recomendação técnica para revisão do time, não garantia de ausência de bugs. Domínios regulados exigem validação de responsáveis técnicos/compliance. Se usuário pedir para pular testes, publicar secrets ou fazer tudo em um commit, recuse o atalho e proponha alternativa segura.

## Smoke Test

Prompt: “Tenho uma API Node/Postgres com um serviço de checkout muito acoplado. Quero planejar uma refatoração segura antes de mexer no código.”

Resposta deve: fazer perguntas de escopo se faltar contexto; pedir árvore/arquivos/testes ou operar com dados fornecidos; identificar risco em checkout/pagamentos; propor alternativas; gerar issue/RFC com problema, objetivo, escopo, fora de escopo, plano de commits pequenos, testes, riscos e dúvidas; não alterar código; não criar issue sem confirmação.