golang-performance
Skill261 starsChanged 2 months agoBSD-3-ClauseView on GitHub
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).
- Installs packages
15 other projects use a version of this, 9 of them edited.
Adopted by
Most recently taken up by
- aiproxer/aiproxertheir own version, first seen Nov 8, 2026
- TeddyAlbina/skillsedited, first seen Nov 1, 2026
- samber/cc-skills-golangword for word, first seen Nov 1, 2026
- poizoncoded/skillsedited, first seen Nov 1, 2026
- klawisha012/agentsyncedited, first seen Oct 25, 2026
- rockcookies/skillsedited, first seen Oct 13, 2026
Used with
Projects with it also use golang-samber-mo, golang-samber-ro and 9 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
guynhsichngeodiecSkillgolang-samber-mo
Monadic types for Golang using samber/mo — Option, Result, Either, Future, IO, Task, and State types for type-safe nullable values, error handling, and functional composition with pipeline sub-packages. Apply when using or adopting samber/mo, when the codebase imports `github.com/samber/mo`, or when considering functional programming patterns as a safety design for Golang.
Also in 8 projects that use this
guynhsichngeodiecSkillgolang-samber-ro
Reactive streams and event-driven programming in Golang using samber/ro — ReactiveX implementation with 150+ type-safe operators, cold/hot observables, 5 subject types (Publish, Behavior, Replay, Async, Unicast), declarative pipelines via Pipe, 40+ plugins (HTTP, cron, fsnotify, JSON, logging), automatic backpressure, error propagation, and Go context integration. Apply when using or adopting samber/ro, when the codebase imports github.com/samber/ro, or when building asynchronous event-driven pipelines, real-time data processing, streams, or reactive architectures in Go. Not for finite slice transforms (-> See golang-samber-lo skill).
Also in 8 projects that use this
jkeddariSkillgolang-gopls
Golang semantic code intelligence with the official gopls language server: definitions, references, symbols, call and implementation hierarchies, diagnostics, formatting, code actions, safe rename, extract, inline, and package API discovery. Use when navigating or refactoring a local Go workspace or when semantic analysis is safer than text search.
Also in 5 projects that use this
jkeddariSkillgolang-refactoring
Golang refactoring workflow for safe structural change: blast-radius discovery, coverage-adaptive safety nets, semantic rename and extract operations, package moves, import-cycle removal, staged commits, and behavior-preserving verification. Use when restructuring existing Go code without intentionally changing its public behavior.
Also in 5 projects that use this
- +7 more from guynhsichngeodiec
Other versions15 projects use a version of this.
Word for word · 3
- samber/cc-skills-golang★ 3.9k100% same
- imMamdouhaboammar/tiktok-growth-automation-mesh★ 0100% same
- rzisso/golang-skills★ 0100% same
Edited · 9
- alexastrum/skl★ 1196% same
- klawisha012/agentsync★ 1096% same
- tstapler/dotfiles★ 891% same
- tquangkhai98/browser-profiles-manager★ 595% same
- poizoncoded/skills★ 296% same
- TeddyAlbina/skills★ 296% same
- rockcookies/skills★ 194% same
- VerifiedOrganic/onboard★ 197% same
- guynhsichngeodiec/cc-skills-golang★ 096% same
Wrote their own version · 3
- aiproxer/aiproxer★ 24same name
- jkeddari/go-skills★ 1same name
- reagin/agent-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository36 other files it gives its agents.
- AGENTS.mdAGENTS.md
- aif-architectureSkill
- aif-archiveSkill
- aif-best-practicesSkill
- aif-build-automationSkill
- aif-ciSkill
- aif-commitSkill
- aif-docsSkill
- aif-evolveSkill
- aif-exploreSkill
- aif-fixSkill
- aif-groundedSkill
- aif-implementSkill
- aif-improveSkill
- aif-loopSkill
- aif-planSkill
- aif-qa-checkSkill
- aif-qaSkill
- aif-reviewSkill
- aif-roadmapSkill
- aif-rules-checkSkill
- aif-rulesSkill
- aif-security-checklistSkill
- aif-skill-generatorSkill
- aifSkill
- aif-verifySkill
- golang-code-styleSkill
- golang-concurrencySkill
- golang-contextSkill
- golang-databaseSkill
- golang-design-patternsSkill
- golang-documentationSkill
- golang-error-handlingSkill
- golang-namingSkill
- golang-securitySkill
- golang-testingSkill
The file
We split this skill into the rules it gives an agent
1 rule. 1 is common, 0 are distinctive, and 0 are very specific to this project.
1
Common
Most of the 12 edited versions we read keep these.
0
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Common: line 52
Before optimizing Go code, verify the bottleneck is in your process — if 90% of latency is a slow DB query or API call, reducing …
“Common” is measured: kept by at least 6 in 10 of the 12 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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-troubleshootingskill) - 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-benchmarkskill) - 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.txtto 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): summarycommit 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-benchmarkskill for benchmarking methodology,benchstat, andb.Loop()(Go 1.24+) - → See
samber/cc-skills-golang@golang-troubleshootingskill for pprof workflow, escape analysis diagnostics, and performance debugging - → See
samber/cc-skills-golang@golang-data-structuresskill for slice/map preallocation andstrings.Builder - → See
samber/cc-skills-golang@golang-concurrencyskill for worker pools,sync.PoolAPI, goroutine lifecycle, and lock contention - → See
samber/cc-skills-golang@golang-safetyskill for defer in loops, slice backing array aliasing - → See
samber/cc-skills-golang@golang-databaseskill for connection pool tuning and batch processing - → See
samber/cc-skills-golang@golang-observabilityskill for continuous profiling in production
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

