clean-architecture

---

name: clean-architecture description: Clean Architecture principles and best practices from Robert C. Martin's book. This skill should be used when designing software systems, reviewing code structure, or refactoring applications to achieve better separation of concerns. Triggers on tasks involving layers, boundaries, dependency direction, entities, use cases, or system architecture.

Clean Architecture Best Practices

Comprehensive guide to Clean Architecture principles for designing maintainable, testable software systems. Based on Robert C. Martin's "Clean Architecture: A Craftsman's Guide to Software Structure and Design." Contains 42 rules across 8 categories, prioritized by architectural impact.

When to Apply

Reference these guidelines when:

• Designing new software systems or modules
• Structuring dependencies between layers
• Defining boundaries between business logic and infrastructure
• Reviewing code for architectural violations
• Refactoring coupled systems toward cleaner structure

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Dependency Direction	CRITICAL	dep-
2	Entity Design	CRITICAL	entity-
3	Use Case Isolation	HIGH	usecase-
4	Component Cohesion	HIGH	comp-
5	Boundary Definition	MEDIUM-HIGH	bound-
6	Interface Adapters	MEDIUM	adapt-
7	Framework Isolation	MEDIUM	frame-
8	Testing Architecture	LOW-MEDIUM	test-

Quick Reference

1. Dependency Direction (CRITICAL)

• dep-inward-only - Source dependencies point inward only
• dep-interface-ownership - Interfaces belong to clients not implementers
• dep-no-framework-imports - Avoid framework imports in inner layers
• dep-data-crossing-boundaries - Use simple data structures across boundaries
• dep-acyclic-dependencies - Eliminate cyclic dependencies between components
• dep-stable-abstractions - Depend on stable abstractions not volatile concretions

2. Entity Design (CRITICAL)

• entity-pure-business-rules - Entities contain only enterprise business rules
• entity-no-persistence-awareness - Entities must not know how they are persisted
• entity-encapsulate-invariants - Encapsulate business invariants within entities
• entity-value-objects - Use value objects for domain concepts
• entity-rich-not-anemic - Build rich domain models not anemic data structures

3. Use Case Isolation (HIGH)

• usecase-single-responsibility - Each use case has one reason to change
• usecase-input-output-ports - Define input and output ports for use cases
• usecase-orchestrates-not-implements - Use cases orchestrate entities not implement business rules
• usecase-no-presentation-logic - Use cases must not contain presentation logic
• usecase-explicit-dependencies - Declare all dependencies explicitly in constructor
• usecase-transaction-boundary - Use case defines the transaction boundary

4. Component Cohesion (HIGH)

• comp-screaming-architecture - Structure should scream the domain not the framework
• comp-common-closure - Group classes that change together
• comp-common-reuse - Avoid forcing clients to depend on unused code
• comp-reuse-release-equivalence - Release components as cohesive units
• comp-stable-dependencies - Depend in the direction of stability

5. Boundary Definition (MEDIUM-HIGH)

• bound-humble-object - Use humble objects at architectural boundaries
• bound-partial-boundaries - Use partial boundaries when full separation is premature
• bound-boundary-cost-awareness - Weigh boundary cost against ignorance cost
• bound-main-component - Treat main as a plugin to the application
• bound-defer-decisions - Defer framework and database decisions
• bound-service-internal-architecture - Services must have internal clean architecture

6. Interface Adapters (MEDIUM)

• adapt-controller-thin - Keep controllers thin
• adapt-presenter-formats - Presenters format data for the view
• adapt-gateway-abstraction - Gateways hide external system details
• adapt-mapper-translation - Use mappers to translate between layers
• adapt-anti-corruption-layer - Build anti-corruption layers for external systems

7. Framework Isolation (MEDIUM)

• frame-domain-purity - Domain layer has zero framework dependencies
• frame-orm-in-infrastructure - Keep ORM usage in infrastructure layer
• frame-web-in-infrastructure - Web framework concerns stay in interface layer
• frame-di-container-edge - Dependency injection containers live at the edge
• frame-logging-abstraction - Abstract logging behind domain interfaces

8. Testing Architecture (LOW-MEDIUM)

• test-tests-are-architecture - Tests are part of the system architecture
• test-testable-design - Design for testability from the start
• test-layer-isolation - Test each layer in isolation
• test-boundary-verification - Verify architectural boundaries with tests

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Reference Files

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information