AGENTS.md for a Go service

An AGENTS.md for a Go HTTP service with sqlc: make targets, error-wrapping style, the codegen-first DB workflow, and hard test rules.

# orderd (Go service)

## Project Overview
Go 1.23 HTTP API: chi router, sqlc-generated Postgres queries, structured
logging with slog. Single binary, config from environment.

## Setup & Commands
```bash
make dev              # run with live reload (air)
make test             # go test ./... with race detector
go test ./internal/orders/ -run TestCreate   # single package/test
make lint             # golangci-lint; the linter config is the style guide
make gen              # regenerate sqlc code after editing queries/*.sql
make migrate-up       # apply migrations (goose)
```

## Structure
- `cmd/orderd/` - main; wiring only, no logic
- `internal/<domain>/` - one package per bounded context (orders, billing);
  each owns its handlers, service, and queries
- `internal/platform/` - shared infra (db pool, middleware, config)
- `queries/*.sql` - sqlc source; generated code lands in `internal/*/gen/`

## Code Style
- Errors: wrap with `fmt.Errorf("doing x: %w", err)`; sentinel errors are
  package-level `var ErrNotFound = errors.New(...)`. No panics outside main.
- Accept interfaces, return structs. Interfaces are defined by the consumer.
- Context first argument, always; no context in struct fields.
- Table-driven tests with subtests; `t.Parallel()` unless there's shared state.

## Database workflow
Edit `queries/*.sql`, then run the codegen, then implement against the
generated types - in that order. Handwritten SQL in Go strings is not accepted.

## Boundaries
- `internal/*/gen/` is generated by sqlc - never edit it directly.
- No `time.Sleep` in tests; use channels or `testing/synctest`.
- Never force-push shared branches; history on `main` is append-only.
- The service binary reads config only from env vars (`internal/platform/config.go`);
  adding a flag requires a config struct field + default + doc line.

## PR Guidelines
- `make lint test` green before review; the race detector is not optional.
- New endpoints ship with the handler test and the sqlc query in the same PR.

These examples are released under CC0. Use them freely, no attribution required. They are provided as is, without warranty of any kind: review and adapt them to your project before use, as you are responsible for the outcome of applying them.