Go Developer

Go Developer

Guide for writing production-quality Go 1.25+ projects following current best practices.

> Structure: This file contains rules, guidelines, and compact examples. For full code examples and deep dives, see the files in references/. Consult them when you need implementation details beyond what's shown here.

Version Support

This guide covers:

• Go 1.25+: Base requirements and common features (all sections below)
• Go 1.25: Runtime, tooling, and stdlib improvements → See [references/go-1.25-features.md](references/go-1.25-features.md)
• Go 1.26: Language changes, GC improvements, new packages → See [references/go-1.26-features.md](references/go-1.26-features.md)

Feature Version Matrix

| Feature | 1.25 | 1.26 | |---------|------|------| | Container-aware GOMAXPROCS | ✅ | ✅ | | sync.WaitGroup.Go() | ✅ | ✅ | | testing/synctest (stable) | ✅ | ✅ | | go doc -http=:6060 | ✅ | ✅ | | go.mod ignore directive | ✅ | ✅ | | Green Tea GC (default) | ❌ (experimental) | ✅ | | new(expr) initialization | ❌ | ✅ | | Self-referential generic types | ❌ | ✅ | | errors.AsType | ❌ | ✅ | | Rewritten go fix with modernizers | ❌ | ✅ | | pprof flame graphs by default | ❌ | ✅ |

Quick Reference

Core Requirements (1.25+):

• Go 1.25+ minimum
• Use go.mod for all dependency management
• golangci-lint for linting
• govulncheck for vulnerability scanning
• Table-driven tests with t.Run
• Interfaces for dependency injection
• Explicit error handling (no panics for expected errors)

Project Overrides

How tool settings are resolved depends on the task:

• Reviewing existing code / PRs: Read go.mod (for go-version)

and .golangci.yml (for linter configuration) from the repository. The project's actual configuration is the source of truth. Do not override what the project already defines.

• Creating new projects: Use the defaults below when no go.mod

exists yet.

Local overrides (see "What Can Be Overridden") apply in both modes and take precedence over both the project config and the defaults below.

Defaults for New Projects

| Setting | Default | |----------------------|--------------------------| | go-version | 1.25 | | linter | golangci-lint v2 | | linter-preset | errcheck, govet, staticcheck, gosec, revive, goimports, misspell, unconvert, unparam, noctx | | test-assertions | testify (optional) | | logger | slog |

What Can Be Overridden

Overrides are not limited to the tool defaults above. A repository can provide any additional context that affects how this skill operates:

• Domain / business context: what the service does, which external

systems it integrates with, critical business invariants the AI would not know from reading code alone.

• Review behavior: which priority levels to comment on, what to

skip, confidence threshold, maximum number of comments.

• Codebase state: ongoing migrations, known tech debt that is

intentional, legacy patterns being phased out (so the AI does not flag them).

• Team conventions: patterns specific to this codebase that differ

from generic best practices.

• External caveats: downstream consumers, deployment constraints,

known limitations in third-party dependencies.

How to Override

Place overrides in whichever local rule file your agent platform uses:

• Cursor: .cursor/rules/go-overrides.mdc (with globs: "**/*.go")
• Claude Code: CLAUDE.md at the repository root
• Generic / agentskills.io: AGENTS.md at the repository root

Only include what differs from the defaults or what adds context the AI cannot infer from the code.

Example override (works in any of the above files):

> Go skill overrides for this repository: > > Domain context: > This is an event-driven microservice consuming from Kafka and writing > to PostgreSQL. Exactly-once semantics matter — always flag missing > transaction boundaries or ack-before-process patterns. > > Review behavior: > - Only flag Priority 1 (Critical) and Priority 2 (Important) issues > - Do not comment on naming conventions or package organization > - Maximum 5 review comments per PR > > Codebase state: > - Migrating from go-kit to plain stdlib HTTP; mixed patterns in > internal/transport/ are intentional > - The pkg/legacy/ directory will be removed after v3.0 launch > > Tool overrides (only when go.mod / .golangci.yml do not define them): > - test-assertions: none (use stdlib only)

Module Configuration (go.mod)

module github.com/yourorg/yourproject

go 1.25

require (
    github.com/some/dependency v1.2.3
)

Rules:

• Pin the minimum Go version you actually require
• Run go mod tidy regularly to keep go.sum clean
• Use go mod verify to check module integrity
• Use go.mod ignore directive (1.25+) to exclude directories from package matching
• Use go work for multi-module development (monorepos); don't commit go.work for libraries

Interfaces and Dependency Injection

Define interfaces where they are used (consumer side), not where they are implemented.

Rules:

• Keep interfaces small (1–3 methods) - prefer composition over fat interfaces
• Accept interfaces, return concrete types
• Use any instead of interface{}
• Verify interface satisfaction at compile time: var _ UserRepository = (*PostgresRepo)(nil)

