/golang-rules

name: golang-rules
description: "Go coding rules: style, patterns, security, testing. Triggers: .go, go.mod, go.sum, Gin, Echo, Gorilla, testing, gofmt."
effort: medium
user-invocable: false
allowed-tools: Read

Go Rules

These rules come from `app/rules/golang/` in ai-toolkit. They cover the project's standards for coding style, frameworks, patterns, security, and testing in Go. Apply them when writing or reviewing Go code.

Go Coding Style

Naming

• MixedCaps/mixedCaps only. No underscores in Go names (except test functions).
• Exported: `PascalCase`. Unexported: `camelCase`. Acronyms: `HTTPClient`, `userID`.
• Short variable names in small scopes: `i`, `r`, `w`, `ctx`, `err`.
• Descriptive names in larger scopes: `userRepository`, `requestTimeout`.
• Package names: short, lowercase, singular (`auth`, `user`, not `utils`, `helpers`).

Packages

• One package per directory. Package name = directory name.
• Avoid `util`, `common`, `helpers` packages. Name by what it provides.
• Keep package APIs small. Export only what consumers need.
• Use `internal/` directory for packages not meant for external consumption.

Functions

• Accept interfaces, return structs.
• First parameter `ctx context.Context` if the function does I/O or may be cancelled.
• Return `(result, error)` tuple. Error is always last return value.
• Use named return values only for documentation, not for naked returns.
• Keep functions short. If >40 lines, consider splitting.

Error Handling

• Always check errors. Never use `_` to discard errors silently.
• Wrap errors with context: `fmt.Errorf("fetching user %s: %w", id, err)`.
• Use sentinel errors (`var ErrNotFound = errors.New(...)`) for expected conditions.
• Use `errors.Is()` and `errors.As()` for error checking, not type assertions.

Formatting

• Use `gofmt` / `goimports`. No formatting debates in Go.
• Use `golangci-lint` with a `.golangci.yml` config in CI.
• Use `go vet` as minimum static analysis.

Struct Design

• Use struct embedding for composition, not inheritance.
• Prefer value receivers for small structs, pointer receivers for large or mutable.
• Be consistent: all methods on a type use the same receiver type.
• Use struct literals with field names: `User{Name: "Ada", Age: 30}`.

Concurrency

• Do not start goroutines without a plan to stop them.
• Use `sync.WaitGroup` or `errgroup.Group` to coordinate goroutines.
• Use channels for communication, mutexes for state protection.
• Prefer `context.Context` for cancellation and timeouts over manual signaling.

Go Frameworks

Standard Library HTTP

• Use `http.NewServeMux()` (Go 1.22+ with method patterns) for simple APIs.
• Use `http.HandlerFunc` for handlers. Compose with middleware pattern.
• Use `context.Context` from `r.Context()` in all handlers.
• Use `http.TimeoutHandler` to prevent slow handlers from hanging.

Chi / Gorilla Mux

• Use Chi for routing with middleware chains and URL params.
• Use `chi.URLParam(r, "id")` to extract path parameters.
• Use middleware groups: `r.Group(func(r chi.Router) { r.Use(authMiddleware) })`.
• Prefer Chi over Gorilla Mux (Gorilla was archived, Chi actively maintained).

Gin / Echo

• Use Gin for high-performance APIs with built-in validation.
• Use binding tags: `binding:"required,email"` on struct fields.
• Use middleware for cross-cutting: logging, recovery, CORS, auth.
• Use `c.ShouldBindJSON()` over `c.BindJSON()` to handle errors yourself.

GORM / sqlx / pgx

• Use `sqlx` for SQL-first with struct scanning (lightweight).
• Use `pgx` directly for PostgreSQL-specific features and performance.
• Use GORM only when rapid prototyping outweighs SQL control.
• Always use prepared statements or parameterized queries.
• Use `sqlx.In()` for dynamic IN clauses safely.

gRPC

• Define services in `.proto` files. Generate Go code with `protoc`.
• Use interceptors for auth, logging, and tracing (equivalent to middleware).
• Use deadlines (context timeout) on every RPC call.
• Use streaming RPCs for real-time data, unary for request-response.

Configuration

• Use `envconfig` or `viper` for configuration from env/files.
• Use struct tags for env mapping: `envconfig:"DATABASE_URL"`.
• Validate config at startup. Fail fast on invalid configuration.
• Use `flag` package for CLI arguments in tools and utilities.

Observability

• Use `slog` (Go 1.21+) for structured logging. Replace `log` package.
• Use OpenTelemetry for distributed tracing and metrics.
• Export metrics via Prometheus endpoint.
• Use `pprof` for CPU and memory profiling in development.

Project Layout

• Follow Standard Go Project Layout: `cmd/`, `internal/`, `pkg/`.
• Entry points in `cmd/appname/main.go`.
• Business logic in `internal/`. Shared libraries in `pkg/`.
• Use `Makefile` for common tasks: build, test, lint, run.

Go Patterns

Error Handling

• Wrap errors with context at each call site: `fmt.Errorf("loading config: %w", err)`.
• Define domain error types with `errors.New()` or custom error structs.
• Use `errors.Is()` for sentinel errors, `errors.As()` for typed errors.
• Return errors, do not panic. Reserve `panic` for truly unrecoverable states.
• Handle errors immediately after the call. No deferred error checking.

Concurrency

• Use `errgroup.Group` for concurrent operations that may fail.
• Use `sync.Once` for one-time initialization (singleton pattern).
• Use `sync.Map` only for append-mostly maps with concurrent access.
• Use buffered channels as semaphores: `sem := make(chan struct{}, maxConcurrency)`.
• Prefer `context.WithTimeout` over manual timers for deadline management.

Interface Design

• Keep interfaces small: 1-3 methods. Compose larger interfaces from smaller ones.
• Define interfaces where they are consumed, not where they are implemented.
• Use `io.Reader`, `io.Writer`, `fmt.Stringer` and standard interfaces where applicable.
• Avoid returning interfaces from functions. Return concrete types.

Options Pattern

• Use functiona