Skills / Software-engineering

Clean Architecture

A good architecture maximizes the number of decisions NOT made.

Clean Architecture is Robert C. Martin's prescriptive software design methodology built on one ironclad rule: all source-code dependencies must point inward, toward abstract business logic, never outward toward frameworks, databases, or UI. Martin organizes every system into four canonical concentric layers — Entities, Use Cases, Interface Adapters, and Frameworks & Drivers — and reinforces this structure with SOLID principles at the class level and cohesion/coupling principles at the component level. The result is a codebase where business logic can be fully tested without a running database, web server, or framework — and where technical choices become swappable implementation details.

By Robert C. Martin  ·  Free

Use this skill See it in action

Specimen 01 · Live diagnosisClean Architecture

Input

“It's a Node.js order management service for e-commerce. Express route handlers call service files, and the service files import Sequelize ORM models…”

Diagnosis

Let's put your architecture through the Dependency Rule.

Full transcript ↓

Calibrated referenceagent-skills.ai

The gap

Make your business rules the center — frameworks, databases, and UI are just plugins

Clean Architecture structures every software system into four named concentric rings, each with explicit rules about what it may and may not depend on. Entities (innermost) hold enterprise-wide business rules and data structures — they are framework-agnostic and maximally stable. Use Cases hold application-specific orchestration logic that coordinates Entities to fulfill system behaviors. Interface Adapters (controllers, presenters, gateways) translate data between the formats used by Use Cases and the formats required by external tools. Frameworks & Drivers (outermost) contain databases, web frameworks, UI, and all volatile technical details. The Dependency Rule is the single governing constraint: source-code dependencies may only point inward; outer rings know about inner rings, never the reverse. This rule is mechanically enforced by the Dependency Inversion Principle (DIP) — one of the five SOLID principles that govern class-level design (SRP, OCP, LSP, ISP, DIP). At the component level, three cohesion principles (REP, CCP, CRP) define what belongs in a package; three coupling principles (ADP, SDP, SAP) govern stability and abstraction relationships between packages. Supporting heuristics include Screaming Architecture (folder structure should reveal the domain, not the framework), the Humble Object pattern (isolate testable logic from hard-to-test boundary code), and BIE decomposition (Boundary, Interactor, Entity).

The problem

Most codebases accumulate structural debt when business logic becomes entangled with frameworks, ORMs, and HTTP handlers — making core rules impossible to test in isolation, painful to migrate between technology stacks, and fragile when business requirements change. Developers lack a binary decision criterion for architecture choices: 'Is this dependency allowed here?' Clean Architecture gives them exactly that criterion — the Dependency Rule — plus named layers and named principles that make the answer unambiguous.

The solution

Apply the Dependency Rule and Clean Architecture's four-layer model to your system and you will know precisely where every class belongs, which dependencies are violations, and how to restructure your codebase so that business logic is fully tested without infrastructure and frameworks become swappable implementation details.

You bring

A description of your system, service, or module — prose, pseudocode, or class names all work
Import graphs, directory structures, or dependency lists you want analyzed for violations
The feature or business capability you are designing or refactoring
Specific pain points: tight coupling to frameworks, untestable business logic, unclear package boundaries

You get

A Dependency Rule Violation Report: every bad dependency named, layer boundary identified, and fix pattern recommended
A Layer Assignment Map classifying each component into its correct Clean Architecture ring with justification
A Use Case Interactor Interface: typed input-port (request model), output-port (response model), and entity dependencies ready to implement
A sequenced Refactoring Roadmap with each step independently shippable and ordered by lowest risk, highest leverage

In action

Watch the methodology work.

Three specimens from a single real session: the same situation, unaided and calibrated, the full transcript, and the skill answering live in the channel where the work happens.

Fig.01  —  The same situation, two ways

Specimens A · B

Specimen AVague

Unaided

“Your `orderService.js` imports Sequelize models at the top, runs SQL queries mid-function, and calculates discounts in the same method that writes to the database. Every unit test requires an active database connection or 200 lines of Sequelize mocks. A new engineer reads `src/routes/`, `src/services/`, `src/models/` and learns nothing about the business — only that you use Express and Sequelize. Switching to Prisma means touching every service file.”

×Vague — nothing concrete to act on.

Specimen BCalibrated

With Clean Architecture

