golang-concurrency
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.
- License 许可
- MIT
- 最近更新
- 2026-07-27
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- golang-concurrency
- license
- MIT
- metadata
- { "author": "samber", "version": "1.1.4", "openclaw": { "emoji": "⚡", "install": [], "homepage": "https://github.com/samber/cc-skills-golang", "requires": { "bins": [ "go" ] } } }
- 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.
- allowed-tools
- Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Agent AskUserQuestion
- compatibility
- Designed for Claude Code or similar AI coding agents, and for projects using Golang.
- user-invocable
- true
02 资源文件 4
- 参考文档evals/evals.json15.6 KB
- 参考文档references/channels-and-select.md4.2 KB
- 参考文档references/pipelines.md6.9 KB
- 参考文档references/sync-primitives.md8.1 KB
03 SKILL.md 正文
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
04 同仓库更多 Skills
mergeable-please
Drive a GitHub pull request toward mergeable. Run when asked to "make a PR mergeable", "loop until the PR is ready", "fix the PR until CI/conflicts/reviews pass", or similar. Repeatedly runs `mergeable-please check`, resolves each reported blocker (conflicts, behind-base, failing/pending required CI, reviewer-loop goals), and loops until the tool reports satisfied.
golang-troubleshooting
Troubleshoot Golang programs systematically - find and fix the root cause. Use when encountering bugs, crashes, deadlocks, or unexpected behavior in Go code. Covers debugging methodology, common Go pitfalls, test-driven debugging, pprof setup and capture, Delve debugger, race detection, GODEBUG tracing, and production debugging. Start here for any 'something is wrong' situation. Not for interpreting profiles or benchmarking (→ See `samber/cc-skills-golang@golang-benchmark` skill) or applying optimization patterns (→ See `samber/cc-skills-golang@golang-performance` skill).
golang-testing
Production-ready Golang tests — table-driven tests, testify suites and mocks, parallel tests, fuzzing, fixtures, goroutine leak detection with goleak, snapshot testing, code coverage, integration tests, idiomatic test naming. Use when writing or reviewing Go tests, choosing a testing approach, setting up Go test CI, or debugging flaky/slow tests. For testify-specific APIs see `samber/cc-skills-golang@golang-stretchr-testify`; for measurement methodology see `samber/cc-skills-golang@golang-benchmark`.
golang-structs-interfaces
Golang struct and interface design patterns — composition, embedding, type assertions, type switches, interface segregation, dependency injection via interfaces, struct field tags, and pointer vs value receivers. Use this skill when designing Go types, defining or implementing interfaces, embedding structs or interfaces, writing type assertions or type switches, adding struct field tags for JSON/YAML/DB serialization, or choosing between pointer and value receivers. Also use when the user asks about "accept interfaces, return structs", compile-time interface checks, or composing small interfaces into larger ones.
golang-stretchr-testify
Comprehensive guide to stretchr/testify for Golang testing. Covers assert, require, mock, and suite packages in depth. Use when writing tests with testify, creating mocks, setting up test suites, or choosing between assert and require. Covers testify assertions, mock expectations, argument matchers, call verification, suite lifecycle, and advanced patterns like Eventually, JSONEq, and custom matchers. Apply when the codebase imports github.com/stretchr/testify.
golang-spf13-cobra
Golang CLI command tree library using spf13/cobra — cobra.Command, RunE vs Run, PersistentPreRunE hook chain, Args validators (NoArgs, ExactArgs, MatchAll, custom), persistent vs local flags, command groups, ValidArgsFunction, RegisterFlagCompletionFunc, ShellCompDirective, usage/help template customization, man-page and markdown doc generation, and testing with SetArgs/SetOut/SetErr. Apply when using or adopting spf13/cobra, or when the codebase imports `github.com/spf13/cobra`. For configuration layering alongside cobra, see the `samber/cc-skills-golang@golang-spf13-viper` skill. For general CLI architecture (project layout, exit codes, signal handling, I/O patterns), see `samber/cc-skills-golang@golang-cli`.