受注一覧の表示が遅いという問い合わせを受け、保守担当者が検証環境でAPIを呼び出します。エラーは出ていません。返ってくる受注も正しそうですが、SQLログを見ると、顧客情報を取得する似たクエリが繰り返されています。ここでは、こうした受注一覧APIのN+1クエリを解消する業務を、Claude Codeで補助する方法を取り上げます。以下のAPI、データ構造、依頼文は実務への応用を考えるための架空の例であり、実際の改修・計測結果ではありません。

想定するのは、受注と顧客を別テーブルで管理する業務システムです。一覧には受注番号、受注日、顧客名を表示し、ログイン利用者が所属する企業の受注だけを返します。担当者はエディター、SQLログ、既存のAPIテスト、検証用DBを使い、リクエスト条件を再現してから実装を調べる前提です。Gitでの差分確認、SQL、APIテスト、企業ごとのデータ分離を理解している開発者を対象とします。

AIを使わない場合も、検索やテストの道具は利用できます。担当者はログから繰り返しを見つけ、ルーティングからサービス層、データ取得処理、レスポンス生成処理へと呼び出しを追います。その後、一括取得への変更を設計し、既存の応答形式や認可条件を保てるか検証します。手間の中心は、コードを書くことだけではありません。複数のファイルから根拠を集め、修正対象と変更してはいけない条件を結び付ける作業にもあります。



Claude Codeの公式資料には、関連コードの探索、バグ修正、リファクタリング、テスト作成に使う依頼パターンが掲載されています。本記事ではその使い方を、受注一覧の調査と小さな改修に応用します。N+1専用の自動修復機能があるという説明ではありません。（出典: Claude Code Docs）

N+1とは、一覧を取得する処理に加え、各行の関連情報を個別に取得することでクエリが増える構造です。架空の実装では、受注一覧を取得した後、ループ内で顧客を検索しているとします。キャッシュや遅延読み込みの挙動によって実際の発行回数は変わるため、コードの見た目だけで原因を確定してはいけません。どのリクエストで、どのSQLが、どの呼び出しから繰り返されたかを対応付けます。

担当者が行う調査は、ログの分類、関連コードの探索、変更案の比較、テスト条件の整理に分けられます。Claude Codeには、このうちファイルをまたぐ探索と、根拠を添えた変更案の下書きを補助させます。人が先に「このループを消す」と決めるより、繰り返しの発生箇所と取得条件を報告させた方が、別の関連取得まで見落としにくいでしょう。ただし、報告されたファイルや処理は担当者が実際に確認します。

| 工程 | AIを使わない場合 | Claude Codeを使う場合 | 人が残す判断 |
| --- | --- | --- | --- |
| 原因調査 | ログと呼び出し元を照合します | 関連箇所と根拠の整理を補助させます | 再現条件と原因を確定します |
| 改修 | 一括取得の差分を作成します | 限定した差分の作成を依頼します | 取得条件と設計を承認します |
| 検証 | テストを追加して結果を読みます | 既存形式に沿うテスト案を依頼します | 期待値と実行結果を確認します |



比較する入力は同じSQLログ、同じソースコード、同じAPI仕様です。成果物も、改修差分、回帰テスト、検証記録にそろえます。AIを使う側だけ応答の互換性確認を省くと、公平な工程比較にはなりません。探索の往復が減っても、誤った提案の修正に時間がかかる場合があります。依頼範囲を原因調査、実装、検証に区切り、それぞれの終了条件を明確にすることが、この使い方の要点です。

実践には、Claude Codeを利用できる開発環境と、既存の起動・テスト手順が分かるリポジトリを用意します。本記事では導入済みの環境を前提とし、インストール方法や利用プランは扱いません。まず担当者が通常の手順で検証環境を動かし、対象APIが再現できることを確かめます。起動できない状態から性能改修までまとめて依頼すると、環境修復と業務ロジックの変更が混ざり、レビューの範囲が広がります。

作業対象は、架空の受注一覧と顧客名の取得処理に限定します。API仕様には、返却フィールド、並び順、ページサイズ、顧客が参照できない場合の表示を記します。検証データは、同じ顧客に複数の受注がある企業、別の企業、顧客を参照できない受注、ページ境界で受注日が重なるケースを含める提案です。個人情報や本番の接続情報を持ち込まず、人工的な顧客名と注文番号を使ってください。



変更前の記録には、対象コミット、DBの状態、リクエスト条件、HTTPステータス、応答本文、SQLの種類と回数、応答時間を残します。SQLログは対象リクエストの範囲を区別し、ヘルスチェックなどの別処理を混ぜないようにします。応答時間はキャッシュ、接続の初期化、他の処理の負荷にも左右されるため、初回と繰り返し実行を区別する条件も決めます。

Claude Codeへ渡す説明には、既存のテストコマンドと実行可能な環境を明記します。分からないコマンドを推測させず、リポジトリ内の説明や設定から確認させる方針です。完了条件は「速くする」では足りません。「レスポンス仕様、認可、並び順を維持し、一覧件数に比例する顧客の個別取得をなくす」と書けば、何を変え、何を維持するのかがレビュー可能になります。これらは本記事で提案する作業条件であり、製品が自動的に保証するものではありません。

操作は、調査依頼、計画確認、限定した実装依頼、結果確認の四段階に分けます。開発リポジトリを対象にしたClaude Codeの会話で、準備したAPI仕様、匿名化済みSQLログ、テスト手順の場所を伝えてください。公式資料では、関連ファイルやディレクトリを渡すための「@」参照と、編集前に調査・計画を行うplan modeが案内されています。必要に応じて、編集前の検討に利用できます。（出典: Claude Code Docs）

