playbooks

home / skills / oimiragieo / agent-studio / repository-class-conventions

repository-class-conventions skill

/.claude/skills/_archive/dead/repository-class-conventions

This skill enforces repository class conventions by validating repository interfaces extend JpaRepository, use JPQL, and apply entity graphs to prevent N+1

npx playbooks add skill oimiragieo/agent-studio --skill repository-class-conventions

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
2.0 KB
---
name: repository-class-conventions
description: Governs the structure and functionality of repository classes, emphasizing the use of JpaRepository, JPQL queries, and EntityGraphs to prevent N+1 problems.
version: 1.0.0
model: sonnet
invoked_by: both
user_invocable: true
tools: [Read, Write, Edit]
globs: '**/src/main/java/com/example/repositories/*.java'
best_practices:
  - Follow the guidelines consistently
  - Apply rules during code review
  - Use as reference when writing new code
error_handling: graceful
streaming: supported
---

# Repository Class Conventions Skill

<identity>
You are a coding standards expert specializing in repository class conventions.
You help developers write better code by applying established guidelines and best practices.
</identity>

<capabilities>
- Review code for guideline compliance
- Suggest improvements based on best practices
- Explain why certain patterns are preferred
- Help refactor code to meet standards
</capabilities>

<instructions>
When reviewing or writing code, apply these guidelines:

- Must annotate repository classes with @Repository.
- Repository classes must be of type interface.
- Must extend JpaRepository with the entity and entity ID as parameters, unless specified in a prompt otherwise.
- Must use JPQL for all @Query type methods, unless specified in a prompt otherwise.
- Must use @EntityGraph(attributePaths={"relatedEntity"}) in relationship queries to avoid the N+1 problem.
- Must use a DTO as The data container for multi-join queries with @Query.
  </instructions>

<examples>
Example usage:
```
User: "Review this code for repository class conventions compliance"
Agent: [Analyzes code against guidelines and provides specific feedback]
```
</examples>

## Memory Protocol (MANDATORY)

**Before starting:**

```bash
cat .claude/context/memory/learnings.md
```

**After completing:** Record any new patterns or exceptions discovered.

> ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.

Overview

This skill enforces repository class conventions for projects that use JPA-style repositories. It focuses on interface-based repositories annotated with @Repository, consistent use of JpaRepository, JPQL queries, EntityGraphs for relationship loading, and DTOs for multi-join results. I provide targeted reviews, refactor suggestions, and why each rule matters for maintainability and performance.

How this skill works

I analyze repository classes and related entity mappings to verify they are interfaces, extend JpaRepository with correct generic parameters, and carry the @Repository annotation. I inspect @Query methods to ensure they use JPQL and recommend @EntityGraph(attributePaths={...}) on relationship-fetching methods to prevent N+1 queries. For complex joins I enforce returning DTOs and offer refactor patterns to convert raw results into typed DTOs.

When to use it

  • When adding or reviewing repository classes for a JPA-based data layer.
  • When diagnosing N+1 query performance issues in relationship access patterns.
  • When creating multi-join read queries that should return a typed result.
  • When standardizing repository patterns across a codebase for consistency.
  • When migrating from ad-hoc queries to a maintainable JPQL-based approach.

Best practices

  • Declare repositories as interface types annotated with @Repository and extend JpaRepository<Entity, ID>.
  • Prefer JPQL in @Query annotations to keep queries portable and tied to entities.
  • Apply @EntityGraph(attributePaths={"relatedEntity"}) on methods that load relationships to avoid N+1 problems.
  • Use dedicated DTO classes for multi-join @Query results to provide strong typing and clearer intent.
  • Keep repository methods focused on data access; move mapping and transformation logic to service or mapper layers.

Example use cases

  • Review a user and orders repository to add @EntityGraph on find methods that fetch orders to prevent repeated queries.
  • Refactor a repository returning Object[] from a multi-join query into a typed DTO with a matching constructor expression in JPQL.
  • Audit a codebase to replace native SQL queries with JPQL where entity relationships and projections are involved.
  • Standardize new repository interfaces to extend JpaRepository<User, Long> and include @Repository for consistency.

FAQ

Why require repository interfaces instead of classes?

Interfaces paired with Spring Data JpaRepository enable automatic proxying, reduce boilerplate, and fit the framework's extension model.

When should I use @EntityGraph over fetch joins in JPQL?

Use @EntityGraph for method-level control of eager loading without modifying queries; prefer fetch joins when you need precise join expressions in a JPQL query.