CLAUDE.md for a Go service

A CLAUDE.md encoding domain-package boundaries, consumer-defined interfaces, and the sqlc edit → generate → fix workflow.

# CLAUDE.md - orderd (Go service)

## Commands
```bash
make dev                                     # live-reload dev server
make test                                    # full suite with -race
go test ./internal/orders/ -run TestCreate   # scope while iterating
make lint                                    # golangci-lint is the style guide
make gen                                     # after editing queries/*.sql
```

## Architecture
- One package per domain under `internal/` (orders, billing, users); each
  owns handler → service → sqlc-generated queries. No cross-domain imports;
  shared code goes through `internal/platform`.
- HTTP layer is chi; handlers decode/validate, call the service, encode.
  Business rules live in the service, never in handlers.
- All SQL is sqlc: source in `queries/`, output in `internal/*/gen/`.

## Conventions
- Wrap errors with context: `fmt.Errorf("creating order: %w", err)`.
- Consumer-defined interfaces; keep them small (1-3 methods).
- Structured logs via slog with the request-scoped logger from middleware -
  no `fmt.Println` debugging left in commits.
- Follow `internal/orders/` as the reference domain package for new domains.

## Workflow
- Schema or query change: edit SQL, `make gen`, then fix compile errors in
  services. The generated diff belongs in the PR.
- Flaky test suspicion: run `go test -race -count=10 ./internal/<pkg>/` before
  blaming infrastructure.

## Do not
- Do not edit `internal/*/gen/` (sqlc output).
- Do not add `time.Sleep` to tests to fix timing; synchronize properly.
- Do not introduce a new dependency for something the stdlib does.

These examples are released under CC0. Use them freely, no attribution required. They are provided as is, without warranty of any kind: review and adapt them to your project before use, as you are responsible for the outcome of applying them.