Go Rig

Go Rig

Strict design and testing discipline for Go projects.

This skill complements CLAUDE.md.

CLAUDE.md owns:

• Go version, toolchain, and commands
• Key style, error, context, and concurrency rules

.claude/rules/ owns:

• Go 1.27 idioms and go fix modernizer catalog (go-idioms.md)
• Detailed style, API, documentation, and testing patterns (go-patterns.md)

This skill adds:

• ATDD/TDD workflow
• design principles and abstraction discipline
• dependency injection discipline
• package-boundary judgment
• documentation discipline
• comment quality standards
• structured review process

Do not restate or override version-specific guidance from CLAUDE.md. If CLAUDE.md is stricter on a shared point, follow CLAUDE.md.

When to Use

Use this skill when:

• implementing a new feature or behavior increment
• refactoring Go code for clearer ownership or testability
• reviewing package boundaries or dependency flow
• replacing hidden collaborator construction with explicit injection
• tightening tests around user-visible or integration behavior

ATDD/TDD Workflow

Test-first is a design tool, not an afterthought.

1. Acceptance first — define the boundary behavior before writing code
2. Acceptance test — add or update an acceptance-level test if the project has that layer; otherwise express boundary behavior in the closest consumer-level test
3. Smallest failing unit test — for the next behavior increment
4. Minimal implementation — only enough to pass
5. Refactor — improve readability and cohesion while green
6. Repeat — next behavior increment

If repository policy does not allow automatic test execution, still design test-first and ask before running.

Test Coverage Expectations

Every meaningful change should cover:

• expected behavior (happy path)
• invalid input and validation failures
• edge cases and boundary values
• error and failure paths
• concurrency behavior when relevant

Use the project’s existing test layers where possible. Reach for acceptance tests when the change is user-visible or integration-heavy, and unit tests when isolating business rules or edge cases.

Definition Of Done

A change is not done when the code "works on one path." It is done when:

• acceptance behavior is specified at the right boundary
• the smallest relevant unit behavior is covered
• failure and edge behavior are covered
• code was refactored back to clarity after going green
• repo test/lint/static-analysis expectations were satisfied or explicitly deferred

Design Principles

Apply without ceremony — these guide decisions, not generate boilerplate.

SRP — each package, type, and function has one clear reason to change. Split when a change in one concern forces changes in an unrelated concern.

DRY — extract repeated validation, mapping, branching, and business rules. Do not DRY away incidental similarity — two things that look alike but change for different reasons should stay separate.

OCP — extend stable areas carefully, but do not invent indirection to satisfy the idea of extensibility. In Go, a concrete type with a small seam at the consumer is usually better than an abstract framework.

When applying SRP/DRY/OCP in Go, prefer deleting duplication caused by mixed responsibilities before introducing new abstractions. The first move is usually better boundaries, not more interfaces.

Abstraction Discipline

• Start with concrete types and direct calls
• Introduce an interface only when a real consumer needs substitution
• Prefer one seam at a boundary over many tiny abstractions in the core
• If an abstraction adds files, wiring, and names but no clear testability or ownership win, do not add it

Avoid:

• repositories or services that only forward calls
• configuration objects passed everywhere to avoid choosing explicit parameters
• “future-proofing” abstractions without a concrete second implementation or consumer

Function Design

• A function should usually do one thing: validate, transform, orchestrate, persist, or render
• If a function mixes business rules with transport, storage, or logging details, split it
• Keep parameter lists explicit and intention-revealing; if many values travel together for one reason, introduce a small typed struct

Refactor when a function:

• needs comments to explain the control flow
• mixes unrelated reasons to change
• carries mutable state across many screens of code
• repeats branching or validation logic that belongs in a helper or type method

Dependency Injection

• Constructors for types that must enforce invariants or own long-lived collaborators
• Function parameters for short-lived collaborators and pure logic
• Never construct DB clients, HTTP clients, loggers, or repositories inside domain methods
• Prefer passing dependencies from the composition root (main, wiring package, or test setup) instead of looking them up deep inside the call stack
• Inject seams for time, randomness, process execution, filesystem, and external I/O when behavior depends on them

Package Design

Organize by domain, not by technical layer.

• Group related domain logic together until splitting clearly improves cohesion
• Keep transport and storage near the owning domain in the repo when the service is small, but do not let core business logic depend on transport details
• Split files when doing so improves readability; file count is not a goal by itself
• Split packages only when coupling pressure is real, not speculative

Avoid:

• deep layering in small services
• internal/platform/ catch-all layers — keep cross-cutting concerns in focused packages
• packages that combine unrelated domains because they share a datastore or transport

Hardcoding And Configuration

• Do not hardcode URLs, ports, credentials, file paths, timeouts, feature flags, environment names, or dependency selection in core logic
• Domain invariants may be constants, but operational values should come from config, constructor parameters, or function arguments
• Prefer typed config structs validated at startup over scattered os.Getenv calls
• Keep configuration loading at the edge; pass validated values inward