Go Concurrency Skill

Operator Context

Hardcoded Behaviors (Always Apply)

• CLAUDE.md Compliance: Read and follow repository CLAUDE.md before writing concurrent code
• Over-Engineering Prevention: Use concurrency only when justified by I/O, CPU parallelism, or measured bottleneck. Sequential code is correct by default
• Context First Parameter: All cancellable or I/O operations accept

  context.Context

  as first parameter
• No Goroutine Leaks: Every goroutine must have a guaranteed exit path via context, channel close, or explicit shutdown
• Race Detector Required: Run

  go test -race

  on all concurrent code during development
• Channel Ownership: Only the sender closes a channel. Never close from receiver side
• Select With Context: Every

  select

  statement in concurrent code must include a

  <-ctx.Done()

  case

Default Behaviors (ON unless disabled)

• errgroup Over WaitGroup: Prefer

  golang.org/x/sync/errgroup

  for goroutine management with error collection
• Buffered Channel Sizing: Buffer size matches expected backpressure, not arbitrary large numbers
• Directional Channel Returns: Return

  <-chan T

  (receive-only) from producer functions to prevent caller misuse
• Mutex Scope Minimization: Lock only the critical section, use

  defer Unlock()

  immediately after

  Lock()

• Loop Variable Safety: Use Go 1.22+ loop variable semantics; remove legacy

  item := item

  shadows in new code
• Graceful Shutdown: Workers and servers implement clean shutdown with drain timeout
• Atomic for Counters: Use

  atomic.Int64

  /

  atomic.Value

  for simple shared counters instead of mutex

Optional Behaviors (OFF unless enabled)

• Gopls MCP Analysis: Use gopls MCP tools to trace channel usage and context propagation —

  go_symbol_references

  for tracing channel flow,

  go_file_context

  for understanding goroutine spawn sites,

  go_diagnostics

  after concurrent code edits. Fallback:

  gopls references

  CLI or LSP tool
• Container GOMAXPROCS Tuning: Configure GODEBUG flags for container CPU limit overrides
• Performance Profiling: Profile goroutine counts and channel contention under load
• Custom Rate Limiter: Build token-bucket rate limiter instead of using

  golang.org/x/time/rate

What This Skill CAN Do

• Guide implementation of worker pools, fan-out/fan-in, and pipeline patterns
• Apply correct context propagation through concurrent call chains
• Select appropriate sync primitives (Mutex, RWMutex, WaitGroup, Once, atomic)
• Implement rate limiting with context-aware waiting
• Diagnose and fix race conditions, deadlocks, and goroutine leaks
• Structure graceful shutdown for background workers and servers

What This Skill CANNOT Do

• Fix general Go bugs unrelated to concurrency (use systematic-debugging instead)
• Optimize non-concurrent performance (use performance optimization workflows instead)
• Write tests for concurrent code (use go-testing skill instead)
• Handle Go error handling patterns (use go-error-handling skill instead)

Instructions

Step 1: Assess Concurrency Need

1. Is the work I/O-bound? (network, database, filesystem) -- concurrency likely helps
2. Is the work CPU-bound? -- concurrency helps only if parallelizable
3. Is there a measured bottleneck? -- if not measured, don't assume

Step 2: Choose the Right Primitive

sync.Mutex

sync.RWMutex

errgroup.Group

sync.WaitGroup

sync.Once

atomic.Int64

Step 3: Context Propagation

func FetchData(ctx context.Context, id string) (*Data, error) {
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()

    resultCh := make(chan *Data, 1)
    errCh := make(chan error, 1)

    go func() {
        data, err := slowOperation(id)
        if err != nil {
            errCh <- err
            return
        }
        resultCh <- data
    }()

    select {
    case data := <-resultCh:
        return data, nil
    case err := <-errCh:
        return nil, fmt.Errorf("fetch failed: %w", err)
    case <-ctx.Done():
        return nil, fmt.Errorf("fetch cancelled: %w", ctx.Err())
    }
}

// USE context: I/O, cancellable operations, request-scoped values
func FetchUserData(ctx context.Context, userID string) (*User, error) { ... }

