Skip to main content
affpapa.org
RU EN
skill CX Codex

clean-architecture · pproenca — Claude Code skill: Clean Architecture rules

A skill with 42 rules from Robert C. Martin's book: it tells the agent which way dependencies should point and where layer boundaries belong.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓ 
npx skills add pproenca/dot-skills --skill clean-architecture -a claude-code
Open on GitHub

What clean-architecture does

The skill splits Clean Architecture into 42 rules across 8 categories. Each rule lives in its own file under references/ and carries a prefix: dep- for dependency direction, entity- for entities, usecase- for use cases, comp- for component cohesion, bound- for boundaries, adapt- for adapters, frame- for framework isolation, test- for testing. Priority follows architectural impact: dependency direction and entity design are marked CRITICAL, use case isolation and component cohesion are HIGH.

The agent picks it up when you design a new system or module, sort out dependencies between layers, separate business logic from infrastructure, hunt for architectural violations, or untangle a coupled codebase. Triggers are layers, boundaries, dependency direction, entities, use cases, system architecture.

Rules point to files like references/dep-inward-only.md with explanations and code examples. Worth adding before your project structure settles: reversing dependency direction in finished code costs more than setting it right at the start.

What it helps with

  • design layers so dependencies point inward only
  • keep business logic free of framework and ORM code
  • spot architectural boundary violations during code review
  • split use cases into separate input and output ports
  • remove cyclic dependencies between components

Example prompts for the agent

  • check this project structure against the clean-architecture rules and list boundary violations
  • split this module into entities, use cases and adapters following clean-architecture
  • which clean-architecture rules does this file break?

How to install clean-architecture

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill clean-architecture -a claude-code

2Manually: put the files in place

~/.claude/skills/clean-architecture/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/clean-architecture/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about clean-architecture

How do I install clean-architecture in Claude?

Run npx skills add pproenca/dot-skills --skill clean-architecture -a claude-code. The skill file lands at ~/.claude/skills/clean-architecture/SKILL.md.

What does clean-architecture do?

It hands the agent a rule set from Robert C. Martin's book: dependency direction, entity design, use case isolation, boundaries, adapters, framework isolation and testing. The agent applies them while designing, reviewing and refactoring.

Which platforms does the skill support?

Besides Claude there are commands for Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. For GitHub Copilot the install goes through gh skill install pproenca/dot-skills clean-architecture.

Source text

