Clean Ddd Hexagonal
Design APIs and services with DDD, Clean Architecture, and hexagonal ports/adapters without guessing layer boundaries.
Overview
Clean DDD Hexagonal is an agent skill most often used in Build (also Validate) that applies DDD, Clean Architecture, and hexagonal ports/adapters when designing scalable, testable backend services.
Install
npx skills add https://github.com/ccheney/robust-skills --skill clean-ddd-hexagonalWhat is this skill?
- Opinionated synthesis of DDD, Clean Architecture, Hexagonal, Onion—with pointers to when each source applies
- When-to-use table: complex domains and long-lived systems vs skip for simple CRUD/MVP
- Language-agnostic patterns for Go, Rust, Python, TypeScript, Java, C#
- Covers aggregates, value objects, domain events, CQRS, event sourcing, outbox, anti-corruption layer
- Explicit anti-pattern: do not treat this as one canonical architecture model for every question
Adoption & trust: 3.1k installs on skills.sh; 51 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are growing an API or microservice but layers are tangled, domain logic leaks into HTTP handlers, and every new integration breaks tests.
Who is it for?
Indie SaaS or API products with real business rules, multi-year maintenance, or a growing backend where ports/adapters will pay off.
Skip if: Simple CRUD prototypes, throwaway MVPs, or tiny solo scripts where architecture ceremony slows shipping.
When should I use this skill?
Designing APIs, microservices, or scalable backend structure; triggers on DDD, Clean Architecture, Hexagonal, entities, aggregates, repositories, CQRS, event sourcing, outbox, or anti-corruption layer.
What do I get? / Deliverables
You get clear bounded contexts, dependency rules, and adapter boundaries so new features land in the domain core instead of spaghetti infrastructure.
- Layer and bounded-context recommendations
- Port/adapter boundaries for integrations
- Guidance on when CQRS or event sourcing applies
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Backend structure is decided while you Build, even when earlier Validate scoping informed the domain—canonical shelf stays Build/backend. Backend subphase matches microservices, repositories, use cases, and adapter wiring—not frontend or launch SEO work.
Where it fits
Map bounded contexts before committing to microservices so validation work does not freeze the wrong seams.
Introduce use cases and repository interfaces before wiring Postgres and message bus adapters.
Add a payment provider behind a port with an anti-corruption layer instead of leaking vendor types into the domain.
Review a PR for dependency rule violations—domain importing infrastructure—and redirect fixes to adapters.
How it compares
Use as structured design guidance—not a code generator—for backend shape instead of ad-hoc folder splits copied from a tutorial.
Common Questions / FAQ
Who is clean-ddd-hexagonal for?
Solo builders and small teams designing language-agnostic backend services who need DDD and hexagonal discipline without hiring an architect full-time.
When should I use clean-ddd-hexagonal?
During Validate when scoping bounded contexts for a serious build, and during Build/backend when modeling aggregates, repositories, and integration adapters—skip for bare CRUD MVPs.
Is clean-ddd-hexagonal safe to install?
It is documentation-only architecture advice; review the Security Audits panel on this page and apply patterns to your own repo—no automatic code execution.
SKILL.md
READMESKILL.md - Clean Ddd Hexagonal
# Clean Architecture + DDD + Hexagonal Backend architecture combining DDD tactical patterns, Clean Architecture dependency rules, and Hexagonal ports/adapters for maintainable, testable systems. This skill is an **opinionated synthesis** of several related architecture traditions. It is not a single canonical architecture model. Use the original source that matches the design question you are answering: DDD for domain modeling, Hexagonal Architecture for ports/adapters, Clean Architecture for dependency direction, Onion Architecture for domain-centered layering, and CQRS/Event Sourcing only for specific read/write or temporal requirements. ## When to Use (and When NOT to) | Use When | Skip When | |----------|-----------| | Complex business domain with many rules | Simple CRUD, few business rules | | Long-lived system (years of maintenance) | Prototype, MVP, throwaway code | | Team of 5+ developers | Solo developer or small team (1-2) | | Multiple entry points (API, CLI, events) | Single entry point, simple API | | Need to swap infrastructure (DB, broker) | Fixed infrastructure, unlikely to change | | High test coverage required | Quick scripts, internal tools | **Start simple. Evolve complexity only when needed.** Most systems don't need full CQRS or Event Sourcing. ## Pattern Boundaries | Pattern | Primary Question | Use It For | Do Not Treat As | |---------|------------------|------------|-----------------| | **DDD** | How do we model a complex business domain? | Ubiquitous language, bounded contexts, aggregates, value objects | A folder structure by itself | | **Hexagonal Architecture** | How does the application interact with the outside world? | Ports, driver adapters, driven adapters, testable application core | A mandate for six sides or one exact package layout | | **Clean Architecture** | Which direction should dependencies point? | Inward dependency rule, use case boundaries, framework independence | A universal four-folder template | | **Onion Architecture** | How do we keep the domain model central? | Domain-centered layers and dependency inversion | A separate requirement when Clean/Hexagonal already solve the local problem | | **CQRS** | Do reads and writes need different models? | Bounded contexts with divergent read/write workloads | A default application architecture | | **Event Sourcing** | Do we need state from a complete event history? | Audit, temporal queries, replayable workflows | A persistence default for CRUD systems | ## CRITICAL: The Dependency Rule Dependencies point **inward only**. Outer layers depend on inner layers, never the reverse. ``` Infrastructure → Application → Domain (adapters) (use cases) (core) ``` **Violations to catch:** - Domain importing database/HTTP libraries - In this architecture style, controllers calling repositories directly instead of application use cases - Entities depending on application services **Design validation:** "Create your application to work without either a UI or a database" — Alistair Cockburn. If you can run your domain logic from tests with no infrastructure, your boundaries are correct. ## Quick Decision Trees ### "Where does this code go?" ``` Where does it go? ├─ Pure business logic, no I/O → domain/ ├─ Orchestrates domain + has side effects → application/ ├─ Talks to external systems → infrastructure/ ├─ Defines HOW to interact (inte