Golang Performance

Samuel BertheCommunityCreated by samberDistributed by Samuel Berthe

Skill
Guidelines
Software development
MIT
Low risk

From the author

Golang performance optimization patterns and methodology - if X bottleneck, then apply Y. Covers allocation reduction, CPU efficiency, memory layout, GC tuning, pooling, caching, and hot-path optimization. Use when profiling or benchmarks have identified a bottleneck and you need the right optimization pattern to fix it. Also use when performing performance code review to suggest improvements or benchmarks that could help identify quick performance gains. Not for measurement methodology (→ See `samber/cc-skills-golang@golang-benchmark` skill) or debugging workflow (→ See `samber/cc-skills-golang@golang-troubleshooting` skill).

— the description by samber

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to identifying and resolving performance bottlenecks in Golang applications. It emphasizes a data-driven philosophy: profile first, hypothesize, apply a single optimization, and re-measure. It covers critical areas including memory allocation reduction, CPU efficiency, cache locality, runtime tuning, and algorithmic improvements. The skill is designed to guide developers through the iterative cycle of benchmarking and optimization, ensuring that changes are statistically significant and documented.

What it does

Provides a decision tree for mapping pprof signals to specific optimization patterns.
Defines an iterative workflow for benchmarking, diagnosing, and verifying performance improvements.
Offers deep-dive patterns for memory management, CPU hot-path optimization, and I/O efficiency.
Includes guidance on avoiding common Go performance pitfalls like lock contention and unnecessary allocations.
Supports architectural performance reviews through multi-agent orchestration.
Integrates with standard Go tooling like benchstat for statistical validation of changes.

When to use it

When profiling or benchmarks have identified a specific performance bottleneck.
When conducting a performance-focused code review to suggest structural improvements.
When you need to reduce GC pressure or latency in high-throughput Go services.
When you need to verify if a proposed optimization actually yields a measurable gain.

Advantages

Reduces reliance on intuition by enforcing a measurement-first methodology.
Provides actionable patterns for common Go-specific performance issues.
Ensures performance improvements are statistically validated using benchstat.
Helps prevent performance regressions by encouraging documented benchmarks.
Enables systematic identification of bottlenecks across memory, CPU, and I/O.

Usage examples

“My service has high GC overhead. How can I reduce allocations?”: The agent will guide you through identifying allocation hot-spots using pprof, suggest patterns like sync.Pool or pre-allocation, and help you verify the reduction in allocs/op using benchstat.
“Review this package for performance anti-patterns.”: The agent will perform an architectural scan, checking for issues like unbounded goroutines, missing connection pools, or inefficient data structures, and provide a report with optimization recommendations.
“I suspect a function is CPU-bound. How do I optimize it?”: The agent will help you establish a baseline benchmark, analyze the CPU profile to check for inlining or cache locality issues, and suggest specific code changes to improve execution speed.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/samber/golang-performance/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip golang-performance.zip -d .agents/skills

Documentation by samber

Persona: You are a Go performance engineer. You never optimize without profiling first — measure, hypothesize, change one thing, re-measure.

Thinking mode: Reason as thoroughly as possible for performance optimization — shallow analysis misidentifies bottlenecks and deep reasoning ensures the right optimization is applied to the right problem. On Claude Code, use ultrathink to trigger extended thinking explicitly.

Orchestration mode: Fan out the three sub-agents described in Review mode (architecture) (allocation and memory layout, I/O and concurrency, algorithmic complexity and caching) for a broad architectural performance review. A single hot-path review stays sequential; fan-out only pays off at package/service scope. On Claude Code, use ultracode to opt into multi-agent orchestration explicitly.

Modes:

Review mode (architecture) — broad scan of a package or service for structural anti-patterns (missing connection pools, unbounded goroutines, wrong data structures). Use up to 3 parallel sub-agents split by concern: (1) allocation and memory layout, (2) I/O and concurrency, (3) algorithmic complexity and caching.
Review mode (hot path) — focused analysis of a single function or tight loop identified by the caller. Work sequentially; one sub-agent is sufficient.
Optimize mode — a bottleneck has been identified by profiling. Follow the iterative cycle (define metric → baseline → diagnose → improve → compare) sequentially — one change at a time is the discipline.

Dependencies:

benchstat: go install golang.org/x/perf/cmd/benchstat@latest

Go Performance Optimization

Core Philosophy

