## Build & Development Commands
- Use modules only. Run go mod tidy after any dependency change.
- Compile with go build ./... (or go install ./...) and always include -trimpath and -buildvcs=true.
- Leverage new Go 1.24 tooling
- go get -tool / tool meta-pattern to manage developer CLIs in go.mod.
- go build -json or go test -json for machine-readable CI output.
- Race & fuzz: go test -race ./... and (where useful) go test -fuzz=Fuzz.*.
- Static analysis: run go vet ./... plus golangci-lint run with a strict config (default fast-linters, style, and security sets).
- Code generation: commit every file produced by go generate ./...; guard the target directories in CI.

## Testing Guidelines
- Default to table-driven tests—define an inline slice of structs and iterate with t.Run.
- Assertions use github.com/stretchr/testify/require; prefer require over assert to stop on first failure and keep logs readable.
- Subtests & parallelism: call t.Parallel() in each sub-test when safe; name sub-tests with clear, human-readable strings.
- Coverage: go test -coverprofile=coverage.out && go tool cover -func=coverage.out; fail CI if coverage < 90 %.
- Benchmarks live in *_test.go; run with go test -bench=. -benchmem.
- Fuzz targets go in *_test.go and are gated behind build tag //go:build fuzz.
- No flaky sleeps—use fake clocks or context deadlines instead.

## Code Style & Guidelines
- Always run gofmt -s (or goimports); zero diff is mandatory.
- Follow “Go Code Review Comments.” Short package names, upper-camel exported identifiers, error strings without caps, etc.
- Latest language:
- Use generic type aliases where it simplifies APIs.
- Prefer the range f() iterator pattern added in 1.23/1.24 for streaming.
- Opt into map performance tweaks and sync/atomic generics when appropriate.
- Error handling: wrap with %w, expose sentinel errors, and test them with errors.Is/As.
- Context: first param in any request-scoped func (func Do(ctx context.Context, ...)).
- Concurrency: avoid goroutine leaks; use context or errgroup for fan-out.
- Lint gates: enable staticcheck, unused, revive, goimports, errcheck, gosec in golangci-lint config.

## Documentation Guidelines
- Doc comments before every exported symbol—first sentence starts with the identifier name and ends with a period.
- Package-level docs live in doc.go; begin with Package foo sentence.
- Examples: include runnable ExampleXxx functions for key APIs.
- README / module docs explain high-level design; reference them from pkg.go.dev badge.
- Keep CHANGELOG anchored to Go releases; note when 1.24-specific features are used.