Member-only story

| AI | Hexagonal Architecture | Open Source |

How to Write AI Instructions That Actually Work with Hexagonal Architecture

Stop writing generic prompts. Use a structured Ports & Adapters template to generate production-ready Java/Spring Boot code with any LLM

--

Press enter or click to view image in full size

Introduction

Have you ever asked an AI to create a Spring Boot use case and got something like this?

@RestController
public class OrderController {

    @Autowired
    private OrderRepository repository; // 😱

    @PostMapping("/orders")
    public Order createOrder(@RequestBody OrderRequest request) {
        // business logic straight inside the controller
        if (request.getAmount() <= 0) {
            throw new RuntimeException("Invalid amount");
        }
        return repository.save(new Order(request));
    }
}

Controller calling the repository directly. Business logic is in the wrong place. No ports, no separation, nothing. The code even compiles — and that’s exactly what makes it dangerous.

The mistake here is not the AI’s. It’s yours.

Not your intelligence — the way you’re supplying context. An AI with no architectural context will generate the…