Agent skill

clean-ddd-hexagonal

Proactively apply when designing APIs, microservices, or scalable backend structure. Triggers on DDD, Clean Architecture, Hexagonal, ports and adapters, entities, value objects, domain events, CQRS, event sourcing, repository pattern, use cases, onion architecture, outbox pattern, aggregate root, anti-corruption layer. Use when working with domain models, aggregates, repositories, or bounded contexts. Clean Architecture + DDD + Hexagonal patterns for backend services, language-agnostic (Go, Rust, Python, TypeScript, Java, C#).

View SKILL.md on GitHub Repository
Stars 33
Forks 0

Install this agent skill to your Project

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

SKILL.md

Clean Architecture + DDD + Hexagonal

Backend architecture combining DDD tactical patterns, Clean Architecture dependency rules, and Hexagonal ports/adapters for maintainable, testable systems.

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.

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
  • Controllers calling repositories directly (bypassing 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 (interface)    → port (domain or application)
└─ Implements a port                      → adapter (infrastructure)

"Is this an Entity or Value Object?"

Entity or Value Object?
├─ Has unique identity that persists → Entity
├─ Defined only by its attributes    → Value Object
├─ "Is this THE same thing?"         → Entity (identity comparison)
└─ "Does this have the same value?"  → Value Object (structural equality)

"Should this be its own Aggregate?"

Aggregate boundaries?
├─ Must be consistent together in a transaction → Same aggregate
├─ Can be eventually consistent                 → Separate aggregates
├─ Referenced by ID only                        → Separate aggregates
└─ >10 entities in aggregate                    → Split it

Rule: One aggregate per transaction. Cross-aggregate consistency via domain events (eventual consistency).

Directory Structure

src/
├── domain/                    # Core business logic (NO external dependencies)
│   ├── {aggregate}/
│   │   ├── entity              # Aggregate root + child entities
│   │   ├── value_objects       # Immutable value types
│   │   ├── events              # Domain events
│   │   ├── repository          # Repository interface (DRIVEN PORT)
│   │   └── services            # Domain services (stateless logic)
│   └── shared/
│       └── errors              # Domain errors
├── application/               # Use cases / Application services
│   ├── {use-case}/
│   │   ├── command             # Command/Query DTOs
│   │   ├── handler             # Use case implementation
│   │   └── port                # Driver port interface
│   └── shared/
│       └── unit_of_work        # Transaction abstraction
├── infrastructure/            # Adapters (external concerns)
│   ├── persistence/           # Database adapters
│   ├── messaging/             # Message broker adapters
│   ├── http/                  # REST/GraphQL adapters (DRIVER)
│   └── config/
│       └── di                  # Dependency injection / composition root
└── main                        # Bootstrap / entry point

DDD Building Blocks

Pattern Purpose Layer Key Rule
Entity Identity + behavior Domain Equality by ID
Value Object Immutable data Domain Equality by value, no setters
Aggregate Consistency boundary Domain Only root is referenced externally
Domain Event Record of change Domain Past tense naming (OrderPlaced)
Repository Persistence abstraction Domain (port) Per aggregate, not per table
Domain Service Stateless logic Domain When logic doesn't fit an entity
Application Service Orchestration Application Coordinates domain + infra

Anti-Patterns (CRITICAL)

Anti-Pattern Problem Fix
Anemic Domain Model Entities are data bags, logic in services Move behavior INTO entities
Repository per Entity Breaks aggregate boundaries One repository per AGGREGATE
Leaking Infrastructure Domain imports DB/HTTP libs Domain has ZERO external deps
God Aggregate Too many entities, slow transactions Split into smaller aggregates
Skipping Ports Controllers → Repositories directly Always go through application layer
CRUD Thinking Modeling data, not behavior Model business operations
Premature CQRS Adding complexity before needed Start with simple read/write, evolve
Cross-Aggregate TX Multiple aggregates in one transaction Use domain events for consistency

Implementation Order

  1. Discover the Domain — Event Storming, conversations with domain experts
  2. Model the Domain — Entities, value objects, aggregates (no infra)
  3. Define Ports — Repository interfaces, external service interfaces
  4. Implement Use Cases — Application services coordinating domain
  5. Add Adapters last — HTTP, database, messaging implementations

DDD is collaborative. Modeling sessions with domain experts are as important as the code patterns.

Reference Documentation

File Purpose
references/LAYERS.md Complete layer specifications
references/DDD-STRATEGIC.md Bounded contexts, context mapping
references/DDD-TACTICAL.md Entities, value objects, aggregates (pseudocode)
references/HEXAGONAL.md Ports, adapters, naming
references/CQRS-EVENTS.md Command/query separation, events
references/TESTING.md Unit, integration, architecture tests
references/CHEATSHEET.md Quick decision guide

Sources

Primary Sources

Pattern References

Implementation Guides

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

ccheney/robust-skills

slack-mrkdwn

Proactively apply when generating any Slack text content, chat.postMessage text fields, or text objects with type "mrkdwn". Triggers on mrkdwn, Slack formatting, Slack markdown, Slack bold, Slack italic, Slack link syntax, Slack mentions, Slack date formatting, Slack escaping, Slack text object, verbatim, plain_text, Slack mrkdwn vs markdown, Slack blockquote, Slack code block, Slack strikethrough, Slack user mention, Slack channel mention, Slack emoji, link_names, auto-parsing. Use when formatting Slack message text, writing mrkdwn strings, constructing text objects, escaping user content for Slack, adding mentions or date formatting to messages, or debugging text rendering issues. Slack mrkdwn text formatting syntax for messages, text objects, and attachments.

33 0
Explore
ccheney/robust-skills

feature-slicing

Proactively apply when creating new features/components/pages or setting up frontend project structure. Triggers on FSD, feature slicing, frontend architecture, layer structure, module boundaries, scalable frontend, slice organization. Use when restructuring React/Next.js/Vue/Remix projects, organizing frontend code, fixing import violations, or migrating legacy codebases. Feature-Sliced Design (FSD) architecture for frontend projects.

33 0
Explore
ccheney/robust-skills

slack-block-kit

Proactively apply when generating Slack API payloads with blocks, chat.postMessage calls with structured content, or views.open/views.publish calls. Triggers on Block Kit, Slack blocks, section block, actions block, header block, divider block, context block, table block, markdown block, rich text block, image block, input block, video block, context_actions block, plan block, task_card block, Slack modal, Slack App Home, Slack surfaces, Slack interactive elements, Slack button, Slack select menu, Slack overflow, Slack datepicker, Slack checkboxes, Slack radio buttons, Work Objects, Slack link unfurl, chat.postMessage blocks, views.open, views.update, views.push, views.publish, Slack composition objects. Use when building Block Kit payloads, constructing blocks arrays, creating modals or App Home views, adding interactive elements, implementing link unfurling with Work Objects, or designing rich message layouts. Slack Block Kit UI framework for building rich message layouts, modals, and App Home views.

33 0
Explore
ccheney/robust-skills

postgres-drizzle

Proactively apply when creating APIs, backends, or data models. Triggers on PostgreSQL, Postgres, Drizzle, database, schema, tables, columns, indexes, queries, migrations, ORM, relations, joins, transactions, SQL, drizzle-kit, connection pooling, N+1, JSONB, RLS. Use when writing database schemas, queries, migrations, or any database-related code. PostgreSQL and Drizzle ORM best practices.

33 0
Explore
ccheney/robust-skills

mermaid-diagrams

Proactively suggest diagrams when explaining complex systems. Triggers on diagrams, charts, visualizations, flowcharts, sequence diagrams, architecture diagrams, ER diagrams, state machines, Gantt charts, mindmaps, C4, class diagrams, git graphs. Use when user asks for visual representations of code, systems, processes, data structures, database schemas, workflows, or API flows. Generate Mermaid diagrams in markdown.

33 0
Explore
ccheney/robust-skills

modern-css

Proactively apply when creating design systems, component libraries, or any frontend application. Triggers on CSS Grid, Subgrid, Flexbox, Container Queries, :has(), @layer, @scope, CSS nesting, @property, @function, if(), oklch, color-mix, light-dark, relative color, @starting-style, scroll-driven animations, view transitions, anchor positioning, popover, customizable select, content-visibility, logical properties, text-wrap, interpolate-size, clamp, field-sizing, modern CSS, CSS architecture, responsive design, dark mode, theming, design tokens, cascade layers. Use when writing CSS for any web project, choosing layout approaches, building responsive components, implementing dark mode or theming, creating animations or transitions, styling form elements, or modernizing legacy stylesheets. Modern CSS features and best practices for building interfaces with pure native CSS.

33 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results