Skip to content

project rulesBackend and APIsgo

Go Service Rules

Project rules for Go services: small interfaces, wrapped errors, context everywhere, table-driven tests and no hidden goroutines.

npx workspacetemplates add go-service-rules --tool claude-code

Writes 1 file to your project root

CLAUDE.mdadd to your file22 lines · 1.4 KBFile
# Project rules: Go services

## Layout and style
- `cmd/<app>/main.go` only wires things together. Domain code lives in `internal/`. Keep packages small, named for what they provide, with no `util` or `common` packages.
- Define interfaces where they are used, with one to three methods. Accept interfaces, return concrete types.
- No global mutable state and no `init()` with side effects. Pass dependencies in constructors.

## Errors
- Never ignore an error. Wrap with context: `fmt.Errorf("load user %d: %w", id, err)`. Compare with `errors.Is` and `errors.As`. Handle an error once: log it or return it, not both.
- Do not panic outside `main` and tests.

## Context and concurrency
- `ctx context.Context` is the first parameter of anything that does I/O. Use `http.NewRequestWithContext`, set server and client timeouts, and propagate cancellation.
- Every goroutine has an owner and a way to stop: use `errgroup`, close channels from the sender, and never start one without knowing how it ends.

## HTTP and logging
- Use `net/http` with the standard mux or chi. Decode with a size limit, validate, and return JSON errors with correct status codes.
- Log with `log/slog`, structured fields, no secrets.

## Tests
- Table-driven tests with subtests; use `t.Parallel()` where safe.
- Before finishing run `gofmt`, `go vet ./...`, `golangci-lint run` and `go test -race ./...`.

What it does

Go rewards plain code, and agents tend to write it like Java: big interfaces, global state and swallowed errors. These rules pull generated code back to the idioms that Go teams review for.

They cover project layout, error handling, concurrency and testing, and set the commands that must pass before a change is done.

Example

you › Add an endpoint that fetches a user's orders from the database

agent › The agent adds a handler with a context-bound query, an interface declared in the handler package, wrapped errors, a slog line on failure and a table-driven test run with -race.

Questions

Does it force a framework?
No. It prefers the standard library, with chi as an accepted router. Add your own framework to the file if you use one.
Why must goroutines have an owner?
A goroutine nobody can stop leaks memory and hangs shutdowns. The rule makes the agent decide how each one ends.
  • ASP.NET Core Web API Rules

    Project rulesdotnet

    Free
  • Django Rules

    Project rulespython

    Free
  • Flask Rules

    Project rulespython

    Free
  • GraphQL API Rules

    Project rulesgraphql

    Free