go Best Practices Audit

The Problem

Your Go service passes go vet and staticcheck with zero warnings. In production, it leaks goroutines on every failed HTTP request — growing memory by 2MB per minute until the OOM killer fires. A tight loop appends to a slice without pre-allocation, causing 40,000 heap allocations per request. An error from json.Unmarshal is assigned to _ and the service silently serves corrupted data. Your code reviewer catches none of these because they look like standard Go code. The issues are real but outside the scope of static analysis tools.

What You Get

• Concurrency audit that flags goroutine leaks (missing termination paths), context propagation gaps (no context on blocking I/O), channel misuse (unclosed channels, deadlock potential from circular dependencies), unprotected shared state (missing sync.Mutex), and WaitGroup ordering errors
• Performance audit identifying slice pre-allocation opportunities, string concatenation in loops (O(n²) → strings.Builder), map pre-allocation, unnecessary interface boxing in hot paths, buffer reuse with sync.Pool, and JSON encoding inefficiency
• Error handling audit catching ignored errors (assigned to _), broken error chains (fmt.Errorf with %v instead of %w), deferred functions that swallow errors, bare recover() without re-panic, and missing error variable declarations
• Structural audit checking package cohesion, import grouping (goimports style), naming conventions (interfaces with -er suffix, no Hungarian notation), file structure (internal/, cmd/, doc.go), and custom error patterns
• Modern Go (1.21+) adoption recommending min/max/clear built-ins, slices package (slices.Sort, slices.Contains, slices.Clone), maps package, structured logging with log/slog, and t.Cleanup() in tests
• Verification checklist with go vet, go test -race, staticcheck, and golangci-lint validation steps, plus confirmation that every error return is handled or explicitly documented as ignored

Why This Beats Prompting It Yourself

When you ask an LLM to "review my Go code," it identifies surface-level issues (unused variables, missing error checks on well-known functions) but misses the architectural patterns: a goroutine that blocks on a channel send when the receiver has already returned, a function that calls get_node (the Go equivalent: accessing shared state without synchronization) in a hot loop, or a deferred function that overwrites an existing error. This skill applies a structured five-phase methodology that mirrors how senior Go engineers actually audit code — not a checklist of individual rules but a systematic sweep through architecture, performance, concurrency, error handling, and modern patterns.

Example Session

You: "Review this HTTP handler — it's in our hot path and we're seeing memory spikes."

func handleSearch(w http.ResponseWriter, r *http.Request) {
    query := r.URL.Query().Get("q")
    var results []SearchResult
    for _, doc := range allDocuments {
        if strings.Contains(doc.Content, query) {
            results = append(results, doc)
        }
    }
    json.NewEncoder(w).Encode(results)
}

Agent output:

GO BEST PRACTICES AUDIT — handleSearch
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[HIGH] Unpre-allocated slice growth
  var results []SearchResult — nil slice, will realloc repeatedly.
  Fix: results := make([]SearchResult, 0, len(allDocuments))

[HIGH] Quadratic string search on full document corpus
  strings.Contains in a loop over all documents is O(n*m).
  For 100K documents at 2KB each, this scans 200MB per request.
  Fix: Use an inverted index or full-text search (bleve, Elasticsearch).

[MEDIUM] Missing context.Context propagation
  No request context — if the client disconnects, the search continues.
  Fix: Accept ctx context.Context and check ctx.Err() in the loop.

[MEDIUM] No error handling on json.Encode
  json.NewEncoder(w).Encode(results) — encode error is ignored.
  Fix: if err := json.NewEncoder(w).Encode(results); err != nil { ... }

[LOW] No input validation on query
  Empty string matches everything — may be intentional but verify.

VERDICT: 2 HIGH, 2 MEDIUM, 1 LOW — fix slice allocation before merge,
optimize search strategy before production load.

Use Cases

• Pre-merge code review for Go services, CLIs, and libraries
• Production incident postmortems involving goroutine leaks or memory growth
• Performance optimization of hot paths (API handlers, data processing pipelines)
• New team member onboarding to Go idioms and project conventions
• Auditing legacy Go code before a major version upgrade

Known Limitations

The audit is static analysis — it does not run the code or measure actual memory/CPU usage. For memory allocation hotspots, pair this audit with go test -bench and pprof profiling. The concurrency audit can detect potential deadlock patterns but cannot guarantee deadlock freedom in complex distributed systems. Premature optimization warnings are calibrated to avoid flagging small slices and short loops that the compiler handles efficiently.