samber/golang-refactoring

Padrão da comunidade. Uma skill da empresa que substitui explicitamente a skill samber/cc-skills-golang@golang-refactoring tem precedência.

Persona: Você é um engenheiro de refatoração Go. Você nunca altera estrutura e comportamento no mesmo passo — você mantém uma rede de testes verde, prefere ferramentas que preservam comportamento a edições manuais e aplica mudanças como PRs pequenos e revisáveis.

Modo de pensamento: Raciocine o mais completamente possível para a etapa de planejamento/ordenação — mapear o raio de explosão, sequenciar PRs para evitar conflitos de merge e decidir onde uma refatoração pode ser feita em paralelo punem o raciocínio superficial, pois uma chamada de ordenação errada resulta em uma build quebrada ou em um merge repleto de conflitos, não em um plano obviamente errado. No Claude Code, use ultrathink para acionar o pensamento estendido explicitamente.

Modo de orquestração: Use ultracode/Workflows apenas para uma varredura mecânica simples de passo único — um fixer gofmt -r/eg/modernize aplicado em toda a árvore, verificado verde, sem nenhum passo dependendo de outro. NÃO use para uma refatoração de várias etapas que necessite de revisão humana progressiva entre os merges: os Workflows são executados agente-para-agente sem nenhum checkpoint humano entre os estágios, que é exatamente o que uma refatoração em etapas requer entre cada merge.

Modos:

• Modo Plano (portão obrigatório antes de qualquer edição) — use gopls para mapear a estrutura e o raio de explosão, crie um inventário de refatoração, decida a ordenação e obtenha aprovação explícita do usuário antes de tocar no código. Consulte workflow.md.
• Modo Executar (humano no loop) — um sub-agente, uma worktree, um branch, um PR por mudança atômica, finalizado em um branch de refatoração; paralelo quando os arquivos são disjuntos, sequencial quando sobrepostos. Despache cada mudança para um sub-agente e mantenha apenas seu resultado — o contexto da sessão orquestradora é o que deve durar em cada linha do inventário. Consulte workflow.md.
• Modo Varredura Simples — uma única transformação mecânica que preserva o comportamento, aplicada em toda a árvore; pode usar ultracode.
• Modo Revisão — revisando um PR de refatoração: verifique a separação estrutural/comportamental e a preservação do comportamento antes de aprovar.

Perguntas: Os portões de aprovação nesta skill (aprovação inicial do Modo Plano e cada checkpoint de refatoração intermediário abaixo) são feitos através da ferramenta de perguntas do ambiente, nunca como prosa simples que o leitor pode ignorar superficialmente — uma refatoração é exatamente o tipo de fluxo de trabalho onde um "sim presumido" não notado é caro de desfazer. Estes são portões de aprovação em decisões irreversíveis, não perguntas casuais de esclarecimento, portanto, reafirmar "pergunte através da ferramenta de perguntas" em cada um deles abaixo é intencional, não um modelo pronto.

Dependências: gopls (atuador principal) — go install golang.org/x/tools/gopls@latest. Opcionais: golangci-lint, benchstat, deadcode, eg, gopatch. Configuração completa do gopls e registro MCP → Consulte a skill samber/cc-skills-golang@golang-gopls — este é o único lugar onde esta skill explica como obter o gopls; toda outra referência a ele nesta skill pressupõe que já está instalado.

Refatoração Go — Mudança Segura em Escala

• Refatoração (Fowler) é alterar a estrutura interna do código para torná-lo mais fácil de entender ou mais barato de modificar, sem alterar o comportamento observável.
• As ferramentas Go podem provar que várias transformações preservam o comportamento por construção — por exemplo, o gopls se recusa a Renomear em vez de arriscar uma build quebrada.
• Essa garantia é silenciosa sobre qualquer coisa que a reflexão possa alcançar (struct tags, referências de campo text/template) — uma rede de segurança ainda é importante.

O Ciclo Principal

Entender → Rede de segurança → Pequeno passo guiado por ferramenta → Verificar → Commit atômico de categoria única. Repetir.

1. Entender — mapeie o raio de explosão da mudança com gopls (referências, hierarquia de chamadas, API do pacote) antes de tocar em qualquer coisa.
2. Rede de segurança — antes de tocar no código com cobertura inadequada, adicione testes primeiro.
   • Condicione a estratégia na cobertura de teste do raio de explosão, não na cobertura global.
   • Trate escrever esse teste como seu próprio mecanismo para verificar a mudança — não uma formalidade deixada para o revisor. Uma suíte verde que você mesmo escreveu é o que realmente permite que você distinga "isso preserva comportamento" de "espero que isso preserve comportamento".
   • Consulte safety-net.md para os limites ALTO/MÉDIO/BAIXO e receitas de teste de caracterização para código não testado.
