Skip to main content
Agent skill

Golang Patterns

Idiomatic Go patterns, best practices, and conventions for building robust, efficient, and maintainable Go applications. Use when writing or reviewing Go code and idiomatic structure or conventions are in question.

Get started

Get the complete skill folder, including its scripts and reference files.

·

When to use this skill

Use Golang Patterns when an AI agent needs a reusable SKILL.md workflow for this job: Idiomatic Go patterns, best practices, and conventions for building robust, efficient, and maintainable Go applications. Use when writing or reviewing Go code and idiomatic structure or conventions are in question.

When not to use it

Skip Golang Patterns when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/golang-patterns
# Save SKILL.md to ~/.claude/skills/golang-patterns/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/golang-patterns/SKILL.md. For a shared project, commit the folder at .claude/skills/golang-patterns/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Golang Patterns skill for this task: Use Golang Patterns when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Go Development Patterns

Idiomatic Go patterns and best practices for building robust, efficient, and maintainable applications.

## When to Activate

- Writing new Go code - Reviewing Go code - Refactoring existing Go code - Designing Go packages/modules

## Core Principles

### 1. Simplicity and Clarity

Go favors simplicity over cleverness. Code should be obvious and easy to read.

```go // Good: Clear and direct func GetUser(id string) (*User, error) { user, err := db.FindUser(id) if err != nil { return nil, fmt.Errorf("get user %s: %w", id, err) } return user, nil }

// Bad: Overly clever func GetUser(id string) (*User, error) { return func() (*User, error) { if u, e := db.FindUser(id); e == nil { return u, nil } else { return nil, e } }() } ```

### 2. Make the Zero Value Useful

Design types so their zero value is immediately usable without initialization.

```go // Good: Zero value is useful type Counter struct { mu sync.Mutex count int // zero value is 0, ready to use }

func (c *Counter) Inc() { c.mu.Lock() c.count++ c.mu.Unlock() }

// Good: bytes.Buffer works with zero value var buf bytes.Buffer buf.WriteString("hello")

// Bad: Requires initialization type BadCounter struct { counts map[string]int // nil map will panic } ```

### 3. Accept Interfaces, Return Structs

Functions should accept interface parameters and return concrete types.

```go // Good: Accepts interface, returns concrete type func ProcessData(r io.Reader) (*Result, error) { data, err := io.ReadAll(r) if err != nil { return nil, err } return &Result{Data: data}, nil }

// Bad: Returns interface (hides implementation details unnecessarily) func ProcessData(r io.Reader) (io.Reader, error) { // ... } ```

## Error Handling Patterns

### Error Wrapping with Context

```go // Good: Wrap errors with context func LoadConfig(path string) (*Config, error) { data, err := os.ReadFile(path) if err != nil { return nil, fmt.Errorf("load config %s: %w", path, err) }

var cfg Config if err := json.Unmarshal(data, &cfg); err != nil { return nil, fmt.Errorf("parse config %s: %w", path, err) }

return &cfg, nil } ```

### Custom Error Types

```go // Define domain-specific errors type ValidationError struct { Field string Message string }

func (e *ValidationError) Error() string { return fmt.Sprintf("validation failed on %s: %s", e.Field, e.Message) }

// Sentinel errors for common cases var ( ErrNotFound = errors.New("resource not found") ErrUnauthorized = errors.New("unauthorized") ErrInvalidInput = errors.New("invalid input") ) ```

### Error Checking with errors.Is and errors.As

```go func HandleError(err error) { // Check for specific error if errors.Is(err, sql.ErrNoRows) { log.Println("No records found") return }

// Check for error type var validationErr *ValidationError if errors.As(err, &validationErr) { log.Printf("Validation error on field %s: %s", validationErr.Field, validationErr.Message) return }

// Unknown error log.Printf("Unexpected error: %v", err) } ```

### Never Ignore Errors

```go // Bad: Ignoring error with blank identifier result, _ := doSomething()

// Good: Handle or explicitly document why it's safe to ignore result, err := doSomething() if err != nil { return err }

// Acceptable: When error truly doesn't matter (rare) _ = writer.Close() // Best-effort cleanup, error logged elsewhere ```

## Concurrency Patterns

### Worker Pool

```go func WorkerPool(jobs <-chan Job, results chan<- Result, numWorkers int) { var wg sync.WaitGroup

for i := 0; i < numWorkers; i++ { wg.Add(1) go func() { defer wg.Done() for job := range jobs { results <- process(job) } }() }

wg.Wait() close(results) } ```

