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.

Estos ejemplos se publican bajo CC0: úsalos libremente, sin atribución. Se proveen tal cual, sin garantía de ningún tipo: revísalos y adáptalos a tu proyecto antes de usarlos, ya que eres responsable del resultado de aplicarlos.