コピーして使う調査依頼の例です。山括弧の部分を実在するパスに置き換えます。依頼文による作業範囲の指定と、開発環境側のアクセス制御は別に管理してください。

受注一覧APIのN+1を調査してください。
対象仕様: <API仕様のパス>
SQLログ: <匿名化済みログのパス>
テスト手順: <既存の手順書のパス>

今回は調査と計画だけを行い、ファイルは変更しないでください。
入口からレスポンス生成までを追い、繰り返しSQLの発生箇所を、
ファイルと処理の根拠を添えて示してください。
企業ごとの認可条件、ページ分割、並び順への影響を整理してください。
最小の修正案、追加するテスト、実行する既存コマンドを提案してください。
不明点と未実行の確認項目は分けて報告してください。

計画を読んだ担当者は、受注のページを確定してから、そのページ内の顧客IDを重複なく集め、一括取得できるかを検討します。架空の変更案では、取得した顧客をIDで引ける対応表にし、元の受注順でレスポンスを組み立てます。顧客取得には、既存の企業条件と参照権限を引き継ぎます。受注に複数の子レコードを結合してからページ分割すると、受注の重複や欠落を招くことがあるため、単純な結合が常に適切とは限りません。



計画を承認した後に使う、実装依頼の例です。

確認した計画の範囲で実装してください。
対象は受注一覧の顧客取得と、それを検証するテストです。
ページ内の顧客IDをまとめて取得し、既存の認可条件を維持してください。
応答形式、受注の並び順、顧客を参照できない場合の仕様は変更しません。
依存関係の更新やスキーマ変更が必要なら、実装を進めず理由を報告してください。

既存の形式に沿って回帰テストを追加し、確認した手順で実行してください。
変更ファイル、実行コマンド、結果、未確認事項を分けて報告してください。
コミット、プッシュ、デプロイは行わないでください。

期待する成果物は、限定した改修差分、変更前に問題を捉えられるテスト、実行記録です。「解消しました」という回答だけでは完了にしません。テストを実行できなかった場合は、その制約を引き継いで担当者の検証へ進みます。

レビューでは、クエリ数が減ったことと、APIが正しく動くことを別々に確認します。一括取得で最も避けたいのは、必要な絞り込みまで外してしまう変更です。受注検索に企業条件があっても、顧客検索で別企業の情報を参照できないかを確認します。企業ごとにIDの扱いが異なる設計なら、対応表のキーもIDだけで十分か検討が必要でしょう。顧客に個別の閲覧権限がある場合は、その条件も維持します。

取得結果のテストでは、受注ID、顧客名、件数、並び順、ページ情報を既存仕様と照合します。変更前の応答は比較材料になりますが、正しさの唯一の根拠にはしません。仕様上の期待値も用意し、以前からある不具合を固定していないかを確認します。同じ顧客への受注が複数あるケースは、一括取得後に受注まで重複排除していないかを見るために役立ちます。



ページ分割は、先頭ページだけでは判断できません。次ページとの間に重複や欠落がないか、同じ受注日が並ぶ場合に既存の補助的な並び順が保たれるかを確認します。顧客が存在しない場合や権限上参照できない場合も、既存仕様どおりの応答になる必要があります。空の一覧では顧客取得が不要になることも含め、境界条件をテストします。

公式資料では、Claude Codeにテスト作成を依頼する際は、検証したい振る舞いを具体的に伝え、既存のテスト形式に合わせる使い方が説明されています。この方針を使い、期待値を人が指定してから差分を確認します。（出典: Claude Code Docs）

クエリ数の検証は、顧客を一件ずつ取得する処理が件数に比例して増えないかを見る形にします。API全体では認証や総件数取得のSQLもあり得るため、根拠なく総数を固定しません。AIが追加したテスト自体もレビューし、認可を省いたモックだけで通っていないか、テスト用の設定が本番相当の挙動を隠していないかを確かめます。

改修後は、変更前に保存したデータとリクエスト条件で検証します。データを初期状態へ戻す方法をそろえ、対象コミット、ページサイズ、フィルター、利用者の権限を記録してください。応答本文の確認を済ませたうえで、対象リクエスト内のSQL回数と応答時間を測ります。実行順やキャッシュ条件も記録すれば、コード差分による変化と環境の揺れを区別しやすくなります。

SQLの往復が減っても、応答時間が同じ割合で短くなるとは限りません。一括取得の対象が増えれば、DB側の処理やアプリケーションのメモリ使用が変わる可能性もあります。代表的なページサイズと、許容範囲の大きなページサイズを分けて確認する方法が考えられます。差が安定しないときは、都合のよい一回を採用せず、繰り返した結果の分布や実行条件を残すべきでしょう。本記事では実測していないため、削減率や応答時間の改善幅は示しません。



AI活用の効果は、APIの性能とは別に評価します。仕様とログを整理する準備、調査結果を読む作業、依頼の修正、コードレビュー、テスト、最終承認までを記録してください。関連コードの探索とテスト案の下書きが減っても、前提の伝達や誤った差分の修正が増えれば、作業全体の負担は減らないことがあります。過去の作業記録と比べる場合も、対象の複雑さや担当者の習熟度の違いを併記します。

最初に試す範囲は、検証環境で再現できる受注一覧一本に絞るのが現実的です。SQLログとレスポンスの基準を保存し、Claude Codeには調査だけを依頼してください。その報告が実際のコードと一致し、認可やページ分割への影響を説明できていれば、限定した実装へ進めます。人が承認する対象を小さな差分と検証記録にそろえることで、自社の保守業務で任せられる工程を判断できます。

- Common workflows - Claude Code Docs

参照内容は、2026年11月6日取得の提供資料に基づきます。取得日は機能の公開日を意味しません。