### Context for Cancellation and Timeouts

```go func FetchWithTimeout(ctx context.Context, url string) ([]byte, error) { ctx, cancel := context.WithTimeout(ctx, 5*time.Second) defer cancel()

req, err := http.NewRequestWithContext(ctx, "GET", url, nil) if err != nil { return nil, fmt.Errorf("create request: %w", err) }

resp, err := http.DefaultClient.Do(req) if err != nil { return nil, fmt.Errorf("fetch %s: %w", url, err) } defer resp.Body.Close()

return io.ReadAll(resp.Body) } ```

### Graceful Shutdown

```go func GracefulShutdown(server *http.Server) { quit := make(chan os.Signal, 1) signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)

<-quit log.Println("Shutting down server...")

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) defer cancel()

if err := server.Shutdown(ctx); err != nil { log.Fatalf("Server forced to shutdown: %v", err) }

log.Println("Server exited") } ```

### errgroup for Coordinated Goroutines

```go import "golang.org/x/sync/errgroup"

func FetchAll(ctx context.Context, urls []string) ([][]byte, error) { g, ctx := errgroup.WithContext(ctx) results := make([][]byte, len(urls))

for i, url := range urls { i, url := i, url // Capture loop variables g.Go(func() error { data, err := FetchWithTimeout(ctx, url) if err != nil { return err } results[i] = data return nil }) }

if err := g.Wait(); err != nil { return nil, err } return results, nil } ```

### Avoiding Goroutine Leaks

```go // Bad: Goroutine leak if context is cancelled func leakyFetch(ctx context.Context, url string) <-chan []byte { ch := make(chan []byte) go func() { data, _ := fetch(url) ch <- data // Blocks forever if no receiver }() return ch }

// Good: Properly handles cancellation func safeFetch(ctx context.Context, url string) <-chan []byte { ch := make(chan []byte, 1) // Buffered channel go func() { data, err := fetch(url) if err != nil { return } select { case ch <- data: case <-ctx.Done(): } }() return ch } ```

## Interface Design

### Small, Focused Interfaces

```go // Good: Single-method interfaces type Reader interface { Read(p []byte) (n int, err error) }

type Writer interface { Write(p []byte) (n int, err error) }

type Closer interface { Close() error }

// Compose interfaces as needed type ReadWriteCloser interface { Reader Writer Closer } ```

### Define Interfaces Where They're Used

```go // In the consumer package, not the provider package service

// UserStore defines what this service needs type UserStore interface { GetUser(id string) (*User, error) SaveUser(user *User) error }

type Service struct { store UserStore }

// Concrete implementation can be in another package // It doesn't need to know about this interface ```

### Optional Behavior with Type Assertions

```go type Flusher interface { Flush() error }

func WriteAndFlush(w io.Writer, data []byte) error { if _, err := w.Write(data); err != nil { return err }

// Flush if supported if f, ok := w.(Flusher); ok { return f.Flush() } return nil } ```

## Package Organization

### Standard Project Layout

```text myproject/ ├── cmd/ │ └── myapp/ │ └── main.go # Entry point ├── internal/ │ ├── handler/ # HTTP handlers │ ├── service/ # Business logic │ ├── repository/ # Data access │ └── config/ # Configuration ├── pkg/ │ └── client/ # Public API client ├── api/ │ └── v1/ # API definitions (proto, OpenAPI) ├── testdata/ # Test fixtures ├── go.mod ├── go.sum └── Makefile ```

### Package Naming

```go // Good: Short, lowercase, no underscores package http package json package user

// Bad: Verbose, mixed case, or redundant package httpHandler package json_parser package userService // Redundant 'Service' suffix ```

### Avoid Package-Level State

```go // Bad: Global mutable state var db *sql.DB

func init() { db, _ = sql.Open("postgres", os.Getenv("DATABASE_URL")) }

// Good: Dependency injection type Server struct { db *sql.DB }

func NewServer(db *sql.DB) *Server { return &Server{db: db} } ```

## Struct Design

### Functional Options Pattern

```go type Server struct { addr string timeout time.Duration logger *log.Logger }

type Option func(*Server)

func WithTimeout(d time.Duration) Option { return func(s *Server) { s.timeout = d } }

func WithLogger(l *log.Logger) Option { return func(s *Server) { s.logger = l } }

func NewServer(addr string, opts ...Option) *Server { s := &Server{ addr: addr, timeout: 30 * time.Second, // default logger: log.Default(), // default } for _, opt := range opts { opt(s) } return s }

// Usage server := NewServer(":8080", WithTimeout(60*time.Second), WithLogger(customLogger), ) ```

