Mmcp.market

clean-architecture skill

by wondelai·wondelai/skills·2.3k stars·MIT

Structure software around the Dependency Rule: source code dependencies point inward from frameworks to use cases to entities. Use when the user mentions "architecture layers", "dependency rule", "ports and adapters (hexagonal)", "onion architecture", "screaming architecture", "where should business logic go", "decouple from the database", "swap the framework without a rewrite", or "keep business rules independent". Also trigger when deciding which layer code belongs in, isolating core logic from infrastructure, defining module boundaries, or debating whether the framework should call your code or the reverse. Covers component principles, boundaries, and SOLID. For code-level quality, see clean-code. For domain modeling, see domain-driven-design.

A100/100content scan

Is the clean-architecture skill safe?

Clean: nothing in its files matched our rules. We read 7 files in the folder on 2026-09-28.

No findings.

Install the clean-architecture skill

A skill is a folder. Copy it into your agent's skills folder and the agent loads it when the task matches its description. 

git clone --depth 1 https://github.com/wondelai/skills.git /tmp/skills
mkdir -p ~/.claude/skills
cp -r /tmp/skills/plugins/wondelai-skills/skills/clean-architecture ~/.claude/skills/clean-architecture
available in every project

In the Claude apps, zip the folder and upload it from the Skills settings. The folder on GitHub

The instructions your agent would load

SKILL.md as published, without the frontmatter. Read it on GitHub

Clean Architecture Framework

A disciplined approach to structuring software so that business rules remain independent of frameworks, databases, and delivery mechanisms. Apply these principles when designing system architecture, reviewing module boundaries, or advising on dependency management.

Core Principle

Source code dependencies must point inward — toward higher-level policies. Nothing in an inner circle can know anything about an outer circle. This single rule produces systems that are testable and independent of frameworks, UI, database, and any external agency. Business rules are what matter; databases, web frameworks, and delivery mechanisms are details — when details depend on policies, you can defer decisions, swap implementations, and test business logic in isolation.

Scoring

Goal: 10/10. Score one point for each of the seven Quick Diagnostic rows the architecture satisfies (0-7), then map to a 0-10 band: 6-7 satisfied = 9-10 (Dependency Rule holds, business logic is framework- and DB-independent); 4-5 = 6-8 (core is testable but some details leak inward); 2-3 = 3-5 (framework or persistence dictates structure); 0-1 = 0-2 (no boundaries — business rules live in controllers and ORM models). Report the score, the failed diagnostic rows, and the specific inversion needed to fix each.

1. Dependency Rule and Concentric Circles

Core concept: Organize the architecture as concentric circles — Entities (enterprise business rules) innermost, then Use Cases (application business rules), then Interface Adapters, with Frameworks and Drivers outermost. Source code dependencies always point inward.

Why it works: When high-level policies don't depend on low-level details, you can swap the database, web framework, or API style without touching business logic — the system becomes resilient to the most volatile parts of the stack.

Key insights:

  • Inner circles cannot mention outer circle names — no classes, functions, variables, or data formats from outside
  • Data crossing a boundary must be in the form most convenient for the inner circle, never dictated by the outer
  • Dependency Inversion (interfaces defined inward, implemented outward) is the mechanism that enforces the rule
  • The number of circles is not fixed — four is typical; the rule stays the same
  • Frameworks are details, not architecture — they belong in the outermost circle

Code applications:

See references/dependency-rule.md when an inner-circle import points outward and you need the four-circle code walkthrough, the data-crossing rules, and the four-step dependency-inversion procedure to fix it.

2. Entities and Use Cases

Core concept: Entities encapsulate enterprise-wide business rules — rules that would exist even without software. Use Cases contain application-specific rules that orchestrate the flow of data to and from Entities.

Why it works: Separating what the business does (Entities) from how the application orchestrates it (Use Cases) lets you reuse Entities across applications and change application behavior without altering core business rules.

Key insights:

  • Entities are not database rows — they are objects or pure functions encapsulating critical business rules
  • Use Cases accept Request Models and return Response Models — never framework objects
  • Each Use Case is a single application operation (CreateOrder, ApproveExpense)
  • The Interactor pattern: a Use Case class implements an input boundary interface and calls an output boundary interface
  • Changes to a Use Case should never affect an Entity; Entity changes may ripple to Use Cases

Code applications:

See references/entities-use-cases.md when designing an Interactor or deciding what belongs in an Entity versus a Use Case — full Enterprise vs. Application Business Rules treatment with request/response model examples.

