# AGENTS.md: Go service (standard library)

## Commands
`go build ./...` · `go test -race ./...` · `go vet ./...` · `golangci-lint run` · run: `go run ./cmd/server`

## Layout
- `cmd/server/main.go`: parse config, build dependencies, call `run(ctx)`; `main` only handles exit codes.
- `internal/http/`: routes and handlers; `internal/<domain>/`: logic and storage.

## HTTP
- Routes on `http.NewServeMux()` with method + path patterns: `mux.HandleFunc("POST /orders/{id}/cancel", h.cancel)`; read params with `r.PathValue`.
- Middleware is `func(http.Handler) http.Handler`, composed in one place (logging, recovery, auth, request ID).
- Decode JSON with `json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20))` and `DisallowUnknownFields()`; validate before use.
- One `writeJSON(w, status, v)` and `writeError` helper for consistent responses.
- `http.Server` with `ReadHeaderTimeout`, `ReadTimeout`, `WriteTimeout`, `IdleTimeout`; graceful `Shutdown` on signal via `signal.NotifyContext`.

## Data
- `database/sql` or `pgx/v5` pool created once; queries take `ctx`; parameterized only. Consider `sqlc` for typed queries if it's already set up.

## Style
- Errors wrapped with context (`%w`); log once at the edge with `slog`, don't log-and-return.
- No globals for dependencies; pass a struct with what each handler needs.

## Done
Build, vet, lint, and race tests pass; each handler has an `httptest` test.