“Your `DiscountPolicy.js` has no imports except pure domain types — it tests in under 100ms with no mocks and zero database setup. `SequelizeOrderRepository` is the only file that knows Sequelize exists; swapping it for Prisma means writing one new adapter class. Your `src/domain/` folder reads like a business requirements document: Order, InventoryItem, PlaceOrder, CalculateDiscount. The Dependency Rule Violation Report shows zero violations.”

◦Specific, grounded, and ends with one clear next step.

Fig.02  —  A real session, unedited

In-app · assistant

Clean ArchitectureClaude

Clean Architecture

Let's put your architecture through the Dependency Rule. Before I can audit anything, I need to understand the domain — not the technology. What does this system do at its core, what are the central business rules it enforces, and what technology stack are you running? Once I have that, I'll assign components to the four Clean Architecture layers and identify every dependency that's pointing the wrong direction.

It's a Node.js order management service for e-commerce. Express route handlers call service files, and the service files import Sequelize ORM models directly to run queries. Discount calculation and inventory reservation logic lives in those same service files, right next to the database calls. Our test suite requires a running database because of all the Sequelize dependencies.

You have a textbook Dependency Rule violation at the Use Case / Framework boundary — and your test pain is the diagnostic signal. Here's the layer assignment for what you've described:

Entities (innermost ring): Order, InventoryItem, DiscountPolicy — pure business rules, zero Sequelize or Express imports. These are the most stable things in your system.

Use Cases: PlaceOrder, ReserveInventory, CalculateDiscount — application-specific orchestration. Right now these live inside your service files mixed with Sequelize queries, meaning your Use Case layer is reaching outward into Frameworks & Drivers.

Interface Adapters: SequelizeOrderRepository (implements an abstract OrderRepository port), ExpressOrderController (translates HTTP requests into Use Case input models).

Frameworks & Drivers (outermost): Sequelize, Express, your database connection config.

The violation: your service files import Sequelize models directly. That's a Use Case depending on a Framework — an outward-pointing dependency. The Dependency Rule says it must never happen. The fix is Dependency Inversion: define an abstract `OrderRepository` interface in the Use Case layer, implement it with Sequelize in the Interface Adapters layer, and inject the concrete implementation at startup.

That makes sense for the database boundary. But our discount calculation reads promotion rules from the database mid-function. Where does that logic actually belong?

Discount calculation is Entity-level business logic — innermost ring. The promotion rules are data the logic operates on, not the query that fetches them. Here's the Clean Architecture split:

Entity: A `DiscountPolicy` class that takes an `Order` and a list of `PromotionRule` value objects and returns a discounted total. No database imports. Pure, testable domain logic.

Use Case: A `CalculateDiscount` interactor that (a) calls a `PromotionRuleRepository` port to fetch active rules, (b) passes them into `DiscountPolicy.apply()`, and (c) returns the result via an output port.

Interface Adapter: A `SequelizePromotionRuleRepository` that implements the `PromotionRuleRepository` interface using your ORM.

Now you can unit-test `DiscountPolicy` with a hardcoded list of rules — no database, no Express, no Sequelize mocks. If you ever move promotion rules to Redis or a config file, only the Interface Adapter changes. The Entity and Use Case are completely untouched.

This explains exactly why our tests are painful — we're mocking Sequelize everywhere because the logic and the queries are in the same file. Can you check our folder structure too? Right now it's src/routes/, src/services/, src/models/.

Your folder structure screams Express and Sequelize — not e-commerce. That's the Screaming Architecture violation. `routes/`, `services/`, `models/` tells a new engineer nothing about orders, inventory, or promotions; it tells them about your HTTP library and ORM. Martin's heuristic: the top-level directories should reveal the domain.

A Clean Architecture structure for your system:```src/ domain/ entities/ ← Order.js, InventoryItem.js, DiscountPolicy.js usecases/ ← PlaceOrder.js, ReserveInventory.js, CalculateDiscount.js ports/ ← OrderRepository.js, PromotionRuleRepository.js (interfaces only) adapters/ persistence/ ← SequelizeOrderRepository.js, SequelizePromotionRuleRepository.js web/ ← ExpressOrderController.js (HTTP → Use Case input model translation) infrastructure/ database/ ← Sequelize config, migrations, ORM model definitions server/ ← Express app setup, route wiring, DI composition root```

