# AGENTS.md - this project

Instructions for AI coding agents working in this repository.

## Project

A Go + Docker project.

Stack: Go, Docker.

## Commands

- Run: `go run ./cmd/<app>`
- Tests: `go test ./...`
- Vet: `go vet ./...`
- Format: `gofmt -w .`
- Local services: `docker compose up -d`

## Project structure

- Entrypoints in `cmd/<app>/main.go`, private packages in `internal/`.

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

## Go

- Code must be `gofmt`-formatted and pass `go vet`.
- Return errors, do not panic. Wrap with context: `fmt.Errorf("load user %d: %w", id, err)`.
- Pass `context.Context` as the first parameter to anything doing I/O and respect cancellation.
- Use Go 1.22+ `http.ServeMux` patterns (`mux.HandleFunc("GET /items/{id}", h)`, `r.PathValue("id")`) before adding a router dependency.
- Keep interfaces small and define them where they are consumed.
- Write table-driven tests with `t.Run` subtests.
- Use `log/slog` for structured logging.

## Docker

- Use multi-stage builds and slim, pinned base images.
- Run the app as a non-root user in the final image.
- Keep a `.dockerignore` that excludes `.git`, `node_modules`, `.env` and build output.
- Never bake secrets into images; pass them at runtime.

## Reference docs

- [Effective Go](https://go.dev/doc/effective_go)
- [Dockerfile best practices](https://docs.docker.com/build/building/best-practices/)