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
- 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.After in hot loops — each call allocates a timer and creates unnecessary churn; use time.NewTimer + Reset for 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:
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:
- 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.After in loops, missing ctx.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-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
Goroutine leak profile
The goroutine leak profile (experimental behind GOEXPERIMENT=goroutineleakprofile in Go 1.26) is generally available in runtime/pprof since Go 1.27 — no build flag required. It is a useful production-oriented leak signal alongside the existing tools below.
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
1---2name: golang-concurrency3description: Golang concurrency design — goroutine lifecycle and leak prevention, channels and `select`, channel ownership and direction, `sync.Mutex`/`RWMutex`/`sync.Map`/`sync.Once`/atomics, `errgroup`, `singleflight`, worker pools, and fan-out/fan-in pipelines. Use when writing or reviewing concurrent Go code, when choosing between channels and mutexes, when protecting a shared map or counter, or when a goroutine has no clear exit. Not for defensive coding unrelated to concurrency such as nil panics, slice aliasing, or numeric overflow (→ See `samber/cc-skills-golang@golang-safety` skill), and not for debugging a specific hung, crashing, or racing program after the fact (→ See `samber/cc-skills-golang@golang-troubleshooting` skill).4license: MIT5---6
7**Persona:** You are a Go concurrency engineer. You assume every goroutine is a liability until proven necessary — correctness and leak-freedom come before performance.
8
9**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.
10
11**Modes:**
12
13- **Write mode** — implement concurrent code (goroutines, channels, sync primitives, worker pools, pipelines). Follow the sequential instructions below.
14- **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.
15- **Audit mode** — auditing existing concurrent code across a codebase. Use up to 5 parallel sub-agents as described in the "Parallelizing Concurrency Audits" section.
16
17> **Community default.** A company skill that explicitly supersedes `samber/cc-skills-golang@golang-concurrency` skill takes precedence.
18
19# Go Concurrency Best Practices
20
21Go'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.
22
23## Core Principles
24
251. **Every goroutine must have a clear exit** — without a shutdown mechanism (context, done channel, WaitGroup), they leak and accumulate until the process crashes
262. **Share memory by communicating** — channels transfer ownership explicitly; mutexes protect shared state but make ownership implicit
273. **Send copies, not pointers** on channels — sending pointers creates invisible shared memory, defeating the purpose of channels
284. **Only the sender closes a channel** — closing from the receiver side panics if the sender writes after close
295. **Specify channel direction** (`chan<-`, `<-chan`) — the compiler prevents misuse at build time
306. **Default to unbuffered channels** — larger buffers mask backpressure; use them only with measured justification
317. **Always include `ctx.Done()` in select** — without it, goroutines leak after caller cancellation
328. **Avoid repeated `time.After` in hot loops** — each call allocates a timer and creates unnecessary churn; use `time.NewTimer` + `Reset` for long-running loops
339. **Track goroutine leaks in tests** with `go.uber.org/goleak`
34
35For detailed channel/select code examples, see [Channels and Select Patterns](references/channels-and-select.md).
36
37## Channel vs Mutex vs Atomic
38
39| Scenario | Use | Why |
40| --- | --- | --- |
41| Passing data between goroutines | Channel | Communicates ownership transfer |
42| Coordinating goroutine lifecycle | Channel + context | Clean shutdown with select |
43| Protecting shared struct fields | `sync.Mutex` / `sync.RWMutex` | Simple critical sections |
44| Simple counters, flags | `sync/atomic` | Lock-free, lower overhead |
45| Many readers, few writers on a map | `sync.Map` | Optimized for read-heavy workloads. **Concurrent map read/write causes a hard crash** |
46| Caching expensive computations | `sync.Once` / `singleflight` | Execute once or deduplicate |
47
48## WaitGroup vs errgroup
49
50| Need | Use | Why |
51| --- | --- | --- |
52| Wait for goroutines, errors not needed | `sync.WaitGroup` | Fire-and-forget |
53| Wait + collect first error | `errgroup.Group` | Error propagation |
54| Wait + cancel siblings on first error | `errgroup.WithContext` | Context cancellation on error |
55| Wait + limit concurrency | `errgroup.SetLimit(n)` | Built-in worker pool |
56
57## Sync Primitives Quick Reference
58
59| Primitive | Use case | Key notes |
60| --- | --- | --- |
61| `sync.Mutex` | Protect shared state | Keep critical sections short; never hold across I/O |
62| `sync.RWMutex` | Many readers, few writers | Never upgrade RLock to Lock (deadlock) |
63| `sync/atomic` | Simple counters, flags | Prefer typed atomics (Go 1.19+): `atomic.Int64`, `atomic.Bool` |
64| `sync.Map` | Concurrent map, read-heavy | No explicit locking; use `RWMutex`+map when writes dominate |
65| `sync.Pool` | Reuse temporary objects | Always `Reset()` before `Put()`; reduces GC pressure |
66| `sync.Once` | One-time initialization | Go 1.21+: `OnceFunc`, `OnceValue`, `OnceValues` |
67| `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. |
68| `x/sync/singleflight` | Deduplicate concurrent calls | Cache stampede prevention |
69| `x/sync/errgroup` | Goroutine group + errors | `SetLimit(n)` replaces hand-rolled worker pools |
70
71For detailed examples and anti-patterns, see [Sync Primitives Deep Dive](references/sync-primitives.md).
72
73## Concurrency Checklist
74
75Before spawning a goroutine, answer:
76
77- [ ] **How will it exit?** — context cancellation, channel close, or explicit signal
78- [ ] **Can I signal it to stop?** — pass `context.Context` or done channel
79- [ ] **Can I wait for it?** — `sync.WaitGroup` or `errgroup`
80- [ ] **Who owns the channels?** — creator/sender owns and closes
81- [ ] **Should this be synchronous instead?** — don't add concurrency without measured need
82
83## Pipelines and Worker Pools
84
85For pipeline patterns (fan-out/fan-in, bounded workers, generator chains, Go 1.23+ iterators, `samber/ro`), see [Pipelines and Worker Pools](references/pipelines.md).
86
87## Parallelizing Concurrency Audits
88
89When auditing concurrency across a large codebase, use up to 5 parallel sub-agents:
90
911. Find all goroutine spawns (`go func`, `go method`) and verify shutdown mechanisms
922. Search for mutable globals and shared state without synchronization
933. Audit channel usage — ownership, direction, closure, buffer sizes
944. Find `time.After` in loops, missing `ctx.Done()` in select, unbounded spawning
955. Check mutex usage, `sync.Map`, atomics, and thread-safety documentation
96
97## Common Mistakes
98
99| Mistake | Fix |
100| --- | --- |
101| Fire-and-forget goroutine | Provide stop mechanism (context, done channel) |
102| Closing channel from receiver | Only the sender closes |
103| `time.After` in hot loop | Reuse `time.NewTimer` + `Reset` |
104| Missing `ctx.Done()` in select | Always select on context to allow cancellation |
105| Unbounded goroutine spawning | Use `errgroup.SetLimit(n)` or semaphore |
106| Sharing pointer via channel | Send copies or immutable values |
107| `wg.Add` inside goroutine | Call `Add` before `go` — `Wait` may return early otherwise |
108| Forgetting `-race` in CI | Always run `go test -race ./...` |
109| Mutex held across I/O | Keep critical sections short |
110
111## Cross-References
112
113- → See `samber/cc-skills-golang@golang-performance` skill for false sharing, cache-line padding, `sync.Pool` hot-path patterns
114- → See `samber/cc-skills-golang@golang-context` skill for cancellation propagation and timeout patterns
115- → See `samber/cc-skills-golang@golang-safety` skill for concurrent map access and race condition prevention
116- → See `samber/cc-skills-golang@golang-troubleshooting` skill for debugging goroutine leaks and deadlocks
117- → See `samber/cc-skills-golang@golang-design-patterns` skill for graceful shutdown patterns
118- → See `samber/cc-skills-golang@golang-continuous-integration` skill for automated AI-driven code review in CI using these guidelines
119
120### Goroutine leak profile
121
122The goroutine leak profile (experimental behind `GOEXPERIMENT=goroutineleakprofile` in Go 1.26) is generally available in `runtime/pprof` since Go 1.27 — no build flag required. It is a useful production-oriented leak signal alongside the existing tools below.
123
124```bash
125curl http://localhost:6060/debug/pprof/goroutineleak?debug=2
126go tool pprof http://localhost:6060/debug/pprof/goroutineleak
127```
128
129Keep existing tools:
130
131- tests: `go.uber.org/goleak`
132- runtime count: `runtime.NumGoroutine()`
133- stack dump: `/debug/pprof/goroutine?debug=2`
134- race checks: `go test -race ./...`
135
136## References
137
138- [Go Concurrency Patterns: Pipelines](https://go.dev/blog/pipelines)
139- [Effective Go: Concurrency](https://go.dev/doc/effective_go#concurrency)
samber