go

---
name: go
description: "Go module conventions for this repo: idiomatic error handling, goroutines, testing patterns, and toolchain hygiene."
user-invocable: false
allowed-tools:
  - Bash(go *)
---

# Go Project Guide

This repo uses Go. Apply these conventions.

## Modules

- `go.mod` declares the module path and minimum Go version — do not edit manually without `go mod` commands.
- `go mod tidy` after adding or removing imports to keep `go.sum` consistent.
- Use `go mod vendor` in projects that require hermetic builds; add `vendor/` to git.
- Pin indirect dependencies only when a transitive vulnerability requires it.

## Error Handling

- Return errors as the last value; check them at every call site.
- Never ignore an error with `_` unless the function's signature makes it semantically safe.
- Wrap errors with context: `fmt.Errorf("reading config: %w", err)` — the `%w` verb enables `errors.Is`/`errors.As`.
- Define sentinel errors as `var ErrSomething = errors.New("...")` in the package that owns them.

## Goroutines

- Every goroutine must have a clear exit condition — no goroutine leaks.
- Use `context.Context` for cancellation propagation; pass it as the first argument.
- Prefer `sync.WaitGroup` for fan-out + join; prefer channels for producer/consumer patterns.
- Race detector in CI: `go test -race ./...`.

## Testing

- Test files end in `_test.go` and live alongside the code they test.
- Table-driven tests: `[]struct{ name, input, want }` with `t.Run(tc.name, ...)`.
- Use `t.Helper()` in assertion helpers so failure lines point to the call site.
- Benchmarks use `func BenchmarkXxx(b *testing.B)` — run with `go test -bench=.`.

## Formatting

- `gofmt` and `goimports` are non-negotiable — run in CI; reject unformatted code.
- `go vet ./...` catches common mistakes; treat warnings as errors.
- `golangci-lint` for broader static analysis.