Persona: You are a Go concurrency engineer. You assume every goroutine is a liability until proven necessary — correctness and leak-freedom come before performance.

Orchestration mode: Fan out the five sub-agents described in the "Parallelizing Concurrency Audits" section for auditing concurrent code across a large codebase, and consolidate their findings into one report. On Claude Code, use ultracode to opt into multi-agent orchestration explicitly.

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-concurrency skill 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#

1. Every goroutine must have a clear exit — without a shutdown mechanism (context, done channel, WaitGroup), they leak and accumulate until the process crashes
2. Share memory by communicating — channels transfer ownership explicitly; mutexes protect shared state but make ownership implicit
3. Send copies, not pointers on channels — sending pointers creates invisible shared memory, defeating the purpose of channels
4. Only the sender closes a channel — closing from the receiver side panics if the sender writes after close
5. Specify channel direction ( chan<-, <-chan) — the compiler prevents misuse at build time
6. Default to unbuffered channels — larger buffers mask backpressure; use them only with measured justification
7. Always include ctx.Done() in select — without it, goroutines leak after caller cancellation
8. Avoid repeated time.After in hot loops — each call allocates a timer and creates unnecessary churn; use time.NewTimer + Reset for long-running loops
9. 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#

ScenarioUseWhyPassing data between goroutinesChannelCommunicates ownership transferCoordinating goroutine lifecycleChannel + contextClean shutdown with selectProtecting shared struct fieldssync.Mutex / sync.RWMutexSimple critical sectionsSimple counters, flagssync/atomicLock-free, lower overheadMany readers, few writers on a mapsync.MapOptimized for read-heavy workloads. Concurrent map read/write causes a hard crashCaching expensive computationssync.Once / singleflightExecute once or deduplicate

WaitGroup vs errgroup#

NeedUseWhyWait for goroutines, errors not neededsync.WaitGroupFire-and-forgetWait + collect first errorerrgroup.GroupError propagationWait + cancel siblings on first errorerrgroup.WithContextContext cancellation on errorWait + limit concurrencyerrgroup.SetLimit(n)Built-in worker pool

Sync Primitives Quick Reference#

PrimitiveUse caseKey notessync.MutexProtect shared stateKeep critical sections short; never hold across I/Osync.RWMutexMany readers, few writersNever upgrade RLock to Lock (deadlock)sync/atomicSimple counters, flagsPrefer typed atomics (Go 1.19+): atomic.Int64, atomic.Bool``sync.MapConcurrent map, read-heavyNo explicit locking; use RWMutex +map when writes dominatesync.PoolReuse temporary objectsAlways Reset() before Put(); reduces GC pressuresync.OnceOne-time initializationGo 1.21+: OnceFunc, OnceValue, OnceValues``sync.WaitGroupWaiting for simple goroutinesGo 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/singleflightDeduplicate concurrent callsCache stampede preventionx/sync/errgroupGoroutine group + errorsSetLimit(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.Context or done channel
• Can I wait for it? — sync.WaitGroup or errgroup
• 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:

1. Find all goroutine spawns ( go func, go method) and verify shutdown mechanisms
2. Search for mutable globals and shared state without synchronization
3. Audit channel usage — ownership, direction, closure, buffer sizes
4. Find time.After in loops, missing ctx.Done() in select, unbounded spawning
5. Check mutex usage, sync.Map, atomics, and thread-safety documentation

Common Mistakes#

MistakeFixFire-and-forget goroutineProvide stop mechanism (context, done channel)Closing channel from receiverOnly the sender closestime.After in hot loopReuse time.NewTimer + ResetMissing ctx.Done() in selectAlways select on context to allow cancellationUnbounded goroutine spawningUse errgroup.SetLimit(n) or semaphoreSharing pointer via channelSend copies or immutable valueswg.Add inside goroutineCall Add before go — Wait may return early otherwiseForgetting -race in CIAlways run go test -race ./...Mutex held across I/OKeep critical sections short

Cross-References#

• -> See samber/cc-skills-golang@golang-performance skill for false sharing, cache-line padding, sync.Pool hot-path patterns
• -> See samber/cc-skills-golang@golang-context skill for cancellation propagation and timeout patterns
• -> See samber/cc-skills-golang@golang-safety skill for concurrent map access and race condition prevention
• -> See samber/cc-skills-golang@golang-troubleshooting skill for debugging goroutine leaks and deadlocks
• -> See samber/cc-skills-golang@golang-design-patterns skill for graceful shutdown patterns
• -> See samber/cc-skills-golang@golang-continuous-integration skill 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:

bash

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#

• Go Concurrency Patterns: Pipelines
• Effective Go: Concurrency