# Clean Architecture > Apply Robert C. Martin's Clean Architecture, SOLID, and component-decoupling principles when designing, reviewing, or refactoring code — scaled correctly to the size of the task so trivial changes don't get over-engineered. Use this whenever the user asks to design a new feature/service, review code for architectural soundness, refactor toward better layering/testability, decide where a piece of logic belongs (domain vs. use case vs. controller vs. infrastructure), untangle a legacy/brownfield codebase, or explicitly mentions "clean architecture", "hexagonal architecture", "ports and adapters", "onion architecture", "SOLID principles", "dependency inversion", or "separation of concerns". Also trigger when the user is unsure whether a design decision belongs in one layer or another, or asks "is this a violation of X principle". - Skill: `omaromar9091/clean-architecture` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add omaromar9091/clean-architecture` - Raw SKILL.md: https://api.skillmd.com/api/skills/omaromar9091/clean-architecture/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: omaromar9091 (https://skillmd.com/u/omaromar9091) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/omaromar9091/clean-architecture --- # Clean Architecture Engine A practical, calibrated skill for applying Clean Architecture — scaled to task size, grounded in real code, honest about framework compromises, and explicit about error handling, cross-cutting concerns, legacy code, and when *not* to apply any of this. **Read `references/` files as needed — don't load all of them up front.** Each is pointed to below with a note on when it's relevant. --- ## 0. Classify the task first (always do this before anything else) | Task Size | Example | What to apply | |---|---|---| | **Tier 0 — Trivial** | Typo, log message, constant change, off-by-one fix | Just fix it. No layers, no ceremony. | | **Tier 1 — Small change** | Add a field to an existing DTO, new endpoint reusing an existing Use Case, bug fix inside one layer | Respect existing boundaries. No new layers/folders, no 5-step workflow. | | **Tier 2 — New feature/module** | New CRUD feature, new integration, new workflow | Full layer separation (Section 2) + workflow (Section 5), scaled file granularity — see `references/file-granularity.md`. | | **Tier 3 — New system/service** | Greenfield service, major subsystem, long-lived architectural decision | Everything: full layering, SOLID review, verification table (`references/verification.md`), trade-off discussion. | **Before applying anything else, also check Section 6 ("When NOT to apply this")** — a one-off script, a throwaway prototype, or a single-maintainer tool with no growth plan may not need any of this. Say so plainly if that's the case; don't silently over-architect. If unsure which tier applies, default one tier lower than your first instinct and let the person ask for more rigor. **The failure mode this exists to prevent:** Tier 3 ceremony on a Tier 0 fix. A process that makes small changes expensive violates Clean Architecture's own stated goal — minimizing the cost of change over time. --- ## 1. Core philosophy * **Primary objective:** minimize the human cost of building and maintaining the system over time — not maximize adherence to a diagram. * **Primary value:** architecture over behavior. Behavior changes easily if the architecture stays flexible ("soft"). * **Deferral of details:** high-level policy (business rules) must not depend on low-level detail (frameworks, databases, web servers, UI, message brokers). * **Pragmatism over purity:** every rule below has documented exceptions (`references/framework-exceptions.md`). A rule with no acknowledged exceptions usually hasn't met a real framework yet. --- ## 2. The four layers ``` +-----------------------------------------------------------------------+ | 4. Frameworks & Drivers Layer (Web, DB, UI, External APIs, Devices) | | +---------------------------------------------------------------+ | | | 3. Interface Adapters Layer (Controllers, Gateways, Mappers) | | | | +-------------------------------------------------------+ | | | | | 2. Application Business Rules (Use Cases & Ports) | | | | | | +-----------------------------------------------+ | | | | | | | 1. Enterprise Business Rules (Entities) | | | | | | | +-----------------------------------------------+ | | | | | +-------------------------------------------------------+ | | | +---------------------------------------------------------------+ | +-----------------------------------------------------------------------+ ``` ### ⭕ The Dependency Rule > **Source code dependencies must point ONLY inward.** Nothing in an inner circle may know anything about an outer circle — no classes, functions, variables, data formats, or framework imports. **Layer 1 — Entities:** core business concepts, invariants that hold regardless of which application uses them. No framework imports, no DB/HTTP dependencies, no references to outer layers. **Layer 2 — Use Cases:** orchestrates data flow to/from Entities for an application-specific goal. Interactors, input/output ports (interfaces), request/response DTOs. No ORM/DB framework references, no web/HTTP objects (`req`, `res`, `HttpContext`), no concrete outer-layer implementations. **Layer 3 — Interface Adapters:** translates between Use Case/Entity shapes and external agency shapes. Controllers, presenters, view models, repository implementations, mappers. **Layer 4 — Frameworks & Drivers:** the glue — routing, ORM config, DB drivers, UI libraries. Kept at the outer edge; frameworks are details, not the architecture. **For full multi-language code examples (TypeScript, C#, Python) of every layer, plus a before/after fix of the "Smart Controller" anti-pattern → read `references/code-examples.md`.** --- ## 3. SOLID & component principles 1. **SRP** — one module answers to one actor/stakeholder. 2. **OCP** — extend via interfaces/polymorphism; don't edit core code for new behavior. 3. **LSP** — subtypes substitutable for base types; throwing `NotImplementedException` in an override is a violation. 4. **ISP** — small, focused interfaces over large monolithic ones. 5. **DIP** — high-level modules depend on abstractions, not low-level modules. **Component coupling:** ADP (no dependency cycles), SDP (depend toward stability), SAP (abstractness matches stability). --- ## 4. Prohibitions — flag and reject 1. ❌ **Boundary leak** — e.g. `UseCase` importing `SqlUserRepository` instead of `IUserRepository`. 2. ❌ **Leaky ORM entities** used as domain models. 3. ❌ **Smart controllers / fat views** — business logic in a controller or UI event handler. 4. ❌ **HTTP context pollution** — `req`/`res`/`HttpContext` passed into Use Cases or Entities. 5. ❌ **Primitive obsession across boundaries** — raw JSON/strings instead of typed DTOs/Value Objects. 6. ❌ **Circular dependencies.** --- ## 5. Execution workflow (Tier 2/3 only) 1. Define Entities & Value Objects (Layer 1). 2. Define Application Ports & DTOs (Layer 2). 3. Implement Use Case Interactors (Layer 2), relying only on Layer 1/2 abstractions. 4. Implement Interface Adapters & Infrastructure (Layers 3 & 4). 5. Wire dependencies at the Composition Root. Tier 1: skip straight to the layer the change belongs in — don't re-run all five steps for a one-field addition. **Directory structure should announce what the system does, not its framework** (Screaming Architecture) — e.g. `src/Ordering/{Domain,Application,Infrastructure,Presentation}/`, not `src/{Models,Views,Controllers,Services}/`. Never restructure an existing module's folders for a Tier 0/1 fix. --- ## 6. When NOT to apply this skill Clean Architecture has a real cost: more files, more indirection, more upfront design. Skip most/all of it for: - One-off scripts, data migrations run once, throwaway prototypes. - A true MVP/spike explicitly built to validate an idea before a scale-or-rewrite decision. - Small internal tools with a single maintainer, low change frequency, no growth plan. If a person asks to "apply Clean Architecture" to something in these categories, say plainly that the overhead likely isn't worth it, offer a lighter-weight alternative (a single well-organized module, clear function boundaries, no ports/DI), and let them decide. --- ## 7. Legacy code, conflicts, and topics needing more depth Several situations need more than this file's core rules — **read the relevant reference before acting**: - **Working inside an existing legacy/brownfield codebase**, or a codebase whose existing style directly contradicts Clean Architecture → `references/legacy-and-conflicts.md` (Strangler Fig pattern, "clean island" approach, anti-scope-creep rules). - **Error handling across layers** (exceptions vs. Result/Either types, where transport-specific errors get translated) → `references/error-handling.md`. - **Cross-cutting concerns** — transactions/Unit of Work, logging, caching, authorization — where do they belong? → `references/cross-cutting-concerns.md`. - **Domain Events / async workflows** (e.g. "when an order is submitted, notify a different part of the system") → `references/domain-events.md`. - **Evolving a Port's interface without breaking every implementer** → `references/port-versioning.md`. - **Avoiding duplicated validation logic across multiple Use Cases** → `references/shared-validation.md`. - **How many files a small feature actually needs** (don't over-fragment a 15-line feature into 6 files) → `references/file-granularity.md`. - **What to do when you (the AI agent) spot a violation** — flag vs. silently fix vs. escalate → `references/authority-model.md`. - **Structuring a full Tier 2/3 response with a real verification table** (cited evidence, not bare Pass/Fail) → `references/verification.md`. ## Appendix — noted but out of scope Deliberately excluded to keep this skill usable by any programmer rather than DDD specialists: architectural maturity metrics (coupling/instability numbers with thresholds), Aggregate boundary sizing at the full DDD level, and multi-service/microservice Bounded Context boundary-drawing. These are real, deeper questions — but one level above general Clean Architecture.