go-best-practices_skill

Overview

This skill provides concise, opinionated Go best practices to apply while writing, reviewing, or refactoring Go code. It focuses on idiomatic patterns for error handling, interfaces, concurrency, testing, package layout, naming, and code organization. Use it to get actionable recommendations that improve maintainability, correctness, and readability.

How this skill works

When given Go code or a design question, the skill inspects code structure and intent and returns targeted guidance based on Go idioms. It highlights concrete fixes (error wrapping, interface placement, context usage, test structure), points out anti-patterns, and suggests tooling and references for verification. Recommendations are practical and include small code-pattern examples you can apply immediately.

When to use it

• Writing new Go packages or APIs and choosing types/interfaces
• Reviewing or refactoring existing Go code for idiomatic style
• Designing concurrent workflows or coordinating goroutines
• Improving tests, test coverage, and test structure
• Deciding package layout, visibility, or initialization patterns
• Fixing error handling and return-value conventions

Best practices

• Wrap errors with context using %w and check errors immediately; return errors instead of panicking
• Accept interfaces and return concrete types; keep interfaces small and define them at the point of use
• Pass context.Context as the first parameter and use errgroup for coordinating goroutines
• Write table-driven tests, use t.Parallel() for independent cases, and prefer testing behavior over implementation details
• Keep packages small and single-purpose, avoid package-level mutable state, and use internal/ for non-public code
• Prefer short, consistent names (MixedCaps), avoid stuttering, and keep declarations close to use

Example use cases

• Replace log.Fatal or panic with wrapped error returns and sentinel errors for expected conditions
• Refactor a broad exported interface into a narrow consumer-defined interface and return a concrete struct
• Coordinate multiple worker goroutines with errgroup.WithContext to avoid leaks and handle cancellation
• Convert brittle unit tests into table-driven tests with t.Parallel() and helper functions using t.Helper()
• Reorganize a repository to move non-public code into an internal/ package and remove global state