# AGENTS.md — Go (Effective Go)

Idiomatic Go style per *Effective Go* and the official *Go Code Review Comments*.

- Format with `gofmt` / `go fmt`; tabs for indentation, no parentheses on `if`/`for`/`switch`.
- Names use `MixedCaps`/`mixedCaps`, never underscores; export by capitalizing the first letter.
- Package names are short, lower-case, single words; avoid `util`/`common`/`misc` and don't stutter (`chubby.New`).
- Getters drop the `Get` prefix (`Owner()`, `SetOwner()`); one-method interfaces use the `-er` suffix.
- Initialisms keep consistent case: `ServeHTTP`, `appID`, `URL`.
- Error strings are lower-case with no trailing punctuation; prefix with the operation/package when useful.
- Handle every error — return it, handle it, or panic; never discard with `_`. Don't `panic` for normal flow.
- Avoid in-band errors (`-1`, `nil`, `""`); return an extra `error` or `ok bool`.
- Keep the happy path at minimal indentation: check errors early and return; drop the `else` after a terminating `if`.
- Keep interfaces small; accept interfaces, return concrete types; define interfaces in the consuming package, not "for mocking".
- "Do not communicate by sharing memory; instead, share memory by communicating" — prefer channels and `select`.
- Pass `context.Context` as the first parameter; prefer synchronous functions over asynchronous ones.
- Receiver names are a consistent 1–2 letter abbreviation of the type, never `me`/`this`/`self`.
- Pointer receiver to mutate / for large structs / when holding a `sync.Mutex`; value receiver for small immutable types; when in doubt, pointer.
- `defer` cleanup right after acquiring the resource; `new(T)` for zeroed `*T`, `make` for slices/maps/channels.
- Doc comments are full sentences that start with the name and end with a period.
- Use `crypto/rand` for keys/secrets, never `math/rand`.