clean-architecture
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.
- Installs
- 2K
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/pproenca/dot-skills --skill clean-architecture- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads clean-architecture automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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 |
FAQ
What does the clean-architecture skill do?
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.
How do I install clean-architecture?
Run npx skills add https://github.com/pproenca/dot-skills --skill clean-architecture in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/clean-architecture/ (personal) or .claude/skills/clean-architecture/ (project).
Which AI agents can use clean-architecture?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is clean-architecture safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains clean-architecture?
It is published by pproenca in pproenca/dot-skills. It has 2,033 recorded installs.
More from pproenca/dot-skills
zod
pproenca/dot-skills
Zod schema validation best practices for type safety, parsing, and error handling. This skill should be used when defining z.object schemas, using z.string validations, safeParse, or z.infer. This skill does NOT cover React Hook Form integration patterns (use react-hook-form skill) or OpenAPI client generation (use orval skill).
vitest
pproenca/dot-skills
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.
react-hook-form
pproenca/dot-skills
React Hook Form performance optimization for client-side form validation using useForm, useWatch, useController, useFieldArray, the subscribe() API, and the Watch / FormStateSubscribe / FieldArray render-prop components. Covers RHF 7.82 additions including resetDefaultValues() and the disabled field-array option. This skill should be used when building client-side controlled forms with React Hook Form library. This skill does NOT cover React 19 Server Actions, useActionState, or server-side form handling (use react-19 skill for those).
emilkowal-animations
pproenca/dot-skills
Emil Kowalski's animation best practices for web interfaces. Use when writing, reviewing, or implementing animations in React, CSS, or Framer Motion. Triggers on tasks involving transitions, easing, gestures, toasts, drawers, or motion.
nuqs
pproenca/dot-skills
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.
typescript
pproenca/dot-skills
TypeScript performance, tsconfig, type errors, async patterns — triggered when the user asks to "optimize TypeScript performance", "speed up tsc compilation", "configure tsconfig.json", "fix type errors", "improve async patterns", or encounters TS errors (TS2322, TS2339, "is not assignable to"). Also triggers on .ts, .tsx, .d.ts file work involving type definitions, module organization, or memory management. Does NOT cover TypeScript basics, framework-specific patterns, or testing.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.