How to use the JPA/Hibernate Patterns agent skill (jpa-patterns)

What the jpa-patterns skill makes the agent do

A skill is a folder of instructions that an AI agent loads when a task matches its description. The jpa-patterns skill is a single file, SKILL.md, that covers entity design, relationships, query optimization, transactions, auditing, indexing, pagination, and connection pooling in Spring Boot.

When the skill is active, the agent follows its guidance on tasks such as designing entities and table mappings, defining @OneToMany, @ManyToOne and @ManyToMany relationships, preventing N+1 query problems, choosing fetch strategies and projections, configuring transactions, and tuning HikariCP. The skill contains only instructions and code examples. It does not run any programs itself.

Install the jpa-patterns skill

Download the ZIP for the skill from this page and unzip it. You have two options. For a personal skill available in all your projects, unzip it into ~/.claude/skills/. For a skill that only applies to one project, unzip it into that project's .claude/skills/ folder.

You can also upload the skill in the Claude apps. Open Settings, go to Capabilities, then Skills, and upload the ZIP there.

• Personal install: ~/.claude/skills/ (available across projects)
• Project install: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Trigger the skill with natural requests

You do not need a special command. The agent decides to use the skill when your request matches its description, so describe the Spring Boot data-access task in plain language. Mention JPA, Hibernate, Spring Data, entities, queries, pagination, transactions or connection pooling so the match is clear.

Good requests name the specific problem. Include the entity or repository involved and any symptom you see, such as slow pages or many SQL statements in the logs.

• "Review my MarketEntity mapping and tell me where I should add indexes."
• "This list endpoint runs one query per row. Show me how to fix the N+1 problem with JPA."
• "Set up cursor-like pagination for my orders repository in Spring Data JPA."
• "Suggest HikariCP settings for my Spring Boot service and explain the trade-offs."
• "Add auditing with createdAt and updatedAt to my entities."

Examples of what the agent produces

The skill includes concrete patterns the agent can adapt to your code. For auditing, it shows an entity annotated with @EntityListeners(AuditingEntityListener.class) and a configuration class that enables auditing with @EnableJpaAuditing.

For relationships, the guide defaults to lazy loading and suggests a JOIN FETCH query when you need a collection. It also recommends DTO projections for read paths instead of loading full entities.

• Auditing: @CreatedDate and @LastModifiedDate fields with @EnableJpaAuditing enabled.
• Fetch strategy: lazy by default, avoid EAGER on collections, use JOIN FETCH when needed.
• Pagination: PageRequest.of with a sort on createdAt, or an id > :lastId condition for cursor-like paging.
• Connection pool: recommended spring.datasource.hikari properties such as maximum-pool-size=20.

What you need before using it

The skill assumes a Java and Spring Boot project that uses JPA or Hibernate. The examples assume Spring Data JPA. For migrations or query tests you need database access, and the guide suggests Testcontainers for tests.

The skill does not run scripts and does not use the network. Everything it provides is text the agent reads and applies to your code.

• Java and Spring Boot project using JPA/Hibernate
• Spring Data JPA, since the examples depend on it
• Database access for migrations and query tests
• Testcontainers is suggested for tests

Safety notes and review before you apply changes

The skill itself is instructions only, but the advice it gives changes real code and real databases. Pool sizes and index choices depend on your workload, so the values in the guide are starting points, not answers. Check them against your own metrics before deploying.

Do not apply agent suggestions directly to production databases without review. Keep schema changes in migration tools such as Flyway or Liquibase, which the guide recommends over relying on Hibernate auto DDL in production.

• Treat pool sizes and indexes as starting points and verify them with real metrics.
• Review generated migrations before running them against any shared database.
• Ask the agent to show the SQL the query produces, then confirm it in your logs.

Tips for getting better results

Give the agent the entity code and the query or endpoint in question, so it can reason about your actual relationships. To check SQL efficiency, the guide suggests enabling logs with logging.level.org.hibernate.SQL=DEBUG, and logging.level.org.hibernate.orm.jdbc.bind=TRACE to see parameter values.

Ask for a test with @DataJpaTest and Testcontainers when you change a query, so the change is verified against a real database engine.

• Paste the entity and repository code, not just a description.
• Ask for both the query and the SQL logs you would expect to see.
• Ask the agent to explain trade-offs when it recommends a setting.