go

name	go
description	Use when: write or review idiomatic Go with explicit errors, clear concurrency, and small interfaces.

Goal: simple, explicit Go that reads plainly and handles errors honestly.

Use for:

• new packages, services, or CLIs in Go
• reviewing error handling, concurrency, and API shape
• simplifying over-abstracted or clever code

Workflow:

1. Return errors explicitly; wrap with context using %w.
2. Keep interfaces small and defined by the consumer.
3. Use goroutines with clear ownership and a way to stop.
4. Pass context.Context for cancellation and deadlines.
5. Prefer composition and plain structs over inheritance-like tricks.
6. Verify with go test, go vet, and the race detector.

Idioms:

• handle errors immediately; do not ignore them
• defer for cleanup near acquisition
• channels to communicate, mutexes to protect state
• accept interfaces, return concrete types

Rules:

• never discard an error without a stated reason
• guard shared state; run tests with -race
• keep packages cohesive; avoid util grab-bags
• clarity over cleverness; the obvious code wins