CLAUDE.md for a Go project

A CLAUDE.md for a Go project: the stack, the go build, test and vet commands, the error-handling and package rules Go leans on, and the files an agent should leave alone. Copy it into your repo root, fill in the bracketed parts, and commit it so every Claude Code session reads it first.

By Makki · Updated

When to use this

Use it on a Go service or CLI. It leans the agent toward idiomatic Go: errors over panics, small packages, and interfaces accepted rather than returned everywhere. Fill in the project name and point the run command at your entry package.

The template CLAUDE.md

# [Project] — agent guide

## Stack
Go 1.23. Standard library first, with a small set of vetted modules.

## Commands
- Build: `go build ./...`
- Run: `go run ./cmd/app`
- Test: `go test ./...`
- Vet and format: `go vet ./...` then `gofmt -l -w .`

## Conventions
- Return errors, do not panic in library code. Wrap errors with context.
- Keep packages small and named for what they do.
- Accept interfaces, return structs. Keep the exported surface minimal.
- Use table-driven tests for anything with more than one case.

## How to work here
- Run go test and go vet before you call a task done.
- Keep changes small and gofmt-clean.

## Do not
- Do not add a dependency the standard library already covers.
- Do not commit build output or a module you did not mean to vendor.
- Do not ignore an error return without a comment saying why.

Why each section is there

  • Stack sets the Go version and the standard-library-first stance.
  • Commands give the real build, test and vet lines, with gofmt.
  • Conventions carry the error-wrapping and package rules that keep Go readable.
  • Do not stops needless dependencies and silently swallowed errors.

Build one from a form with the CLAUDE.md generator. For how an agent uses the file, see working with agents.

FAQ

Where should the main package live?

The template assumes cmd/app for the entry point. Change the run command to match your layout, such as a single main.go at the root.

Should I add a linter beyond go vet?

If you run golangci-lint, add it to the commands and the how-to-work list. The agent then runs it before calling a task done.