# Clean Architecture > Building maintainable, testable software architectures — an AI agent skill based on *Clean Architecture* by Robert C. Martin. Published 2026-02-23 · Updated 2026-08-17 · Architecture & Systems · Free and MIT-licensed Canonical: https://skills.wondel.ai/skills/clean-architecture/ Source: https://github.com/wondelai/skills/tree/main/clean-architecture **Install:** `npx skills add wondelai/skills/clean-architecture --global` ## What is the Clean Architecture skill? Clean Architecture is a free AI agent skill built on Robert C. Martin’s book. It enforces the Dependency Rule — source code dependencies point inward, from frameworks toward use cases toward entities — so your agent puts business logic where the database, the web framework and the vendor SDK can be swapped without touching it. ## Key concepts from Clean Architecture your agent applies - **The Dependency Rule** — Dependencies point inward — outer layers depend on inner layers, never the reverse. Business rules know nothing about UI or databases. - **Entities & Use Cases** — Entities encapsulate enterprise-wide business rules. Use cases contain application-specific business rules that orchestrate entities. - **Interface Adapters** — Controllers, presenters, and gateways convert data between the format most convenient for use cases and the format used by external agencies. - **Frameworks Are Details** — Frameworks and databases are implementation details — keep them at the outer ring and make them replaceable. - **SOLID Principles** — Single Responsibility, Open-Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion guide component design. ## When to use Clean Architecture — and when not to Reach for it when: - You cannot run a single business rule in a test without booting the web framework and a database first. - Replacing the ORM or upgrading the framework would mean editing files all over the codebase, not just the edges. - Nobody can say which layer a new class belongs in, so everything lands in one enormous services folder. - You are deciding whether to split into microservices and want the boundaries drawn before the deployments are. Reach for something else when: - The app is small and the layers would cost more than they save — Software Design’s complexity test is the better judge. - You know you need boundaries but not where they go — Domain-Driven Design finds the seams the business actually has. - The problem is naming, function length and readability inside one module — Clean Code is the more specific tool. - You need the system to survive a failing dependency, not a cleaner layer diagram — that is Release It!. ## About Robert C. Martin Co-author of the Agile Manifesto, creator of SOLID principles. Robert C. Martin (Uncle Bob) is a software engineer, author, and co-author of the Agile Manifesto. He has been a programmer since 1970 and has shaped how the industry thinks about software design, from SOLID principles to clean architecture. More: https://en.wikipedia.org/wiki/Robert_C._Martin · https://www.wikidata.org/wiki/Q93010 The book: https://openlibrary.org/books/OL31838215M/Clean_Architecture ## Example prompts - Restructure this application to follow Clean Architecture layers using clean-architecture skill _(Architecture)_ - Identify Dependency Rule violations in this codebase using clean-architecture skill _(Architecture review)_ - Design use case and entity layers for this feature using clean-architecture skill _(Design)_ - Decouple the database layer so we can swap ORMs without touching business logic using clean-architecture skill _(Refactoring)_ ## Frequently asked questions ### How do I install the Clean Architecture skill? Run `npx skills add wondelai/skills/clean-architecture --global`. It takes about 30 seconds and needs no account. The Clean Architecture skill then works in Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw and Hermes Agent — anything that reads the open agentskills.io format — and your agent loads it on its own when a task calls for it. It is free and MIT-licensed, and the source is at https://github.com/wondelai/skills. ### Which book is the Clean Architecture skill based on? It packages *Clean Architecture* by Robert C. Martin — co-author of the Agile Manifesto, creator of SOLID principles. The skill distils the book's method into instructions your agent follows while it works, covering the dependency rule, entities & use cases and interface adapters. It sits in the Architecture & Systems part of the library. ### How is this different from the Domain-Driven Design skill? Clean Architecture answers which way dependencies point across a boundary; Domain-Driven Design answers where the boundary belongs and what the things inside it mean. Martin’s rule tells you a repository interface lives in the inner circle and its Postgres implementation outside. Evans tells you it should be an OrderRepository, because Order is an aggregate root in your fulfilment context. Installed together, one supplies direction, the other supplies location and vocabulary. ### What does the Dependency Rule actually say? That source code dependencies may point only inward, toward higher-level policy. An inner circle must not name anything in an outer one — no class, no function, no variable, and especially no data format that an outer layer defines. Because control often has to flow outward at runtime, you invert it: the use case declares an interface, the outer layer implements it, and the source dependency still points in. ### Isn’t Clean Architecture over-engineering for a small app? Often, yes, and the skill will say so if you ask it to. Four concentric circles, an interface per gateway and a DTO at every crossing can easily cost more than they save on a CRUD app with one datastore. What survives at any size is the direction rule plus a real boundary at the one or two points of genuine volatility. Ask which boundaries earn their cost and treat the folder count as negotiable. ### Does it cover microservices? It covers the decision, not the operations. The book’s position, which the skill applies, is that services are units of deployment rather than units of architecture, and that services sharing one fat data model are a distributed monolith with network failures added. Expect it to push you toward a modular monolith with real internal boundaries, from which later extraction is mechanical. For capacity questions use System Design; for runtime failure modes, Release It!. ## Related - All Architecture & Systems skills: https://skills.wondel.ai/skills/architecture/ - Domain-Driven Design: https://skills.wondel.ai/skills/domain-driven-design/ - Data-Intensive Apps: https://skills.wondel.ai/skills/ddia-systems/ - System Design: https://skills.wondel.ai/skills/system-design/ - Release It!: https://skills.wondel.ai/skills/release-it/ - High Perf Browser: https://skills.wondel.ai/skills/high-perf-browser/