---

name: go-refactoring description: > Safe refactoring workflow for Go: behavior-preserving steps, compiler-checked renames, extracting packages, breaking circular dependencies, and strangler migrations — always behind green tests. Use when: "refactor this", "rename across the codebase", "extract a package", "break this circular dependency", "split this god package", "migrate callers", "clean up without changing behavior". Not for: choosing the target architecture (go-architecture-review), adopting new language features (go-modernize), performance rewrites (go-performance-review). user-invocable: true license: MIT compatibility: Designed for Claude Code or similar AI coding agents working on Go projects. Requires the Go toolchain. Requires git. gopls is optional, for semantic rename. allowed-tools: Read Edit Write Glob Grep Bash(go:) Bash(gofmt:) Bash(git:) Bash(gopls:) metadata: author: eduardo-sl version: "1.1.1"

Go Refactoring Workflow

A refactor changes structure, never behavior. The definition of done is mechanical: same tests pass before and after every step, and every step is small enough to revert alone.

1. The Loop

1. Baseline: go build ./... && go test ./... must be green before touching anything. If tests are missing around the target code, write characterization tests FIRST — they pin current behavior, even if that behavior looks wrong.
2. One transformation from the catalog below.
3. Verify: build + tests + go vet ./....
4. Commit. Never mix a refactor commit with a behavior change — reviewers can skim a refactor: commit; they must scrutinize a mixed one.
5. Repeat.

If step 3 fails and the fix isn't obvious in a minute, revert the step rather than debugging a half-applied transformation.

2. Renames — Let Tools Do Them

# Preferred: gopls (understands types, interfaces, embedding)
gopls rename -w internal/service/user.go:#offset newName

# Module path or package import path changes:
# update go.mod, then rewrite imports mechanically
find . -name '*.go' -exec sed -i 's|github.com/acme/old|github.com/acme/new|g' {} +
go build ./...   # the compiler is the reviewer

Never rename an exported identifier of a published library without a deprecation cycle: add the new name, mark the old one // Deprecated: use NewName., delete in the next major version.

3. Extract Package

Moving code out of a god package, in compiler-checked steps:

1. Create the new package; move one type and its methods (gopls or cut/paste), leaving everything else.
2. In the old package, add type aliases so nothing breaks: type User = user.User (aliases, =, not definitions).
3. Build. Migrate importers to the new path in batches; build each batch.
4. Delete the aliases when no importer remains.

This keeps every commit green with an arbitrarily large caller base.

4. Break a Circular Dependency

Packages a → b and b → a won't compile; near-cycles show up as god packages. Three escapes, in order of preference:

1. Extract the shared core: both a and b actually depend on a type — move it to a third package c that imports nothing.
2. Invert with an interface: if store calls back into service, define the callback interface IN store (consumer side) and let service implement it. The arrow flips at compile time.
3. Merge: if two packages can't be described without each other, they were one package all along.

5. Change a Function Signature Safely

For exported functions with many callers:

// Step 1 — add the new form alongside the old
func (s *Service) ProcessCtx(ctx context.Context, id string) error { ... }

// Step 2 — old form delegates; mark deprecated
// Deprecated: use ProcessCtx.
func (s *Service) Process(id string) error {
    return s.ProcessCtx(context.Background(), id)
}

// Step 3 — migrate callers batch by batch, building each batch
// Step 4 — delete the old form (same module) or keep until next major (library)

Inside a single module, prefer atomic signature changes when the compiler can find every caller for you: change it, then chase the build errors — that's the compiler enumerating your TODO list.

6. Strangler Migration for Subsystems

Replacing a subsystem (old store, legacy client) too big for one PR:

1. Define the consumer-side interface the callers actually need.
2. Make the OLD implementation satisfy it; wire callers to the interface.
3. Build the new implementation behind the same interface; test both implementations against one shared conformance test suite.
4. Switch the wiring in the composition root (one line, one commit, trivially revertible). Feature-flag it if risk warrants.
5. Delete the old implementation in its own commit.

7. What Is NOT a Refactor

• "While I'm here" bug fixes — separate commit before or after.
• Reordering struct fields used with positional literals, changing exported error strings callers match on, changing JSON tags — these are behavior changes wearing refactor clothes.
• Rewrites without tests. If you can't pin behavior first, you're not refactoring; you're gambling.

Verification Checklist

1. Baseline build + tests green before the first change
2. Characterization tests added where coverage was missing
3. Each commit is one transformation; refactor: commits contain no behavior change
4. Renames done via gopls/compiler, not find-and-replace on identifiers
5. Package extractions used type aliases to stay green mid-flight
6. No new dependency cycles (go build ./... proves it)
7. Public API changes follow the deprecation cycle
8. go vet ./... and the full test suite pass at every commit, not just the last
9. git log reads as a sequence of safe, revertible steps