CLAUDE.md template for Go

# Go service

A Go module. Change any command below that differs from how this repo builds and tests.

## Commands

```bash
go build ./...  # compile everything
go test ./...  # run the tests
go test -race ./...  # run the tests with the race detector
go vet ./...  # static checks
gofmt -l .  # list files that are not formatted
```

Run the tests and the linter after every code change, and fix failures before saying a task is done.

## Layout

- Executables live in cmd/<name>/, private packages in internal/, and reusable packages in pkg/ if the repo has one.
- Tests sit next to the code as _test.go files. Prefer table-driven tests.
- Keep packages small and named for what they provide. Avoid package-level mutable state.

## Conventions

- Return errors, wrapped with context using fmt.Errorf and %w. Do not panic outside of main and init.
- Pass context.Context as the first argument to anything that does I/O, and respect cancellation.
- Run gofmt on every file you change. No new dependencies without asking.
- Match the style of the file you are editing. Do not reformat files you did not change.

## Database

- Database schema changes go through migration files in the repo. Never edit a migration that has shipped; add a new one.
- Use parameterized queries only. Never run drop, truncate or reset against a shared or production database.

## Secrets

- Never read, print, edit or commit .env files, credentials, API keys or private keys.
- Use placeholder values in examples and tests. If a secret shows up in a file or a log, stop and tell me.

## Deploys

- Never deploy to production. I run production deploys myself.
- Do not change Dockerfiles, CI workflows or deployment manifests without asking.

## Git

- Make small commits on a branch and write messages that say why the change was made.
- Never run git push --force, git reset --hard, git clean, git checkout -- <file>, git stash or git rebase, and never use --no-verify. Ask first.
- Do not push unless I ask.

## Do not touch

- go.sum: never edit by hand. Do not change go.mod or add dependencies without asking.
- Shipped migrations, vendor/ if present, and generated files (*.pb.go, mocks): do not edit by hand, change the source and regenerate.
- Exported function signatures in pkg/ that other modules import: do not change without asking.

# AGENTS.md: Go service

Instructions for any coding agent working in this repository. A Go module. Change any command below that differs from how this repo builds and tests.

## Commands

```bash
go build ./...  # compile everything
go test ./...  # run the tests
go test -race ./...  # run the tests with the race detector
go vet ./...  # static checks
gofmt -l .  # list files that are not formatted
```

Run the tests and the linter after every code change, and fix failures before saying a task is done.

## Layout

- Executables live in cmd/<name>/, private packages in internal/, and reusable packages in pkg/ if the repo has one.
- Tests sit next to the code as _test.go files. Prefer table-driven tests.
- Keep packages small and named for what they provide. Avoid package-level mutable state.

## Conventions

- Return errors, wrapped with context using fmt.Errorf and %w. Do not panic outside of main and init.
- Pass context.Context as the first argument to anything that does I/O, and respect cancellation.
- Run gofmt on every file you change. No new dependencies without asking.
- Match the style of the file you are editing. Do not reformat files you did not change.

## Database

- Database schema changes go through migration files in the repo. Never edit a migration that has shipped; add a new one.
- Use parameterized queries only. Never run drop, truncate or reset against a shared or production database.

## Secrets

- Never read, print, edit or commit .env files, credentials, API keys or private keys.
- Use placeholder values in examples and tests. If a secret shows up in a file or a log, stop and tell me.

## Deploys

- Never deploy to production. I run production deploys myself.
- Do not change Dockerfiles, CI workflows or deployment manifests without asking.

## Git

- Make small commits on a branch and write messages that say why the change was made.
- Never run git push --force, git reset --hard, git clean, git checkout -- <file>, git stash or git rebase, and never use --no-verify. Ask first.
- Do not push unless I ask.

## Do not touch

- go.sum: never edit by hand. Do not change go.mod or add dependencies without asking.
- Shipped migrations, vendor/ if present, and generated files (*.pb.go, mocks): do not edit by hand, change the source and regenerate.
- Exported function signatures in pkg/ that other modules import: do not change without asking.