agentleFS
Sign inStart free
GabrielMartinMoranGabrielMartinMoran/mind/.agents/skills/clean-architecture/SKILL.md

clean-architecture

Skill193 starsChanged 28 days agoMITView on GitHub

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.

28 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use convention-learner, opentelemetry and 9 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • codewithmukeshSkill

    convention-learner

    Detects and enforces project-specific coding conventions by analyzing existing codebase patterns. Learns naming conventions, folder structure, test organization, and coding style from the existing code. Load when: "conventions", "coding standards", "project patterns", "enforce style", "detect patterns", "learn conventions", "code consistency".

    Also in 3 projects that use this

  • codewithmukeshSkill

    opentelemetry

    OpenTelemetry observability for .NET 10 applications. Covers traces, metrics, and logs using the OpenTelemetry SDK with OTLP export. Includes custom ActivitySource, IMeterFactory metrics, resource configuration, and Aspire Dashboard integration. Load this skill when setting up distributed tracing, custom metrics, OTLP export, or when the user mentions "OpenTelemetry", "OTLP", "traces", "spans", "Activity", "ActivitySource", "metrics", "IMeterFactory", "Meter", "Counter", "Histogram", "Gauge", "telemetry", "observability", "distributed tracing", "OTEL", or "Aspire Dashboard".

    Also in 3 projects that use this

  • MovGP0Skill

    modern-csharp

    Modern C# style guidance for Bendex and MicroSea code changes, including primary constructors, expression-bodied members, var usage, target-typed new, lambdas, and pattern matching.

    Also in 3 projects that use this

  • MicrosoftSkill

    resilience

    Apply resilience patterns (retry, backoff, circuit breaking) when writing or reviewing code that makes outbound HTTP/REST calls, database operations, or any I/O that can experience transient failures. Use this skill when: (1) writing new code that calls external services or APIs, (2) reviewing code that uses fetch, HTTP clients, or service-to-service calls, (3) adding queue consumers or workers that interact with remote systems, (4) debugging intermittent failures in production.

    Also in 3 projects that use this

  • hongyuancSkill

    vertical-slice

    Build and evaluate a production-quality vertical slice before advancing from Pre-Production to Production.

    Also in 3 projects that use this

  • wpankSkill

    caching

    Caching strategies, invalidation, eviction policies, HTTP caching, distributed caching, and anti-patterns. Use when designing cache layers, choosing eviction policies, debugging stale data, or optimizing read-heavy workloads.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

1 rule. 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 25 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read individual reference files for detailed explanations and code examples:

    line 102

“Common” is measured: kept by at least 6 in 10 of the 25 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

PriorityCategoryImpactPrefix
1Dependency DirectionCRITICALdep-
2Entity DesignCRITICALentity-
3Use Case IsolationHIGHusecase-
4Component CohesionHIGHcomp-
5Boundary DefinitionMEDIUM-HIGHbound-
6Interface AdaptersMEDIUMadapt-
7Framework IsolationMEDIUMframe-
8Testing ArchitectureLOW-MEDIUMtest-

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

FileDescription
references/_sections.mdCategory definitions and ordering
assets/templates/_template.mdTemplate for new rules
metadata.jsonVersion and reference information

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free