3AceShowHand/agent-skills

Refatorar

Quando Usar

• O usuário pede refatoração, reestruturação, movimentação de código, divisão ou fusão de módulos, simplificação de interface, reescrita em etapas, inversão de dependência ou remoção de código duplicado.
• Uma alteração afirma preservar o comportamento enquanto muda a estrutura.
• Uma refatoração afeta vários pontos de chamada, símbolos públicos, testes ou limites de propriedade.

Quando Não Usar

• A tarefa é uma pequena correção local de bug sem alteração estrutural.
• O usuário pede explicitamente uma alteração de comportamento e não uma refatoração que preserve o comportamento.
• Uma revisão de design mais ampla é necessária antes de decidir se deve refatorar.
• O primeiro passo correto é uma revisão ampla de engenharia porque a área de risco dominante ainda não está clara.

Fluxo de Trabalho

1. Definir o comportamento a ser preservado e a estrutura a ser alterada.
2. Declarar não-objetivos: nenhuma mudança de funcionalidade, nenhuma mudança de compatibilidade, nenhuma mudança de semântica de erros, nenhuma alegação de desempenho a menos que solicitado explicitamente.
3. Inspecionar chamadores, testes, documentação, configurações, código gerado e superfícies públicas afetados pela refatoração.
4. Adicionar testes de caracterização quando o comportamento é importante e a cobertura é fraca.
5. Dividir o trabalho em pequenos passos reversíveis que compilam e testam entre limites significativos.
6. Separar movimentos ou renomeações mecânicas de edições semânticas.
7. Preservar APIs públicas, a menos que o usuário solicite explicitamente uma mudança abrupta.
8. Remover caminhos antigos somente depois que os chamadores forem migrados e o comportamento for verificado.

Referências

• Leia references/refactor-playbook.md antes de planejar uma refatoração de múltiplas etapas.
• Leia references/characterization-tests.md quando os testes forem fracos ou o comportamento precisar ser estabilizado.
• Leia references/review-checklist.md antes de finalizar uma refatoração.

Condições de Parada

• O comportamento preservado não está claro.
• A refatoração requer mudanças amplas de comportamento para ter sucesso.
• API pública, configuração, protocolo, armazenamento, métricas ou semântica de erros podem mudar sem aprovação explícita do usuário.
• O diff mistura refatoração, trabalho de funcionalidade, otimização de desempenho e limpeza de forma que não pode ser revisado com segurança.

Regras de Saída

• Relatar qual comportamento foi pretendido permanecer inalterado.
• Relatar alterações mecânicas separadamente das alterações semânticas.
• Relatar testes ou verificações que protegem o comportamento.
• Declarar quaisquer aspectos de comportamento, compatibilidade ou desempenho não verificados.