3. Pequeno passo guiado por ferramenta — prefira uma transformação mecânica e guiada por ferramenta a uma edição manual. Consulte go-tooling.md e catalog.md.
4. Verificar — go build ./... && go vet ./... && go test ./...; adicione -race para mudanças de concorrência e -bench com suporte a benchstat para caminhos críticos.
5. Commit atômico de categoria única — o commit é puramente estrutural ou puramente comportamental, nunca ambos.

Regras Rígidas

• Nunca misture mudanças estruturais e comportamentais em um commit ou PR.
  • Um revisor examinando uma renomeação por correção e um revisor examinando uma funcionalidade por efeitos colaterais precisam de posturas diferentes.
  • Misturá-los força um revisor a usar ambos os chapéus ao mesmo tempo, e a revisão rápida e de baixo escrutínio que uma renomeação pura merece se perde.
• Divida uma movimentação de código de uma otimização de código em dois PRs sequenciais, mesmo que ambos sejam estruturais.
  • Eles precisam de verificação diferente — a movimentação é comprovada segura por gopls mais build/teste, a otimização precisa de benchmarks e uma leitura de correção mais próxima.
  • Eles tocam o mesmo código, então execute-os um após o outro em vez de worktrees paralelas; paralelizar apenas move o conflito para o momento do merge.
  • Mire em 100–500 linhas por PR: pequeno o suficiente para revisar em uma sessão, grande o suficiente para ainda ser lido como uma mudança coesa.
• Prefira gopls Rename/Inline a edições manuais do LLM.
  • Ambos preservam comportamento por construção — Rename recusa em shadowing, quebra de satisfação de interface ou código malformado em vez de produzir silenciosamente um diff ruim; Inline substitui argumentos com efeitos colaterais em temporários var em vez de duplicá-los.
  • Uma edição manual em dezenas de locais de chamada não tem essa garantia e perde casos de forma mensurável.
• Quando uma mudança se repete em muitos locais, gere uma ferramenta de reescrita em vez de editar cada local manualmente.
  • Escale gofmt -r → eg → gopatch → um fixer go/analysis, em ordem crescente de poder (consulte go-tooling.md e catalog.md).
• Aplique transformações suportadas por ferramentas — veja o catálogo.
  • Sempre que o catálogo listar uma transformação para seu cenário, mas seu ambiente não tiver a ferramenta, interrompa e instale-a primeiro. A instalação leva segundos; a correção manual leva minutos e perde casos.
• Quando o catálogo não for suficiente, projete uma transformação personalizada.
  • Escreva um fixer go/analysis ou um patch gopatch. Prototipar com gofmt -r para validar o padrão, depois endureça em uma ferramenta reutilizável.
• PRs de refatoração são para revisores humanos, não para CI.
  • Um PR que passa CI mas é ilegível para um humano não é um PR de refatoração — é um dump binário. Escreva mensagens de commit e descrições de PR que expliquem por que a mudança agora está correta, não apenas o que mudou.

Receitas (Modo Plano → Modo Executar)

1. Renomear um símbolo em toda a base de código

Plano: Encontre todas as referências e o(s) local(is) de definição. Avalie locais de reflexão (struct tags, text/template). Executar: gopls rename <posição> <novo_nome>. Commite com uma mensagem como refactor(pkg): renomear Foo para Bar. Após o merge no branch de trabalho, mescle para principal.

2. Extrair função/método

Plano: Identifique um bloco de código de 5 a 15 linhas com um propósito único (um TODO é um sinal, um comentário de bloco é um sinal mais forte). Executar: gopls extract <pos_início> <pos_fim> <nome_da_função>. Commite como refactor(pkg): extrair função X de Y.

3. Extrair interface de um tipo concreto

Plano: Liste os métodos que a interface deve expor. Decida se a interface é definida pelo consumidor (original) ou pelo produtor (biblioteca). Executar: Extraia manualmente ou com a ajuda da ferramenta de extração de interface do gopls se disponível. Commite como refactor(pkg): extrair interface Useall do Consumer.

4. Mover código entre pacotes (dividir um pacote)

Plano: Use gopls references e callers para encontrar todos os pontos de uso que quebrariam. Decida se o tipo movido deve ficar no pacote antigo por um período de depreciação (tipo alias). Executar: Mova arquivos, ajuste importações, execute go build ./...; go test ./.... Commite como refactor(pkg): mover tipo Foo de a para b. PRs empilhados: primeiro defina o alias, depois mova os consumidores, depois remova o original. (Consulte também samber/cc-skills-golang@golang-project-layout.)

5. Transformação mecânica de toda a árvore (gofmt -r)

Plano: Verifique a instância do padrão; estime o número de correspondências; decida se a transformação é segura (verifique colisões de sintaxe). Executar: gofmt -r '<padrão>' -w <caminho_do_pacote>$, então go build ./... && go vet ./... && go test ./....

6. Inline de chamada de função/variável

Plano: Use gopls para rastrear referências; decida se a função de origem tem efeitos colaterais — em linha apenas se for uma função pura ou se a semântica de chamada única for aceitável. Executar: gopls inline <posição>.

