元記事: JPAのN+1問題を減らすときに入れる jpa-patternsスキル（cccskills）
スキルのページ: jpa-patterns
この記事の結論
jpa-patternsを入れると、Spring Bootで開発するエンジニアは、JPA/Hibernateのエンティティ設計やN+1問題の対策をAIエージェントと一緒に進められます。
この記事では、依頼したときに返ってくる内容、インストール方法、依頼文の例を順に紹介します。
最後は、提案を取り込む前に確かめておきたい点です。
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は、Spring BootでのJPA/Hibernateの設計から性能調整までを1つの方針でまとめたスキルです。
扱う範囲は、エンティティ、リポジトリ、トランザクション、インデックス、接続プールまで。
ここからは作業ごとに分けて見ていきます。
新しいエンティティでは、テーブル名や列の長さ、必須かどうかをアノテーションで明示するのが基本です。
列挙型は文字列で保存し、作成日時と更新日時は監査機能（auditing）で自動記録します。
関連は@OneToManyや@ManyToOneなどで定義し、親子の削除連動もこの段階で決めておく方針です。
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の中身を読み、不審な処理がないことを確認してください。
自動で直るわけではありません。
エージェントが遅延読み込みやJOIN FETCH、射影を使った取得方法を提案し、取り込むかどうかは開発者が決めます。
取り込んだあとは、SQLログで本数を確かめてください。
対象はSpring BootでのJPA/Hibernateです。
コード例はSpring Data JPAのリポジトリや@Transactionalを前提にしているため、それ以外の構成ではそのまま使えません。
使えます。
新しいエンティティの設計だけでなく、既存の関連付けや検索・更新処理の見直しも対象です。
一覧表示で大量のSQLが出ている箇所から頼むと、SQLログで効果を比べやすくなります。
jpa-patternsは、Spring BootでJPA/Hibernateを使うエンジニアが、エンティティ設計やN+1問題の対策をエージェントと進めるためのスキルです。
関連付け、ページ分割、インデックス、トランザクションを同じ方針で見直せます。
提案はテストとSQLログで確かめてから取り込んでください。
詳しい情報はcccskills のページにまとめています。
この記事は cccskills の読みもの「JPAのN+1問題を減らすときに入れる jpa-patternsスキル」の転載です。
スキルの詳細とインストール方法は cccskills の jpa-patterns のページ にあります。