1---2name: go3description: Go development skill covering style, idioms, testing, concurrency, and distributed systems patterns. Use when writing, reviewing, or modifying Go code. Also use when the user asks about Go best practices, architecture decisions, or debugging Go-specific issues. Covers Go 1.22+ features including range-over-func, enhanced routing, generics, and testing/synctest.4---56# Go78This skill contains opinionated guidance for writing production Go code. The rules here reflect deliberate choices — follow them even when they conflict with generic Go advice from other sources.910## Core principles1112- **Clarity over cleverness.** Code is read far more than it's written. Prefer the obvious approach.13- **Concrete first, abstract later.** Start with concrete types, plain functions, and simple loops. Introduce generics, iterators, or interfaces only when duplication or a clear design need forces it.14- **Small interfaces, big structs.** Interfaces should have 1-2 methods. Define them at the consumer, not the implementor.15- **Errors are values.** Handle them explicitly. Don't panic in library code. Wrap at boundaries, not at every return.16- **Test the exported API.** Unexported functions are implementation details. If the public behavior is correct, the internals are correct by definition.1718## References1920Read these **only** when the task involves the relevant topic. Do not read all references upfront.2122### Style and idioms2324| File | Read when... |25|------|-------------|26| `references/style/style.md` | Writing any new Go code, reviewing naming, structuring packages, or deciding on function signatures. This is the most broadly applicable reference. |2728### Testing2930| File | Read when... |31|------|-------------|32| `references/testing/unit-testing.md` | Writing or modifying `*_test.go` files, adding test coverage, or reviewing test structure. |33| `references/modern-go/synctest.md` | Testing code that uses goroutines, channels, timers, tickers, or context deadlines. |3435### Modern Go features3637| File | Read when... |38|------|-------------|39| `references/modern-go/error-handling-evolution.md` | Creating error types, wrapping errors, using `errors.Is`/`errors.As`, or deciding between sentinel errors and custom types. |40| `references/modern-go/generics.md` | Writing or reviewing generic functions, type constraints, or deciding whether generics are warranted. |41| `references/modern-go/iterators.md` | Implementing custom iterators, using `iter.Seq`/`iter.Seq2`, replacing channel-based iteration, or composing lazy sequences. |42| `references/modern-go/enhanced-http-routing.md` | Writing HTTP handlers with `net/http`, registering routes with method matching or path wildcards. |43| `references/modern-go/structured-logging.md` | Adding logging with `log/slog`, choosing log levels, or structuring log output. |4445### Distributed systems4647| File | Read when... |48|------|-------------|49| `references/distributed-systems/retries-and-backoffs.md` | Adding retry logic, exponential backoff, jitter, or using `cenkalti/backoff`. |50| `references/distributed-systems/circuit-breakers.md` | Protecting against cascading failures, wrapping external service calls with `failsafe-go`. |51| `references/distributed-systems/timeouts-and-cancellation.md` | Setting timeouts on outgoing calls, propagating `context.Context`, or debugging context cancellation issues. |5253### Common combinations5455Some tasks require multiple references. Read all that apply:5657- **Writing a new service client** → style + timeouts + retries + circuit breakers + error handling58- **Writing tests for concurrent code** → unit testing + synctest59- **Adding a new HTTP endpoint** → style + enhanced HTTP routing + error handling60- **Reviewing a PR** → style + whichever topic-specific references match the changed code
ivaaaan