3. Interface Adapters and Frameworks

Core concept: Interface Adapters convert data between the form convenient for Use Cases/Entities and the form required by external agencies. Frameworks and Drivers are the outermost layer — glue code to the outside world.

Why it works: When the web framework, ORM, or message queue is confined to the outer circles, replacing any of them is a localized change. The database is a detail; the web is a detail; details should be plugins to your business rules, not the skeleton of the application.

Key insights:

  • Controllers translate HTTP into Use Case input; Presenters translate Use Case output into view models
  • Gateways implement repository interfaces defined by Use Cases — the inner circle defines the contract, the outer fulfills it
  • Business rules never know whether data lives in SQL, NoSQL, or flat files, or that delivery is HTTP
  • Treat frameworks with suspicion — they want you to couple to them; keep them at arm's length

Code applications:

See references/adapters-frameworks.md when wiring controllers, presenters, or gateways, or arguing that the database/web is a detail — covers plugin architecture and how to confine a framework to the edges.

4. Component Principles

Core concept: Components are the units of deployment. Three cohesion principles govern what goes inside a component; three coupling principles govern relationships between components.

Why it works: Poorly composed components create ripple effects where one change forces redeployment of unrelated code; the principles keep changes localized and releases independent.

Key insights:

  • REP (Reuse/Release Equivalence): classes in a component must be versionable and releasable as a unit
  • CCP (Common Closure): classes that change for the same reason at the same time belong together — SRP for components
  • CRP (Common Reuse): don't force users to depend on classes they don't use
  • ADP (Acyclic Dependencies): the component graph must have no cycles — break them with DIP or a new component
  • SDP (Stable Dependencies): depend in the direction of stability
  • SAP (Stable Abstractions): stable components should be abstract; unstable ones concrete

Code applications:

See references/component-principles.md when grouping classes into deployable components or breaking a dependency cycle — each of REP, CCP, CRP, ADP, SDP, SAP worked through with the instability metric.

5. SOLID Principles

Core concept: Five class-and-module-level principles — Single Responsibility, Open-Closed, Liskov Substitution, Interface Segregation, Dependency Inversion — the mid-level building blocks that make the Dependency Rule possible.

Why it works: Each principle addresses a specific way dependencies go wrong, preventing the rigidity, fragility, and immobility that turn codebases into legacy nightmares.

Key insights:

  • SRP: a module has one reason to change — it serves one actor (not "does one thing")
  • OCP: extend behavior by adding new code, not modifying existing code — strategy and plugin patterns
  • LSP: subtypes must be usable through the base interface without the client knowing — violated by unexpected exceptions or ignored methods
  • ISP: clients should not depend on methods they don't use — fat interfaces create needless coupling
  • DIP: high-level modules and low-level modules both depend on abstractions defined by the high-level module

Code applications:

See references/solid-principles.md when applying SRP/OCP/LSP/ISP/DIP to a specific class or diagnosing a violation — each principle worked through with code examples and the smell it prevents.

6. Boundaries and Boundary Anatomy

Core concept: A boundary is a line between things that matter and things that are details, implemented through polymorphism: dependencies cross pointing inward while control flow may cross either way.

Why it works: Every boundary buys the option to defer a decision or swap an implementation; strategic boundary placement determines whether a system is a joy or a pain to maintain over years.

Key insights:

  • Full boundaries use reciprocal interfaces on both sides; partial boundaries use a simpler strategy or facade
  • Humble Object pattern: split boundary code into a hard-to-test part (close to the boundary) and an easy-to-test part (the logic)
  • Services are not automatically architectural boundaries — a microservice with a fat shared data model is a monolith with network calls
  • Tests are the most isolated component: they depend inward, nothing depends on them
  • Premature boundaries are expensive, but so are missing ones — draw them at points of likely volatility

Code applications:

See references/boundaries.md when deciding where to draw a boundary, choosing full vs. partial, or applying the Humble Object pattern — also covers services as boundaries, test boundaries, and Main as the ultimate plugin.

Common Mistakes

Quick Diagnostic

Further Reading

Based on Robert C. Martin's definitive guide to software architecture:

  • "Clean Architecture: A Craftsman's Guide to Software Structure and Design" by Robert C. Martin

About the Author

