AIがコードを書く時代になりました。
2025年はAIエージェントの時代とされ1、開発者はAIを使ってより戦略的なタスクに集中できるようになっています。
しかし、人間が「読みやすい」と感じるコードが、AIにとって必ずしも理解しやすいとは限りません2。
AIエージェントを使ったコーディング（Agentic Coding）では、きれいに整理されたフォルダ構成ほど、AIエージェントの処理に時間がかかるのです。
2025年には82%の組織がAIエージェントを導入する計画を立てている3という状況で、この問題は多くの開発者が直面する課題となるでしょう。
1. AIエージェントがコードを理解する仕組み（探索から始まる）
AIエージェントがコードを書く際、まず既存のコードを探索し理解することから始めます。
これは人間がプロジェクトに参加する際に、まずファイル構成を把握するのと似ています。
ただし、AIエージェントの探索方法は人間とは大きく異なります。
基本的に ls -R コマンド4のように、フォルダ構造を再帰的に調べていきます。
つまり、全体を一度に把握しようとするのです。
1.1. トークンという制約
ここで重要になるのが「トークン」という概念です。
トークンとは、AIが文章を理解するときの最小単位のことで、日本語なら1文字がおよそ1トークンに相当します。
AIには「コンテキストウィンドウ」という制限があります。
これは一度に理解できる文章の長さの上限で、トークン数で決まります。
AIも一度に処理できる情報量に上限があるのです。
2. 構造化されたコードが引き起こす問題（フォルダ階層）
きれいに整理されたプロジェクトでは、機能ごとにフォルダを分け、階層を深くしてファイルを整理します。
これは人間にとって理解しやすい構造です。
しかし、AIエージェントにとっては違います。
深い階層構造を探索するには、それだけ多くのトークンを消費します。
フォルダが深ければ深いほど、AIの理解能力を圧迫するのです。
2.1. ファイル間の依存関係という落とし穴
さらに問題となるのが、ファイル間の参照関係です。
プログラムでは import や require といった仕組みで、他のファイルの機能を使います。
人間にとって、これは適切な責任分離を表現する優れた仕組みです。
ところが、AIエージェントは参照されているファイルもすべて理解しようとします。
A.jsがB.jsを参照し、B.jsがC.jsを参照している場合、AIは3つのファイルすべてをコンテキストに読み込む必要があります。
これにより、トークン消費量が急激に増加するのです。
3. トークン消費と注意の分散
トークン量が増えると、AIの生成品質は低下します。
これは研究でも実証されている現象で、AIは長い文章の中央部分への注意が薄れることで見落としが増えるからです。
たとえば、人間が長い小説を読むとき、途中の章の内容を忘れてしまうことがあります。
AIも同様に、大量の情報を一度に処理しようとすると、重要な部分を見逃してしまうのです。
スタンフォード大学の研究により、LLMは長いプロンプトの最初や最後に現れる重要な情報を拾い上げやすいが、中央部分に埋もれた情報は見落としやすいことが明らかになっています5。
これは、開発者にとって見過ごせない重要な制約です。
3.1. 計算コストの急激な増加
テキストの長さが2倍になると、LLMは4倍のメモリと計算能力を必要とします6。
この二次的スケーリングは、処理速度の低下とコストの増加を意味します。
また、文章が長くなるほど推論速度も遅くなります。
3.2. モデルによる差異
長文を得意とするAIモデルも存在しますが、基本原則は変わりません。Google Gemini 1.5 Proのように100万トークンの文脈を扱えるモデル7でも、情報が中央部分にある場合の性能低下は避けられません。
トークン量が少なければ少ないほど、より正確で質の高いコードを生成できます。
4. 現在の主要なAgentic Codingツール
2025年現在、複数のAgentic Codingツールが実用化されています。GitHub Copilotがエージェントモードでマルチステップのコーディングタスクを実行できるようになったほか、Devin AI、Cursor、Clineなどが注目を集めています8。
これらのツールには共通する特徴があります。
どれも自律的な計画立案と実行能力を持ちながら、人間との協働を前提とした設計になっています。
完全自動化ではなく、「ジュニア開発者」のような役割でコードを生成し、人間がレビューする形での利用が効果的とされています。
4.1. フレームワークの多様化
AIエージェント構築のためのフレームワークも急速に発展しています。AutoGen、CrewAI、LangChain、Microsoft Semantic Kernelなど、様々な選択肢が開発者に提供されています。
これらのフレームワークにより、従来はプログラミング経験が必要だったAIエージェントの構築が、より多くの人にとってアクセス可能になっています。
5. 解決策としてのルール設計と最適化手法
AIエージェントの探索を効率化するには、適切な「ルール」を提供することが重要です。
これは道案内をするときに、明確な目印を伝えるのと似ています。
正しいルールを伝えることで、AIは無駄な探索をせずに済み、トークン消費を抑えながら生成品質を安定させることができます。
5.1. 実践的なアプローチ
具体的には、プロジェクトの構造や依存関係を説明するドキュメントを用意したり、YAMLファイルでフォルダやファイルの責務を一覧化したりする方法が考えられます。
また、repomixのようなツール9を使って、コードベース全体を1つのファイルにまとめることも有効です。
5.2. 注意機構の最適化
最新の研究では、関連性の高い情報に焦点を当てる注意機構技術を活用して、AIがコンテキストウィンドウ内の重要な部分だけに集中できるようにする手法が注目されています。
これにより、情報過多による性能低下を防ぐことができます。
5.3. 戦略的なトランケーション
すべての情報が等しく重要ではないため、戦略的にコードの不要な部分を削除し、タスクに必要な中核要素のみを保持することで、AIの情報過多を防ぐことができます。
6. 小さなプロジェクトから始める実験
AIツールの導入を検討している場合、まず期待値を適切に設定することが大切です。
「きれいなコードなら人間と同じように理解してくれる」という期待は、現時点では現実的ではありません。
6.1. 段階的なアプローチ
最初は小さく、シンプルな構造のプロジェクトから試すことをお勧めします。
ファイル数が少なく、依存関係が単純なプロジェクトであれば、AIエージェントの真価を体験できるでしょう。
成功体験を積んでから、徐々に複雑なプロジェクトに挑戦することで、AIとの協働方法を学べます。
7. 開発手法の変化への準備
従来の「人間が読みやすいコード」の考え方は、AIとの協働において見直しが必要です。
これは開発手法の根本的な変化を意味します。
視認性を高めるためのファイル分割や、美しい階層構造は、AIにとって理解の障壁となる場合があります。
人間の直感とAIの処理特性の違いを理解し、両者にとって最適な設計を模索する時代が来ています。
7.1. 新しいスキルセット
エンジニアには、AI特性を理解したコード設計というスキルが求められるようになるでしょう。
これは従来の設計原則に加えて、トークン効率やコンテキスト管理を考慮した新しいアプローチです。
8. まとめ
AIエージェントを使ったコーディングでは、従来の「人間にとって読みやすいコード」という常識を見直す必要があります。
深い階層構造や細かなファイル分割は、AIのトークン消費を増加させ、生成品質の低下を招く可能性があります。
成功のポイントは、シンプルな構造から始めること、適切なルールを提供すること、そして人間中心の設計とAI中心の設計の違いを理解することです。
スタンフォード大学の研究が示すように、LLMは中央部分の情報を見落としやすいという制約を踏まえ、重要な情報を先頭や末尾に配置する設計が有効です。
2025年にAIエージェントの採用が本格化する中で、Agentic Codingはコード構造設計における新たな視点を開発者に要求しています。
GitHub Copilot、Devin AI、Cursorなどの実用的なツールが登場している今こそ、従来の開発手法を見直し、AI協働時代に適した新しいアプローチを模索する時期といえるでしょう。
- マイクロソフトは2025年を「AIエージェントの時代」と位置づけ、GitHub CopilotやAzure AI Foundryなどの大幅なアップデートを発表している – Microsoft Build 2025: The age of AI agents and building the open agentic web
- 熊井悠(くまいゆう)@AI駆動開発|クマイ総研さん: 「Agentic Codingで考えるAI駆動開発で気をつけるべきこと3点 ・フォルダ構成・ファイル依存関係のヒントをコンテキストに含める(Rulesやコンテキスト ・視認性を高めるようなファイル分割した実装は可能な限り避ける ・実装計画でエージェントのファイル探索と実装対象をわかりやすくする」 / X–
- Capgemini社の調査によると、調査対象組織の82%が2026年までにAIエージェントを統合する計画を持っており、主にメール生成、コーディング、データ分析などのタスクでの活用を予定している – Top 10 AI Agent Trends and Predictions for 2025
- ls -Rは、Linuxやmacでディレクトリの内容を再帰的に（サブディレクトリも含めて）表示するコマンド。AIエージェントは同様の方法でプロジェクト全体のファイル構造を一度に把握しようとする – IBM – AI Agents in 2025: Expectations vs. Reality
- この研究は「Lost in the Middle」として知られ、マルチドキュメント質問応答とキー・バリュー検索タスクにおいて、関連情報の位置を変えるだけで性能が大幅に低下することを実証した – Lost in the Middle: How Language Models Use Long Contexts
- これは「二次的スケーリング」と呼ばれる現象で、Transformerアーキテクチャの数学的制約により、コンテキスト長の二乗に比例して計算コストが増加する – Why larger LLM context windows are all the rage – IBM Research
- Google Gemini 1.5 Proは2024年2月にリリースされ、当時最長となる100万トークンのコンテキストウィンドウを実現。これは約1時間の動画または70万語に相当する – The Battle of RAG and Large Context LLMs
- これらのツールは従来の「単発のコード提案」から進化し、プロジェクト全体を理解して複数ステップにわたるタスクを自律的に実行する能力を持つ – Top 5 Agentic AI Coding Assistants April 2025
- repomixは、複数のソースコードファイルを1つの大きなファイルに結合するツール。AIエージェントがプロジェクト全体を一度に理解できるようにすることで、ファイル間の依存関係による複雑さを軽減する – How to Become an Agentic AI Expert in 2025?