opencode-workflow/skills/language-go/SKILL.md

name	description
language-go	Go-specific code design reference for the Code Design Agent. Load only when the architecture or repository indicates Go. Covers package layout, interfaces, errors, configuration, testing, and build conventions without changing system architecture.

This skill provides Go-specific guidance for code-level design.

Announce at start: "I'm using the language-go skill to apply Go-specific code design conventions."

When To Load

Load this skill only when one or more of the following is true:

• The architecture explicitly names Go or Golang
• The repository contains go.mod
• The repository contains Go packages under paths such as cmd/, internal/, or pkg/

Do not load this skill for non-Go projects.

Purpose

Translate system architecture into idiomatic Go code design. This skill helps choose package boundaries, interface conventions, struct design, error handling, dependency injection, testing patterns, and build structure for Go services.

Go Design Rules

1. Prefer small packages with clear ownership over deep technical layering
2. Prefer constructor injection and explicit dependencies
3. Keep interfaces close to the consumer when possible; do not create interfaces purely for decoration
4. Use context.Context as the first parameter for request-scoped operations
5. Return error explicitly; do not rely on panics for control flow
6. Keep domain entities free of transport and persistence concerns unless the project already uses shared structs intentionally

Project Structure Guidance

• Use cmd/{service}/main.go for application entrypoints
• Use internal/ for application-private packages
• Use pkg/ only for genuinely reusable packages shared across binaries or modules
• Prefer feature-oriented directories when the feature has multiple layers that evolve together
• Keep generated code, mocks, and migrations in clearly named top-level or feature-local directories

Interface Guidance

• Repository and service methods should usually accept context.Context
• Prefer narrow interfaces such as UserReader and UserWriter when consumers need partial behavior
• Do not define interfaces for concrete helpers unless they cross a meaningful boundary or improve testability
• Return concrete domain values from repositories/services unless pointer semantics are required by mutation or nilability

Model Guidance

• Use domain structs for business logic, DTO structs for transport, and persistence structs only when storage mapping differs materially
• Use time.Time for timestamps and explicit ID types where the codebase already has a convention
• Keep JSON tags on DTOs; keep DB tags on persistence structs
• If a single struct is used across layers, justify it explicitly in the code design doc

Error Guidance

• Prefer wrapped errors with %w when adding context
• Define stable error codes separately from human-readable messages
• Reserve sentinel errors for branchable states such as not found, conflict, unauthorized, and invalid input
• Map service-layer errors to transport-layer status codes explicitly

Dependency Injection Guidance

• Default to constructor injection
• Prefer manual wiring in cmd/ or a small bootstrap package unless the project already standardizes on a DI tool
• Keep wiring shallow and explicit

Testing Guidance

• Default to table-driven tests for pure logic
• Prefer standard library testing plus a small assertion helper set unless the repository already standardizes on a framework
• Use mocks only at true boundaries such as repositories, outbound clients, or queues
• Prefer integration tests with real infrastructure for repositories and migrations when feasible

Build Guidance

• Use a multi-stage Docker build for services
• Keep Makefile targets small and composable, for example fmt, lint, test, build, run
• Document required Go version from go.mod

Output Constraint

This skill is reference-only. It does not create files by itself. Apply its guidance inside docs/code-design/{date}-{feature}.md only.