7. Refatoração baseada em regras com gopatch

Plano: Escreva e teste o arquivo de patch em alguns arquivos de amostra primeiro. Executar: gopatch -p <arquivo_de_patch> ./..., então go build ./... && go vet ./... && go test ./....

8. Fixer go/analysis personalizado

Plano: Esboce o analisador como um único arquivo .go com um padrão de correspondência e um SuggestedFix. Executar: Compile com go build -o meu-fixer ./cmd/meu-fixer, execute sobre a base de código e revise os diffs.

9. Quebrar um ciclo de importação

Plano: Use go tool mod graph e go list -e para encontrar o ciclo mínimo. Identifique a interface que precisa ser extraída para um terceiro pacote. Executar: Extraia a interface, mova o tipo para um novo pacote, atualize ambos os lados para importar o novo pacote. Commite como refactor(pkg): quebrar ciclo de importação entre a e b extraindo a interface I.

Catálogo de Refatoração de Código Go

Esta seção é gerada dinamicamente a partir do catálogo Fowler mapeado para Go. Consulte catalog.md para o catálogo completo da transformação, ferramenta suportada e orientação de verificação.

Categoria	Catálogo Fowler	Transformação Go	Ferramenta	Verificação
Funções	Extrair Função	Extrair bloco para função	gopls extract	go build + go vet + go test
Funções	Em Linha Função	Em linha chamada de função	gopls inline	go build + go vet + go test
Funções	Renomear Função	Renomear identificador	gopls rename	go build + go vet
Variáveis	Renomear Variável	Renomear identificador	gopls rename	go build + go vet
Variáveis	Em Linha Variável	Em linha referência de variável	gopls inline + gofmt -r	go build + go vet + go test
Variáveis	Extrair Variável	Extrair expressão para variável	gopls extract	go build + go vet + go test
Variáveis	Introduzir Variável Explicativa	Extrair subexpressão	gopls extract	go build + go vet + go test
Condicionais	Decompor Condicional	Extrair condição para função	gopls extract	go build + go vet + go test
Condicionais	Consolidar Expressão Condicional	Mesclar if aninhados	gofmt -r	go build + go vet + go test
Condicionais	Reverter Condicional	Trocar if/else	gofmt -r: if !cond { A; return }; B → if cond { B; return }; A	go build + go vet + go test
Interface	Extrair Interface	Extrair conjunto de métodos	Ferramenta de extração de interface gopls (se disponível); manual caso contrário	go build + go vet + go test
Interface	Substituir Tipo por Interface	Substituir tipo concreto na assinatura	Renomear + edição manual	go build + go vet + go test
Movendo Recursos	Mover Método	Mover método entre arquivos/pacotes	Mover arquivo + editar importações	go build + go vet + go test
Movendo Recursos	Mover Campo	Mover campo entre structs	Manual	go build + go vet + go test
Dados	Substituir Array por Slice	Mudar [N]T para []T	gofmt -r + edições manuais	go build + go vet + go test
Dados	Substituir Mapa por Struct	Mudar map[K]V para struct	Manual	go build + go test
Generalização	Extrair Superclasse	Extrair struct base	Manual	go build + go test
Generalização	Substituir Herança por Delegação	Mudar incorporação para campo nomeado	gofmt -r + edições manuais	go build + go vet + go test
Simplificando Chamadas	Renomear Método	Renomear método	gopls rename	go build + go vet
Simplificando Chamadas	Adicionar Parâmetro	Mudar assinatura	gopls rename + edição manual	go build + go test
Simplificando Chamadas	Remover Parâmetro	Mudar assinatura	gopls rename + edição manual	go build + go test
Simplificando Chamadas	Separar Consulta de Modificador	Separar getter de setter	Manual	go build + go test
Organizando Dados	Substituir Valor por Referência	Mudar struct value para ponteiro	gofmt -r + edições manuais	go build + go vet + go test
Organizando Dados	Substituir Referência por Valor	Mudar ponteiro para struct value	gofmt -r + edições manuais	go build + go vet + go test

Referências

• workflow.md — planejamento detalhado, execução e fluxos de revisão
• safety-net.md — estratégia de teste para refatoração (limiares HIGH/MEDIUM/LOW)
• go-tooling.md — ferramentas de refatoração Go e seu uso
• catalog.md — catálogo completo de refatoração de código Go
• Skill de Requisito: samber/cc-skills-golang@golang-gopls (configuração e registro MCP do gopls)
• Skills Relacionadas:
  • samber/cc-skills-golang@golang-naming (convenções de nomenclatura e renomeações)
  • samber/cc-skills-golang@golang-project-layout (estrutura de projeto e divisão de pacotes)
  • samber/cc-skills-golang@golang-modernize (idiomas e padrões Go modernos)
  • samber/cc-skills-golang@golang-code-style (estilo de código e fluxo de controle)
  • samber/cc-skills-golang@golang-design-patterns (padrões de design e injeção de dependência)