AGENTS.md template for Go

# Project instructions

This repository is a Go module. Preserve package boundaries, exported API behavior, error semantics, and the project's established approach to contexts, logging, configuration, and concurrency.

## Start here

- Read the nearest `go.mod`, package files, tests, interfaces, and callers before editing.
- Use the Go version and toolchain declared by the module.
- Prefer the standard library and existing dependencies over adding a new package for a small task.
- Keep changes scoped and preserve uncommitted user work.

## Commands

- `go mod download`: download declared module dependencies.
- `go test ./...`: run tests across all packages in the module.
- `go test -race ./...`: run the race detector for concurrency-sensitive changes.
- `go vet ./...`: report suspicious constructs.
- `go build ./...`: compile all packages and commands.
- `gofmt -w <changed-files>`: format changed Go files.

Replace these commands when the repository uses a Makefile, task runner, workspace, build tags, generated code, or platform-specific targets.

## Repository map

- `cmd/`: executable entry points and dependency wiring.
- `internal/`: implementation packages that cannot be imported outside the module tree.
- `pkg/`: public packages only when this repository intentionally exposes them.
- `api/` or `proto/`: external schemas and generated interfaces.
- Files ending in `_test.go`: package and external-package tests.

## Go rules

- Keep packages cohesive and avoid import cycles or generic utility packages with no clear owner.
- Accept interfaces where behavior is consumed; do not create an interface solely to mirror one concrete type.
- Propagate `context.Context` through request-scoped work and never store it in a long-lived struct.
- Wrap errors with useful operation context while preserving errors needed by `errors.Is` or `errors.As`.
- Ensure every goroutine has an owner, cancellation path, bounded lifetime, and observable error handling.
- Protect shared state deliberately; never fix a race with timing or sleeps.

## Compatibility and security

- Preserve exported names, JSON fields, protocol schemas, and CLI flags unless a breaking change is explicit.
- Validate untrusted input at the boundary and cap unbounded reads, retries, concurrency, and allocations.
- Do not log credentials, tokens, request bodies, or personal data.
- Do not edit generated files by hand; update their source and use the repository's generator.

## Testing and validation

- Add table-driven tests for meaningful input classes and regression cases.
- Run the focused package test first, then `go test ./...`.
- Run the race detector when goroutines, channels, shared state, caches, or callbacks change.
- Run `go vet`, formatting, and a full build before completion.

## Definition of done

- The affected package and its callers compile and test successfully.
- Exported behavior and error semantics remain compatible unless intentionally changed.
- Concurrency has explicit ownership and cancellation with no new races.
- Formatting, vet, tests, and the build pass using repository commands.
- The handoff names affected packages, validation performed, and remaining compatibility risk.