Profile before optimizing — intuition about bottlenecks is wrong ~80% of the time. Use pprof to find actual hot spots (→ See samber/cc-skills-golang@golang-troubleshooting skill)
Allocation reduction yields the biggest ROI — Go's GC is fast but not free. Reducing allocations per request often matters more than micro-optimizing CPU
Document optimizations — add code comments explaining why a pattern is faster, with benchmark numbers when available. Future readers need context to avoid reverting an "unnecessary" optimization

Rule Out External Bottlenecks First

Before optimizing Go code, verify the bottleneck is in your process — if 90% of latency is a slow DB query or API call, reducing allocations won't help.

Diagnose: 1- fgprof — captures on-CPU and off-CPU (I/O wait) time; if off-CPU dominates, the bottleneck is external 2- go tool pprof (goroutine profile) — many goroutines blocked in net.(*conn).Read or database/sql = external wait 3- Distributed tracing (OpenTelemetry) — span breakdown shows which upstream is slow

When external: optimize that component instead — query tuning, caching, connection pools, circuit breakers (→ See samber/cc-skills-golang@golang-database skill, Caching Patterns).

Iterative Optimization Methodology

The cycle: Define Goals → Benchmark → Diagnose → Improve → Benchmark

Define your metric — latency, throughput, memory, or CPU? Without a target, optimizations are random
Write an atomic benchmark — isolate one function per benchmark to avoid result contamination (→ See samber/cc-skills-golang@golang-benchmark skill)
Measure baseline — go test -bench=BenchmarkMyFunc -benchmem -count=6 ./pkg/... | tee /tmp/report-1.txt
Diagnose — use the Diagnose lines in each deep-dive section to pick the right tool
Improve — apply ONE optimization at a time with an explanatory comment
Compare — benchstat /tmp/report-1.txt /tmp/report-2.txt to confirm statistical significance
Commit — paste the benchstat output in the commit body so reviewers and future readers see the exact improvement; follow the perf(scope): summary commit type
Repeat — increment report number, tackle next bottleneck

Refer to library documentation for known patterns before inventing custom solutions. Keep all /tmp/report-*.txt files as an audit trail.

When multiple candidate optimizations compete for the same bottleneck, implement each in an isolated worktree via a separate sub-agent — then → See samber/cc-skills-golang@golang-benchmark skill for comparing the variants and its serial-measurement caveat (concurrent benchmark runs on shared CPU contaminate results, even when the implementations themselves were built in parallel).

Decision Tree: Where Is Time Spent?

Bottleneck	Signal (from pprof)	Action
Too many allocations	`alloc_objects` high in heap profile	Memory optimization
CPU-bound hot loop	function dominates CPU profile	CPU optimization
GC pauses / OOM	high GC%, container limits	Runtime tuning
Network / I/O latency	goroutines blocked on I/O	I/O & networking
Repeated expensive work	same computation/fetch multiple times	Caching patterns
Wrong algorithm	O(n²) where O(n) exists	Algorithmic complexity
Lock contention	mutex/block profile hot	→ See `samber/cc-skills-golang@golang-concurrency` skill
Slow queries	DB time dominates traces	→ See `samber/cc-skills-golang@golang-database` skill

Common Mistakes

Mistake	Fix
Optimizing without profiling	Profile with pprof first — intuition is wrong ~80% of the time
Default `http.Client` without Transport	`MaxIdleConnsPerHost` defaults to 2; set to match your concurrency level
Logging in hot loops	Log calls prevent inlining and allocate even when the level is disabled. Use `slog.LogAttrs`
`panic`/`recover` as control flow	panic allocates a stack trace and unwinds the stack; use error returns
`unsafe` without benchmark proof	Only justified when profiling shows >10% improvement in a verified hot path
No GC tuning in containers	Set `GOMEMLIMIT` to 80-90% of container memory to prevent OOM kills
`reflect.DeepEqual` in production	50-200x slower than typed comparison; use `slices.Equal`, `maps.Equal`, `bytes.Equal`

Deep Dives

Memory Optimization — allocation patterns, backing array leaks, sync.Pool, struct alignment
CPU Optimization — inlining, cache locality, false sharing, ILP, reflection avoidance
I/O & Networking — HTTP transport config, streaming, JSON performance, cgo, batch operations
Runtime Tuning — GOGC, GOMEMLIMIT, GC diagnostics, GOMAXPROCS, PGO
Caching Patterns — algorithmic complexity, compiled patterns, singleflight, work avoidance
Production Observability — Prometheus metrics, PromQL queries, continuous profiling, alerting rules

CI Regression Detection

Automate benchmark comparison in CI to catch regressions before they reach production. → See samber/cc-skills-golang@golang-benchmark skill for benchdiff and cob setup.

Cross-References

