CLAUDE.md

CLAUDE.md for a Go project

Tells Claude how to build, test and vet the code and how errors are handled in Go style. Fits a backend service or a command-line tool written in Go.

Tested with Claude Code 2.1.329

Spots to fill

  • {{project_name}}Project namee.g. ledger
  • {{module_path}}Module path from go.mode.g. github.com/acme/ledger
CLAUDE.md
# {{project_name}}

Go module `{{module_path}}`.

## Commands
- Build: `go build ./...`
- Test all: `go test ./...`
- Test one package with the race detector: `go test -race ./internal/store/...`
- Vet and lint: `go vet ./... && golangci-lint run`
- Format: `gofmt -w .` (done automatically by most editors; still run it)

Run build, vet and the tests of the packages you touched before saying a task is done.

## Layout
- `cmd/<name>/main.go`: entry points only, no logic.
- `internal/`: application code, not importable from outside the module.
- Table-driven tests in `*_test.go` next to the code.

## Conventions
- Return errors, do not panic; wrap with `fmt.Errorf("doing x: %w", err)`.
- Pass `context.Context` as the first argument to anything that does I/O.
- Keep interfaces small and define them where they are used.
- No global mutable state; inject dependencies through constructors.

## Do not
- Edit generated files (`*.pb.go`, `*_gen.go`); change the source and regenerate.
- Add a module without explaining why; run `go mod tidy` after any change.

Related lessons

Type to search the reference, templates and lessons.