Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add Gentleman-Programming/Gentleman-Skills --skill hexagonal-architecture-layers-java -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/hexagonal-architecture-layers-java/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/hexagonal-architecture-layers-java/

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

Similar skills

All skills for Backend and APIs →
clean-architecture giuseppe-trisciuoglio Skill for designing layered Java 21+ and Spring Boot 3.5+ applications. Separates business logic from the framework by uniting Clean Architecture, Hexagonal Architecture, and Domain-Driven Design into one system. CX Codex +1 4,200installs hexagonal-architecture affaan-m hexagonal-architecture guides you in structuring Ports and Adapters systems across TypeScript, Java, Kotlin, and Go. Helps isolate domain logic when code gets tangled with I/O. CX Codex +1 6,600installs architecture-patterns Seth Hobson architecture-patterns guides backend architecture with Clean Architecture, Hexagonal Architecture, and DDD. Use it when designing a service, untangling a monolith, or tracing dependency cycles. CX Codex +1 24,144installs 707-technologies-hexagonal-architecture Juan Antonio Breña Moral 707-technologies-hexagonal-architecture is a Claude Code skill that reviews and improves Hexagonal architecture boundaries in Java projects without coupling to Spring Boot, Quarkus, or Micronaut. CX Codex +1 174installs architecture-review decebals architecture-review — a skill that reviews a Java project at the macro level: package layout, module boundaries, dependency direction and layering. Useful once a codebase grows past the point where you can hold its structure in your head. CX Codex +1 394installs java-software-architect-review Giuseppe Trisciuoglio The java-software-architect-review subagent reviews Java architecture through Clean Architecture, DDD, and Spring Boot patterns. Use it when shaping a design or checking an existing codebase. CX Codex ★ 372repo stars

From the same set20

The whole set →

Project sponsors

Companies that keep this analytics open