# Go Best Practices

> 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'.

- Skill: `poteto/go-best-practices` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add poteto/go-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/poteto/go-best-practices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: poteto (https://skillmd.com/u/poteto)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/poteto/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](references/patterns.md) for code examples.

## Rules

1. **main.go is a stub.** Call `cmd.Execute()` and nothing else. Gate
   diagnostics (pprof) behind env vars.

2. **One bootstrap path.** All modes (interactive, headless, test) share the
   same initialization function. Two paths will drift.

3. **Ordered shutdown.** Cancel dependents before their dependencies, then run
   independent cleanup in parallel under a timeout context. WaitGroup the
   parallel phase.

4. **Never block the sender.** Non-blocking channel sends with an explicit
   drop policy. Log drops at debug level. Document the policy.

5. **Test concurrency mechanically.** `testing/synctest` for deterministic
   timing, `goleak.VerifyNone` for leak detection, dedicated regression tests
   for timer/channel deadlocks.

6. **Explicit config precedence.** Global → project → flags. Walk up from CWD
   to discover project configs, reverse so closest wins, deep-merge.

7. **Centralize platform paths.** One function per concern. Resolution order:
   env override → XDG → platform default → fallback.

8. **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.

9. **Golden tests over matrices.** Cross dimensions (layout × theme × size)
   as parallel subtests. Sweep continuous ranges to catch off-by-one bugs.

10. **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.