Error Handling

Return errors explicitly - never use panics for expected failures:

• Wrap errors with context
• Sentinel errors for known conditions
• Custom error types for structured context

Inspect error chains with errors.Is (sentinels), errors.As (typed), or errors.AsType[T] (1.26, generic). See [references/REFERENCE.md](references/REFERENCE.md) for a full 3-layer error wrapping example (repo → service → handler).

Rules:

• ALWAYS wrap errors with fmt.Errorf("context: %w", err)
• NEVER ignore errors (use _ only when truly intentional, add a comment)
• NEVER return err.Error() to API clients — return static, pre-defined messages; log the full error internally
• NEVER wrap errors with full structs that may contain sensitive fields (passwords, tokens, PII) — select safe fields explicitly
• Translate errors at API boundaries — map domain errors to HTTP/gRPC status codes in a dedicated translation function; never let raw upstream errors reach the response
• Use errors.Is for sentinel errors, errors.As for typed errors
• Define sentinel errors at the package level with var Err... = errors.New(...)
• Panic only for programmer errors (nil pointer dereference, index out of bounds in init)

Generics (1.18+) and Iterators (1.23+)

Rules:

• Use generics for reusable data structures and algorithms, not for everything
• Prefer interfaces when you need runtime polymorphism (method dispatch)
• Use comparable constraint for map keys and equality checks
• Use cmp.Ordered for types that support `, =`
• Don't over-engineer: if a function works fine with any or a concrete type, don't add generics
• Use iter.Seq[T] for single-value iterators, iter.Seq2[K, V] for key-value pairs
• Always check yield's return value and stop if it returns false
• Use slices.Collect, maps.Collect to materialize iterators into concrete types
• Prefer iterators over returning []T when the caller may not need all elements (lazy evaluation)

See [references/generics-guide.md](references/generics-guide.md) for generic functions, constraints, data structures, self-referential types (1.26), when NOT to use generics, and composable iterator pipelines.

Concurrency

Goroutines and Channels

