ddd-repository-placement

Guides placement of repository interfaces in the use case layer of clean architecture.

Updated Jun 23, 2026
One-click install
npx skills add https://github.com/j5ik2o/marp-ai-base --skill ddd-repository-placement-j5ik2o
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: ddd-repository-placement
Source: https://github.com/j5ik2o/marp-ai-base/tree/main/.agents/skills/ddd-repository-placement
Command: npx skills add https://github.com/j5ik2o/marp-ai-base --skill ddd-repository-placement-j5ik2o

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Deciding where to place repository interfaces in a DDD or clean architecture codebase is a recurring design debate, and placing them in the domain layer often leads to unwanted coupling between domain models and persistence concerns. This Skill explains why repository interfaces belong in the use case layer and how structure enforces that design intent. ## Core Features & Use Cases - Placement Rationale: Explains why repository interfaces should live in the use case layer (as output ports) rather than the domain layer, preventing domain models from depending on persistence. - Detection Patterns: Shows directory-structure symptoms of misplaced repositories, such as OrderRepository.java sitting in the domain or interface-adapter layers, and the correct layout. - Review Checklist: Provides concrete checks for placement, domain-to-repository imports, and aggregate ID-based referencing. - Use Case: While reviewing a Java clean architecture project, you notice domain services accumulating injected repositories. Use this Skill to justify moving the interfaces to the use case layer and to enforce aggregate ID references. ## Quick Start Ask the AI where repository interfaces should be placed in a clean architecture project and have it review your package structure for misplaced repositories.

Frequently Asked Questions about ddd-repository-placement

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

FAQPage Schema
Where should repository interfaces go in clean architecture?

Repository interfaces should be placed in the use case layer as output ports, not in the domain layer. This keeps domain models free of persistence concepts and makes the dependency direction explicit in the package structure.

Why is putting repositories in the domain layer a problem?

Physical proximity invites coupling: aggregates and domain services start calling repositories directly, and the domain layer becomes aware of save and find operations. Domain models should contain only pure business rules.

Does DDD require repositories to be in the domain layer?

Traditional DDD treats repositories as part of the domain since they manage aggregate lifecycles. In practice, clean architecture conventions place the interface in the use case layer to keep dependencies clear, accepting a deviation from DDD orthodoxy.

How do I detect misplaced repository interfaces in my project?

Check whether files like OrderRepository.java sit under domain/ or interface-adapters/ packages. The correct layout defines the interface in the use case layer and places implementations like JpaOrderRepository in the infrastructure or adapter layer.

How should aggregates reference other aggregates without repositories?

Aggregates should reference other aggregates by ID, such as storing a CustomerId instead of the Customer entity. The use case layer then uses repositories to resolve those IDs into entities when needed.