# AGENTS.md — Go

Drop this in your repository root and symlink CLAUDE.md to it:

    ln -s AGENTS.md CLAUDE.md

Then delete every line that is not true of YOUR repository, and add the
corrections you have had to make to an agent twice. Under 100 lines is the
target — every line competes for attention with every other line.

From Go at https://learn-go.org/ai/ — free to use, MIT.

---

Go 1.23. Standard layout: cmd/, internal/, pkg/.

## Commands
- Everything: `make check`  (gofmt, go vet, golangci-lint, go test -race)
- Test:       `go test -race -count=1 -timeout 60s ./...`
- One test:   `go test -run TestName ./internal/pkg -v`

## Conventions
- Errors wrap with %w and context: `fmt.Errorf("load user %s: %w", id, err)`.
  Never %v — it breaks errors.Is.
- Compare errors with errors.Is / errors.As, never ==.
- No naked returns. No panic outside main() and package init.
- context.Context is the first parameter of anything doing I/O, and is
  actually plumbed through — not accepted and dropped.
- Interfaces are declared by the consumer, in the consumer's package, and
  are small. One or two methods.
- Table-driven tests with t.Run subtests.
- Use the stdlib: os.ReadFile not ioutil, any not interface{}, slices and
  maps packages, log/slog not logrus.

## Concurrency (the only place the compiler will not save you)
- Every goroutine must have a guaranteed exit path.
- Prefer errgroup.WithContext over raw WaitGroup + channels.
- TestMain calls goleak.VerifyTestMain.
- -race is always on. Never remove it to make the suite faster.