go-context

Files (5)

• SKILL.md
• cause-and-detach.md · references/
• http-and-testing.md · references/
• timeout-budgets.md · references/
• values.md · references/

SKILL.md (first lines)

# Go Context

`context.Context` controls cancellation, deadlines, and request-scoped values
across API boundaries. Misusing it causes goroutine leaks, orphaned work,
and subtle production bugs.

> Community default. A project skill or agent-config rule that explicitly
> supersedes `go-context` takes precedence over this one.

Detailed reference material, loaded on demand:

- `references/timeout-budgets.md` — dividing a parent's remaining budget,
  reading `ctx.Deadline()`.
- `references/values.md` — context key types, accessors, collision traps.
- `references/http-and-testing.md` — request context in handlers and
  middleware, and cancellation tests.
- `references/cause-and-detach.md` — `WithCancelCause`, `WithTimeoutCause`,
  `WithoutCancel`, `AfterFunc`.

Read a reference file only when the section below is not enough.

## 1. Core Rules

### Context is always the first parameter:

```go
// ✅ Good — context is first
func GetUser(ctx context.Context, id string) (*User, error)
func (s *Service) Process(ctx context.Context, req Request) error

// ❌ Bad — context buried in the middle or end
func GetUser(id string, ctx context.Context) (*User, error)
func Process(req Request, ctx context.Context) error
```

### NEVER store context in a struct:

```go
// ❌ Bad — context stored in struct
type Server struct {
    ctx    context.Context // NEVER do this
    cancel context.CancelFunc
}

// ✅ Good — pass context through method parameters
func (s *Server) Shutdown(ctx context.Context) error {
    return s.httpServer.Shutdown(ctx)
}
```

Context represents the lifetime of a single operation, not the lifetime of an object.

### NEVER pass nil context:

```go
// ❌ Bad
doSomething(nil, data)

// ✅ Good — use context.TODO() if unsure which context to use
doSomething(context.TODO(), data)

// ✅ Good — use context.Background() for top-level/main
doSomething(context.Background(), data)
```

## 2. Cancellation

### Always defer cancel:

```go
// ✅ Good — cancel called even if operation succeeds
ctx, cancel := context.WithCancel(parentCtx)
defer cancel()

result, err := longOperation(ctx)
```

Failing to call cancel leaks resources (timers, goroutines) until the parent
context is cancelled.

### Use WithCancel for manual cancellation:

```go
func (s *Supervisor) Run(ctx context.Context) error {
    ctx, cancel := context.WithCancel(ctx)
    defer cancel()

    g, ctx := errgroup.WithContext(ctx)

    g.Go(func() error { return s.runWorkerA(ctx) })
    g.Go(func() error { return s.runWorkerB(ctx) })

    // If any worker returns an error, errgroup cancels ctx,
    // which signals all other workers to stop.
    return g.Wait()
}
```

### Check context cancellation in loops:

```go
// ✅ Good — respects cancellation
func processItems(ctx context.Context, items []Item) error {
    for _, item := range items {
        if err := ctx.Err(); err != nil {
            return fmt.Errorf("processing cancelled: %w", err)
        }
        if err := process(ctx, item); err != nil {
            return fmt.Errorf("process item %s: %w", item.ID, err)
        }
    }
    return nil
}

// ❌ Bad — runs to completion even if cancelled
func processItems(ctx context.Context, items []Item) error {
    for _, item := range items {
        process(ctx, item) // ignores ctx cancellation between items
    }

From eduardo-sl/go-agent-skills, MIT.

More from eduardo-sl/go-agent-skills