clean-architecture
pproenca/dot-skills
Clean Architecture principles and best practices for designing maintainable, testable software systems.
What is clean-architecture?
This skill provides comprehensive guidance on Robert C. Martin's Clean Architecture principles across 42 rules organized into 8 categories. Use it when designing new systems, reviewing code structure, refactoring for better separation of concerns, or defining architectural boundaries and dependencies.
- Apply dependency direction rules to ensure dependencies point inward only
- Design entities with pure business rules isolated from persistence concerns
- Structure use cases with explicit input/output ports and single responsibilities
- Organize components by cohesion and stability rather than technical frameworks
- Define clear architectural boundaries using humble objects and partial boundaries
- Create interface adapters that translate between layers without leaking concerns
How to install clean-architecture
npx skills add https://github.com/pproenca/dot-skills --skill clean-architectureHow to use clean-architecture
- 1.Reference the rule categories table to identify which priority level applies to your task (Dependency Direction, Entity Design, Use Case Isolation, etc.)
- 2.Read the specific rule reference files for detailed explanations and code examples matching your scenario
- 3.Apply the relevant rules when designing new modules, reviewing code, or refactoring existing systems
- 4.Use the rule prefixes (dep-, entity-, usecase-, comp-, bound-, adapt-, frame-, test-) to quickly locate guidance on specific architectural concerns
- 5.Verify your design against multiple rule categories to ensure comprehensive architectural alignment
Use cases
- Designing a new microservice or application from scratch with clean layered architecture
- Refactoring a tightly coupled monolith to separate business logic from infrastructure
- Reviewing code structure to identify dependency violations and architectural anti-patterns
- Establishing component boundaries and defining which classes change together
- Migrating from one framework to another while preserving domain logic
- Software architects designing system structure
- Backend developers refactoring applications toward cleaner architecture
- Code reviewers evaluating architectural compliance
- Teams establishing architectural standards and guidelines
- Developers learning Clean Architecture principles from Robert C. Martin's book
clean-architecture FAQ
Apply Clean Architecture when designing systems that need to be maintainable and testable over time, especially when business logic needs to remain independent from frameworks and infrastructure. It's particularly valuable for domain-driven systems where business rules are complex and likely to change.
Clean Architecture is a specific form of layered architecture that emphasizes dependency direction (dependencies point inward), boundary definition, and isolation of business logic from frameworks. It's stricter about what can depend on what compared to generic layered approaches.
External dependencies belong in the infrastructure layer or interface adapters layer. Use anti-corruption layers and gateways to abstract external system details, keeping your domain layer free from framework and library dependencies.
Yes. Each microservice should have its own internal clean architecture with proper layer separation. Services must have internal clean architecture even if they communicate across service boundaries.
Your architecture is clean when: dependencies point inward only, entities contain pure business rules with no persistence awareness, use cases orchestrate entities through ports, frameworks are isolated to outer layers, and tests can verify architectural boundaries.
Full instructions (SKILL.md)
Source of truth, from pproenca/dot-skills.
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 onlydep-interface-ownership- Interfaces belong to clients not implementersdep-no-framework-imports- Avoid framework imports in inner layersdep-data-crossing-boundaries- Use simple data structures across boundariesdep-acyclic-dependencies- Eliminate cyclic dependencies between componentsdep-stable-abstractions- Depend on stable abstractions not volatile concretions
2. Entity Design (CRITICAL)
entity-pure-business-rules- Entities contain only enterprise business rulesentity-no-persistence-awareness- Entities must not know how they are persistedentity-encapsulate-invariants- Encapsulate business invariants within entitiesentity-value-objects- Use value objects for domain conceptsentity-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 changeusecase-input-output-ports- Define input and output ports for use casesusecase-orchestrates-not-implements- Use cases orchestrate entities not implement business rulesusecase-no-presentation-logic- Use cases must not contain presentation logicusecase-explicit-dependencies- Declare all dependencies explicitly in constructorusecase-transaction-boundary- Use case defines the transaction boundary
4. Component Cohesion (HIGH)
comp-screaming-architecture- Structure should scream the domain not the frameworkcomp-common-closure- Group classes that change togethercomp-common-reuse- Avoid forcing clients to depend on unused codecomp-reuse-release-equivalence- Release components as cohesive unitscomp-stable-dependencies- Depend in the direction of stability
5. Boundary Definition (MEDIUM-HIGH)
bound-humble-object- Use humble objects at architectural boundariesbound-partial-boundaries- Use partial boundaries when full separation is prematurebound-boundary-cost-awareness- Weigh boundary cost against ignorance costbound-main-component- Treat main as a plugin to the applicationbound-defer-decisions- Defer framework and database decisionsbound-service-internal-architecture- Services must have internal clean architecture
6. Interface Adapters (MEDIUM)
adapt-controller-thin- Keep controllers thinadapt-presenter-formats- Presenters format data for the viewadapt-gateway-abstraction- Gateways hide external system detailsadapt-mapper-translation- Use mappers to translate between layersadapt-anti-corruption-layer- Build anti-corruption layers for external systems
7. Framework Isolation (MEDIUM)
frame-domain-purity- Domain layer has zero framework dependenciesframe-orm-in-infrastructure- Keep ORM usage in infrastructure layerframe-web-in-infrastructure- Web framework concerns stay in interface layerframe-di-container-edge- Dependency injection containers live at the edgeframe-logging-abstraction- Abstract logging behind domain interfaces
8. Testing Architecture (LOW-MEDIUM)
test-tests-are-architecture- Tests are part of the system architecturetest-testable-design- Design for testability from the starttest-layer-isolation- Test each layer in isolationtest-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 |
Related skills
More from pproenca/dot-skills and the wider catalog.
zod
Zod schema validation best practices for type safety, parsing, and error handling.
emilkowal-animations
Emil Kowalski's animation best practices for React, CSS, and Framer Motion.
react-hook-form
Performance optimization guide for React Hook Form client-side forms with 45 rules across 8 categories.
vitest
Vitest testing framework patterns for test setup, async testing, mocking with vi.*, snapshots, and test performance (formerly test-vitest). This skill should be used when writing or debugging Vitest tests. This skill does NOT cover TDD methodology (use test-tdd skill), API mocking with MSW (use test-msw skill), or Jest-specific APIs.
nuqs
nuqs (type-safe URL query state) best practices for Next.js and other React frameworks. This skill should be used when writing, reviewing, or refactoring code that uses nuqs for URL state management. Triggers on tasks involving useQueryState, useQueryStates, search params, URL state, query parameters, nuqs parsers, limitUrlUpdates, Standard Schema, NuqsAdapter, or Next.js routing with state.
code-simplifier
Code simplification skill for improving clarity, consistency, and maintainability while preserving exact behavior. Use when simplifying code, reducing complexity, cleaning up recent changes, applying refactoring patterns, or improving readability. Triggers on tasks involving code cleanup, simplification, refactoring, or readability improvements.