「このバグを直して」とAIに頼んだだけなのに、なかなか修正が始まらない。
気づけばAIは、たくさんのファイルを開き、同じ場所を何度も検索し、最後には「影響範囲が広いため確認が必要です」と答えている。
皆さんも、こんな経験はありませんか？
AIコーディングを始めたばかりの頃は、驚くほど速く感じます。ところが、プロジェクトが大きくなると、同じくらいの修正でも時間がかかるようになります。回答がずれたり、関係のない場所を壊したりすることも増えてきます。
実は、AIの性能だけが原因とは限りません。
AIが変更前に読み解かなければならない情報が増えているのかもしれません。
この記事では、1つの修正のためにAIが読む量を IRV（Issue Reading Volume） と呼びます。呼び方は新しいですが、見ているのは実務でおなじみの「変更前の調査範囲」です。
AIコーディングの速さを保つには、変更ごとの調査範囲を小さく保つ。
この記事では、身近な例を見ながら、IRVの考え方と、次の開発から試せる改善方法を紹介します。
この記事でわかること
この記事を読むことで、次のことがわかります。
- AIへの修正依頼が、だんだん遅くなる理由
- AIが変更前に読み解く情報量を確認する方法
- ファイルを減らさずに、AIが読む範囲を小さくする方法
- やってはいけないIRVの減らし方
- 次のIssueですぐに使えるチェックリスト
それでは、身近なチャットアプリの例から見ていきましょう。
AIへの修正依頼、前より遅くなっていませんか？
開発を始めたばかりの頃
たとえば、AIに「メッセージ送信のバグを直して」と頼んだとします。
開発初期の処理は単純です。メッセージを受け取り、AIモデルへ送り、結果を保存して表示する。この段階なら、AIが読むのは送信処理とテストだけです。必要な情報が少ないため、すぐに修正へ進めます。
数か月後の同じプロジェクト
運用を続けると、いろいろな機能が加わります。
- 通信に失敗したときの再試行
- 画面を開き直したときの再接続
- 二重送信の防止
- ユーザーごとの利用制限
- 課金と監査ログ
- 古いバージョンとの互換性
すると、「メッセージ送信を直す」という同じ依頼でも、AIは多くのことを確認しなければなりません。
| 確認すること | 開発初期 | 機能が増えた後 |
|---|---|---|
| 読む処理 | 送信処理 | 送信・再試行・保存・課金など |
| 状態の場所 | ほぼ1か所 | 複数の場所から更新される |
| テスト | 数本 | 多くの機能へ影響する |
| AIの作業 | すぐ修正 | まず探索と影響確認 |
機能が増えること自体は悪くありません。
問題は、1つの変更を判断するために、関係する機能の中身を毎回すべて読まなければならないことです。
IRVとは何か？難しい指標なの？
IRVは、1つのIssueを理解し、修正し、安全を確認するために読んだ量です。
ここでいうIssueは、「バグを1つ直す」「機能を1つ追加する」といった作業単位です。
IRVには、ソースコードだけでなく、次の情報も含めます。
| 種類 | 具体例 |
|---|---|
| ソースコード | 実装、型、設定ファイル |
| テスト | 単体テスト、結合テスト |
| 仕様 | Issue本文、受入条件 |
| 説明資料 | README、設計メモ、開発ルール |
たとえば、あるバグ修正で、ソースコード1,200行、テスト500行、仕様・資料300行を読んだとします。この2,000行が、そのIssueで観測したIRVです。
正確な行数を最初から集計できなくても構いません。まずは「何ファイル読んだか」「どの機能まで調査が広がったか」を記録するだけでも役立ちます。
コードベース全体の大きさとは違う
IRVで大切なのは、プロジェクト全体の行数ではありません。
100万行のシステムでも、1つの変更を5ファイルで判断できれば、変更前の調査範囲は小さくできます。反対に、1万行の小さなシステムでも、1つのルールが10か所へ散らばっていれば、毎回多くのファイルを読むことになります。
小さく保ちたいのは、コードベースではなく、1つの変更に必要な理解範囲です。
なぜ、変更前に読む情報は増えるのか？
1つのルールが、いろいろな場所へ散らばる
「同じメッセージを2回保存しない」というルールを考えてみましょう。
この判断に必要な情報が、送信処理、再接続処理、状態管理、保存処理、課金処理へ散らばっていたら、AIは1つのバグを直すために5つの機能を読み、それぞれの関係を組み立て直します。
私はこの状態を、知識のフラグメンテーションと呼んでいます。
HDDの中で1つのファイルがバラバラに置かれると、読み出しに手間がかかります。それと同じように、1つの判断に必要な知識が散らばると、AIも人間も理解に時間がかかります。
では、すべてを1つの巨大なファイルへまとめればよいのでしょうか？
答えは「いいえ」です。
大切なのは、ファイル数ではなく、そのルールを誰が管理するのかを明確にすることです。
IRVを減らす3つの実践テクニック
テクニック1：ルールの持ち主を決める
まず、「このルールを誰が管理するのか」を1つ決めます。
先ほどの例なら、「同じメッセージかどうかを判断する責任」を重複判定の部品に集めます。送信画面、再接続処理、課金処理が、それぞれ別の判定方法を持つ状態は避けます。
AIが最初に確認する場所が明確になるため、調査の入口を見つけやすくなります。
テクニック2：部品どうしの約束を書く
関数名や引数だけでは、安全に使えるか判断できないことがあります。
保存処理なら、次の約束まで書いておきます。
- 同じデータをもう一度送るとどうなるか
- 同時に2回送られたらどうなるか
- 失敗したとき、もう一度試してよいか
- 成功した時点で、どこまで保存されているか
この約束を「契約」と呼びます。
契約がわかれば、AIは保存処理の細かな中身まで読まずに利用できます。契約どおりに動くことを確認するテストも、近くに置いておくとさらに判断しやすくなります。
テクニック3：同じ理由で変わる知識を集める
一緒に変更することが多いルールは、同じ場所で見つけられるようにします。
反対に、課金と画面表示のように、違う理由で変わるものは分けます。そして、その間を先ほどの契約でつなぎます。
| 状態 | AIが確認するもの |
|---|---|
| 改善前 | 複数の機能を読み、隠れたルールを探す |
| 改善後 | 変更する機能と、相手の契約を読む |
知識を変更理由に合わせて整理し直す。これが、この記事でいう「知識のデフラグ」です。
やってはいけないIRVの減らし方
IRVは、小さければ小さいほどよいのでしょうか？
そうではありません。
少なく読んだ結果、バグやセキュリティ問題を見逃したら改善とは呼べません。
| やってはいけないこと | 起きる問題 |
|---|---|
| 巨大な1ファイルへ全部まとめる | 違うルールが混ざり、変更しにくくなる |
| コメントや仕様を削る | 数字だけ減り、理解しにくくなる |
| 読む量に上限を付ける | 必要な影響確認まで止めてしまう |
| 別のAIに大量調査を隠す | 全体の読取コストは減っていない |
| テストを省略する | 速く見えても品質が下がる |
障害調査やセキュリティ変更など、本当に広い確認が必要なIssueもあります。
目指すのは、最小のIRVではありません。
安全に変更するために必要な情報は読み、関係のない内部事情は読まなくて済む状態を作る。
このバランスが重要です。
次のIssueでできるIRVチェック
大がかりな計測システムは必要ありません。
まず、次のIssueを1つだけ選びます。作業が終わったら、以下を確認してください。
- 今回変更した機能は何か
- そのルールと状態を管理している場所はどこか
- AIはどのソース、テスト、仕様を読んだか
- 調査が別の機能へ広がった理由は何か
- 次の似たIssueで、読まなくて済むようにできるものは何か
調査が広がる主な理由は、ルールの分散、状態の持ち主が不明、部品どうしの約束が不明、テストや仕様の入口が見つからない、といったものです。Issue自体が本当に複数機能へまたがっている場合もあります。
ファイルを何個減らしたかではなく、次の似たIssueで、何を読まなくて済むようになったかを確認します。
AIエージェントへ渡す指示の例
普段使っているCodexやClaude Codeにも、次のように頼めます。
変更を始める前に、ルールを管理している場所、状態を管理している場所、他の部品との約束、正しい動作を確認するテスト、最初に読む必要がある最小の範囲を確認してください。
調査が別の機能へ広がったら、その理由を記録してください。
完了時に「次の似たIssueで読まなくて済むもの」と「新しく理解が必要になったもの」を教えてください。
これは「読む量を制限する指示」ではありません。
必要な調査は続けながら、なぜ範囲が広がったのかを見えるようにする指示です。
まとめ
AIへの修正依頼が以前より遅くなったとき、モデルやプロンプトを変える前に、AIが読んでいる範囲を見てみてください。
この記事のポイントは5つです。
- IRVは、1つのIssueでAIが読み解く情報量
- コード全体の大きさより、1回の変更に必要な理解範囲を見る
- ルールと状態の持ち主を明確にする
- 部品どうしの約束を書き、内部まで読まなくて済むようにする
- 品質を守りながら、次のIssueで不要になる読取を増やす
最初から行数を正確に集計しなくても構いません。
まずは次のIssueで、AIが開いたファイルを並べてみましょう。そして、作業の最後に1つだけ問いかけます。
次の似たIssueでは、何を読まなくて済むようにできるだろう？
この問いを繰り返すと、プロジェクトが大きくなっても、AIと人間が迷いにくいコードへ少しずつ育てていけます。
もう少し詳しく知りたい方へ
- 同じファイルを何度も読んだ場合は、「重複を除いた量」と「延べ読取量」を分けます。
- 1つのIssueが複数セッションに分かれた場合は、Issue単位へまとめます。
- ログから復元できない読取は、0ではなく「不明」と記録します。
- IRVだけで生産性を判断せず、解決率、時間、費用、レビュー負担も一緒に見ます。
- リファクタリング後は、単体・結合・回帰テストで動作を確認します。
IRVは、本記事で提案する呼び方と観測の枠組みです。標準化された指標でも、「IRVが小さければ必ず生産性が上がる」と証明された法則でもありません。Issueの難しさ、利用するモデル、ツール、テスト時間なども開発速度に影響します。
参考文献
- David L. Parnas, “On the Criteria To Be Used in Decomposing Systems into Modules”, 1972
- Robert C. Martin, “The Single Responsibility Principle”, 2014
- Nicole Forsgren et al., “The SPACE of Developer Productivity”, 2021
- Martin Fowler, “Definition Of Refactoring”, 2004
- Anthropic, “Effective Context Engineering for AI Agents”, 2025