Golang Concurrency

Samuel BertheCommunityCreated by samberDistributed by Samuel Berthe

Skill
Guidelines
Software development
MIT
Low risk

From the author

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).

— the description by samber

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a comprehensive framework for designing and auditing concurrent Go applications. It emphasizes structured concurrency, focusing on goroutine lifecycle management, leak prevention, and the correct application of synchronization primitives like channels, mutexes, and atomics. The skill includes specific patterns for worker pools, fan-out/fan-in pipelines, and error propagation using errgroup, while providing a systematic approach to auditing codebases for concurrency issues.

What it does

Provides design patterns for goroutine lifecycle management and clean shutdown.
Offers guidance on choosing between channels, mutexes, atomics, and sync primitives.
Defines best practices for implementing worker pools and pipeline architectures.
Includes a structured checklist for reviewing concurrent code and identifying potential leaks.
Supports multi-agent orchestration for auditing concurrency across large codebases.
References standard synchronization tools like errgroup, singleflight, and sync.Map.

When to use it

When writing new concurrent Go code that requires robust lifecycle management.
When reviewing pull requests to identify goroutine leaks or ownership violations.
When auditing an existing codebase for unprotected shared state or synchronization errors.
When determining the appropriate concurrency primitive for a specific synchronization task.

Advantages

Promotes structured concurrency to prevent goroutine leaks and deadlocks.
Standardizes the use of synchronization primitives across development teams.
Facilitates systematic auditing of complex concurrent systems.
Provides clear, actionable patterns for common concurrency challenges.

Usage examples

“Review this PR for goroutine leaks and synchronization issues.”: The agent analyzes the diff, checking for missing context propagation, improper channel closure, and unprotected shared state.
“Help me implement a worker pool for processing tasks.”: The agent provides a pattern using errgroup.SetLimit to manage bounded concurrency and ensure clean error handling.
“Audit the codebase for potential concurrency bugs.”: The agent orchestrates multiple sub-agents to scan for mutable globals, improper channel usage, and missing context cancellation.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/samber/golang-concurrency/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip golang-concurrency.zip -d .agents/skills

Documentation by samber

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:

[ ] 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:

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

Files

ATTRIBUTION.mdAdded by AutoGineer911 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md9.3 KiB
evals/evals.json16.1 KiB
references/channels-and-select.md4.3 KiB
references/pipelines.md7.2 KiB
references/sync-primitives.md8.6 KiB

references/sync-primitives.md

Sync Primitives Deep Dive

sync.Mutex
- Embedding Convention
sync.RWMutex
sync/atomic
sync.Map
sync.Pool
sync.Once
sync.WaitGroup
- Go 1.25+: wg.Go
- Go <1.25 fallback
golang.org/x/sync/singleflight
golang.org/x/sync/errgroup
- Bounded Concurrency with SetLimit

sync.Mutex

Protects shared state with exclusive access. MUST hold the lock for the shortest time possible — NEVER hold a mutex across I/O, network calls, or channel operations.

type SafeCache struct {
    mu    sync.Mutex
    items map[string]string
}

func (c *SafeCache) Get(key string) (string, bool) {
    c.mu.Lock()
    defer c.mu.Unlock()
    v, ok := c.items[key]
    return v, ok
}

func (c *SafeCache) Set(key, value string) {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.items[key] = value
}

Embedding Convention

Embed the mutex as an unexported field, placed directly above the fields it protects:

type Registry struct {
    mu      sync.Mutex // protects entries
    entries map[string]Entry
}

sync.RWMutex

SHOULD be used when reads greatly outnumber writes. Multiple goroutines can hold RLock simultaneously; Lock is exclusive.

type Config struct {
    mu     sync.RWMutex
    values map[string]string
}

func (c *Config) Get(key string) string {
    c.mu.RLock()
    defer c.mu.RUnlock()
    return c.values[key]
}

func (c *Config) Set(key, value string) {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.values[key] = value
}

Pitfall: Do not upgrade RLock to Lock — this deadlocks. Release RLock first, then acquire Lock.

sync/atomic

Lock-free operations for simple values. SHOULD be preferred over Mutex for simple counter operations. Faster than mutex for low-contention counters and flags.

// ✓ Good — atomic for a simple counter
var requestCount atomic.Int64

func handleRequest() {
    requestCount.Add(1)
}

func getCount() int64 {
    return requestCount.Load()
}

// ✓ Good — atomic.Bool for a shutdown flag
var shuttingDown atomic.Bool

func shutdown() {
    shuttingDown.Store(true)
}

func isRunning() bool {
    return !shuttingDown.Load()
}

Go 1.19+ provides typed atomics (atomic.Int64, atomic.Bool, atomic.Pointer[T]) — prefer these over raw atomic.AddInt64/atomic.LoadInt64.

sync.Map

SHOULD only be used for write-once/read-many patterns. Optimized for two common patterns: (1) keys are written once and read many times, (2) multiple goroutines read/write disjoint key sets. For other patterns, a plain map + sync.RWMutex is faster.

var cache sync.Map

func Get(key string) (any, bool) {
    return cache.Load(key)
}

func Set(key string, value any) {
    cache.Store(key, value)
}

func GetOrSet(key string, compute func() any) any {
    if v, ok := cache.Load(key); ok {
        return v
    }
    v, _ := cache.LoadOrStore(key, compute())
    return v
}

When NOT to use sync.Map: when you need to iterate, get the length, or when writes are frequent and keys overlap heavily. Use sync.RWMutex + map instead.

sync.Pool

Reuse temporary objects to reduce GC pressure. MUST NOT store pointers to stack-allocated objects. Objects in the pool may be reclaimed at any GC cycle — do not store persistent state.

