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.