# Go Best Practices

Production Go patterns, lifecycle, concurrency, config, testing, CI.

- Repository: https://github.com/poteto/noodle (577 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-03-19
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add poteto/noodle --skill go-best-practices -g -a claude-code -y`
Codex: `npx skills add poteto/noodle --skill go-best-practices -g -a codex -y`
Cursor: `npx skills add poteto/noodle --skill go-best-practices -g -a cursor -y`
Gemini CLI: `npx skills add poteto/noodle --skill go-best-practices -g -a gemini-cli -y`

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

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

The rest: https://github.com/poteto/noodle/blob/HEAD/.agents/skills/go-best-practices/SKILL.md