Back to Skills

clean-architecture

Provides implementation patterns for Clean Architecture, Hexagonal Architecture (Ports & Adapters), and Domain-Driven Design in Java 21+ Spring Boot 3.5+ applications. Use when structuring layered architectures, separating domain logic from frameworks, implementing ports and adapters, creating entities/value objects/aggregates, or refactoring monolithic codebases for testability and maintainability.

311stars36forksUpdated 7/25/2026

Security Assessment

Safe(95/100)
Security Score95/100

About clean-architecture

This skill provides implementation patterns for Clean Architecture, Hexagonal Architecture (Ports & Adapters), and Domain-Driven Design tactical patterns in Java 21+ and Spring Boot 3.5+ applications. It addresses the problem of tightly coupled, hard-to-test codebases by teaching clear separation of concerns, framework-independent domain logic, and disciplined dependency management so business rules do not depend on Spring or infrastructure.

The skill explains the layered dependency rule (Domain, Application, Infrastructure, Adapter) with the Spring Boot equivalents for each layer, and a feature-based package structure separating domain models, ports (driving and driven), application services, DTOs, persistence adapters, and REST controllers. Its reference files provide concrete, framework-free Java patterns: records for immutable value objects with validation, sealed interfaces for domain events, strongly-typed IDs to prevent ID confusion, factory methods that enforce invariants, a Result type for explicit success/failure handling without exceptions, builder patterns for complex aggregates, and domain-service patterns for logic that spans entities. A companion reference covers the Spring Boot implementation side — JPA entities and repository adapters, application services annotated with `@Service` and `@Transactional`, and domain-event publishing.

Target users are Java and Spring Boot developers and architects who are structuring new applications, refactoring monoliths for testability, implementing swappable ports and adapters, or applying DDD tactical patterns such as entities, value objects, and aggregates. It is a guidance-and-pattern reference skill: it teaches conventions and supplies example code rather than automating a build or deployment.

FAQ

What languages and frameworks does this skill assume?

Java 21+ and Spring Boot 3.5+, using modern language features like records and sealed interfaces.

What architectural patterns does it cover?

Clean Architecture layering with the dependency rule, Hexagonal Architecture (Ports & Adapters), and Domain-Driven Design tactical patterns including entities, value objects, aggregates, domain events, and repositories.

How does it keep domain logic framework-independent?

It places the domain layer with zero Spring dependencies, uses records for value objects, defines repository interfaces (ports) in the domain, and keeps business logic in entities via a rich domain model, with adapters implementing infrastructure concerns.

When is this skill most useful?

When architecting new Spring Boot apps, refactoring tightly coupled code into testable layers, designing swappable ports and adapters, or creating testable business logic without a Spring context.

Does it generate a full application?

It focuses on patterns, package organization, and example code across its SKILL.md and two reference files; it guides implementation rather than scaffolding a complete deployable project.

All Files

3 files
references/java-clean-architecture.md8.4 KB
View
SKILL.md15.8 KB
View
references/spring-boot-implementation.md11.8 KB
View

Install clean-architecture

Download and extract the skill files to your .claude/skills/ directory.

Quick Setup:

  1. Copy the skill folder to .claude/skills/
  2. Claude will automatically detect and use the skill