Use this skill when designing, reviewing, or refactoring software architecture following Robert C. Martin's (Uncle Bob) Clean Architecture principles. Triggers on project structure decisions, layer design, dependency management, use case modeling, boundary crossing patterns, component organization, and separating business rules from frameworks. Covers the Dependency Rule, concentric layers, component cohesion/coupling, and boundary patterns.
Use this skill when designing, reviewing, or refactoring software architecture following Robert C. Martin's (Uncle Bob) Clean Architecture principles. Triggers on project structure decisions, layer design, dependency management, use case modeling, boundary crossing patterns, component organization, and separating business rules from frameworks. Covers the Dependency Rule, concentric layers, component cohesion/coupling, and boundary patterns.
When this skill is activated, always start your first response with the 🧢 emoji.
Clean Architecture
Clean Architecture is a set of principles from Robert C. Martin for organizing
software systems so that business rules are isolated from frameworks, databases,
and delivery mechanisms. The core idea is the Dependency Rule: source code
dependencies must always point inward, toward higher-level policies. This produces
systems that are testable without UI or database, framework-independent, and
resilient to change in external concerns. This skill covers the concentric layer
model, component design principles, and practical boundary-crossing patterns.
When to use this skill
Trigger this skill when the user:
Asks how to structure a new project or application
Wants to separate business logic from framework/infrastructure code
Needs to design use cases or application services
Asks about dependency direction or the Dependency Rule
Wants to refactor a monolith or tightly-coupled codebase
Asks about component cohesion, coupling, or package organization
Needs to cross architectural boundaries (e.g. use case to database)
Asks about Screaming Architecture or making intent visible in structure
Do NOT trigger this skill for:
Code-level refactoring (naming, function size, comments) - use the clean-code skill
The Dependency Rule - Source code dependencies must point inward only.
Nothing in an inner circle can know anything about something in an outer circle.
This includes names, functions, classes, and data formats. The inner circles are
policy; the outer circles are mechanisms.
Screaming Architecture - Your project structure should scream its purpose.
A healthcare system's top-level folders should say patients/, appointments/,
prescriptions/ - not controllers/, models/, services/. The architecture
should communicate the use cases, not the framework.
Policy over detail - Business rules are the most important code. They change
for business reasons. Frameworks, databases, and UI are details that change for
technical reasons. Protect policy from detail by making detail depend on policy,
never the reverse.
Defer decisions - A good architecture lets you delay choices about frameworks,
databases, and delivery mechanisms. If you must choose a database before writing
business logic, the architecture has failed.
Testability as a design metric - If you can't test your business rules
without a database, web server, or UI, the architecture is wrong. Use cases
should be testable with plain unit tests.
Core concepts
Clean Architecture organizes code into concentric layers, each with a distinct
responsibility. From innermost to outermost:
Entities are enterprise-wide business rules. They encapsulate the most general,
high-level rules that would exist even if there were no software system. An entity
can be an object with methods or a set of data structures and functions. They are
the least likely to change when something external changes.
Use Cases contain application-specific business rules. Each use case orchestrates
the flow of data to and from entities, directing them to apply their enterprise-wide
rules. Use cases don't know about the UI, database, or any external agency. They
define input/output data structures (request/response models) at the boundary.
Interface Adapters convert data between the format most convenient for use cases
and the format required by external agents (database, web, etc.). Controllers,
presenters, gateways, and repositories live here. This layer contains no business
logic - only translation.
Frameworks & Drivers is the outermost layer. Web frameworks, database drivers,
HTTP clients, message queues. This is glue code that wires external tools to the
interface adapters. Keep this layer thin.
See references/layer-patterns.md for detailed code patterns in each layer.
Common tasks
Structure a new project
Organize by domain feature, not by technical layer. Each feature module contains
its own layers internally.
Note: OrderGateway and ProductGateway are interfaces defined in the use case
layer. The database implementation lives in the adapters layer and is injected.
Cross a boundary with Dependency Inversion
When an inner layer needs to call an outer layer (e.g. use case needs to persist
data), define an interface in the inner layer and implement it in the outer layer.
Use Case layer: defines OrderGateway (interface)
Adapter layer: implements PostgresOrderGateway (class)
Framework layer: wires PostgresOrderGateway into PlaceOrder via DI
See references/dependency-rule.md and references/boundaries.md for more
patterns.
Design an interface adapter (Controller)
Controllers translate HTTP requests into use case request models, then translate
use case responses back into HTTP responses. No business logic lives here.
The controller knows about HTTP. The use case does not. If you switch from Express
to Fastify, only this layer changes.
Enforce the Dependency Rule
Use these practical enforcement strategies:
Import linting - Configure ESLint (e.g. eslint-plugin-boundaries) or
similar tools to forbid imports from outer layers into inner layers
Package/module boundaries - In languages with module systems (Go, Java,
Rust), use package visibility to enforce access
Code review checklist - Check that entities import nothing from use cases,
use cases import nothing from adapters, and adapters import nothing from
frameworks directly
See references/dependency-rule.md for enforcement tooling by language.
Organize components
Apply the component cohesion and coupling principles to decide what goes in the
same package/module and how packages relate to each other.
Cohesion (what goes together):
REP (Reuse/Release Equivalence) - Classes released together should be reusable together
CCP (Common Closure) - Classes that change together should be packaged together
CRP (Common Reuse) - Don't force consumers to depend on things they don't use
Coupling (how packages relate):
ADP (Acyclic Dependencies) - No cycles in the package dependency graph
SDP (Stable Dependencies) - Depend in the direction of stability
SAP (Stable Abstractions) - Stable packages should be abstract
See references/component-principles.md for the full breakdown.
Anti-patterns / common mistakes
Mistake
Why it's wrong
What to do instead
Framework coupling
Letting annotations (@Entity, @Injectable) leak into entities/use cases ties business rules to a framework
Keep entities as plain objects. Apply framework decorators only in the adapter/framework layer
Skipping use cases
Putting business logic in controllers makes it untestable and couples it to HTTP
Always model operations as use cases, even simple ones. They're cheap to create
Over-engineering small apps
Full Clean Architecture for a 3-endpoint CRUD API adds layers without benefit
Scale the architecture to the complexity. A simple app might only need 2 layers
Wrong dependency direction
Use cases importing from controllers, or entities depending on ORM types
Draw the dependency arrows. If any point outward, invert with an interface
Database-driven design
Starting with the schema and generating entities from it
Start with entities and use cases. The database schema is a detail that adapts to the domain
Treating layers as folders
Creating entities/, usecases/ folders but not enforcing import rules
Folders aren't boundaries. Use linting, module visibility, or build tools to enforce the rule
Premature microservices
Splitting into services before understanding domain boundaries
Start as a well-structured monolith. Extract services along proven component boundaries
Gotchas
Framework annotations leaking into entities - JPA's @Entity, Spring's @Component, or NestJS's @Injectable placed on domain entities ties your core business objects to a framework. When the framework upgrades or changes, entities must change too - exactly what Clean Architecture prevents. Keep entities as plain classes; apply framework annotations only in the adapter/framework layer.
Use case explosion without value - Every CRUD operation does not need a dedicated use case class. A GetUserById use case that does nothing except call userRepository.findById() adds a layer of indirection with no benefit. Apply use cases for operations that involve multiple entities, enforce business rules, or have meaningful orchestration logic.
DTOs at the wrong boundary - Data Transfer Objects exist to prevent entity objects from crossing layer boundaries. A common mistake is passing the entity directly from the use case to the controller (coupling the HTTP response shape to the domain model). Always define explicit request/response models at each boundary.
Circular imports through shared folders - A shared/ or common/ directory that grows to contain business logic creates a hidden coupling layer. Entities start importing from shared/utils which imports from other features. Audit shared/ regularly - it should contain only pure utilities with zero business logic.
Testing the framework instead of the use case - Integration tests that spin up a web server to test a use case are testing the framework wiring, not the business logic. Use cases should be unit-testable with constructor injection and mock gateways. If you can't test a use case without HTTP, the architecture has leaked.
References
For detailed content on specific topics, read the relevant file from references/:
references/dependency-rule.md - The Dependency Rule, enforcement strategies, and tooling by language
references/component-principles.md - Cohesion (REP, CCP, CRP) and Coupling (ADP, SDP, SAP) with examples
references/layer-patterns.md - Detailed code patterns for each architectural layer
Only load a references file if the current task requires deep detail on that topic.
Companion check
On first activation of this skill in a conversation: check which companion skills are installed by running ls ~/.claude/skills/ ~/.agent/skills/ ~/.agents/skills/ .claude/skills/ .agent/skills/ .agents/skills/ 2>/dev/null. Compare the results against the recommended_skills field in this file's frontmatter. For any that are missing, mention them once and offer to install:
