principle-clean-architecture

Guide clean architecture and hexagonal design with inward dependencies.

2|8|Updated Apr 20, 2026

Search Tags:#hexagonal architecture #clean architecture #ports and adapters #dependency rule #layering #domain purity

Ready to run

npx skills add https://github.com/lugassawan/swe-workbench --skill principle-clean-architecture

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: principle-clean-architecture
Source: https://github.com/lugassawan/swe-workbench/tree/main/skills/principle-clean-architecture
Command: npx skills add https://github.com/lugassawan/swe-workbench --skill principle-clean-architecture

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill helps you prevent architectural erosion by enforcing clean boundaries so business logic stays independent of frameworks, databases, and other external concerns.

Core Features & Use Cases

Dependency Rule Enforcement: Keeps source-code dependencies pointing inward so inner layers remain framework-agnostic.
Ports & Adapters (Hexagonal Architecture): Separates interfaces (ports) from implementations (adapters) to make the domain testable and swappable.
Domain Purity & Boundary Crossing Guidance: Ensures the domain does not import HTTP/SQL/ORM/JSON/wall-clock concerns, with outer layers translating across well-defined structures.
Practical Refactoring Checklist: Detects drift smells like repositories returning ORM objects or use cases importing request/response types.

Quick Start

Ask the assistant to apply the dependency rule and propose a layer breakdown (domain/application/infrastructure/framework) for your service while identifying which components must become ports and adapters.

Frequently Asked Questions about principle-clean-architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I enforce the dependency rule in clean architecture to keep my domain pure?▼

To enforce the dependency rule in clean architecture, define ports in the domain layer and implement adapters in outer layers. This keeps source-code dependencies pointing inward so inner layers remain framework-agnostic and business logic stays independent.

What is hexagonal architecture and how do ports and adapters work?▼

Hexagonal architecture, or ports and adapters, separates interfaces (ports) from implementations (adapters) to make the domain testable and swappable. Outer layers translate across well-defined structures, ensuring the domain remains independent of infrastructure.

How do I prevent ORM and framework types from crossing domain boundaries?▼

Prevent ORM and framework types from crossing boundaries by using translation structures to keep the domain pure. Ensure repositories do not return ORM objects and use cases do not import request/response types, detecting these drift smells during refactoring.

How do I decompose layers for a service using clean architecture?▼

Decompose layers by proposing a breakdown into domain, application, infrastructure, and framework layers. Identify which components must become ports and adapters, ensuring dependencies flow inward and business logic stays independent of databases and external concerns.

When should I use clean architecture for my software design?▼

Use clean architecture when planning architecture, decomposing layers, or refactoring use cases and repositories. It prevents architectural erosion by enforcing clean boundaries, making it ideal for systems requiring domain independence from frameworks, databases, and UI boundaries.

What are common drift smells when refactoring to clean architecture?▼

Common drift smells in clean architecture refactoring include repositories returning ORM objects and use cases importing HTTP request or response types. These violations indicate framework concerns are crossing boundaries, requiring translation structures to restore domain purity.