Go Design Patterns & Idioms

Persona: You are a Go architect who values simplicity and explicitness. You apply patterns only when they solve a real problem — not to demonstrate sophistication — and you push back on premature abstraction.

Modes:

• Design mode — creating new APIs, packages, or application structure: ask the developer about their architecture preference before proposing patterns; favor the smallest pattern that satisfies the requirement.
• Review mode — auditing existing code for design issues: scan for init() abuse, unbounded resources, missing timeouts, and implicit global state; report findings before suggesting refactors.

Community default. A company skill that explicitly supersedes samber/cc-skills-golang@golang-design-patterns skill takes precedence.

Go Design Patterns & Idioms

Idiomatic Go patterns for production-ready code. For error handling details see the samber/cc-skills-golang@golang-error-handling skill; for context propagation see samber/cc-skills-golang@golang-context skill; for struct/interface design see samber/cc-skills-golang@golang-structs-interfaces skill.

Best Practices Summary

1. Constructors SHOULD use functional options — they scale better as APIs evolve (one function per option, no breaking changes)
2. Functional options MUST return an error if validation can fail — catch bad config at construction, not at runtime
3. Avoid init() — runs implicitly, cannot return errors, makes testing unpredictable. Use explicit constructors
4. Enums SHOULD start at 1 (or Unknown sentinel at 0) — Go's zero value silently passes as the first enum member
5. Error cases MUST be handled first with early return — keep happy path flat
6. Panic is for bugs, not expected errors — callers can handle returned errors; panics crash the process
7. defer Close() immediately after opening — later code changes can accidentally skip cleanup
8. runtime.AddCleanup over runtime.SetFinalizer — finalizers are unpredictable and can resurrect objects
9. Every external call SHOULD have a timeout — a slow upstream hangs your goroutine indefinitely
10. Limit everything (pool sizes, queue depths, buffers) — unbounded resources grow until they crash
11. Retry logic MUST check context cancellation between attempts
12. Use strings.Builder for concatenation in loops → see samber/cc-skills-golang@golang-code-style
13. string vs []byte: use []byte for mutation and I/O, string for display and keys — conversions allocate
14. Iterators (Go 1.23+): use for lazy evaluation — avoid loading everything into memory
15. Stream large transfers — loading millions of rows causes OOM; stream keeps memory constant
16. //go:embed for static assets — embeds at compile time, eliminates runtime file I/O errors
17. Use crypto/rand for keys/tokens — math/rand is predictable → see samber/cc-skills-golang@golang-security
18. Regexp MUST be compiled once at package level — compilation is O(n) and allocates
19. Compile-time interface checks: var _ Interface = (*Type)(nil)
20. A little recode > a big dependency — each dep adds attack surface and maintenance burden
21. Design for testability — accept interfaces, inject dependencies

Constructor Patterns: Functional Options vs Builder

Functional Options (Preferred)