| name | go-best-practices |
| description | Production Go patterns — lifecycle, concurrency, config, testing, CI. Use when writing, reviewing, or refactoring Go code. Triggers on Go code review, Go refactoring, or 'go best practices'.
|
Go Best Practices
| Pattern | When to apply |
|---|
| Minimal main | New binaries |
| Single bootstrap | App wiring across modes |
| Ordered shutdown | Long-running processes |
| Non-blocking fanout | Channel-based event systems |
| Concurrency testing | Any goroutine code |
| Layered config | Multi-source configuration |
| Cross-platform paths | File/config path resolution |
| Secure debug logging | HTTP client instrumentation |
| Golden test matrices | Rendering / output components |
| Focused linters | CI pipeline setup |
Read references/patterns.md for code examples.
Rules
-
main.go is a stub. Call cmd.Execute() and nothing else. Gate
diagnostics (pprof) behind env vars.
-
One bootstrap path. All modes (interactive, headless, test) share the
same initialization function. Two paths will drift.
-
Ordered shutdown. Cancel dependents before their dependencies, then run
independent cleanup in parallel under a timeout context. WaitGroup the
parallel phase.
-
Never block the sender. Non-blocking channel sends with an explicit
drop policy. Log drops at debug level. Document the policy.
-
Test concurrency mechanically. testing/synctest for deterministic
timing, goleak.VerifyNone for leak detection, dedicated regression tests
for timer/channel deadlocks.
-
Explicit config precedence. Global → project → flags. Walk up from CWD
to discover project configs, reverse so closest wins, deep-merge.
-
Centralize platform paths. One function per concern. Resolution order:
env override → XDG → platform default → fallback.
-
Redact secrets in debug logs. Wrap http.RoundTripper. Filter headers
matching authorization, api-key, token, secret. Gate on debug level to
skip allocation in prod.
-
Golden tests over matrices. Cross dimensions (layout × theme × size)
as parallel subtests. Sweep continuous ranges to catch off-by-one bugs.
-
Focused linters, not all linters. Enable what catches real bugs
(bodyclose, noctx, tparallel). Disable noisy defaults. Add project-specific
checks as scripts. Always -race in tests.
