go-ops
Go development patterns, concurrency, error handling, testing, and project structure. Use for: golang, go, goroutine, channel, context, errgroup, go test, go mod, go build, interface, generics, table-driven tests, worker pool, sync.Mutex, sync.WaitGroup, pprof, go vet, golangci-l
Install
npx skills add https://github.com/0xDarkMatter/claude-mods/tree/main/skills/go-ops
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install 0xdarkmatter-claude-mods@llmmart
git clone https://github.com/0xDarkMatter/claude-mods.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole 0xdarkmatter/claude-mods collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Go Operations
Comprehensive Go skill covering idiomatic patterns, concurrency, and production practices.
Module Quick Start
# New module
go mod init github.com/user/project
# Add dependency
go get github.com/lib/pq@latest
# Tidy (remove unused, add missing)
go mod tidy
# Vendor dependencies
go mod vendor
# Workspace (multi-module)
go work init ./api ./shared
go work use ./cli
Error Handling Decision Tree
What kind of error?
│
├─ Known, expected condition (e.g. "not found")
│ └─ Sentinel error: var ErrNotFound = errors.New("not found")
│ └─ Caller checks: errors.Is(err, ErrNotFound)
│
├─ Need to carry structured data (status code, field name)
│ └─ Custom error type: type ValidationError struct { Field, Message string }
│ └─ Implement Error() string
│ └─ Caller checks: errors.As(err, &validErr)
│
├─ Adding context to an existing error
│ └─ Wrap: fmt.Errorf("load config: %w", err)
│ └─ Preserves original for Is/As checks
│
├─ Truly unrecoverable (corrupted state, programmer bug)
│ └─ panic("invariant violated: ...")
│ └─ Almost never in library code
│
└─ Multiple errors from concurrent work
└─ errors.Join(err1, err2) or multierr package
Error Wrapping Convention
// Add context at each layer, don't repeat the function name
func LoadUser(id int) (*User, error) {
row, err := db.Query("SELECT ...", id)
if err != nil {
return nil, fmt.Errorf("load user %d: %w", id, err)
}
// ...
}
Concurrency Decision Tree
What's the concurrency pattern?
│
├─ Run N independent tasks, collect results
│ └─ errgroup.Group (cancels on first error)
│
├─ Fire-and-forget background work
│ └─ go func() with context for cancellation
│ └─ ALWAYS handle the error or log it
│
├─ Producer/consumer pipeline
│ └─ Channels (buffered for throughput)
│ └─ Close channel when producer is done
│
├─ Rate-limited concurrent work
│ └─ Semaphore: make(chan struct{}, maxConcurrency)
│
├─ Shared mutable state
│ └─ sync.Mutex or sync.RWMutex
│ └─ Prefer channels if the state is simple
│
├─ One-time initialization
│ └─ sync.Once
│
└─ Wait for N goroutines to finish (no error collection)
└─ sync.WaitGroup
errgroup Quick Start
import "golang.org/x/sync/errgroup"
g, ctx := errgroup.WithContext(ctx)
g.SetLimit(10) // max 10 concurrent goroutines
for _, url := range urls {
g.Go(func() error {
return fetch(ctx, url)
})
}
if err := g.Wait(); err != nil {
return fmt.Errorf("fetch urls: %w", err)
}
Deep dive: Load ./references/concurrency.md for worker pools, fan-out/fan-in, pipeline patterns, context best practices.
Interface Design
Accept interfaces, return structs.
// Good: function accepts interface
func Process(r io.Reader) error { ... }
// Good: return concrete type
func NewServer(cfg Config) *Server { ... }
// Bad: returning interface (hides implementation, prevents extension)
func NewServer(cfg Config) ServerInterface { ... }
Common Stdlib Interfaces
| Interface | Methods | Use For |
|---|---|---|
io.Reader |
Read([]byte) (int, error) |
Any byte source |
io.Writer |
Write([]byte) (int, error) |
Any byte sink |
io.Closer |
Close() error |
Resource cleanup |
fmt.Stringer |
String() string |
String representation |
error |
Error() string |
Error values |
sort.Interface |
Len, Less, Swap |
Custom sorting |
http.Handler |
ServeHTTP(w, r) |
HTTP handlers |
encoding.BinaryMarshaler |
MarshalBinary() ([]byte, error) |
Binary encoding |
Functional Options Pattern
type Option func(*Server)
func WithPort(port int) Option {
return func(s *Server) { s.port = port }
}
func WithTimeout(d time.Duration) Option {
return func(s *Server) { s.timeout = d }
}
func NewServer(opts ...Option) *Server {
s := &Server{port: 8080, timeout: 30 * time.Second} // defaults
for _, opt := range opts {
opt(s)
}
return s
}
// Usage
srv := NewServer(WithPort(9090), WithTimeout(5*time.Second))
Deep dive: Load ./references/interfaces-generics.md for generics, type constraints, embedding, type assertions.
Testing Quick Reference
// Table-driven test
func TestAdd(t *testing.T) {
tests := []struct {
name string
a, b int
expected int
}{
{"positive", 1, 2, 3},
{"zero", 0, 0, 0},
{"negative", -1, -2, -3},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got := Add(tt.a, tt.b)
if got != tt.expected {
t.Errorf("Add(%d, %d) = %d, want %d", tt.a, tt.b, got, tt.expected)
}
})
}
}
# Run tests
go test ./...
# With coverage
go test -cover -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
# Run specific test
go test -run TestAdd ./pkg/math/
# Benchmarks
go test -bench=. -benchmem ./...
# Race detector
go test -race ./...
# Fuzz testing
go test -fuzz=FuzzParse ./...
Deep dive: Load ./references/testing.md for mocking with interfaces, httptest, testcontainers, golden files.
Common Gotchas
| Gotcha | Why | Fix |
|---|---|---|
| Nil slice vs empty slice | var s []int is nil, s := []int{} is empty. json.Marshal gives null vs [] |
Use make([]int, 0) or []int{} if JSON matters |
| Goroutine leak | Goroutine blocked on channel with no reader/writer | Use context.WithCancel, always provide exit path |
| Defer in loop | Deferred calls don't run until function returns | Wrap loop body in a closure or use explicit cleanup |
| Interface nil pitfall | (*MyType)(nil) assigned to error interface is not == nil |
Return nil explicitly, not a nil typed pointer |
| Range variable capture | Loop var reused (pre-Go 1.22) | Use go func(v T) { ... }(v) or upgrade to Go 1.22+ |
| String concatenation in loop | O(n^2) allocation | Use strings.Builder |
sync.WaitGroup Add after Go |
Race condition | Call wg.Add(1) before go func() |
| Unbuffered channel deadlock | Send/receive must happen concurrently | Use buffered channel or separate goroutines |
map not safe for concurrent use |
Race condition, may crash | Use sync.Mutex or sync.Map |
Project Structure
project/
├── cmd/
│ ├── api/main.go # Entry points
│ └── worker/main.go
├── internal/ # Private packages
│ ├── handler/
│ ├── service/
│ └── repository/
├── pkg/ # Public packages (optional)
├── go.mod
├── go.sum
├── Makefile # or justfile
└── .golangci.yml
Deep dive: Load ./references/project-structure.md for workspace mode, build tags, ldflags, linting config.
Performance Quick Reference
# CPU profile
go test -cpuprofile=cpu.prof -bench=. ./...
go tool pprof cpu.prof
# Memory profile
go test -memprofile=mem.prof -bench=. ./...
go tool pprof -alloc_space mem.prof
# Trace
go test -trace=trace.out ./...
go tool trace trace.out
# Escape analysis
go build -gcflags='-m' ./...
| Optimization | When | Pattern |
|---|---|---|
| Pre-allocate slices | Known size | make([]T, 0, n) |
strings.Builder |
String concatenation | var b strings.Builder |
sync.Pool |
Frequent alloc/free of same type | pool.Get() / pool.Put() |
| Struct field alignment | Memory-sensitive | Group fields by size (largest first) |
| Buffer reuse | I/O-heavy | bufio.NewReaderSize(r, 64*1024) |
Deep dive: Load ./references/performance.md for pprof walkthrough, benchmarking patterns, escape analysis.
Reference Files
Load these for deep-dive topics. Each is self-contained.
| Reference | When to Load |
|---|---|
./references/concurrency.md |
Goroutines, channels, context, sync primitives, worker pools, pipelines |
./references/error-handling.md |
Error wrapping, sentinel errors, custom types, multi-error, panic/recover |
./references/testing.md |
Table tests, mocking, httptest, benchmarks, fuzz, testcontainers, golden files |
./references/interfaces-generics.md |
Interface design, embedding, type assertions, generics, type constraints |
./references/project-structure.md |
Standard layout, go.mod, workspaces, build tags, ldflags, golangci-lint |
./references/performance.md |
pprof, trace, benchmarks, escape analysis, sync.Pool, struct alignment |
./references/expert-insights.md |
HTTP server (Go 1.22 routing), graceful shutdown, http.Client tuning, JSON helpers |
See Also
docker-ops- Multi-stage builds for Go binaries (scratch/distroless)ci-cd-ops- Go CI pipelines, caching go modules, goreleasertest-engineering- Cross-language testing strategies
Files (claude-mods)
-
assets
-
.gitkeep 0 B · in bundle
-
-
references
-
concurrency.md 18.8 KB
Loading… -
error-handling.md 15.3 KB
Loading… -
expert-insights.md 4.3 KB
Loading… -
interfaces-generics.md 16.2 KB
Loading… -
performance.md 17.3 KB
Loading… -
project-structure.md 12.6 KB
Loading… -
testing.md 16.7 KB
Loading…
-
-
scripts
-
.gitkeep 0 B · in bundle
-
-
SKILL.md 9.4 KB
--- name: go-ops description: "Go development patterns, concurrency, error handling, testing, and project structure. Use for: golang, go, goroutine, channel, context, errgroup, go test, go mod, go build, interface, generics, table-driven tests, worker pool, sync.Mutex, sync.WaitGroup, pprof, go vet, golangci-lint, go workspace, functional options, middleware, http handler." license: MIT allowed-tools: "Read Write Bash" metadata: author: claude-mods related-skills: docker-ops, ci-cd-ops, api-design-ops, test-engineering --- # Go Operations Comprehensive Go skill covering idiomatic patterns, concurrency, and production practices. ## Module Quick Start ```bash # New module go mod init github.com/user/project # Add dependency go get github.com/lib/pq@latest # Tidy (remove unused, add missing) go mod tidy # Vendor dependencies go mod vendor # Workspace (multi-module) go work init ./api ./shared go work use ./cli ``` ## Error Handling Decision Tree ``` What kind of error? │ ├─ Known, expected condition (e.g. "not found") │ └─ Sentinel error: var ErrNotFound = errors.New("not found") │ └─ Caller checks: errors.Is(err, ErrNotFound) │ ├─ Need to carry structured data (status code, field name) │ └─ Custom error type: type ValidationError struct { Field, Message string } │ └─ Implement Error() string │ └─ Caller checks: errors.As(err, &validErr) │ ├─ Adding context to an existing error │ └─ Wrap: fmt.Errorf("load config: %w", err) │ └─ Preserves original for Is/As checks │ ├─ Truly unrecoverable (corrupted state, programmer bug) │ └─ panic("invariant violated: ...") │ └─ Almost never in library code │ └─ Multiple errors from concurrent work └─ errors.Join(err1, err2) or multierr package ``` ### Error Wrapping Convention ```go // Add context at each layer, don't repeat the function name func LoadUser(id int) (*User, error) { row, err := db.Query("SELECT ...", id) if err != nil { return nil, fmt.Errorf("load user %d: %w", id, err) } // ... } ``` ## Concurrency Decision Tree ``` What's the concurrency pattern? │ ├─ Run N independent tasks, collect results │ └─ errgroup.Group (cancels on first error) │ ├─ Fire-and-forget background work │ └─ go func() with context for cancellation │ └─ ALWAYS handle the error or log it │ ├─ Producer/consumer pipeline │ └─ Channels (buffered for throughput) │ └─ Close channel when producer is done │ ├─ Rate-limited concurrent work │ └─ Semaphore: make(chan struct{}, maxConcurrency) │ ├─ Shared mutable state │ └─ sync.Mutex or sync.RWMutex │ └─ Prefer channels if the state is simple │ ├─ One-time initialization │ └─ sync.Once │ └─ Wait for N goroutines to finish (no error collection) └─ sync.WaitGroup ``` ### errgroup Quick Start ```go import "golang.org/x/sync/errgroup" g, ctx := errgroup.WithContext(ctx) g.SetLimit(10) // max 10 concurrent goroutines for _, url := range urls { g.Go(func() error { return fetch(ctx, url) }) } if err := g.Wait(); err != nil { return fmt.Errorf("fetch urls: %w", err) } ``` **Deep dive**: Load `./references/concurrency.md` for worker pools, fan-out/fan-in, pipeline patterns, context best practices. ## Interface Design ``` Accept interfaces, return structs. ``` ```go // Good: function accepts interface func Process(r io.Reader) error { ... } // Good: return concrete type func NewServer(cfg Config) *Server { ... } // Bad: returning interface (hides implementation, prevents extension) func NewServer(cfg Config) ServerInterface { ... } ``` ### Common Stdlib Interfaces | Interface | Methods | Use For | |-----------|---------|---------| | `io.Reader` | `Read([]byte) (int, error)` | Any byte source | | `io.Writer` | `Write([]byte) (int, error)` | Any byte sink | | `io.Closer` | `Close() error` | Resource cleanup | | `fmt.Stringer` | `String() string` | String representation | | `error` | `Error() string` | Error values | | `sort.Interface` | `Len, Less, Swap` | Custom sorting | | `http.Handler` | `ServeHTTP(w, r)` | HTTP handlers | | `encoding.BinaryMarshaler` | `MarshalBinary() ([]byte, error)` | Binary encoding | ### Functional Options Pattern ```go type Option func(*Server) func WithPort(port int) Option { return func(s *Server) { s.port = port } } func WithTimeout(d time.Duration) Option { return func(s *Server) { s.timeout = d } } func NewServer(opts ...Option) *Server { s := &Server{port: 8080, timeout: 30 * time.Second} // defaults for _, opt := range opts { opt(s) } return s } // Usage srv := NewServer(WithPort(9090), WithTimeout(5*time.Second)) ``` **Deep dive**: Load `./references/interfaces-generics.md` for generics, type constraints, embedding, type assertions. ## Testing Quick Reference ```go // Table-driven test func TestAdd(t *testing.T) { tests := []struct { name string a, b int expected int }{ {"positive", 1, 2, 3}, {"zero", 0, 0, 0}, {"negative", -1, -2, -3}, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { got := Add(tt.a, tt.b) if got != tt.expected { t.Errorf("Add(%d, %d) = %d, want %d", tt.a, tt.b, got, tt.expected) } }) } } ``` ```bash # Run tests go test ./... # With coverage go test -cover -coverprofile=coverage.out ./... go tool cover -html=coverage.out # Run specific test go test -run TestAdd ./pkg/math/ # Benchmarks go test -bench=. -benchmem ./... # Race detector go test -race ./... # Fuzz testing go test -fuzz=FuzzParse ./... ``` **Deep dive**: Load `./references/testing.md` for mocking with interfaces, httptest, testcontainers, golden files. ## Common Gotchas | Gotcha | Why | Fix | |--------|-----|-----| | Nil slice vs empty slice | `var s []int` is nil, `s := []int{}` is empty. `json.Marshal` gives `null` vs `[]` | Use `make([]int, 0)` or `[]int{}` if JSON matters | | Goroutine leak | Goroutine blocked on channel with no reader/writer | Use `context.WithCancel`, always provide exit path | | Defer in loop | Deferred calls don't run until function returns | Wrap loop body in a closure or use explicit cleanup | | Interface nil pitfall | `(*MyType)(nil)` assigned to `error` interface is not `== nil` | Return `nil` explicitly, not a nil typed pointer | | Range variable capture | Loop var reused (pre-Go 1.22) | Use `go func(v T) { ... }(v)` or upgrade to Go 1.22+ | | String concatenation in loop | O(n^2) allocation | Use `strings.Builder` | | `sync.WaitGroup` Add after Go | Race condition | Call `wg.Add(1)` before `go func()` | | Unbuffered channel deadlock | Send/receive must happen concurrently | Use buffered channel or separate goroutines | | `map` not safe for concurrent use | Race condition, may crash | Use `sync.Mutex` or `sync.Map` | ## Project Structure ``` project/ ├── cmd/ │ ├── api/main.go # Entry points │ └── worker/main.go ├── internal/ # Private packages │ ├── handler/ │ ├── service/ │ └── repository/ ├── pkg/ # Public packages (optional) ├── go.mod ├── go.sum ├── Makefile # or justfile └── .golangci.yml ``` **Deep dive**: Load `./references/project-structure.md` for workspace mode, build tags, ldflags, linting config. ## Performance Quick Reference ```bash # CPU profile go test -cpuprofile=cpu.prof -bench=. ./... go tool pprof cpu.prof # Memory profile go test -memprofile=mem.prof -bench=. ./... go tool pprof -alloc_space mem.prof # Trace go test -trace=trace.out ./... go tool trace trace.out # Escape analysis go build -gcflags='-m' ./... ``` | Optimization | When | Pattern | |-------------|------|---------| | Pre-allocate slices | Known size | `make([]T, 0, n)` | | `strings.Builder` | String concatenation | `var b strings.Builder` | | `sync.Pool` | Frequent alloc/free of same type | `pool.Get()` / `pool.Put()` | | Struct field alignment | Memory-sensitive | Group fields by size (largest first) | | Buffer reuse | I/O-heavy | `bufio.NewReaderSize(r, 64*1024)` | **Deep dive**: Load `./references/performance.md` for pprof walkthrough, benchmarking patterns, escape analysis. ## Reference Files Load these for deep-dive topics. Each is self-contained. | Reference | When to Load | |-----------|-------------| | `./references/concurrency.md` | Goroutines, channels, context, sync primitives, worker pools, pipelines | | `./references/error-handling.md` | Error wrapping, sentinel errors, custom types, multi-error, panic/recover | | `./references/testing.md` | Table tests, mocking, httptest, benchmarks, fuzz, testcontainers, golden files | | `./references/interfaces-generics.md` | Interface design, embedding, type assertions, generics, type constraints | | `./references/project-structure.md` | Standard layout, go.mod, workspaces, build tags, ldflags, golangci-lint | | `./references/performance.md` | pprof, trace, benchmarks, escape analysis, sync.Pool, struct alignment | | `./references/expert-insights.md` | HTTP server (Go 1.22 routing), graceful shutdown, http.Client tuning, JSON helpers | ## See Also - `docker-ops` - Multi-stage builds for Go binaries (scratch/distroless) - `ci-cd-ops` - Go CI pipelines, caching go modules, goreleaser - `test-engineering` - Cross-language testing strategies
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.