golang

Files (19)

• SKILL.md
• benchmarking.md · references/
• caching.md · references/
• cli-tools.md · references/
• concurrency.md · references/
• context.md · references/
• documentation.md · references/
• errors.md · references/
• generics.md · references/
• http-clients.md · references/
• http-servers.md · references/
• interfaces.md · references/
• json.md · references/
• logging.md · references/
• pprof.md · references/
• project-structure.md · references/
• scheduling.md · references/
• testing.md · references/
• tracing.md · references/

SKILL.md (first lines)

# Golang

Senior Go developer with deep expertise in Go 1.27+, concurrent programming, and
cloud-native microservices. Specializes in idiomatic patterns, performance
optimization, and production-grade systems.

## Core Workflow

1. **Analyze architecture** — Review module structure, interfaces, and concurrency patterns
2. **Design interfaces** — Create small, focused interfaces with composition
3. **Implement** — Write idiomatic Go with proper error handling and context propagation; run `go vet ./...` before proceeding
4. **Lint & validate** — Run `golangci-lint run` and fix all reported issues before proceeding
5. **Optimize** — Eliminate allocations
6. **Test** — Table-driven tests with `-race` flag, fuzzing; confirm race detector passes before committing

## Reference Guide

Load detailed guidance based on context:

| Topic | Reference | Load When |
| --- | --- | --- |
| Concurrency | `references/concurrency.md` | Goroutines, channels, select, sync primitives, leaks |
| Context | `references/context.md` | Context values, request-scoped metadata, cancellation propagation |
| Errors | `references/errors.md` | Error wrapping, sentinel errors, `errors.Is`/`As`, custom error types |
| Interfaces | `references/interfaces.md` | Interface design, io.Reader/Writer, composition |
| Generics | `references/generics.md` | Type parameters, generic methods, constraints, generic patterns |
| Testing | `references/testing.md` | Table-driven tests, synctest, httptest, mocks, fuzzing, coverage |
| Benchmarking | `references/benchmarking.md` | `go test -bench`, `-benchmem`, `-benchtime`, `-trace`, profiles |
| Profiling (pprof) | `references/pprof.md` | CPU/heap/`goroutineleak` profiles, `go tool pprof`, contention, leaks |
| Logging | `references/logging.md` | Structured logging, JSON logging |
| JSON | `references/json.md` | `encoding/json/v2`, struct tags, Options |
| Tracing | `references/tracing.md` | Distributed tracing, OpenTelemetry, spans, trace propagation |
| Documentation | `references/documentation.md` | Code comments, godoc conventions, deprecations, `//go:fix inline` |
| Project Structure | `references/project-structure.md` | Module layout, internal packages, go.mod |
| CLI Tools | `references/cli-tools.md` | CLI design, flags, subcommands, env vars, configuration |
| Scheduler | `references/scheduling.md` | Background jobs, cron schedules, long-running workers, graceful shutdown |
| HTTP Servers | `references/http-servers.md` | HTTP routing, middleware, logging, error handling, API design, h2c |
| HTTP Clients | `references/http-clients.md` | HTTP client config, transports, timeouts, retries, observability |
| Caching | `references/caching.md` | In-memory caching, FIFO, LRU, TTL |

## Core Pattern Example

Goroutine with proper context cancellation and error propagation:

```go
// worker runs until ctx is cancelled or an error occurs. Errors are returned via
// the errs channel; the caller must drain it.
func worker(ctx context.Context, jobs <-chan Job, errs chan<- error) {
    for {
        select {
        case <-ctx.Done():
            errs <- fmt.Errorf("worker cancelled: %w", ctx.Err())
            return
        case job, ok := <-jobs:
            if !ok {
                return // jobs channel closed; clean exit
            }
            if err := process(ctx, job); err != nil {
                errs <- fmt.Errorf("process job %v: %w", job.ID, err)
                return
            }
        }
    }
}

func runPipeline(ctx context.Context, jobs []Job) error {
    ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
    defer cancel()

    jobs := make(chan Job, len(jobs))
    errs := make(chan error, 1)

    go worker(ctx, jobs, errs)

    for _, j := range jobs {
        jobs <- j
    }
    close(jobs)

    select {
    case err := <-errs:
        return err
    case <-ctx.Done():
        return fmt.Errorf("pipeline timed out: %w", ctx.Err())
    }
}
```

Key properties demonstrated: bounded goroutine lifetime via `ctx`, error propagation with `%w`, no goroutine leak on cancellation.

## Constraints

### MUST DO

- Use gofumpt (when available, otherwise gofmt) and golangci-lint on all code
- Add context.Context to all blocking operations
- Handle all errors explicitly (no naked returns)
- Write table-driven tests with subtests
- Document all exported functions, types, and packages
- Propagate errors with `fmt.Errorf("%w", err)`, `errors.Join`
- Run tests with `-race` (race detector), `-count N`, `-cpu 1,8`, `-timeout T`

### MUST NOT DO

- Ignore errors (avoid _ assignment without justification)
- Use panic for normal error handling
- Create goroutines without clear lifecycle management
- Skip context cancellation handling
- Use reflection without performance justification
- Mix sync and async patterns carelessly
- Hardcode configuration (use functional options or env vars)
- Implementing `min`, `max` or other functions that are now built-in (Go 1.21+)
- Explicitly define a variable that is only consumed in one place (e.g. `foo := bar(); use(foo)`, just do `use(bar())` instead)
- Use legacy `foo := foo` in loops on Go 1.22+ codebases
- Fork a dependency and patch it locally unless explicitly asked to do so (implement workaroudn OR halt and ask how to proceed)
- Import `encoding/json` in new code; use `encoding/json/v2` (existing v1 call sites are fine)

## Output Templates

From lrstanley/skills, MIT.

More from lrstanley/skills