Raw view: Go Service CLAUDE.md
No invisible, zero-width, or bidi-control characters detected.
# {{PROJECT_NAME}}
Go service. Module `{{MODULE_PATH}}`, Go {{GO_VERSION}} (the `go` directive in `go.mod` is authoritative). Entry point `cmd/{{BINARY_NAME}}/main.go`; everything else under `internal/`.
## Commands
| Task | Command |
|------|---------|
| Build | `go build ./...` |
| Run | `go run ./cmd/{{BINARY_NAME}}` |
| Test | `go test ./... -race -count=1` (one test: `go test ./internal/foo -run 'TestBar$' -v`) |
| Format check | `gofmt -l .` (must print nothing) and `goimports -l .` |
| Lint | `golangci-lint run ./...` (config in `.golangci.yml`) |
| Vet | `go vet ./...` |
| Tidy deps | `go mod tidy` then confirm `git diff --exit-code go.mod go.sum` |
| Generate | `go generate ./...` (then commit the output) |
Definition of done: `gofmt -l .` prints nothing, `go vet ./...` and `golangci-lint run ./...` exit 0, `go test ./... -race -count=1` passes, and `go mod tidy` leaves no diff. Paste the `ok` lines from the test run.
## Layout
- `cmd/<binary>/main.go` only wires dependencies and calls `run(ctx, args, stdout)`. Keep `main` under 30 lines.
- `internal/<domain>/` holds one package per domain concept. Exported API surface is the minimum the service needs.
- `internal/platform/` holds adapters (database, HTTP clients, queues). Domain packages depend on interfaces they define, not on `platform`.
- No `pkg/` directory. No `utils` or `common` packages.
## Errors
- Wrap with context and `%w`: `return fmt.Errorf("load user %s: %w", id, err)`. The message says what was being attempted, not "error" or "failed".
- Check with `errors.Is` and `errors.As`; never compare error strings.
- Sentinel errors are package-level `var ErrNotFound = errors.New("user: not found")`. Custom error types implement `Error()` and, if they wrap, `Unwrap()`.
- Handle an error exactly once: either return it or log it, not both. Only `main`/`run` and request-boundary middleware log.
- Never `panic` outside `main` for configuration that cannot be loaded. No `_ = err`.
## Context
- Every function that does IO or can block takes `ctx context.Context` as its first parameter. Do not store a context in a struct.
- Derive timeouts at the boundary: `ctx, cancel := context.WithTimeout(ctx, 5*time.Second); defer cancel()`.
- Pass request-scoped values (trace ID, user) with typed keys defined in `internal/platform/ctxkeys`. Do not use string keys.
- Do not use `context.Background()` or `context.TODO()` below `main` and tests.
## Code conventions
- Accept interfaces, return structs. Define interfaces where they are consumed, with 1-3 methods.
- Constructor `NewX(deps...) (*X, error)`; no `init()` functions; no package-level mutable state.
- Struct fields and function parameters that are optional go in an `Options` struct, not variadic functional options, unless the package already uses them.
- Logging through `log/slog` with the logger passed in explicitly. Use `slog.String`, `slog.Int` attributes, not `fmt.Sprintf` in messages.
- Concurrency: every `go` statement has a documented owner and a way to stop (`ctx` or a `done` channel). Use `errgroup.Group` for fan-out.
## Tests
- Table-driven: `tests := []struct{ name string; in X; want Y; wantErr error }`, loop with `t.Run(tt.name, func(t *testing.T) { t.Parallel(); ... })`.
- Assertions with the standard library and `github.com/google/go-cmp/cmp`; print `cmp.Diff(want, got)` on failure. No `testify` unless already imported in that package.
- Test files live next to the code (`foo_test.go`). Use `package foo_test` for black-box tests; `package foo` only when you must reach unexported identifiers.
- Fakes over mocks: hand-written fake implementations in `internal/<domain>/<domain>test/`. No generated mock frameworks.
- Integration tests need the `integration` build tag: `//go:build integration` and run with `go test -tags=integration ./...`.
- Golden files under `testdata/`; update with `go test ./... -update` only when the change is intentional, and mention it in the report.
## Do not
- Do not edit `go.sum` by hand or run `go get -u` across the module. Upgrade one dependency at a time with `go get example.com/mod@vX.Y.Z`.
- Do not add `//nolint` without the linter name and a reason: `//nolint:errcheck // close error is irrelevant here`.
- Do not introduce `interface{}`/`any` in exported signatures where a generic or concrete type works.
- Do not commit generated code without the `// Code generated ... DO NOT EDIT.` header intact.