clean-architecture

Original：🇺🇸 English

Translated

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.

4installs

Sourcepproenca/dot-skills

Added on2026-02-04

NPX Install

npx skill4agent add pproenca/dot-skills clean-architecture

SKILL.md Content

View Translation Comparison →

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


dep-
entity-
usecase-
comp-
bound-
adapt-
frame-
test-

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