Compatible with Cursor, Claude Code, Cline, Roo Code, Antigravity

Layered Monolith to Hexagonal / Clean Architecture Refactor

Refactor tangled MVC controllers and service layers into Clean Architecture (Ports & Adapters).

Clean ArchitectureHexagonalDDDRefactoringBackend

v1.0.0 · Updated 2026-08

Skill Objective

Isolate core domain entities and business rules from web frameworks and database drivers using Clean Architecture (Ports & Adapters).

Execution Workflow Procedure

Ordered steps the coding agent executes when performing this skill.

Extract Pure Domain Entities

Create pure domain entities containing business logic with zero framework, web, or ORM annotations.

Define Inbound & Outbound Ports

Declare use case interfaces (Inbound Ports) and repository/gateway interfaces (Outbound Ports).

Implement Infrastructure Adapters

Implement REST controllers and JPA/SQL repositories as adapters implementing port interfaces.

Agent Safety Guardrails & Anti-Hallucination Rules

DO NOT allow domain models to depend on ORM or web controller classes.
DO NOT put business logic inside controllers or database repositories.

Expected Output Format

Domain entities, use cases, ports, and adapters.

💎 Pure Domain Layer: Entities and business rule validation.

🔌 Ports & Adapters: Use cases, repository interfaces, and REST adapters.

Domain Verification Checks

Dependency Inversion: Domain logic depends only on interfaces, never on infrastructure.

Pure Domain Model: Entities are free of framework annotations.

Testability: 100% of domain use cases are testable without spinning up web/DB servers.

Example Agent Invocations

"Refactor this tightly coupled OrderService mixing HTTP headers, direct SQL, and business logic into Clean Architecture."

"Restructure this NestJS module into hexagonal domain, application, and infrastructure layers."

Install / Configure This Skill

# Place in .cursorrules or create .cursor/rules/hexagonal-clean-architecture-refactor.mdc
# Trigger: Whenever you perform layered monolith to hexagonal / clean architecture refactor

---
name: hexagonal-clean-architecture-refactor
description: Decouple domain logic from web frameworks and databases using Ports & Adapters (Hexagonal Architecture).
version: 1.0.0
compatibility: [Cursor, Claude Code, Cline, Roo Code, Antigravity]
---

# Layered Monolith to Hexagonal / Clean Architecture Refactor

## Objective
Decouple business domain logic from databases and frameworks using Clean Architecture and Ports & Adapters.

## Workflow
1. **Pure Domain**: Extract domain entities containing business rules with zero framework dependencies.
2. **Ports Definition**: Declare Inbound (Use Case) and Outbound (Repository/Client) interfaces.
3. **Adapters Implementation**: Implement REST controllers and persistence repositories as interchangeable adapters.

Complementary Agent Prompt

Need a quick one-time prompt for chat?

Try the Monolith to Clean / Hexagonal Architecture Refactor — a lightweight version designed for 1-click copying directly into Claude, ChatGPT, or Cursor chat.

View Prompt