// ✅ Always handle goroutine lifecycle
func (s *Server) Start(ctx context.Context) error {
    g, ctx := errgroup.WithContext(ctx)

    g.Go(func() error {
        if err := s.httpServer.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
            return err
        }
        return nil
    })

    g.Go(func() error {
        5 methods) - split them
- ❌ `interface{}` / `any` when a concrete type or generic works
- ❌ Goroutine leaks - always ensure goroutines can exit
- ❌ Unbuffered channels in hot paths without careful design
- ❌ `time.Sleep` in tests - use `testing/synctest` or channels

## Go 1.25 and 1.26 Features

- **Go 1.25**: See [references/go-1.25-features.md](references/go-1.25-features.md)
- **Go 1.26**: See [references/go-1.26-features.md](references/go-1.26-features.md)

## Checklist

### For Code Authors

When creating Go code:

- [ ] Go 1.25+ features used where appropriate
- [ ] All errors handled explicitly (no `_` without comment)
- [ ] Errors wrapped with `fmt.Errorf("context: %w", err)`
- [ ] `context.Context` passed as first parameter
- [ ] `cancel()` called for every `WithCancel`/`WithTimeout`
- [ ] `defer Close()` on DB rows, HTTP response bodies, file handles
- [ ] Interfaces defined at consumer side, kept small
- [ ] Table-driven tests with `t.Run`
- [ ] `-race` flag used in CI
- [ ] `golangci-lint` passes
- [ ] `govulncheck` passes
- [ ] Structured logging with `slog`
- [ ] No hardcoded secrets
- [ ] `internal/` used for private code

### For Code Reviewers

**Review quality rules (apply before writing any comment):**

- **Only comment when confident.** If you are uncertain whether
  something is actually wrong, do not comment. A false positive wastes
  more reviewer and author time than a missed suggestion.
- **Signal over noise.** A review with 2 critical findings is more
  valuable than one with 15 mixed-confidence suggestions. Fewer,
  higher-quality comments.
- **Default scope: Priority 1 and 2 only.** Do not comment on Priority
  3 issues unless the repository overrides explicitly request it.
- **Never comment on pure style preferences** that the configured
  linter does not flag. If golangci-lint passes, the style is acceptable.
- **Respect the codebase's current state.** If code is in a known
  migration, uses legacy patterns being phased out, or has documented
  tech debt, do not flag those patterns unless the override says
  otherwise.
- **Use domain context when available.** A missing transaction boundary
  in a payment service is critical; the same issue in a CLI utility may
  not be. Weigh findings against what the code actually does, not just
  generic rules.
- **Honor review behavior overrides.** If the repository sets a maximum
  comment count, confidence threshold, or excludes certain categories,
  follow those constraints strictly.
- **Findings are sensor data, not verdicts.** Never imply a change is safe
  to merge because the review is clean — surface what you checked and what
  you could not. Borrowed confidence is itself a risk. You may be one of
  several reviewers on this PR; a clean result from you covers only the
  priorities in this skill, not the PR as a whole.
- **Stay in your lane.** Focus on the priorities defined here (Go
  correctness, security, resource safety). Don't expand into generic
  coverage another reviewer is better positioned to provide — independent,
  specialized signal is more valuable than correlated overlap.

### Review Priorities

When reviewing Go code, first classify each changed file by blast radius:

- **Critical** (auth, payments, crypto, data-deletion, DB migrations, anything handling untrusted input or PII): full rigor — escalate borderline findings up one priority level.
- **Standard** (business logic, APIs, service layers): normal priority rules.
- **Low** (config, docs, generated code, test-only changes): P1 only — do not nitpick.

Then prioritize findings:

**Priority 1 - Critical Issues (Must Fix):**

1. **Security vulnerabilities** (SQL injection, hardcoded secrets, path traversal, prompt injection — untrusted/user-controlled text flowing into an LLM call without safeguards; this risk is latent in runtime data, not visible in the diff)
2. **Ignored errors** (silent failures, missing error checks)
3. **Goroutine leaks** (goroutines that can never exit)
4. **Data races** (shared state without synchronization)
5. **Resource leaks** (missing `defer Close()` on DB rows, HTTP response bodies, file handles; missing `defer cancel()` on contexts)
6. **Newly suppressed security-linter checks** — `//nolint gosec` added in this diff; treat the suppressed warning as an active finding. Pre-existing suppressions are out of scope.
7. **Suspicious test changes** — assertions weakened or rewritten to match new (possibly broken) behavior, tests deleted or marked `t.Skip`, coverage of the changed code path removed. When a diff changes both code and its tests, verify the tests still assert *correct* behavior, not just *current* behavior.

**Priority 2 - Important Improvements (Should Fix):**

1. **Missing context propagation** (functions missing `ctx context.Context`)
2. **Error wrapping** (errors without context, missing `fmt.Errorf("...: %w", err)`)
3. **Testing gaps** (missing table-driven tests, no race detection)

**Priority 3 - Nice to Have (Consider Fixing):**

1. **Naming conventions** (non-idiomatic names)
2. **Package organization** (generic package names)
3. **Fat interfaces** (interfaces with too many methods — split them)
4. **Performance** (unnecessary allocations, missing benchmarks). Escalate
   to Priority 2 when the impact is concrete: hot-path allocations,
   missing connection pooling, or blocking operations in goroutines
   serving concurrent requests.
5. **Reinvention** — new code that reimplements an existing stdlib or internal helper instead of reusing it. Escalate to Priority 2 if the reimplemented helper handles security-sensitive logic.
6. **Generic safety gate weakening** — unrelated `//nolint` without justification, skipped non-critical tests, relaxed coverage thresholds, loosened `.golangci.yml` config.

## PR Review Workflow

> **Tip:** For PRs that touch multiple languages, use the **pr-reviewer** skill — it orchestrates language-specific review across Go, Python, and more in a single pass.

When asked to review a PR (by number, URL, or branch name):

### Step 1: Gather context
- Fetch the PR description, metadata, and diff using `gh pr view` and
  `gh pr diff`
- **Fast-fail screening:** a sprawling diff, mass test rewrites, or a
  vague/missing intent statement are themselves findings. Flag "PR too
  large to review confidently — recommend splitting" rather than
  rubber-stamping.
- Read `go.mod` and `.golangci.yml` for the project's actual
  configuration
- Read any local overrides (`.cursor/rules/`, `AGENTS.md`, `CLAUDE.md`)
- Fetch existing review comments (`gh pr view --comments`) and skip
  findings already raised by another reviewer or the author — don't
  restate them
- Identify which files changed and their purpose from the PR description

### Step 2: Review
- Apply the review quality rules and priority levels above
- Assess changes against the PR's stated intention — flag deviations
  from what the PR says it does, not just generic code quality
- Ignore files excluded by local overrides (e.g. frozen directories)

### Step 3: Present findings
- Show findings to the user grouped by priority, with file paths and
  line numbers
- Do NOT post to GitHub until the user explicitly approves
- If there are no findings worth flagging, say so — a clean review is
  a valid outcome

### Step 4: Post (only when approved)
- Post each finding as a separate inline review comment on the specific
  line in the PR
- Use a single review submission (not individual comments) so the
  author gets one notification, not N
- Submit as a neutral `COMMENT` review, not `REQUEST_CHANGES`. The user
  decides the disposition via follow-up commands below.

### Follow-up commands
These should work without repeating the full context:
- **"re-review"** — fetch latest changes, review only new/modified
  hunks, and present findings
- **"approve"** — approve the PR with a constructive comment
- **"reque

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [gvre](https://github.com/gvre)
- **Source:** [gvre/skills](https://github.com/gvre/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.