Home › Go › Go stdlib HTTP service AGENTS.md

Go stdlib HTTP service AGENTS.md

AGENTS.md for Go 1.27 services using only net/http, slog, and database/sql or pgx, with no web framework.

AGENTS.mdGo

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

# 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.