Now `src/domain/` has zero imports from `adapters/` or `infrastructure/` — the Dependency Rule is enforced by directory convention. The folder screams 'Order Management System.' Want me to generate the TypeScript interface definitions for `OrderRepository` and the `PlaceOrder` interactor next, or should we tackle the full Dependency Rule Violation Report first?

Let's do the violation report — I want to see the full scope before we start refactoring.

Here's your Dependency Rule Violation Report based on what you've described:

VIOLATION 1 — Use Case → Framework (Severity: Critical)File: `src/services/orderService.js`Violating import: `const { Order } = require('../models/Order')` (Sequelize model)Boundary crossed: Use Case layer importing from Frameworks & Drivers ringFix: Define abstract `OrderRepository` port in `src/domain/ports/`. Inject `SequelizeOrderRepository` at startup.

VIOLATION 2 — Use Case → Framework (Severity: Critical)File: `src/services/discountService.js`Violating import: Direct Sequelize query inside `calculateDiscount()`Boundary crossed: Entity-level logic mixed with persistence in the Use Case layerFix: Extract `DiscountPolicy` entity. Define `PromotionRuleRepository` port. Move query to `SequelizePromotionRuleRepository`.

VIOLATION 3 — Screaming Architecture (Severity: Moderate)Structure: `src/routes/`, `src/services/`, `src/models/`Violation: Top-level structure reveals framework (Express/Sequelize), not domain (Orders/Inventory/Payments)Fix: Restructure to `src/domain/`, `src/adapters/`, `src/infrastructure/` as outlined above.

Estimated refactoring scope: 2–3 sprints. Recommend starting with `DiscountPolicy` extraction (zero-dependency, immediate test wins) before tackling the `OrderRepository` port inversion. Each step is independently deployable.

Reply to Clean Architecture…

What the skill is doing

01Dependency Rule Auditor

02Layer Assignment Classifier

03Use Case Interactor Designer

Fig.03  —  The same skill, in the channel you already use

WhatsApp · live

9:41

CAClean Architecturetyping…

Messages are end-to-end encrypted. No one outside of this chat can read them.

Today

It's a Node.js order management service for e-commerce. Express route handlers call service files, and the service files import Sequelize ORM models d…9:14✓✓

Let's put your architecture through the Dependency Rule.9:14

Before I can audit anything, I need to understand the domain — not the technology.9:15

What does this system do at its core, what are the central business rules it enforces, and what technology stack are you running?9:15

Message

The same skill, where the work happens.

No new app to learn. The methodology runs over the WhatsApp Business API, so the answer lands as a reply in the thread you’re already in — same rigour, zero context-switch.

◦Reads the situation, names the pattern, returns one concrete next move.

◦Delivered in seconds, inside a conversation that already exists.

Specimen · WhatsApp Business API · live

Capabilities

What it does, specifically.

Each capability is a distinct move drawn straight from the source methodology — not a generic assistant guessing.

CapabilityC-01

Dependency Rule Auditor

Analyzes import graphs, module relationships, or described dependency chains and flags every dependency that crosses a layer boundary in the wrong direction. Each violation is explained — which layer is importing which, why it violates the rule — and paired with a recommended fix pattern: Port interface, Adapter class, or Dependency Inversion.

◦ MethodBased on Martin's Dependency Rule: 'Source code dependencies must point only inward, toward higher-level policies' — the single binary criterion that governs every architectural decision in Clean Architecture.

CapabilityC-02

Layer Assignment Classifier

Given any class, module, or service description, identifies which of the four concentric rings it belongs to — Entities, Use Cases, Interface Adapters, or Frameworks & Drivers — and explains the reasoning with reference to the component's responsibilities, volatility, and permissible dependencies.

◦ MethodBased on Martin's four canonical layers: Entities hold enterprise-wide business rules; Use Cases hold application-specific orchestration; Interface Adapters translate between layer formats; Frameworks & Drivers are the outermost, most volatile details.

CapabilityC-03

Use Case Interactor Designer

Defines the complete interface for a Use Case Interactor: the input port (request model), output port (response model or presenter interface), and the Entity and Gateway dependencies the interactor requires. Produces typed interface definitions in the user's language of choice, ready to implement.

◦ MethodBased on Martin's Boundary/Interactor/Entity (BIE) decomposition: the Use Case layer owns abstract port interfaces; Interface Adapters implement them; Entities are called by the Interactor with no outward dependencies.

CapabilityC-04

SOLID Principle Reviewer

