@baselane/packs 0.1.3 → 0.1.5

package/packs/go-rules/rendered/.claude/skills/golang-patterns/SKILL.md

@@ -0,0 +1,673 @@
+---
+name: golang-patterns
+description: Idiomatic Go patterns, best practices, and conventions for building robust, efficient, and maintainable Go applications — API shape, error handling, concurrency, interface design, package organization, and performance. Use when writing, reviewing, or refactoring Go code, or designing Go packages/modules.
+---
+
+# Go Development Patterns
+
+Idiomatic Go patterns and best practices for building robust, efficient, and maintainable applications.
+
+## When to use
+
+- 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
+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...
+    return buf.Bytes()
+}
+\`\`\`
+
+### 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.