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.

Detailed reference material, loaded on demand:

• references/bulk-rewrites.md — gofmt -r, //go:fix inline, eg, gopatch and custom analyzers, with the verification to run after.

Read a reference file only when the summary below is not enough.

0. Risk, Checkpoints, and When Not To

Stop for the developer's approval before any cross-package move, exported API change, deletion, or change to code with no tests. Question the refactor itself when the code is stable and nothing planned touches it, when it is critical and untested, or when no concrete next change gets easier.

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

After a rename, grep for the old name in struct tags, templates, SQL and anything reflection reads — gopls guards compilation, not those. Renaming a field silently desyncs it from its json/db tag.

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)

On Go 1.26+, add //go:fix inline above the deprecated wrapper and step 3 becomes go fix ./... — for your module now, and for every downstream module when it next runs go fix.

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. Bulk Mechanical Rewrites

When the same change lands at many sites, encode it once and let a tool apply it: gofmt -r for syntactic expressions, //go:fix inline + go fix for callers of your own APIs, eg for type-aware expression rewrites, gopatch for statements and imports, a go/analysis fixer for migrations you will run again. A tool's rewrite is reviewable and re-runnable; forty hand edits are neither. Examples: references/bulk-rewrites.md.

8. 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
10. High-risk steps approved by the developer before they start
11. Struct tags, templates and SQL grepped after every rename