var bufPool = sync.Pool{
    New: func() any {
        return new(bytes.Buffer)
    },
}

func process(data []byte) string {
    buf := bufPool.Get().(*bytes.Buffer)
    defer func() {
        buf.Reset()
        bufPool.Put(buf)
    }()

    buf.Write(data)
    // ... transform ...
    return buf.String()
}

Rules:

Always Reset() before Put() — returning dirty objects causes bugs
Do not assume an object from Get() is zeroed — the New func only runs if the pool is empty
Best for short-lived, frequently allocated objects (buffers, encoders, temporary structs)

sync.Once

MUST be used for one-time initialization. Execute exactly once, regardless of how many goroutines call it concurrently. Thread-safe by design.

type DBClient struct {
    initOnce  sync.Once
    closeOnce sync.Once
    conn      *sql.DB
}

func (c *DBClient) getConn() *sql.DB {
    c.initOnce.Do(func() {
        var err error
        c.conn, err = sql.Open("postgres", dsn)
        if err != nil {
            panic(fmt.Sprintf("db init: %v", err))
        }
    })
    return c.conn
}

func (c *DBClient) Close() error {
    var err error
    c.closeOnce.Do(func() {
        err = c.conn.Close()
    })
    return err
}

Go 1.21+ also provides sync.OnceFunc, sync.OnceValue, and sync.OnceValues for simpler use cases:

var loadConfig = sync.OnceValue(func() *Config {
    cfg, err := parseConfig("config.yaml")
    if err != nil {
        panic(err)
    }
    return cfg
})

// Usage: cfg := loadConfig()

sync.WaitGroup

Use sync.WaitGroup when you only need to wait for a set of goroutines to finish.

Go 1.25+: `wg.Go`

WaitGroup.Go starts a goroutine, adds it to the group, and removes it from the group when the function returns.

func processAll(items []Item) {
    var wg sync.WaitGroup

    for _, item := range items {
        // Go 1.22+ loop variables are per-iteration when the module has `go 1.22+`.
        // Do not add `item := item` solely for closure capture in modern modules.
        wg.Go(func() {
            process(item)
        })
    }

    wg.Wait()
}

Rules:

WaitGroup.Go is Go 1.25+, not Go 1.24.
The function passed to wg.Go must not panic.
WaitGroup does not propagate errors and does not cancel siblings.
For first-error-wins, cancellation, concurrency limits, or returned values, use golang.org/x/sync/errgroup.

Benefits of wg.Go():

No manual Add/Done bookkeeping
Lower risk of Add/Wait ordering bugs
Cleaner API for simple fire-and-wait work

When to use: Go 1.25+ projects for simple goroutines that must all finish, do not return errors, do not need cancellation, and must not panic. Use errgroup when work returns errors, needs cancellation, limits, or first-error behavior.

Go <1.25 fallback

func processAll(ctx context.Context, items []Item) {
    var wg sync.WaitGroup
    for _, item := range items {
        wg.Add(1) // Add BEFORE go
        go func(item Item) {
            defer wg.Done()
            process(ctx, item)
        }(item)
    }
    wg.Wait() // blocks until all goroutines finish
}

// ✗ Bad — Add inside the goroutine (race: Wait may return before Add runs)
go func() {
    wg.Add(1)
    defer wg.Done()
    process(item)
}()

golang.org/x/sync/singleflight

Deduplicates concurrent calls for the same key. When multiple goroutines request the same resource simultaneously, only one executes; the rest wait and share the result.

var group singleflight.Group

func GetUser(ctx context.Context, id string) (*User, error) {
    v, err, _ := group.Do(id, func() (any, error) {
        // Only one goroutine executes this for a given id
        return db.QueryUser(ctx, id)
    })
    if err != nil {
        return nil, err
    }
    return v.(*User), nil
}

Use cases: cache stampede prevention, deduplicating expensive lookups (DB, API), rate-limited external service calls.

golang.org/x/sync/errgroup

Goroutine group with error propagation. Returns the first error from any goroutine. With WithContext, cancels remaining goroutines on first error.

func fetchAll(ctx context.Context, urls []string) ([]Response, error) {
    g, ctx := errgroup.WithContext(ctx) // cancel siblings on first error
    results := make([]Response, len(urls))

    for i, url := range urls {
        g.Go(func() error {
            resp, err := fetch(ctx, url)
            if err != nil {
                return fmt.Errorf("fetching %s: %w", url, err)
            }
            results[i] = resp // safe: each goroutine writes to its own index
            return nil
        })
    }

    if err := g.Wait(); err != nil {
        return nil, err
    }
    return results, nil
}

Bounded Concurrency with SetLimit

SHOULD use SetLimit to bound concurrency and avoid unbounded goroutine spawning.

g, ctx := errgroup.WithContext(ctx)
g.SetLimit(10) // at most 10 goroutines run concurrently

for _, task := range tasks {
    g.Go(func() error {
        return process(ctx, task)
    })
}
return g.Wait()

This replaces hand-rolled worker pools for most use cases.

→ See samber/cc-skills-golang@golang-concurrency skill for high-level patterns and decision trees.

Requirements and compatibility

Written for: Claude Code, OpenAI Codex

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Declares allowed tools, Claude Code frontmatter, Needs network access

The author says: Designed for Claude Code, Codex or similar harness, and for projects using Golang.

Security

What our scanner noticed· Low risk

Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

samber

Publisher

Samuel Berthe (Community)

Distributed by

Samuel Berthe

Source

samber/cc-skills-golang · skills/golang-concurrency · commit bb1d43d

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by samber or Samuel Berthe.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download golang-concurrency.zip