Evaluates a class design, method signature, or module structure against each of the five SOLID principles, flagging violations with specific code-level evidence and recommending targeted refactors. Particular attention is paid to the Dependency Inversion Principle as the mechanical enforcement of the Dependency Rule.

◦ MethodBased on Martin's formulation of SOLID as the class-level complement to Clean Architecture's layer rules: SRP (one reason to change), OCP (open for extension, closed for modification), LSP (substitutability), ISP (no unused interface dependencies), DIP (depend on abstractions — the bridge between SOLID and the Dependency Rule).

CapabilityC-05

Screaming Architecture Auditor

Assesses a project's directory structure or module naming to determine whether it reveals the domain — Orders, Inventory, Payments — or instead reveals the framework — Controllers, Models, Routes. Produces a restructuring recommendation that surfaces domain intent at the top level.

◦ MethodBased on Martin's Screaming Architecture heuristic: 'Your architecture should tell readers about the system, not about the frameworks you used in your system. If you are building a health care system, new programmers should see health care, not Spring or Hibernate.'

CapabilityC-06

Refactoring Roadmap Builder

Given a legacy or tightly coupled codebase description, produces a sequenced, incremental plan to migrate toward Clean Architecture boundaries — starting with the lowest-risk, highest-leverage extractions and progressing to full layer separation without requiring a rewrite.

◦ MethodBased on Martin's migration guidance: identify Dependency Rule violations first, introduce Port interfaces at existing seams, extract Entities as pure domain objects, then pull Use Cases out of service layers before finally isolating Infrastructure in the outermost ring.

Tested

Graded before it shipped.

Every skill is scored against independent scenarios for methodology fidelity before it goes live — not vibes, a rubric.

What it produces

OutputD-01

Dependency Rule Violation Report

A structured list of every detected boundary violation, organized by layer pair (e.g., Use Case → Framework, Entity → Interface Adapter). Each entry names the violating class, identifies the bad dependency, explains which rule it breaks, and recommends a concrete fix: Port interface, Adapter extraction, or constructor injection.

OutputD-02

Clean Architecture Layer Map

A classified inventory of your system's components organized into the four concentric rings, making visible which classes are stable Entities, which are Use Case orchestrators, which are translating Interface Adapters, and which are volatile infrastructure details. Serves as the canonical reference for architecture reviews and team onboarding.

OutputD-03

Use Case Interactor Interface

A fully specified interface definition for a Use Case — input port (request model), output port (response model or presenter interface), Entity dependencies, gateway interfaces, and exception types — ready to be implemented in your language of choice with zero framework imports.

OutputD-04

Refactoring Roadmap

A prioritized, step-by-step migration plan for moving a coupled codebase toward Clean Architecture, with each step scoped to be independently releasable. Includes the Dependency Rule justification for each move, which tests to write before each extraction, and which violations it eliminates.

The source

Grounded in the original work.

Every answer traces back to a real source and the practitioner who wrote it — not a secondhand summary. Here is the source of record.

Source authorA-01

Robert C. Martin

Robert C. Martin (known universally as 'Uncle Bob') co-signed the Agile Manifesto in 2001, authored Clean Code (2008) and Clean Architecture (Prentice Hall, 2017) — two of the most widely read books in professional software engineering — and founded Clean Coders LLC. With over 50 years of software development experience spanning embedded systems, enterprise platforms, and distributed architectures, he developed the SOLID principles, introduced the concept of Screaming Architecture, and produced the Clean Coders video series: 30+ hours of methodology instruction with worked examples across multiple technology stacks.

Status · Inspired by Robert C. Martin’s work — not yet claimed. Are you Robert C. Martin?

Primary sourceS-01

Clean Architecture: A Craftsman's Guide to Software Structure and Design

by Robert C. Martin

Co-signer of the Agile Manifesto (2001); author of Clean Code and Clean Architecture (Prentice Hall); originator of SOLID principles; keynote speaker at NDC, GOTO, and YOW conferences; founder of Clean Coders LLC.

Read the original ↗

Citationcleancoder.com

In the build queue

Be first to run it.

Clean Architecture is being built right now. Leave your email and we’ll tell you the moment it goes live.

Notify meEmail

At launchMy service layer imports the ORM directly and business logic lives next to database queries — I'm pretty sure this violates the Dependency Rule. Can you run a layer assignment on my architecture, identify every violation, and build me a refactoring roadmap to clean it up?