Clean Architecture

Guides applying Clean Architecture and Hexagonal patterns in Java Spring Boot applications.

Updated May 12, 2026
One-click install
npx skills add https://github.com/ZzZueszZ/claude-kit --skill clean-architecture-zzzueszz
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: Clean Architecture
Source: https://github.com/ZzZueszZ/claude-kit/tree/main/.claude/skills/clean-architecture
Command: npx skills add https://github.com/ZzZueszZ/claude-kit --skill clean-architecture-zzzueszz

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Spring Boot projects often suffer from tangled layers where domain logic leaks into controllers, JPA annotations pollute business entities, and framework dependencies make code untestable. This Skill enforces a strict layered architecture so business rules stay independent of frameworks. ## Core Features & Use Cases - Layered Dependency Rules: Defines the Dependency Rule with clear import boundaries across Domain, Application, Infrastructure, and Presentation layers. - Ports & Adapters Patterns: Provides concrete templates for repository adapters, port interfaces, JPA entity separation, and domain-to-JPA mapping. - Testing & Anti-Pattern Guidance: Includes per-layer testing strategies, common mistake examples, a standard package structure, and a compliance checklist. - Use Case: When building a new Spring Boot microservice, use this Skill to scaffold the correct package structure, keep domain entities free of JPA/Spring annotations, and implement repository adapters that map between domain and persistence models. ## Quick Start Ask the AI to review or generate a Spring Boot feature following Clean Architecture with separated domain, application, infrastructure, and presentation layers.

Frequently Asked Questions about Clean Architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I apply Clean Architecture in a Spring Boot project?▼

Organize code into four layers: domain (pure entities and repository interfaces), application (use case services and ports), infrastructure (JPA entities and adapters), and presentation (REST controllers). Dependencies must only point inward, with the domain layer importing no framework code.

What is the difference between a domain entity and a JPA entity?▼

A domain entity contains business logic and uses only Java core types with no framework annotations. A JPA entity carries @Entity, @Table, and @Column annotations for persistence. A repository adapter maps between the two so the domain stays framework-independent.

Can the domain layer use Spring or JPA annotations in Clean Architecture?▼

No. The domain layer must not import Spring, JPA, Jackson, or web classes. Only Java core and Lombok annotations like @Getter and @Builder are allowed, keeping business rules independent of frameworks and fully unit-testable without mocks.

When should I create a port interface in the application layer?▼

Create a port for any external dependency: database access, external APIs like payment or email, messaging systems, file storage, or authentication providers. Internal logic, in-memory calculations, and pure domain behavior do not need ports.

Why is putting business logic in the service layer a mistake?▼

Application services should only orchestrate use cases, not contain business rules. Rules like stock validation or order submission belong in domain entity methods, producing rich domain models instead of anemic ones and keeping logic reusable and testable.