→ See samber/cc-skills-golang@golang-benchmark skill for benchmarking methodology, benchstat, and b.Loop() (Go 1.24+)
→ See samber/cc-skills-golang@golang-troubleshooting skill for pprof workflow, escape analysis diagnostics, and performance debugging
→ See samber/cc-skills-golang@golang-data-structures skill for slice/map preallocation and strings.Builder
→ See samber/cc-skills-golang@golang-concurrency skill for worker pools, sync.Pool API, goroutine lifecycle, and lock contention
→ See samber/cc-skills-golang@golang-safety skill for defer in loops, slice backing array aliasing
→ See samber/cc-skills-golang@golang-database skill for connection pool tuning and batch processing
→ See samber/cc-skills-golang@golang-observability skill for continuous profiling in production

Files

ATTRIBUTION.mdAdded by AutoGineer911 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md9.3 KiB
assets/prometheus-alerts.yml662 B
evals/evals.json91.6 KiB
references/caching.md8.7 KiB
references/cpu.md18.3 KiB
references/io-networking.md14.2 KiB
references/memory.md10.1 KiB
references/observability.md5.5 KiB
references/runtime.md11.8 KiB

references/caching.md

Caching Patterns

The fastest code is code that doesn't run. Caching pre-computed results, deduplicating concurrent requests, and avoiding unnecessary work are often the highest-leverage performance improvements.

Compiled Pattern Caching
- Regexp at package level
- Template caching
- Precomputed lookup tables
Request-Level Caching
- singleflight for cache stampede prevention
- LRU caches
Algorithmic Complexity
Work Avoidance
- Map lookups over slice scanning
- Early returns and short-circuit loops
- Avoid iterator chains
- Replace indirect function calls with direct loops

Compiled Pattern Caching

Diagnose: 1- go tool pprof (CPU profile) — look for regexp.Compile, regexp.MustCompile, or template.Parse appearing in hot paths; their presence means patterns are being recompiled per call instead of once 2- go test -bench -benchmem — benchmark per-call compilation vs cached version; expect 10-12x improvement and allocs/op dropping to zero for the compilation step

Regexp at package level

regexp.Compile parses a pattern into a state machine — ~5,700ns per compilation. Match operations on a compiled regexp cost ~450ns. Compiling per-call wastes 10-12x:

// Bad — compiled on every call
func isValid(email string) bool {
    re := regexp.MustCompile(`^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$`)
    return re.MatchString(email)
}

// Good — compiled once, safe for concurrent use
var emailRegex = regexp.MustCompile(`^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$`)

func isValid(email string) bool { return emailRegex.MatchString(email) }

Note: regexp.MustCompile panics on invalid patterns — fine for package-level constants (caught at startup). Use regexp.Compile for user-provided patterns. Go's regexp uses linear-time matching (no backtracking).

Template caching

template.Parse is equally expensive. Parse once at startup:

var reportTmpl = template.Must(template.ParseFiles("templates/report.html"))

Precomputed lookup tables

When a computation is pure (same input → same output) and the input space is small, replace calculation with array lookup:

var hexDigit = [16]byte{'0','1','2','3','4','5','6','7','8','9','a','b','c','d','e','f'}

func byteToHex(b byte) (byte, byte) {
    return hexDigit[b>>4], hexDigit[b&0x0f] // two array lookups vs branching logic
}

If the table fits in L1/L2 cache, lookup is faster than even simple computation.

Request-Level Caching

Diagnose: 1- go tool pprof (goroutine profile) — look for many goroutines blocked on the same external call (HTTP fetch, DB query); this signals a cache stampede where N goroutines all miss the cache simultaneously 2- fgprof — shows off-CPU wait time; look for the same fetch function dominating wall-clock time across many goroutines, confirming duplicated concurrent work 3- go tool pprof -alloc_objects — check if cache miss handling allocates heavily; high alloc counts on fetch functions confirm the stampede is also generating GC pressure

singleflight for cache stampede prevention

When a cache entry expires, many goroutines may simultaneously discover the miss and all request the same expensive computation. singleflight ensures only one goroutine fetches while others wait:

import "golang.org/x/sync/singleflight"

var (
    cache sync.Map
    sf    singleflight.Group
)

func GetWeather(city string) (string, error) {
    if val, ok := cache.Load(city); ok {
        return val.(string), nil
    }

    // Only one goroutine fetches; others block on the same key
    result, err, _ := sf.Do(city, func() (any, error) {
        data, err := fetchFromAPI(city)
        if err == nil { cache.Store(city, data) }
        return data, err
    })
    return result.(string), err
}

