JPAのN+1問題を減らすときに入れる jpa-patternsスキル

使うとこうなる

jpa-patternsを入れると、エージェントは関連付けの定義と検索処理を一緒に見直し、N+1問題を防ぐ取得方法を提案します。N+1問題とは、一覧を1回取得したあと、各行の関連データを取るためにSQLが行数分だけ追加で発行される状態のことです。たとえば次のように頼みます。

このエンティティの関連付けを見直し、N+1問題を防ぐ取得方法を提案して

エージェントはまず、関連の読み込み方を確認します。スキルの方針は、関連を遅延読み込み（使う時点で取りに行く方式）にそろえ、コレクションにEAGERを付けないことです。親と子をまとめて使う箇所に限って、JOIN FETCHを使ったクエリをリポジトリに足す案が返ってきます。

@Query("select m from MarketEntity m left join fetch m.positions where m.id = :id")
Optional<MarketEntity> findWithPositions(@Param("id") Long id);

一覧画面のように読むだけの処理には、DTO射影を使う案も出ます。DTO射影とは、IDや名前など必要な項目だけを持つ軽い型で結果を受け取る方法です。変更したあとはHibernateのSQLログを出し、発行されるSQLの本数で効果を確かめる流れになります。

jpa-patternsでできること

jpa-patternsは、Spring BootでのJPA/Hibernateの設計から性能調整までを1つの方針でまとめたスキルです。扱う範囲は、エンティティ、リポジトリ、トランザクション、インデックス、接続プールまで。ここからは作業ごとに分けて見ていきます。

データ構造と関連付けを設計する

新しいエンティティでは、テーブル名や列の長さ、必須かどうかをアノテーションで明示するのが基本です。列挙型は文字列で保存し、作成日時と更新日時は監査機能（auditing）で自動記録します。関連は@OneToManyや@ManyToOneなどで定義し、親子の削除連動もこの段階で決めておく方針です。

関連データ取得のSQLを減らす

SQLを減らす手段は、取得方法の指定と射影の2つです。関連は遅延読み込みを基本にし、必要な検索だけJOIN FETCHでまとめて取得します。読み取り専用の画面では、エンティティ全体を返さず、必要な列だけを返す射影を使うのが原則です。

更新処理とトランザクションを見直す

更新はサービス層のメソッドに@Transactionalを付けてまとめます。読むだけのメソッドには@Transactional(readOnly = true)を付け、長く続くトランザクションは避けるのが方針です。トランザクションをまたいでエンティティを持ち回らないことも、見直しの対象に入ります。

ページ分割とインデックスを改善する

一覧検索ではPageRequestで件数と並び順を指定し、Pageで受け取ります。大量データなら、最後に読んだIDより大きい行を順に取るカーソル風のページ分割も選べます。

インデックスを張る先は、状態や外部キーなど、よく絞り込む列です。検索条件と同じ並びの複合インデックスも検討対象になります。

書き込み・接続・テストを整える

複数件の登録は、saveAllとHibernateのバッチ設定でまとめて送ります。接続プールのHikariCPには推奨値が示されています。本番のテーブル変更はFlywayかLiquibaseで管理する方針です。データアクセスのテストには、@DataJpaTestとTestcontainersで本番に近い環境を作る構成が推奨されています。

インストール方法

入れ方は、コマンドで入れる方法とエージェントに頼む方法の2つです。コマンドは次のとおりで、Claude CodeやCodexなど、入れる先のエージェントを選べます。

npx skills add https://github.com/affaan-m/ECC --skill jpa-patterns

エージェントに任せる場合は、次の文面をそのまま送ってください。中身を確認してから配置するよう頼む内容なので、確認の手順を省かずに済みます。

次の Agent Skill をインストールしてください。
https://github.com/affaan-m/ECC/tree/main/skills/jpa-patterns

まず SKILL.md と付属ファイルの中身を確認し、不審な処理（外部への送信、認証情報の読み取りなど）がないことを確かめてから、Claude Code なら ~/.claude/skills/jpa-patterns/、Codex なら ~/.agents/skills/jpa-patterns/ に配置してください。

置き場所は、すべてのプロジェクトで使うか、特定のプロジェクトだけで使うかで変わります。

エージェント	すべてのプロジェクトで使う	特定のプロジェクトだけで使う
Claude Code	~/.claude/skills/	プロジェクトの.claude/skills/
Codex	~/.agents/skills/	プロジェクトの.agents/skills/

jpa-patternsはaffaan-m/ECCリポジトリに含まれるスキルの1つです。ファイルはSKILL.mdだけなので、配置前に全体を読み通せます。

使い方の例

日常の開発でそのまま使える依頼文を3つ紹介します。どれも、スキルを入れたエージェントに日本語で送るだけです。

一覧検索にページ分割を追加し、必要なインデックスを検討して

返ってくるのは、PageRequestで件数と並び順を指定し、Pageを返すリポジトリメソッドの案です。あわせて、絞り込みの列と並び順に合わせた複合インデックス（たとえば状態と作成日時）が提案されます。件数が多い一覧には、IDを基準に続きを取るカーソル風の方式も選択肢として示されます。

注文サービスのトランザクション範囲を確認して、読み取り専用にできるメソッドを教えて

読むだけのメソッドに対して返ってくるのは、readOnly = trueを付ける案です。長く続くトランザクションや、トランザクションをまたいでエンティティを持ち回る書き方があれば、見直し対象として挙がります。伝播設定（トランザクションの引き継ぎ方）を慎重に選ぶよう指摘されるのも特徴でしょう。

リポジトリのテストを書いて、N+1が起きていないかSQLログで確かめられるようにして

この依頼には、@DataJpaTestとTestcontainersを使うテストの案が返ってきます。SQLとバインド値をログに出す次の設定も一緒に示されるので、発行されたSQLの本数を自分の目で確かめられます。

logging.level.org.hibernate.SQL=DEBUG
logging.level.org.hibernate.orm.jdbc.bind=TRACE

注意点

jpa-patternsは、Spring BootとJPA/Hibernateを前提にしたスキルです。別のORMを使う構成やSpring Data JPAを使わない構成には、示されるコード例がそのまま当てはまりません。

本番のテーブル変更はFlywayかLiquibaseで行い、Hibernateの自動DDL（エンティティからテーブルを自動生成する機能）には頼らない方針です。自動DDLで運用しているプロジェクトでは、この前提の違いを踏まえて提案を読む必要があります。マイグレーションは追加型を基本とし、計画なしに列を削除しない点も押さえておきましょう。

接続プールの推奨値は固定の数値で、LOBの設定はPostgreSQL向けです。2次キャッシュも「慎重に検討する」という位置づけなので、自分のデータベースや負荷に合うかを確かめてから使います。

提案された変更は、テストと実際のSQLログで確かめてから取り込むのが安全です。 スキルはMITライセンスで公開されています。インストール前にSKILL.mdの中身を読み、不審な処理がないことを確認してください。

まとめ

jpa-patternsは、Spring BootでJPA/Hibernateを使うエンジニアが、エンティティ設計やN+1問題の対策をエージェントと進めるためのスキルです。関連付け、ページ分割、インデックス、トランザクションを同じ方針で見直せます。提案はテストとSQLログで確かめてから取り込んでください。詳しい情報はcccskills のページにまとめています。