// NO context needed: pure computation
func CalculateTotal(prices []float64) float64 { ... }

Step 4: Implement the Pattern

// Mutex for state protection
type SafeCounter struct {
    mu    sync.Mutex
    count int
}

func (c *SafeCounter) Increment() {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.count++
}

// RWMutex for read-heavy workloads
type Cache struct {
    mu    sync.RWMutex
    items map[string]any
}

func (c *Cache) Get(key string) (any, bool) {
    c.mu.RLock()
    defer c.mu.RUnlock()
    item, ok := c.items[key]
    return item, ok
}

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

import "golang.org/x/sync/errgroup"

func ProcessAll(ctx context.Context, items []Item) error {
    g, ctx := errgroup.WithContext(ctx)

    for _, item := range items {
        g.Go(func() error {
            return process(ctx, item)  // Go 1.22+: item captured correctly
        })
    }

    return g.Wait()
}

type Config struct {
    once   sync.Once
    config *AppConfig
    err    error
}

func (c *Config) Load() (*AppConfig, error) {
    c.once.Do(func() {
        c.config, c.err = loadConfigFromFile()
    })
    return c.config, c.err
}

// Unbuffered: synchronous, sender blocks until receiver ready
ch := make(chan int)

// Buffered: async up to buffer size
ch := make(chan int, 100)

// Guidelines:
// - Use unbuffered when you need synchronization
// - Use buffered to decouple sender/receiver timing
// - Buffer size should match expected backpressure

references/concurrency-patterns.md

Step 5: Run Race Detector

# ALWAYS run with race detector during development
go test -race -count=1 -v ./...

# Run specific test with race detection
go test -race -run TestConcurrentOperation ./...

Step 6: Concurrency Checklist

• Context propagation - All I/O operations accept context
• Goroutine exit paths - Every goroutine can terminate
• Channel closure - Channels closed by sender only
• Select with context - All selects include

  <-ctx.Done()

• Proper synchronization - Shared state protected
• Race detector passes -

  go test -race

  clean
• Graceful shutdown - Workers stop cleanly
• No goroutine leaks - All goroutines tracked

Error Handling

Error: "DATA RACE detected by race detector"

1. Identify the variable from the race detector output (it shows goroutine stacks)
2. Protect with

   sync.Mutex

   for complex state, or

   atomic

   for simple counters
3. If using channels, ensure the variable is only accessed by one goroutine at a time
4. Re-run

   go test -race

   to confirm fix

Error: "all goroutines are asleep - deadlock!"

1. Check for unbuffered channel sends with no receiver ready
2. Check for mutex lock ordering inconsistencies
3. Ensure channels are closed when done to unblock

   range

   loops
4. Add buffering to channels where appropriate

Error: "context deadline exceeded" in concurrent operations

1. Check if timeout is realistic for the operation
2. Verify context is propagated correctly (not using

   context.Background()

   when a parent context exists)
3. Ensure goroutines check

   ctx.Done()

   in their select loops
4. Consider increasing timeout or adding per-operation timeouts with

   context.WithTimeout

Anti-Patterns

Anti-Pattern 1: Goroutine Without Exit Path

go func() { for { doWork() } }()

<-ctx.Done()

Anti-Pattern 2: Unnecessary Concurrency

Anti-Pattern 3: Closing Channel From Receiver Side

close(ch)

defer close(ch)

Anti-Pattern 4: Mutex Lock Without Defer Unlock

mu.Lock()

mu.Unlock()

Unlock()

defer mu.Unlock()

mu.Lock()

Anti-Pattern 5: Ignoring Context in Select

select { case msg := <-ch: handle(msg) }

<-ctx.Done()

select

case <-ctx.Done(): return

References

• Anti-Rationalization - Prevents shortcut rationalizations
• Verification Checklist - Pre-completion checks

Domain-Specific Anti-Rationalization

go test -race

Reference Files

• ${CLAUDE_SKILL_DIR}/references/concurrency-patterns.md

  : Worker pool, fan-out/fan-in, pipeline, rate limiter, and graceful shutdown patterns with full code examples