hexagonal-architecture-layers-java — Claude Code skill
The hexagonal-architecture-layers-java skill structures Java services around Domain, Application, and Infrastructure layers. Use it for new services or Spring refactoring.
MIT 250 installs ★ 678 updated 2026-03-28
npx skills add Gentleman-Programming/Gentleman-Skills --skill hexagonal-architecture-layers-java -a claude-codeWhat hexagonal-architecture-layers-java does
This skill sets boundaries for hexagonal architecture in Java services. The Domain layer keeps business rules free from framework annotations, persistence details, and I/O. Application defines use cases and ports, invokes domain logic, and sends external work through those ports.
Infrastructure supplies port implementations and connects adapters such as controllers, repositories, and clients. The material includes examples for an Order model, input and output ports, a use-case service, and a Spring JPA adapter with wiring. It also flags direct domain dependencies on Spring repositories and JPA annotations.
A domain class that carries Spring annotations or calls a repository directly breaks the intended dependency direction. The skill is also suited to designs with several adapters, such as REST alongside messaging or JPA alongside Mongo.
What it helps with
- split a Java service into Domain, Application, and Infrastructure
- define input and output ports around a use case
- remove Spring, JPA, and I/O concerns from the domain
- connect REST, messaging, JPA, or Mongo through adapters
Example prompts for the agent
- Restructure this Java service into Domain, Application, and Infrastructure layers.
- Check whether the domain depends on Spring annotations, JPA, or direct I/O.
- Move order persistence behind an output port and an infrastructure adapter.
How to install hexagonal-architecture-layers-java
1Skills CLI (Vercel)
npx skills add Gentleman-Programming/Gentleman-Skills --skill hexagonal-architecture-layers-java -a claude-code2Manually: put the files in place
~/.claude/skills/hexagonal-architecture-layers-java/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/hexagonal-architecture-layers-java/
1Skills CLI (Vercel)
npx skills add Gentleman-Programming/Gentleman-Skills --skill hexagonal-architecture-layers-java -a codex2Manually: put the files in place
.agents/skills/hexagonal-architecture-layers-java/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add Gentleman-Programming/Gentleman-Skills --skill hexagonal-architecture-layers-java -a cursor2Manually: put the files in place
.cursor/skills/hexagonal-architecture-layers-java/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install Gentleman-Programming/Gentleman-Skills community/hexagonal-architecture-layers-java/SKILL.md2Manually: put the files in place
.github/skills/hexagonal-architecture-layers-java/SKILL.md1Skills CLI (Vercel)
npx skills add Gentleman-Programming/Gentleman-Skills --skill hexagonal-architecture-layers-java -a gemini-cli2Platform CLI
gemini skills install https://github.com/Gentleman-Programming/Gentleman-Skills --path community/hexagonal-architecture-layers-javaManually: put the files in place
.devin/skills/hexagonal-architecture-layers-java/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add Gentleman-Programming/Gentleman-Skills --skill hexagonal-architecture-layers-java -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about hexagonal-architecture-layers-java
How do I install hexagonal-architecture-layers-java in Claude Code?
Run npx skills add Gentleman-Programming/Gentleman-Skills --skill hexagonal-architecture-layers-java -a claude-code, then check ~/.claude/skills/hexagonal-architecture-layers-java/SKILL.md.
What does hexagonal-architecture-layers-java do?
It guides Java service design with separate Domain, Application, and Infrastructure layers, using ports and adapters while pointing out dependency-boundary mistakes.
Can this skill handle multiple adapters?
Yes. Its patterns cover combinations such as REST with messaging and JPA with Mongo, connected through application ports and infrastructure adapters.
Source text
SKILL.md · MIT
---
name: hexagonal-architecture-layers-java
description: >
Hexagonal architecture layering for Java services with strict boundaries.
Trigger: When structuring Java apps by Domain/Application/Infrastructure, or refactoring toward clean architecture.
metadata:
author: diegnghrmr
version: "1.0"
---
## When to Use
Load this skill when:
- Designing a new Java service with clean, testable layers
- Refactoring Spring code to isolate the domain from frameworks
- Supporting multiple adapters (REST + messaging, JPA + Mongo)
- Enforcing dependency direction and clear module boundaries
## Critical Patterns
### Pattern 1: Domain is pure
Domain has no framework annotations, no persistence concerns, and no I/O.
### Pattern 2: Application orchestrates
Application defines use cases and ports, calling domain logic and delegating I/O to ports.
### Pattern 3: Infrastructure adapts
Infrastructure implements ports and wires adapters (controllers, repositories, clients).
## Code Examples
### Example 1: Domain model + output port
```java
package com.acme.order.domain;
public record OrderId(String value) { }
public final class Order {
private final OrderId id;
private final Money total;
public Order(OrderId id, Money total) {
this.id = id;
this.total = total;
}
public OrderId id() { return id; }
public Money total() { return total; }
}
```
```java
package com.acme.order.application.port;
import com.acme.order.domain.Order;
import com.acme.order.domain.OrderId;
public interface OrderRepositoryPort {
OrderId nextId();
void save(Order order);
}
```
### Example 2: Application use case + input port
```java
package com.acme.order.application.usecase;
import com.acme.order.application.port.OrderRepositoryPort;
import com.acme.order.domain.Order;
import com.acme.order.domain.OrderId;
import com.acme.order.domain.Money;
public interface PlaceOrderUseCase {
OrderId place(Money total);
}
public final class PlaceOrderService implements PlaceOrderUseCase {
private final OrderRepositoryPort repository;
public PlaceOrderService(OrderRepositoryPort repository) {
this.repository = repository;
}
@Override
public OrderId place(Money total) {
OrderId id = repository.nextId();
Order order = new Order(id, total);
repository.save(order);
return id;
}
}
```
### Example 3: Infrastructure adapter + wiring
```java
package com.acme.order.infrastructure.persistence;
import com.acme.order.application.port.OrderRepositoryPort;
import com.acme.order.domain.Order;
import com.acme.order.domain.OrderId;
import org.springframework.stereotype.Repository;
@Repository
public final class OrderJpaAdapter implements OrderRepositoryPort {
private final SpringOrderRepository repository;
private final OrderMapper mapper;
public OrderJpaAdapter(SpringOrderRepository repository, OrderMapper mapper) {
this.repository = repository;
this.mapper = mapper;
}
@Override
public OrderId nextId() {
return new OrderId(java.util.UUID.randomUUID().toString());
}
@Override
public void save(Order order) {
repository.save(mapper.toEntity(order));
}
}
```
## Anti-Patterns
### Don't: Put framework annotations in domain
```java
// BAD: domain tied to JPA
@jakarta.persistence.Entity
public class Order {
@jakarta.persistence.Id
private String id;
}
```
### Don't: Call infrastructure directly from domain
```java
// BAD: domain depends on Spring repository
public class Order {
private final SpringOrderRepository repository;
}
```
## Quick Reference
| Task | Pattern |
|------|---------|
| Persist domain data | Define output port in application, implement in infrastructure |
| Expose use case | Define input port and service in application |
| Keep domain pure | No annotations, no I/O, no framework imports |
## Resources
- Hexagonal Architecture: https://alistair.cockburn.us/hexagonal-architecture/
- Clean Architecture: https://www.oreilly.com/library/view/clean-architecture/9780134494272/
© diegnghrmr · MIT · Gentleman-Programming/Gentleman-Skills