Claude-skill-registry go-service-hexagonal

Define, review, and scaffold Go service directory structures using hexagonal (ports-and-adapters / “jexagonal”) architecture and Go best practices. Use when creating or refactoring Go services, deciding package boundaries, organizing cmd/internal/api/config/deploy/migrations, or choosing layouts for common service types (HTTP REST API, gRPC API, async worker/consumer, scheduled job, CLI, multi-binary repos).

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/go-service-hexagonal" ~/.claude/skills/majiayu000-claude-skill-registry-go-service-hexagonal && rm -rf "$T"

manifest: skills/data/go-service-hexagonal/SKILL.md

source content

Go Service Hexagonal

Workflow

1) Choose the repo shape

Use single-service repo when one deployable dominates the repo.
Use multi-binary repo when multiple deployables share a domain and are released together (API + worker + migrator).
Use monorepo when many services share tooling but keep each service isolated under
```
<service>/cmd/<service>-<binary>
```
and
```
<service>/internal/...
```
.

2) Choose the service kind

HTTP REST/JSON API → use
```
references/layout-http-rest.md
```
gRPC API → use
```
references/layout-grpc.md
```
Worker/consumer/scheduler/job → use
```
references/layout-worker.md
```
CLI (ops tools, admin, local runner) → use
```
references/layout-cli.md
```

3) Apply hexagonal (ports-and-adapters) boundaries

Put business rules in
```
internal/domain
```
.
Put use cases in
```
internal/app
```
and define inbound ports in
```
internal/interface
```
.
Define outbound ports (interfaces to DB, queues, HTTP clients) in
```
internal/adapter
```
.
Implement inbound adapters in
```
internal/interface/*
```
(primary) and outbound adapters in
```
internal/adapter/*
```
(secondary).
Choose a settings mode: none (defaults only), env (env-only), or config (env + optional config file via Koanf, env overrides config). Use
```
internal/interface/options
```
only for config mode.
Perform all wiring in a single composition root:
```
internal/bootstrap.Compose(...)
```
and keep
```
cmd/*
```
thin.

Use

references/architecture-rules.md

as the dependency rulebook.

4) Refactor an existing project

Read
```
references/refactor-workflow.md
```
.
For minimal, necessary tests during refactors, read
```
references/refactor-testing.md
```
.
Create a refactor plan using
```
references/refactor-plan-template.md
```
and agree on it with the user before making changes.
Execute the plan in small, explicit steps and confirm after each step.
Track the plan in a checkboxed
```
REFACTORING.md
```
at repo root and mark completed items as you finish them.

Scaffolding

Run the scaffolder to generate a starting tree plus minimal compileable stubs:

python3 scripts/scaffold_hex_service.py --root <repo> --service <name> --kinds http,worker

Pick a settings mode:

Defaults only:
```
--settings none
```
Env only (default):
```
--settings env
```
Env + config file (Koanf):
```
--settings config
```

Example (config mode):

python3 scripts/scaffold_hex_service.py --root <repo> --service <name> --kinds http --settings config

Config files (when enabled) support json/yaml/toml with keys:

http_addr

pprof_addr

pprof_port

log_level

. If the config file has no extension, TOML is assumed. Environment values override config values when both are set.

HTTP scaffolding defaults to Echo. For explicit Echo:

python3 scripts/scaffold_hex_service.py --root <repo> --service <name> --kinds http --http-framework echo

For a pure

net/http

baseline:

python3 scripts/scaffold_hex_service.py --root <repo> --service <name> --kinds http --http-framework nethttp

HTTP scaffolds include

GET /health/live

and

GET /health/ready

, plus request logging using Logrus (

github.com/sirupsen/logrus

Optional (opt-in) HTTP debug endpoints:

```
--http-pprof
```
adds handlers under
```
GET /debug/pprof/*
```
(pprof index + profiles).
```
--http-trace
```
adds
```
GET /debug/pprof/trace
```
(execution trace).
These run on a separate debug HTTP server and are activated only when
```
PPROF_PORT
```
is set (e.g.
```
PPROF_PORT=6060
```
); optionally set
```
PPROF_ADDR
```
to change the bind address (default
```
127.0.0.1
```
).
The handler mux is scaffolded as a dedicated inbound adapter:
```
internal/interface/debughttp
```
.

For new projects, if

--module

is omitted the module path defaults to the

<repo>

folder name (no

github.com/...

assumption). If

go.mod

is created (new project), the scaffolder runs

go mod tidy

to fetch dependencies (Echo + Logrus). Use

--skip-deps

to skip.

Generated projects include required

README.md

AGENTS.md

, and

Makefile

at repo root. When HTTP is scaffolded, the project also includes

test/health_test.go

Then edit the generated packages to match your domain and ports.

Reference Index

Read

references/index.md

and then open only the layout file(s) you need for the chosen service kind.