golang-hex-clean

Guides Go Hexagonal Clean Architecture implementation with strict layering, DDD patterns, and idiomatic style rules.

Updated Apr 11, 2026
One-click install
npx skills add https://github.com/lurodrisilva/personal-skills --skill golang-hex-clean-lurodrisilva
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: golang-hex-clean
Source: https://github.com/lurodrisilva/personal-skills/tree/main/coding/golang-hex-clean
Command: npx skills add https://github.com/lurodrisilva/personal-skills --skill golang-hex-clean-lurodrisilva

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Building Go services without enforced architectural boundaries leads to tangled dependencies, untestable code, and inconsistent style. This Skill enforces strict Hexagonal (Ports & Adapters) layering with dependency inversion and synthesizes idiomatic Go conventions from the Google, Uber, and Effective Go style guides. ## Core Features & Use Cases - Strict Dependency Law: Defines which packages may import each other across domain, application, adapter, and infrastructure layers, with violations treated as automatic failures. - Phased Implementation Workflow: Detects the request mode (new aggregate, use case, endpoint, full feature) and walks through domain modeling, CQRS handlers, adapters, and wiring with complete code templates. - Idiomatic Go Enforcement: Covers naming, error wrapping with %w, interface ownership by consumers, concurrency rules, table-driven testing, and 95% coverage requirements. - Use Case: When asked to add a new order feature to a Go microservice, the Skill generates the aggregate root, value objects, repository port, command/query handlers, HTTP adapter, and DI wiring in the correct layers. ## Quick Start Ask the AI to add a new end-to-end feature, such as a customer aggregate with create and get endpoints, to your Go hexagonal architecture project.

Frequently Asked Questions about golang-hex-clean

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I structure a Go project with hexagonal architecture?▼

Place all code under internal/ with four layers: domain (entities, value objects, repository ports), application (CQRS handlers), adapter (inbound HTTP/gRPC and outbound persistence), and infrastructure (config, DI, server). The cmd/ directory holds only the main entrypoint.

Where should repository interfaces be defined in Go clean architecture?▼

Repository interfaces are defined in the domain package by their consumer, for example internal/domain/order/repository.go. Concrete implementations live in internal/adapter/outbound/persistence/. Never define an interface and its only implementation in the same package.

How do I implement CQRS command handlers in Go?▼

Create a command struct with primitive fields and a handler struct with injected port dependencies. The Handle method takes context first, translates primitives to domain types, orchestrates validate-construct-persist-publish, and returns error last with %w wrapping.

What Go naming conventions does this skill enforce?▼

It enforces MixedCaps without snake_case, no Get prefix on getters, consistent initialisms like URL and ID, one-to-two letter receivers, -er suffix for single-method interfaces, and lowercase single-word package names without util or common.

When should I use %w versus %v for Go error wrapping?▼

Use %w by default within your application to preserve the error chain for errors.Is and errors.As. Use %v at system boundaries like RPC or IPC where wrapping would leak implementation details to external callers.

What are the limitations of hexagonal architecture for small Go services?▼

The strict layering, port interfaces, and per-aggregate file structure add boilerplate that may not pay off for trivial CRUD services or prototypes. The pattern is most valuable for long-lived services with complex domain logic and multiple adapters.