# Go Conventions

> Carlos Becker's Go implementation and review conventions. Use when writing or reviewing Go in caarlos0, GoReleaser, nFPM, env, svu, fang, and related projects.

- Skill: `caarlos0/go-conventions` (Agent Skill)
- Install (CLI): `npx skillmds@latest add caarlos0/go-conventions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/caarlos0/go-conventions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: caarlos0 (https://skillmd.com/u/caarlos0)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/caarlos0/go-conventions

---


# Go Conventions

Follow repository instructions first. Prefer idiomatic, unsurprising Go with a
small public surface and few dependencies.

- Use the standard library unless a dependency provides clear, necessary value.
  Every new `require` in `go.mod` needs justification.
- Wrap errors with context using `%w`; use `errors.Is` and `errors.As`. Error
  messages are lowercase, have no trailing punctuation, and say what failed.
- Put implementation details in `internal/`. Define interfaces at the consumer
  and add generics or functional options only when concrete callers need them.
- For CLIs, follow existing Cobra and fang patterns rather than introducing a
  second framework.
- Use struct tags for declarative configuration when the repository already
  follows that pattern.
- Write surgical regression tests with `testify/require`. Use per-case `t.Run`;
  use tables only when cases genuinely share a shape. Keep decisive assertions
  at the failing test line rather than hiding them in helpers.
- Discover and use repository `make` targets such as `test`, `lint`, `build`,
  and `ci`; do not assume they exist.
- Keep release and container changes reproducible. Follow existing GoReleaser
  configuration and pin container images to digests when that is the repository
  convention.

Run `gofmt` and the repository's existing targeted tests and lint commands. Do
not add retries, timeouts, abstractions, or compatibility layers without a
demonstrated problem.