Skip to content
Skills Library
Programming · Learning & explanation

hexagonal-pattern-guide

/hexagonal-pattern-guide

Use when isolating an application or domain core from its I/O and delivery mechanisms behind interfaces: hexagonal / ports-and-adapters / clean / onion architecture. Triggers on decoupling the domain from the database/UI/framework, driving (primary) vs driven (secondary) adapters, dependency inversion / the dependency rule ('depend on an interface, not the implementation'), a composition root wiring adapters to ports, swapping a real adapter for a fake in tests, or keeping business logic free of infrastructure, even when the user doesn't say 'hexagonal' and says 'ports and adapters' or 'clean

Repository
platform ↗
Licence
MIT
Last repository change
08.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
9
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 08.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when isolating an application or domain core from its I/O and delivery mechanisms behind interfaces: hexagonal / ports-and-adapters / clean / onion architecture. Triggers on decoupling the domain from the database/UI/framework, driving (primary) vs driven (secondary) adapters, dependency inversion / the dependency rule ('depend on an interface, not the implementation'), a composition root wiring adapters to ports, swapping a real adapter for a fake in tests, or keeping business logic free of infrastructure, even when the user doesn't say 'hexagonal' and says 'ports and adapters' or 'clean

Triggers from the description

depend on an interface, not the implementationt sayand saysor
Original author description

Use when isolating an application or domain core from its I/O and delivery mechanisms behind interfaces: hexagonal / ports-and-adapters / clean / onion architecture. Triggers on decoupling the domain from the database/UI/framework, driving (primary) vs driven (secondary) adapters, dependency inversion / the dependency rule ('depend on an interface, not the implementation'), a composition root wiring adapters to ports, swapping a real adapter for a fake in tests, or keeping business logic free of infrastructure, even when the user doesn't say 'hexagonal' and says 'ports and adapters' or 'clean

How it works

  1. Essentials
  2. Gotchas
  3. Example
  4. Progressive Disclosure
Original SKILL.md headings · 38 lines, 291 words
SKILL.md preview
---
name: hexagonal-pattern-guide
description: "Use when isolating an application or domain core from its I/O and delivery mechanisms behind interfaces: hexagonal / ports-and-adapters / clean / onion architecture. Triggers on decoupling the domain from the database/UI/framework, driving (primary) vs driven (secondary) adapters, dependency inversion / the dependency rule ('depend on an interface, not the implementation'), a composition root wiring adapters to ports, swapping a real adapter for a fake in tests, or keeping business logic free of infrastructure, even when the user doesn't say 'hexagonal' and says 'ports and adapters' or 'clean architecture'."
---

# Hexagonal Architecture (Ports and Adapters)

Isolate the domain core behind ports it owns, so every I/O and delivery mechanism is an interchangeable adapter on the outside.

## Essentials

- **Driving in, driven out** - primary adapters call into the core; secondary adapters are called out by it, see [references/ports-and-adapters.md](references/ports-and-adapters.md)
- **Dependencies point inward** - the core names no adapter; the dependency rule + dependency inversion, see [references/dependency-inversion.md](references/dependency-inversion.md)
- **Wiring lives in one composition root** - see [references/composition-root.md](references/composition-root.md)
- **Testability is the payoff** - fake the driven adapters, drive the core in a test, no real I/O, see [references/testability.md](references/testability.md)

## Gotchas

- The hexagon isn't six of anything. It just signals "many ports", not a top/bottom layering.
- Ports-and-adapters is not the microkernel pattern: hexagonal isolates the domain behind a usually-fixed set of ports; an open, _registered_ plug-in set is microkernel-pattern-guide. They share the adapter mechanism, nothing more.
- If a unit test needs a real database or network, the boundary leaked: narrow the port or invert the dependency.

## Example

```go
// core owns the port; it never imports a driver
type Repository interface{ Save(o Order) error }

type OrderService struct{ repo Repository } // depends on the port, not Postgres

// driven adapter (outside): a PostgresRepository implementation of the port
// driving adapter (outside): an HTTP handler that calls OrderService
// test: an InMemoryRepository fake, no database
```

## Progressive Disclosure

- Read [references/ports-and-adapters.md](references/ports-and-adapters.md) - Load when defining ports and driving/driven adapters around a core
- Read [references/dependency-inversion.md](references/dependency-inversion.md) - Load when deciding which way dependencies point or detecting a core leak
- Read [references/composition-root.md](references/composition-root.md) - Load when wiring concrete adapters to ports in one place
- Read [references/testability.md](references/testability.md) - Load when testing a core in isolation with fakes/test doubles
Files in this package (9)
  • SKILL.md 3 KB
  • SOURCES.md 2 KB
  • eval-queries.json 5 KB
  • evals.json 3 KB
  • moon.yml 1 KB
  • references/composition-root.md 2 KB
  • references/dependency-inversion.md 1 KB
  • references/ports-and-adapters.md 2 KB
  • references/testability.md 2 KB

Versions

The database has no other skills named hexagonal-pattern-guide.

Database snapshot: 13.11.2026 · package version 9ad4cdb93ffb (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100hexagonal-clean-onion-architecture
    Use this skill when isolating core domain business logic from external frameworks, databases, and transport layers via ports & adapters.
  • 100ddd-architecture-hexagonal
    Comprehensive guidance for Hexagonal Architecture (Ports & Adapters) — Alistair Cockburn's hexagonal architecture with domain core, port definitions, adapter implementations, and full Java/Spring Boot implementation steps. Covers primary/driving adapters, secondary/driven…
  • 100hexagonal-architecture
    Use when structuring a Symfony app with ports & adapters / clean architecture — keeping the domain framework-free, defining interfaces (ports) in the domain and implementations (adapters) in infrastructure. Use when the task mentions hexagonal, ports/adapters, or "keep the domain pure".
  • 100707-technologies-hexagonal-architecture
    Use when you need framework-agnostic Hexagonal architecture guidance for Java projects - ports and adapters boundaries, application core independence, driving and driven adapters, dependency direction, infrastructure leakage detection, optional architecture tests, and…
  • 100hexagonal
    Hexagonal Architecture (Ports and Adapters), Onion Architecture, and their relationship to Clean Architecture -- enabling technology-independent domain logic with high testability. USE FOR: hexagonal architecture, ports and adapters, onion architecture, driving/driven adapters,…
  • 100hexagonal
    Expert Hexagonal Architecture (Ports and Adapters) assistance covering driving/driven ports, infrastructure adapters, domain core isolation, and test stubbing. Use when decoupling domain logic from databases/HTTP frameworks, improving testability, or modernizing enterprise applications.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.