---
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.2.0"
---

# 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

| Risk | Transformations | Before you start |
|---|---|---|
| Low | gopls rename, extract/inline variable, organize imports | Green build and tests |
| Medium | Extract function or method, inline a call across packages, add/remove a parameter | Tests that cover every changed call site |
| High | Move types across packages, split or merge packages, break cycles, change exported API | Full safety net, and the developer's sign-off |

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

```bash
# 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:

```go
// 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