Robert C. Martin ("Uncle Bob") is a software engineer programming since 1970, a founding signatory of the Agile Manifesto, and the author of Clean Code, The Clean Coder, Clean Architecture, and Clean Agile. His SOLID principles are foundational vocabulary in object-oriented design, and his work argues that architecture is about managing dependencies and keeping business rules independent of infrastructure details.

More skills from wondelai/skills

  • A37signals-wayBuild lean, opinionated products using the 37signals philosophy from "Getting Real", "Rework", and "Shape Up". Use when the user mentions "Getting Real", "Rework", "Shape Up", "37signals", "Basecamp method", "six-week cycles", "fixed time variable scope", "appetite vs estimates", "betting table", "breadboarding", "fat marker sketch", "build less", "underdo the competition", "opinionated software", "we have too many meetings", "how do we ship faster", or "stop overbuilding". Also trigger when cutting scope to ship sooner, running a small team, or avoiding long-term roadmaps. Covers shaping, betting, building, and the art of saying no. For MVP validation, see lean-startup. For design sprints, see design-sprint.
  • A37signals-wayBuild lean, opinionated products using the 37signals philosophy from "Getting Real", "Rework", and "Shape Up". Use when the user mentions "Getting Real", "Rework", "Shape Up", "37signals", "Basecamp method", "six-week cycles", "fixed time variable scope", "appetite vs estimates", "betting table", "breadboarding", "fat marker sketch", "build less", "underdo the competition", "opinionated software", "we have too many meetings", "how do we ship faster", or "stop overbuilding". Also trigger when cutting scope to ship sooner, running a small team, or avoiding long-term roadmaps. Covers shaping, betting, building, and the art of saying no. For MVP validation, see lean-startup. For design sprints, see design-sprint.
  • A37signals-wayBuild lean, opinionated products using the 37signals philosophy from "Getting Real", "Rework", and "Shape Up". Use when the user mentions "Getting Real", "Rework", "Shape Up", "37signals", "Basecamp method", "six-week cycles", "fixed time variable scope", "appetite vs estimates", "betting table", "breadboarding", "fat marker sketch", "build less", "underdo the competition", "opinionated software", "we have too many meetings", "how do we ship faster", or "stop overbuilding". Also trigger when cutting scope to ship sooner, running a small team, or avoiding long-term roadmaps. Covers shaping, betting, building, and the art of saying no. For MVP validation, see lean-startup. For design sprints, see design-sprint.
  • Aarchitecture-optimizationGuided journey from a working codebase grown slow and tangled to one measurably fast, cleanly bounded, and readable. Orchestrates eight skills phase by phase - working-with-legacy-code, clean-architecture, software-design-philosophy, refactoring-patterns, system-design, ddia-systems, release-it, pragmatic-programmer - every phase carries its method inline so it runs standalone, asking the user questions at every decision point and recording results in the project docs/ folder (PERFORMANCE.md, ARCHITECTURE.md, ARCHITECTURE-OPTIMIZATION-PLAN.md) so the journey resumes across sessions. Use when the user wants to make an app faster, untangle drifted boundaries, fix slow endpoints and queries, or says ''it works but it is slow and getting worse''. For an untested prototype, improve-code-quality; for an aged codebase you fear to touch, remove-technical-debt; for greenfield structure, design-code-architecture; for marketing-site page speed, improve-website. For one framework in isolation, invoke that skill directly.
  • Aarchitecture-optimizationGuided journey from a working codebase grown slow and tangled to one measurably fast, cleanly bounded, and readable. Orchestrates eight skills phase by phase - working-with-legacy-code, clean-architecture, software-design-philosophy, refactoring-patterns, system-design, ddia-systems, release-it, pragmatic-programmer - every phase carries its method inline so it runs standalone, asking the user questions at every decision point and recording results in the project docs/ folder (PERFORMANCE.md, ARCHITECTURE.md, ARCHITECTURE-OPTIMIZATION-PLAN.md) so the journey resumes across sessions. Use when the user wants to make an app faster, untangle drifted boundaries, fix slow endpoints and queries, or says ''it works but it is slow and getting worse''. For an untested prototype, improve-code-quality; for an aged codebase you fear to touch, remove-technical-debt; for greenfield structure, design-code-architecture; for marketing-site page speed, improve-website. For one framework in isolation, invoke that skill directly.
  • Aarchitecture-optimizationGuided journey from a working codebase grown slow and tangled to one measurably fast, cleanly bounded, and readable. Orchestrates eight skills phase by phase - working-with-legacy-code, clean-architecture, software-design-philosophy, refactoring-patterns, system-design, ddia-systems, release-it, pragmatic-programmer - every phase carries its method inline so it runs standalone, asking the user questions at every decision point and recording results in the project docs/ folder (PERFORMANCE.md, ARCHITECTURE.md, ARCHITECTURE-OPTIMIZATION-PLAN.md) so the journey resumes across sessions. Use when the user wants to make an app faster, untangle drifted boundaries, fix slow endpoints and queries, or says ''it works but it is slow and getting worse''. For an untested prototype, improve-code-quality; for an aged codebase you fear to touch, remove-technical-debt; for greenfield structure, design-code-architecture; for marketing-site page speed, improve-website. For one framework in isolation, invoke that skill directly.
  • Ablue-ocean-strategyCreate uncontested market space using value innovation instead of competing head-to-head. Use when the user mentions "blue ocean", "red ocean", "strategy canvas", "ERRC framework", "value innovation", "non-customers", "buyer utility map", "the market is too crowded", "how do we stand out", or "escape the price war". Also trigger when exploring a new market category, or finding underserved or non-customers. Covers the Four Actions Framework, Six Paths, buyer utility map, and value-cost trade-offs. For real strategy formulation and bad-strategy detection, see good-strategy-bad-strategy. For tech adoption strategy, see crossing-the-chasm. For product positioning, see obviously-awesome.
  • Ablue-ocean-strategyCreate uncontested market space using value innovation instead of competing head-to-head. Use when the user mentions "blue ocean", "red ocean", "strategy canvas", "ERRC framework", "value innovation", "non-customers", "buyer utility map", "the market is too crowded", "how do we stand out", or "escape the price war". Also trigger when exploring a new market category, or finding underserved or non-customers. Covers the Four Actions Framework, Six Paths, buyer utility map, and value-cost trade-offs. For real strategy formulation and bad-strategy detection, see good-strategy-bad-strategy. For tech adoption strategy, see crossing-the-chasm. For product positioning, see obviously-awesome.
  • Ablue-ocean-strategyCreate uncontested market space using value innovation instead of competing head-to-head. Use when the user mentions "blue ocean", "red ocean", "strategy canvas", "ERRC framework", "value innovation", "non-customers", "buyer utility map", "the market is too crowded", "how do we stand out", or "escape the price war". Also trigger when exploring a new market category, or finding underserved or non-customers. Covers the Four Actions Framework, Six Paths, buyer utility map, and value-cost trade-offs. For real strategy formulation and bad-strategy detection, see good-strategy-bad-strategy. For tech adoption strategy, see crossing-the-chasm. For product positioning, see obviously-awesome.
  • Aclean-architectureStructure software around the Dependency Rule: source code dependencies point inward from frameworks to use cases to entities. Use when the user mentions "architecture layers", "dependency rule", "ports and adapters (hexagonal)", "onion architecture", "screaming architecture", "where should business logic go", "decouple from the database", "swap the framework without a rewrite", or "keep business rules independent". Also trigger when deciding which layer code belongs in, isolating core logic from infrastructure, defining module boundaries, or debating whether the framework should call your code or the reverse. Covers component principles, boundaries, and SOLID. For code-level quality, see clean-code. For domain modeling, see domain-driven-design.
  • Aclean-architectureStructure software around the Dependency Rule: source code dependencies point inward from frameworks to use cases to entities. Use when the user mentions "architecture layers", "dependency rule", "ports and adapters (hexagonal)", "onion architecture", "screaming architecture", "where should business logic go", "decouple from the database", "swap the framework without a rewrite", or "keep business rules independent". Also trigger when deciding which layer code belongs in, isolating core logic from infrastructure, defining module boundaries, or debating whether the framework should call your code or the reverse. Covers component principles, boundaries, and SOLID. For code-level quality, see clean-code. For domain modeling, see domain-driven-design.
  • Aclean-codeWrite readable, maintainable code through disciplined naming, small functions, and clean error handling. Use when the user mentions "clean up this code", "this function is too long", "code smells", "naming conventions", "boy scout rule", "single responsibility", or "unit test quality". Also trigger when reviewing a pull request for readability, untangling a messy function, debating comment styles, or improving error-handling patterns. Covers SRP, comment discipline, formatting, and unit testing. For refactoring techniques, see refactoring-patterns. For architecture and dependency rules, see clean-architecture.

All agent skills → · MCP servers