Refactoring & Architecture Audit Checklist

Red flags in package coupling, globals, and init() abuse.

Walk this checklist before a major release, after onboarding spikes, or when compile times and incident rates climb together.

How to Use This Checklist

• Score each tier during a one-hour architecture review or blameless post-incident retro.
• Fix Critical items before adding features on top of the debt.
• Track findings in tickets linked to ADRs when the fix changes boundaries.
• Re-run quarterly or when module count or team size doubles.

Critical - Stop the Bleeding

1. Global mutable state for DB, config, or clients: Replace with constructor injection from main.

   • Globals: var db *sql.DB used across packages
   • Injection: NewService(repo Repository) wired once at startup

2. Import cycles between production packages: Extract shared contracts or invert dependency direction.

   • Cycle: handler imports service imports handler
   • Fix: Move interfaces to consumer or internal/contracts

3. init() performs I/O or panics on misconfiguration: Fail in main with clear errors instead.

   • init side effect: Opens DB in init()
   • main fail-fast: cfg, err := Load(); if err != nil { log.Fatal(err) }

4. Business rules only in HTTP handlers: Move validation and workflows to services with unit tests.

   • Fat handler: 200-line ServeHTTP with SQL
   • Service: Register(ctx, email) tested without httptest

5. Secrets or endpoints hardcoded in library packages: Load from env/flags in composition root only.

   • Hardcoded: const apiURL = "https://prod..."
   • Config struct: Config.APIURL validated at boot

High - Coupling and Boundaries

6. God package (util, common, helpers): Split by capability (internal/timeutil, internal/validate).
7. Domain packages import net/http, gin, or gRPC generated code: Move adapters to internal/adapter/*.
8. Wide interfaces (10+ methods) consumed by one caller: Split or define consumer-side one-method ports.
9. Exported identifiers that no external module uses: Unexport or move to internal/ to freeze API surface.
10. cmd/ binaries duplicating wiring divergently: Extract shared Provide* helpers or Wire set.
11. Repositories return HTTP DTOs or ORM models with framework tags: Map to domain structs at repository boundary.
12. Missing context.Context on I/O functions: Add ctx as first parameter; plumb from handlers.

Medium - Maintainability Signals

13. Test suite requires Docker for pure business logic tests: Introduce fakes at service boundaries.
14. Duplicate error strings instead of sentinels: Use var ErrNotFound = errors.New(...) and errors.Is.
15. Panics for expected errors in libraries: Return errors; reserve panic for programmer bugs.
16. Blank imports (_) without comment explaining side effect: Document registration purpose or remove.
17. Packages named after layers only (models, controllers) with cross-imports: Reorganize by feature slice.
18. More than three levels of nested packages without ownership: Flatten or align to team boundaries.
19. replace directives committed for local laptop paths: Use go.work locally; keep go.mod portable.
20. No ADR for last major boundary change (split, ORM adoption, RPC): Write ADR before the next change piles on.

Low - Polish and Future Cost

21. Inconsistent logging (fmt, log, slog mixed): Standardize on slog or team logger at edges.
22. Handlers without request size limits or timeouts: Add http.Server timeouts and MaxBytesReader.
23. Public module lacking LICENSE and tagged releases: Add LICENSE; tag semver for consumers.
24. Generated code edited by hand: Regenerate from go generate, sqlc, or buf in CI.
25. Comments describe obsolete architecture ("temporary until v2") years later: Update docs or finish migration.

Applying the Checklist in Order

• Critical (1-5): Address before scaling traffic or team - incidents and data corruption risk dominate.
• High (6-12): Schedule in the current quarter - each item slows every feature afterward.
• Medium (13-20): Batch into refactors adjacent to feature work - boy scout rule per package.
• Low (21-25): Tie to platform chores sprint - reduces onboarding friction.

FAQs

Related

• Architecture in Go: Small Interfaces, Explicit Dependencies - Target architecture
• Handler-Service-Repository Layering - Layer refactor destination
• Architecture Decision Records for Go Teams - Record outcomes
• Common Anti-Patterns in Go Codebases - Code-level smells
• Architecture & Design Best Practices - Prevention habits

External Related Links

• Effective Go - Official guide to writing clear, idiomatic Go.
• Learn Go with Tests - TDD-focused introduction to Go.
• Stack Overflow – Go Tag - Q&A for Go programming.
• The Go Programming Language (ebook) - Donovan & Kernighan.
• Learning Go (2nd Edition, O'Reilly) - Jon Bodner on O'Reilly.

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).