clean-ddd-hexagonal

ccheney/robust-skills

Design backend domain boundaries using DDD, Clean Architecture, and hexagonal ports/adapters.

What is clean-ddd-hexagonal?

A reference skill for architecting or reviewing backend systems using Domain-Driven Design, Clean Architecture, and hexagonal (ports/adapters) patterns. Use it to model aggregates, define bounded contexts, isolate use cases, or refactor dependencies—not for routine CRUD operations.

Model business domain language and consistency rules using DDD bounded contexts and aggregates
Establish unidirectional dependency flow from outer layers (HTTP, persistence, messaging) toward domain core
Define ports (interfaces) and adapters to swap infrastructure implementations without changing domain logic
Decide between CQRS, Event Sourcing, and outbox patterns when reads/writes or cross-aggregate atomicity require special handling
Validate transactional boundaries and invariants within aggregates and across bounded contexts

How to install clean-ddd-hexagonal

npx skills add https://github.com/ccheney/robust-skills --skill clean-ddd-hexagonal

Claude Code

Cursor

Windsurf

Cline

How to use clean-ddd-hexagonal

1.Identify the concrete domain or dependency problem you need to solve
2.Review the relevant reference guide (LAYERS.md for layering, DDD-STRATEGIC.md for contexts, DDD-TACTICAL.md for entities/aggregates, HEXAGONAL.md for ports, CQRS-EVENTS.md for event patterns, TESTING.md for validation)
3.Apply the pattern to your existing codebase, preserving language and architecture unless change is part of the task
4.Document the boundaries, tradeoffs, and invariants affected by your design decision
5.Validate changed contracts and invariants at the appropriate test level

Use cases

Good for

Refactoring a monolith to separate domain concerns into bounded contexts with clear contracts
Designing an aggregate model when business rules require specific transactional boundaries and entity relationships
Reviewing dependency direction in a layered codebase to ensure domain logic remains independent of HTTP and persistence details
Choosing between eventual consistency and cross-aggregate transactions by making tradeoffs explicit
Introducing ports and adapters to allow multiple implementations (e.g., REST, gRPC, or event-driven interfaces)

Who it's for

Backend architects designing or reviewing system structure
Domain-driven development teams modeling complex business logic
Teams refactoring toward cleaner dependency boundaries
Engineers deciding between architectural patterns (CQRS, Event Sourcing, repository interfaces)

clean-ddd-hexagonal FAQ

When should I use DDD and Clean Architecture vs. keeping things simple?

Use these patterns when you have a non-trivial business domain with multiple consistency rules, entity relationships, or infrastructure choices. Simple CRUD can remain simple; team size and file count do not determine necessity.

Do I have to follow the folder layout shown in the references?

No. The skill is an opinionated synthesis, not a mandatory structure. Your explicit instructions and project conventions take precedence; adapt naming and directories as needed.

What if I don't know all the business invariants yet?

Identify the specific missing rule and continue work that does not depend on it. Do not invent business behavior or require a discovery workshop for a local fix.

When should I use CQRS or Event Sourcing?

Treat CQRS, Event Sourcing, and repository interfaces as choices justified by the task. Use them when reads and writes need different models, or when state must be reconstructed from event history—not by default.

How do I handle changes that span multiple aggregates?

Prefer transactions within a single aggregate. When cross-aggregate atomicity is required, make that tradeoff explicit and consider an outbox pattern to ensure reliable database changes and external event delivery together.

Full instructions (SKILL.md)

Source of truth, from ccheney/robust-skills.

name: clean-ddd-hexagonal description: Design or review backend domain and dependency boundaries using DDD, Clean Architecture, and ports/adapters. Use for aggregate modeling, bounded contexts, use-case isolation, or architecture refactoring; not routine CRUD changes.

Clean Architecture, DDD, and Hexagonal Architecture

Use these related patterns to solve a concrete domain or dependency problem. This is an opinionated synthesis, not a mandatory folder layout. The user's explicit instructions take precedence over this skill's guidelines.

Choose the scope

Start from the requested behavior, existing domain model, and current dependencies. Preserve the project's language and architecture unless changing them is part of the task. Simple CRUD can remain simple; team size, entity count, and file length do not determine whether DDD is appropriate.

Design question	Relevant pattern
What language and consistency rules describe the business?	DDD, bounded contexts, aggregates
Which way should source dependencies point?	Clean/Onion Architecture
How can the application use different interfaces or infrastructure?	Hexagonal ports and adapters
Do reads and writes need different models?	CQRS
Must state be reconstructed from an event history?	Event Sourcing

If a business invariant is unknown, identify the specific missing rule and continue work that does not depend on it. Do not invent business behavior or require a discovery workshop for a local fix.

Preserve the boundaries that matter

Keep domain behavior independent of HTTP, persistence, and messaging implementations. Put orchestration in application use cases and external I/O in adapters.
Model entity identity separately from value-object equality. Choose aggregate boundaries from transactional invariants and contention.
Prefer transactions contained within an aggregate. When a requirement needs cross-aggregate atomicity, make that tradeoff explicit rather than silently replacing it with eventual consistency.
Use an outbox when a committed database change and external event delivery must be reliable together.
Treat CQRS, Event Sourcing, repository interfaces, and separate presentation folders as choices justified by the task. Adapt example naming and directories to the project.

Deliver the requested model, patch, or review with affected boundaries and the tradeoffs that explain them. Validate changed invariants and adapter contracts at the appropriate level; an architecture question does not require implementing every pattern.

References

Load the reference for the decision being made, not the whole collection.

Task	Reference
Layer placement, dependency direction, composition root	LAYERS.md
Bounded contexts, ubiquitous language, context mapping	DDD-STRATEGIC.md
Entities, value objects, aggregates, repositories	DDD-TACTICAL.md
Ports, driver/driven adapters, alternative layouts	HEXAGONAL.md
CQRS, events, outbox, sagas, Event Sourcing	CQRS-EVENTS.md
Domain, integration, or architecture test design	TESTING.md
Compact pattern and placement lookup	CHEATSHEET.md