→ See samber/cc-skills-golang@golang-concurrency skill for singleflight API details and sync.Map vs RWMutex decision guidance. → Generics alternative: Use github.com/samber/go-singleflightx to avoid interface{} boxing overhead; expect 2-4x faster result retrieval compared to the standard library's singleflight.Group.

LRU caches

For bounded caches with eviction, the standard library's container/list works but has poor cache locality (each node is a separate heap allocation). For high-performance LRU:

github.com/hashicorp/golang-lru — thread-safe, simple API
github.com/elastic/go-freelru — merges hashmap and ringbuffer into contiguous memory, ~37x faster than sharded implementations

When using third-party cache libraries, refer to the library's official documentation for current API signatures.

Algorithmic Complexity

Diagnose: 1- go tool pprof (CPU profile) — look for functions with high cumulative time that contain nested loops or repeated linear scans; these are algorithmic complexity bottlenecks 2- go test -bench — benchmark with different input sizes (100, 1K, 10K, 100K); if time grows quadratically (10x input → 100x time), the algorithm is O(n²) and needs replacement

Before micro-optimizing, check that the algorithm itself isn't the bottleneck. A constant-factor improvement on an O(n²) algorithm loses to a naive O(n log n) implementation at scale.

Common complexity traps in Go:

Pattern	Complexity	Fix	Fixed complexity
`slices.Contains` in a loop	O(n·m)	Build `map[T]struct{}` first, then lookup	O(n+m)
Nested loops for matching	O(n²)	Index with a map, sort+binary search, or `slices.BinarySearch`	O(n log n) or O(n)
Repeated `append` without prealloc	O(n²) amortized copies	`make([]T, 0, n)`	O(n)
String concatenation with `+=`	O(n²) total copies	`strings.Builder`	O(n)
Linear scan for min/max/dedup	O(n) per query	Sort once, query many times	O(n log n) + O(log n) per query

Think in Big-O first, then optimize constants. A 10x constant-factor improvement matters; switching from O(n²) to O(n) matters more.

Work Avoidance

Diagnose: 1- go tool pprof (CPU profile) — look for linear scan functions (slices.Contains, slices.Index) or iterator chains (Filter, Map) consuming CPU in hot paths 2- go test -bench — benchmark the current approach vs a map-based or early-return version; expect O(n) → O(1) for membership tests, significant improvement for short-circuit loops

Map lookups over slice scanning

Contains(slice, element) is O(n). Map lookups are O(1). When doing multiple membership tests against the same collection, build a map once:

// Bad — O(n*m), checking Contains per element
for _, item := range subset {
    if !Contains(collection, item) { return false } // O(n) per check
}

// Good — O(n+m), build map once, O(1) lookups
seen := make(map[T]struct{}, len(collection))
for _, item := range collection { seen[item] = struct{}{} }
for _, item := range subset {
    if _, ok := seen[item]; !ok { return false }
}

Use struct{} (0 bytes) instead of bool (1 byte) for set maps.

Early returns and short-circuit loops

Return immediately when the answer is known. Finding the target on iteration 3 of 1000 saves 997 iterations:

// Bad — always iterates full collection
found := false
for _, item := range collection {
    if item == target { found = true }
}
return found

// Good — returns on first match
for i := range collection {
    if collection[i] == target { return true }
}
return false

Avoid iterator chains

Chaining iterator operations (Filter → Map → First) creates closures and intermediate machinery. A direct loop is simpler and faster:

// Bad — creates 2 iterators with closures
result, ok := First(Filter(collection, predicate))

// Good — single pass, early return, no closures
for i := range collection {
    if predicate(collection[i]) { return collection[i], true }
}

Replace indirect function calls with direct loops

When a function wraps another function (e.g., FromSlicePtr calling Map with a closure), the closure indirection prevents inlining. Replace with a direct loop:

// Bad — Map() with closure, per-element function call overhead
func FromSlicePtr(items []*T) []T {
    return Map(items, func(p *T) T { return *p })
}

// Good — direct loop, inlineable, -13% to -17% time
func FromSlicePtr(items []*T) []T {
    result := make([]T, len(items))
    for i := range items { result[i] = *items[i] }
    return result
}

Requirements and compatibility

Written for: Claude Code, OpenAI Codex

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Declares allowed tools, Claude Code frontmatter

The author says: Designed for Claude Code, Codex or similar harness, and for projects using Golang.

Security

What our scanner noticed· Low risk

Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

samber

Publisher

Samuel Berthe (Community)

Distributed by

Samuel Berthe

Source

samber/cc-skills-golang · skills/golang-performance · commit bb1d43d

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by samber or Samuel Berthe.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download golang-performance.zip