### Embedding for Composition

```go type Logger struct { prefix string }

func (l *Logger) Log(msg string) { fmt.Printf("[%s] %s\n", l.prefix, msg) }

type Server struct { *Logger // Embedding - Server gets Log method addr string }

func NewServer(addr string) *Server { return &Server{ Logger: &Logger{prefix: "SERVER"}, addr: addr, } }

// Usage s := NewServer(":8080") s.Log("Starting...") // Calls embedded Logger.Log ```

## Memory and Performance

### Preallocate Slices When Size is Known

```go // Bad: Grows slice multiple times func processItems(items []Item) []Result { var results []Result for _, item := range items { results = append(results, process(item)) } return results }

// Good: Single allocation func processItems(items []Item) []Result { results := make([]Result, 0, len(items)) for _, item := range items { results = append(results, process(item)) } return results } ```

### Use sync.Pool for Frequent Allocations

```go var bufferPool = sync.Pool{ New: func() interface{} { return new(bytes.Buffer) }, }

func ProcessRequest(data []byte) []byte { buf := bufferPool.Get().(*bytes.Buffer) defer func() { buf.Reset() bufferPool.Put(buf) }()

buf.Write(data) // Process...

// buf.Bytes() aliases the pooled buffer, which the deferred Put hands // to the next Get. Copy before returning, or callers race with reuse. return bytes.Clone(buf.Bytes()) // Go 1.20+; else append([]byte(nil), buf.Bytes()...) } ```

Never return or retain `buf.Bytes()` from a pooled buffer past `Put`: copy it, or let the caller pass in an `io.Writer` so no copy is needed.

### Avoid String Concatenation in Loops

```go // Bad: Creates many string allocations func join(parts []string) string { var result string for _, p := range parts { result += p + "," } return result }

// Good: Single allocation with strings.Builder func join(parts []string) string { var sb strings.Builder for i, p := range parts { if i > 0 { sb.WriteString(",") } sb.WriteString(p) } return sb.String() }

// Best: Use standard library func join(parts []string) string { return strings.Join(parts, ",") } ```

## Go Tooling Integration

### Essential Commands

```bash # Build and run go build ./... go run ./cmd/myapp

# Testing go test ./... go test -race ./... go test -cover ./...

# Static analysis go vet ./... staticcheck ./... golangci-lint run

# Module management go mod tidy go mod verify

# Formatting gofmt -w . goimports -w . ```

### Recommended Linter Configuration (.golangci.yml)

```yaml linters: enable: - errcheck - gosimple - govet - ineffassign - staticcheck - unused - gofmt - goimports - misspell - unconvert - unparam

linters-settings: errcheck: check-type-assertions: true govet: enable: - shadow

issues: exclude-use-default: false ```

## Quick Reference: Go Idioms

| Idiom | Description | |-------|-------------| | Accept interfaces, return structs | Functions accept interface params, return concrete types | | Errors are values | Treat errors as first-class values, not exceptions | | Don't communicate by sharing memory | Use channels for coordination between goroutines | | Make the zero value useful | Types should work without explicit initialization | | A little copying is better than a little dependency | Avoid unnecessary external dependencies | | Clear is better than clever | Prioritize readability over cleverness | | gofmt is no one's favorite but everyone's friend | Always format with gofmt/goimports | | Return early | Handle errors first, keep happy path unindented |

## Anti-Patterns to Avoid

```go // Bad: Naked returns in long functions func process() (result int, err error) { // ... 50 lines ... return // What is being returned? }

// Bad: Using panic for control flow func GetUser(id string) *User { user, err := db.Find(id) if err != nil { panic(err) // Don't do this } return user }

// Bad: Passing context in struct type Request struct { ctx context.Context // Context should be first param ID string }

// Good: Context as first parameter func ProcessRequest(ctx context.Context, id string) error { // ... }

// Bad: Mixing value and pointer receivers type Counter struct{ n int } func (c Counter) Value() int { return c.n } // Value receiver func (c *Counter) Increment() { c.n++ } // Pointer receiver // Pick one style and be consistent ```

**Remember**: Go code should be boring in the best way - predictable, consistent, and easy to understand. When in doubt, keep it simple.

Intended uses

  • Use Golang Patterns when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.