SKILL.md · MIT 
---
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`](references/dep-inward-only.md) - Source dependencies point inward only
- [`dep-interface-ownership`](references/dep-interface-ownership.md) - Interfaces belong to clients not implementers
- [`dep-no-framework-imports`](references/dep-no-framework-imports.md) - Avoid framework imports in inner layers
- [`dep-data-crossing-boundaries`](references/dep-data-crossing-boundaries.md) - Use simple data structures across boundaries
- [`dep-acyclic-dependencies`](references/dep-acyclic-dependencies.md) - Eliminate cyclic dependencies between components
- [`dep-stable-abstractions`](references/dep-stable-abstractions.md) - Depend on stable abstractions not volatile concretions

### 2. Entity Design (CRITICAL)

- [`entity-pure-business-rules`](references/entity-pure-business-rules.md) - Entities contain only enterprise business rules
- [`entity-no-persistence-awareness`](references/entity-no-persistence-awareness.md) - Entities must not know how they are persisted
- [`entity-encapsulate-invariants`](references/entity-encapsulate-invariants.md) - Encapsulate business invariants within entities
- [`entity-value-objects`](references/entity-value-objects.md) - Use value objects for domain concepts
- [`entity-rich-not-anemic`](references/entity-rich-not-anemic.md) - Build rich domain models not anemic data structures

### 3. Use Case Isolation (HIGH)

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

### 4. Component Cohesion (HIGH)

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

### 5. Boundary Definition (MEDIUM-HIGH)

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

### 6. Interface Adapters (MEDIUM)

- [`adapt-controller-thin`](references/adapt-controller-thin.md) - Keep controllers thin
- [`adapt-presenter-formats`](references/adapt-presenter-formats.md) - Presenters format data for the view
- [`adapt-gateway-abstraction`](references/adapt-gateway-abstraction.md) - Gateways hide external system details
- [`adapt-mapper-translation`](references/adapt-mapper-translation.md) - Use mappers to translate between layers
- [`adapt-anti-corruption-layer`](references/adapt-anti-corruption-layer.md) - Build anti-corruption layers for external systems

### 7. Framework Isolation (MEDIUM)

- [`frame-domain-purity`](references/frame-domain-purity.md) - Domain layer has zero framework dependencies
- [`frame-orm-in-infrastructure`](references/frame-orm-in-infrastructure.md) - Keep ORM usage in infrastructure layer
- [`frame-web-in-infrastructure`](references/frame-web-in-infrastructure.md) - Web framework concerns stay in interface layer
- [`frame-di-container-edge`](references/frame-di-container-edge.md) - Dependency injection containers live at the edge
- [`frame-logging-abstraction`](references/frame-logging-abstraction.md) - Abstract logging behind domain interfaces

### 8. Testing Architecture (LOW-MEDIUM)

- [`test-tests-are-architecture`](references/test-tests-are-architecture.md) - Tests are part of the system architecture
- [`test-testable-design`](references/test-testable-design.md) - Design for testability from the start
- [`test-layer-isolation`](references/test-layer-isolation.md) - Test each layer in isolation
- [`test-boundary-verification`](references/test-boundary-verification.md) - Verify architectural boundaries with tests

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |

© pproenca · MIT · pproenca/dot-skills

Similar skills

Everything for Code review and refactoring →

clean-architecture by other authors comes first.

clean-architecture wondelai A skill that keeps business rules independent of framework and database by enforcing one rule: source code dependencies point inward. CX Codex +1 7,300installs clean-architecture codewithmukesh A skill that lays out .NET code across four projects, keeps dependencies pointing inward, and shows where use case handlers belong. CX Codex +1 3,000installs clean-architecture giuseppe-trisciuoglio Guides Clean Architecture, hexagonal architecture and DDD patterns in Java 21+ Spring Boot 3.5+ projects. Use it when separating domain code from frameworks or refactoring coupled code. CX Codex +1 4,000installs architecture-compass stark-ai-de A skill for architecture decisions: sets up repository-native ADR governance, audits drift, and plans bounded refactors. CX Codex +1 2,700installs architecture-patterns secondsky A skill that gives your agent backend architecture templates: Clean Architecture layers, ports and adapters, and Domain-Driven Design building blocks. CX Codex +1 493installs guarding-architecture riekelt Enforces system boundaries by turning structural invariants into breaking build tests. Useful when code crosses module limits or adds unwanted cross-package imports. CX Codex +1 18,000installs architecture-advisor codewithmukesh Runs a questionnaire on domain, team and system lifetime, then recommends an architecture for your .NET project. Useful before you lay out folders. CX Codex +1 2,800installs android-clean-architecture affaan-m Tells the agent how to split an Android or KMP project into layers: modules, dependency rules, UseCases, repositories, plus Room, SQLDelight and Ktor patterns. CX Codex +1 5,200installs

From the same set45

vitest Equips your coding agent with 44 prioritized rules for writing, debugging, and speeding up Vitest suites. Covers async patterns, mocks, and test isolation. CX Codex +1 6,100installs react-hook-form Optimizes client-side forms using React Hook Form 7.82.0 and prevents unnecessary re-renders across field subscriptions, validation, and controlled UI inputs. CX Codex +1 3,000installs emilkowal-animations A set of 58 web animation rules based on Emil Kowalski's work for React and Framer Motion. Helps tune easing curves, gestures, and UI timing. CX Codex +1 2,800installs nuqs A skill with 39 nuqs rules covering typed parsers, adapters, Server Components and URL update performance. Useful when an agent writes or refactors URL state code. CX Codex +1 2,300installs code-simplifier A skill that gives AI agents 47 rules for cleaning up recently changed code without altering what it does. CX Codex +1 1,600installs expo-react-native-performance Performance guidelines with 42 prioritized rules for Expo React Native apps. Helps agents refactor startup bottlenecks, list virtualization, re-renders, and animations. CX Codex +1 1,500installs framer-motion Optimizes React animations using Framer Motion guidelines: slashes bundle size, eliminates unnecessary re-renders, and polishes gesture or scroll transitions. CX Codex +1 1,100installs msw A skill with 45 rules for Mock Service Worker v2: setup, handlers, test integration, GraphQL. Useful when your agent writes or fixes HTTP mocks. CX Codex +1 842installs

Project sponsors

Companies that keep this analytics open
Gold sponsor
Nutra.Club

Impressions, clicks and code copies — open statistics. We keep the numbers public for the same reason NeBlask itself is public. Become a sponsor