golang-concurrency
samber/cc-skills-golang
Go concurrency patterns: goroutines, channels, locks, and structured concurrency best practices.
What is golang-concurrency?
Expert guidance for writing and reviewing concurrent Go code. Use when implementing goroutines, channels, select statements, sync primitives, worker pools, or pipelines—and when auditing for goroutine leaks, race conditions, and ownership violations.
- Implement concurrent code with goroutines, channels, and sync primitives (Mutex, RWMutex, atomic, Once, WaitGroup, errgroup)
- Review PRs for goroutine leaks, missing context propagation, channel ownership violations, and unprotected shared state
- Audit codebases for common concurrency mistakes using parallel sub-agents
- Provide decision guidance on channels vs mutexes vs atomics for specific scenarios
- Design worker pools, fan-out/fan-in pipelines, and structured shutdown mechanisms
How to install golang-concurrency
npx skills add https://github.com/samber/cc-skills-golang --skill golang-concurrency- Go toolchain installed
- golangci-lint (optional, for linting concurrent code)
How to use golang-concurrency
- 1.Describe your concurrency task: writing new code, reviewing a PR, or auditing existing code
- 2.For write mode: follow the sequential instructions to implement goroutines, channels, and sync primitives safely
- 3.For review mode: provide the diff and the skill will check for leaks, missing context, ownership violations, and unprotected state
- 4.For audit mode: specify the codebase scope and the skill will spawn up to 5 parallel sub-agents to check goroutine spawns, shared state, channel usage, and mutex patterns
- 5.Run go test -race ./... to validate race-condition freedom
Use cases
- Writing a worker pool with bounded concurrency using errgroup.SetLimit()
- Reviewing concurrent code for goroutine leaks and missing ctx.Done() in select statements
- Auditing a large codebase for time.After in hot loops and improper channel closure
- Choosing between sync.Mutex, sync.Map, and atomic for protecting shared state
- Implementing graceful shutdown with context cancellation across multiple goroutines
- Go backend engineers writing concurrent services
- Code reviewers auditing goroutine-heavy codebases
- DevOps and platform teams building worker pools and pipelines
- Anyone debugging goroutine leaks, race conditions, or deadlocks in Go
golang-concurrency FAQ
Use channels to pass data and transfer ownership between goroutines. Use mutexes to protect shared struct fields in critical sections. Use atomics for simple counters and flags. See the Channel vs Mutex vs Atomic table in the skill for detailed scenarios.
Every goroutine must have a clear exit: pass context.Context or a done channel, include ctx.Done() in every select statement, and use sync.WaitGroup or errgroup to wait for completion. Test with go.uber.org/goleak to detect leaks.
Each time.After() allocates a new timer. In hot loops, this creates unnecessary churn. Instead, use time.NewTimer() once and call Reset() to reuse it.
Only the sender closes a channel. Closing from the receiver side panics if the sender writes after close. Use a done channel or context to signal the sender to stop and close.
Use errgroup.SetLimit(n) to cap concurrent goroutines, or implement a semaphore pattern. Never spawn unbounded goroutines—they will exhaust memory and crash the process.
Full instructions (SKILL.md)
Source of truth, from samber/cc-skills-golang.
name: golang-concurrency description: "Golang concurrency patterns. Use when writing or reviewing concurrent Go code involving goroutines, channels, select, locks, sync primitives, errgroup, singleflight, worker pools, or fan-out/fan-in pipelines. Also triggers when you detect goroutine leaks, race conditions, channel ownership issues, or need to choose between channels and mutexes." user-invocable: true license: MIT compatibility: Designed for Claude Code or similar AI coding agents, and for projects using Golang. metadata: author: samber version: "1.1.4" openclaw: emoji: "⚡" homepage: https://github.com/samber/cc-skills-golang requires: bins: - go install: [] allowed-tools: Read Edit Write Glob Grep Bash(go:) Bash(golangci-lint:) Bash(git:*) Agent AskUserQuestion
Persona: You are a Go concurrency engineer. You assume every goroutine is a liability until proven necessary — correctness and leak-freedom come before performance.
Modes:
- Write mode — implement concurrent code (goroutines, channels, sync primitives, worker pools, pipelines). Follow the sequential instructions below.
- Review mode — reviewing a PR's concurrent code changes. Focus on the diff: check for goroutine leaks, missing context propagation, ownership violations, and unprotected shared state. Sequential.
- Audit mode — auditing existing concurrent code across a codebase. Use up to 5 parallel sub-agents as described in the "Parallelizing Concurrency Audits" section.
Community default. A company skill that explicitly supersedes
samber/cc-skills-golang@golang-concurrencyskill takes precedence.
Go Concurrency Best Practices
Go's concurrency model is built on goroutines and channels. Goroutines are cheap but not free — every goroutine you spawn is a resource you must manage. The goal is structured concurrency: every goroutine has a clear owner, a predictable exit, and proper error propagation.
Core Principles
- Every goroutine must have a clear exit — without a shutdown mechanism (context, done channel, WaitGroup), they leak and accumulate until the process crashes
- Share memory by communicating — channels transfer ownership explicitly; mutexes protect shared state but make ownership implicit
- Send copies, not pointers on channels — sending pointers creates invisible shared memory, defeating the purpose of channels
- Only the sender closes a channel — closing from the receiver side panics if the sender writes after close
- Specify channel direction (
chan<-,<-chan) — the compiler prevents misuse at build time - Default to unbuffered channels — larger buffers mask backpressure; use them only with measured justification
- Always include
ctx.Done()in select — without it, goroutines leak after caller cancellation - Avoid repeated
time.Afterin hot loops — each call allocates a timer and creates unnecessary churn; usetime.NewTimer+Resetfor long-running loops - Track goroutine leaks in tests with
go.uber.org/goleak
For detailed channel/select code examples, see Channels and Select Patterns.
Channel vs Mutex vs Atomic
| Scenario | Use | Why |
|---|---|---|
| Passing data between goroutines | Channel | Communicates ownership transfer |
| Coordinating goroutine lifecycle | Channel + context | Clean shutdown with select |
| Protecting shared struct fields | sync.Mutex / sync.RWMutex | Simple critical sections |
| Simple counters, flags | sync/atomic | Lock-free, lower overhead |
| Many readers, few writers on a map | sync.Map | Optimized for read-heavy workloads. Concurrent map read/write causes a hard crash |
| Caching expensive computations | sync.Once / singleflight | Execute once or deduplicate |
WaitGroup vs errgroup
| Need | Use | Why |
|---|---|---|
| Wait for goroutines, errors not needed | sync.WaitGroup | Fire-and-forget |
| Wait + collect first error | errgroup.Group | Error propagation |
| Wait + cancel siblings on first error | errgroup.WithContext | Context cancellation on error |
| Wait + limit concurrency | errgroup.SetLimit(n) | Built-in worker pool |
Sync Primitives Quick Reference
| Primitive | Use case | Key notes |
|---|---|---|
sync.Mutex | Protect shared state | Keep critical sections short; never hold across I/O |
sync.RWMutex | Many readers, few writers | Never upgrade RLock to Lock (deadlock) |
sync/atomic | Simple counters, flags | Prefer typed atomics (Go 1.19+): atomic.Int64, atomic.Bool |
sync.Map | Concurrent map, read-heavy | No explicit locking; use RWMutex+map when writes dominate |
sync.Pool | Reuse temporary objects | Always Reset() before Put(); reduces GC pressure |
sync.Once | One-time initialization | Go 1.21+: OnceFunc, OnceValue, OnceValues |
sync.WaitGroup | Waiting for simple goroutines | Go 1.25+: prefer wg.Go(func(){ ... }) for fire-and-wait tasks that do not panic and do not need error propagation. For Go <1.25 use Add/Done. For errors/cancellation/limits, use errgroup with context. |
x/sync/singleflight | Deduplicate concurrent calls | Cache stampede prevention |
x/sync/errgroup | Goroutine group + errors | SetLimit(n) replaces hand-rolled worker pools |
For detailed examples and anti-patterns, see Sync Primitives Deep Dive.
Concurrency Checklist
Before spawning a goroutine, answer:
- How will it exit? — context cancellation, channel close, or explicit signal
- Can I signal it to stop? — pass
context.Contextor done channel - Can I wait for it? —
sync.WaitGrouporerrgroup - Who owns the channels? — creator/sender owns and closes
- Should this be synchronous instead? — don't add concurrency without measured need
Pipelines and Worker Pools
For pipeline patterns (fan-out/fan-in, bounded workers, generator chains, Go 1.23+ iterators, samber/ro), see Pipelines and Worker Pools.
Parallelizing Concurrency Audits
When auditing concurrency across a large codebase, use up to 5 parallel sub-agents (Agent tool):
- Find all goroutine spawns (
go func,go method) and verify shutdown mechanisms - Search for mutable globals and shared state without synchronization
- Audit channel usage — ownership, direction, closure, buffer sizes
- Find
time.Afterin loops, missingctx.Done()in select, unbounded spawning - Check mutex usage,
sync.Map, atomics, and thread-safety documentation
Common Mistakes
| Mistake | Fix |
|---|---|
| Fire-and-forget goroutine | Provide stop mechanism (context, done channel) |
| Closing channel from receiver | Only the sender closes |
time.After in hot loop | Reuse time.NewTimer + Reset |
Missing ctx.Done() in select | Always select on context to allow cancellation |
| Unbounded goroutine spawning | Use errgroup.SetLimit(n) or semaphore |
| Sharing pointer via channel | Send copies or immutable values |
wg.Add inside goroutine | Call Add before go — Wait may return early otherwise |
Forgetting -race in CI | Always run go test -race ./... |
| Mutex held across I/O | Keep critical sections short |
Cross-References
- -> See
samber/cc-skills-golang@golang-performanceskill for false sharing, cache-line padding,sync.Poolhot-path patterns - -> See
samber/cc-skills-golang@golang-contextskill for cancellation propagation and timeout patterns - -> See
samber/cc-skills-golang@golang-safetyskill for concurrent map access and race condition prevention - -> See
samber/cc-skills-golang@golang-troubleshootingskill for debugging goroutine leaks and deadlocks - -> See
samber/cc-skills-golang@golang-design-patternsskill for graceful shutdown patterns - -> See
samber/cc-skills-golang@golang-continuous-integrationskill for automated AI-driven code review in CI using these guidelines
Go 1.26 experimental goroutine leak profile
For Go 1.26 diagnostics, there is an experimental goroutine leak profile. It is useful for production-oriented leak investigation, but is gated by GOEXPERIMENT=goroutineleakprofile; do not rely on it as default stable behavior.
Typical usage when the experiment is enabled:
curl http://localhost:6060/debug/pprof/goroutineleak?debug=2
go tool pprof http://localhost:6060/debug/pprof/goroutineleak
Keep existing tools:
- tests:
go.uber.org/goleak - runtime count:
runtime.NumGoroutine() - stack dump:
/debug/pprof/goroutine?debug=2 - race checks:
go test -race ./...
References
Related skills
More from samber/cc-skills-golang and the wider catalog.
golang-code-style
Go code style conventions for clarity, control flow, and readability—line breaking, variable declarations, and when comments help.
golang-error-handling
Idiomatic Go error handling: wrapping, inspection, structured logging, and production-grade error tracking.
golang-performance
Go performance optimization patterns: identify bottlenecks with profiling, then apply the right fix.
golang-design-patterns
Idiomatic Go design patterns: functional options, constructors, error handling, resource lifecycle, graceful shutdown, and resilience.
golang-testing
Production-ready Go tests with table-driven patterns, testify integration, parallel execution, fuzzing, and leak detection.
golang-security
Security best practices and vulnerability prevention for Go code—injection, crypto, secrets, and authentication.