boshu2/refatorar

Refatorar — um experimento estrutural

Refatorar altera a estrutura preservando o comportamento observável. Ela executa uma transformação escolhida pelo solicitante e relata o resultado.

Prompt

Refatore billing-service/internal/retry/backoff.go: extraia o cálculo de backoff exponencial de RetryRequest para sua própria função, sem nenhuma outra mudança de comportamento. Registre uma linha de base, execute go test ./internal/retry/... antes e depois, e reporte o resumo do diff, comandos, resultados e tudo que não foi verificado.

Funciona quando

• O relatório nomeia o comportamento preservado e cita a execução de go test ./internal/retry/... tanto antes quanto depois.
• git diff --stat toca apenas internal/retry/backoff.go, nunca um arquivo não relacionado.
• Hashes de saídas douradas são capturados e comparados byte a byte sempre que a superfície alterada produz saída, ex.: sha256sum antes e depois.
• A lista de comportamento não verificado do relatório está presente na saída mesmo quando vazia, nomeando qualquer superfície que os portões pularam.

Procedimento

1. Nomeie o comportamento preservado, a superfície de aceitação focada e o problema estrutural concreto para seus chamadores. Reutilize os termos de domínio dos chamadores e exemplos comportamentais aceitos; preserve seu significado durante a mudança.
2. Registre uma linha de base honesta, incluindo quaisquer falhas ambientais reproduzíveis. Para uma avaliação comparando comportamento executável, fixe o código-fonte inicial e construa sua linha de base antes das edições; mantenha esse binário e as entradas de comparação. Compare o candidato usando essas entradas e o mesmo conjunto de ferramentas. Isso não adiciona nenhum ritual de comparação executável à refatoração comum.
3. Aplique uma transformação delimitada: extrair, renomear, inserir, simplificar, encapsular, mover ou remover código morto. Julgue o resultado pelo que os chamadores devem entender e onde uma regra de domínio deve ser alterada, não apenas pelo tamanho do arquivo.
4. Execute a verificação focada e a menor verificação de regressão no nível de pacote justificada pela superfície alterada.
5. Retorne o resumo do diff, comandos, resultados e comportamento não verificado.

Não combine uma correção de comportamento recém-descoberta com a mudança estrutural. Um resultado vermelho é evidência para o solicitante; esta skill não reverte, restringe, tenta novamente, confirma, valida ou encaminha trabalho subsequente automaticamente.

Custo de responsabilidade e interface

Antes de adicionar uma interface ou dividir um módulo, inspecione chamadores representativos. Conte os conceitos que eles precisam coordenar: configuração necessária, ordenação, estados, tratamento de erros e regras de domínio repetidas. Um limite útil coloca uma regra coesa sob um único dono e permite que os chamadores solicitem um resultado sem reproduzir essa regra. Rejeite um wrapper que apenas adiciona outro nome ou empurra a mesma coordenação para seus chamadores. Limites existentes são suficientes quando nenhum problema concreto do chamador justifica alterá-los.

Use o vocabulário do chamador para operações e tipos extraídos. Uma ambiguidade de nomenclatura que altera o comportamento pertence à definição de domínio existente; consulte Domain apenas quando essa distinção precisar de trabalho. Renomear um símbolo público, campo persistido ou valor de protocolo é uma mudança de compatibilidade a menos que o escopo aceito a forneça.

Quando a transformação precisar de uma emenda — um limite de extração, interface ou divisão de módulo — e houver mais de um candidato a emenda, sonde antes de cortar. Execute a sonda em isolamento descartável (um branch de rascunho, worktree ou árvore copiada que a política do solicitante permita): esboce a emenda, veja o que ela força — chacoalhada de assinatura, ciclos de importação, reescrita de testes — depois descarte a sonda e mantenha apenas o conhecimento. Condição de parada: no máximo duas sondas; se o segundo candidato a emenda também resistir, reporte ambas as descobertas ao solicitante em vez de tentar uma terceira. Cortar a primeira emenda imaginável diretamente na árvore de trabalho é o modo de falha emenda prematura: o limite errado se calcifica porque revertê-lo agora custa mais do que conviver com ele.

Portões de neutralidade

"Preservação de comportamento" é uma afirmação a ser executada, não declarada. Proteja a transformação com prova de identidade comportamental:

• A verificação focada e a verificação de regressão no nível de pacote passam tanto antes quanto depois, com o mesmo conjunto de falhas preexistentes — nenhum vermelho novo, e nenhum vermelho que silenciosamente desapareceu (um teste que para de executar é uma mudança de comportamento).
• Para superfícies que produzem saída (geradores, serializadores, formatadores, relatórios), aplique hash nas saídas: capture hashes de saída dourada sobre entradas idênticas antes da mudança e compare byte a byte depois. Uma divergência de hash é uma diferença de comportamento a ser exposta e explicada, nunca ignorada; o solicitante decide se deve manter, restringir ou reverter a mudança.
• Mensagens de erro observáveis, códigos de saída e assinaturas públicas na superfície alterada fazem parte do comportamento, a menos que o solicitante os exclua.

Um portão de neutralidade que foi pulado ou restringido depois do fato é o modo de falha neutralidade post-hoc — o diff decide o que foi testado. Nomeie qualquer superfície que os portões não cobriram na lista de comportamento não verificado do relatório.

Referências

• Simplificação preservadora de comportamento
• Cenários comportamentais
• Referência de capacidade upstream — Matt Pocock; adaptação original AgentOps.