1. なぜ「エージェントがコードを書く仕組み」を理解する必要があるのか
生成AIによるアプリケーション開発が一般化するにつれ、AIエージェントがどのように情報を処理し、変更を加え、答えを生成しているのかを理解する必要性が高まっている。
特に、「〇〇機能を実装して」といった抽象的な要求を投げたとき、エージェント内部で実際に何が起こっているのかを把握することは、成功率の向上に直結する。
以下では、Google Gemini CLI を例に、その内部メカニズムを整理し、そこから導かれるコンテキスト・エンジニアリングの重要性について論じる。
2. Gemini CLI におけるコーディングサイクル
Gemini CLI では、1 回のエージェントサイクルは主に以下の 3 要素で構成される。
- Schedule
- Tool Call
- Generate Prompt
重要なのは、この一連の処理が一度だけで完結するのではなく、応答生成前に何度もループするという点である。
ユーザが一言プロンプトを送ってから最終回答が返るまでの間に、内部では複数回の Tool Call と Prompt 生成が実行される。
これらの Tool Call の結果はContext領域に追加され、次サイクルの入力となる。
以下の図がそのイメージである。ツール呼び出しをするごとに、コンテキストにそのツールの結果が追加されていくのがわかる。
3. なぜコンテキストが問題になるのか
コンテキストサイズと性能劣化
LLM の性能指標には「コンテキスト長（Context Window）」がある。
これは、エージェントが同時に扱える情報量の上限を示し、これが溢れた瞬間から問題が発生する。
コンテキストが満杯
→ 古い情報を圧縮・削除
→ 文脈を失い性能が急低下
→ 論理破綻した回答が出やすくなる
Claude Code ではこの上限に近づくと自動的に Compact（要約） が走るが、その瞬間に重要な情報が消滅することがある。
Context Rot（コンテキストの腐敗）
Context Rot のレポートでは、
長大なコンテキストを持つほど、文脈の整合性が失われ、情報参照の失敗が増えるということが実証されている。
Q&A のような単純タスクでさえ、コンテキストが長いというだけで失敗率が上昇する。
つまり、以下の二つが常にトレードオフになる。
- 必要情報を十分に与える
- コンテキストを短く保つ
このバランスをどう取るかが「Context Engineering」の核心である。
4. Context Engineering の基本思想
ポイントは次の一文に集約できる。
「必要最低限の情報だけを LLM に渡すようにコンテキストを制御する。」
コード生成には、本来以下の情報が必要となる。
- どのファイルを変更するか
- システムアーキテクチャ
- 関連コンポーネントの依存
- コーディング規約
- テスト計画
- セキュリティ要件
- 既存コードの制約
しかし、これらを全て一度にコンテキストへ投入すると、性能低下を招く。
必要情報をどう 「選択」「分割」「後から必要に応じて読み込む」 か。
これを管理する技法が Context Engineering である。
5. Claude Code における現状の Context Engineering
結論として、Claude Code 自体は高度なコンテキスト管理機構をまだ備えていない。
しかし、公式が推奨する方法が1つある。
SubAgents（サブエージェント）
公式の SubAgents は、Context Engineering と直接関係する。
ポイントは以下の仕様である。
Context preservation:
Each subagent operates in its own context,
preventing pollution of the main conversation
and keeping it focused on high-level objectives.
サブエージェントは独自コンテキストで動くため、メインの文脈を汚さない。
これはコンテキスト長を抑えるうえで極めて有効である。
SubAgents の弱点
ただし明確な欠点もある。
- メインエージェントは「サブエージェントで何が起きたか」を知らない
- 結果だけ取得し、途中過程は不可視
よって、システム構造全体を把握すべき フロントエンド担当サブエージェント のような運用は不向き
Claude CodeのAdam Wolffはこう述べている。
Don't anthropomorphize subagents.
Use them to organize your prompts and elide context.
Subagents are best when they can do lots of work but then
provide small amounts of information back to the main conversation thread.
適している用途
- Code Review
- Data Analysis
- Testing / Building
- Playwright / Chrome DevTools
「過程は不要だが結果だけ欲しいタスク」に最適ということである。
6. 今後の展望と現時点での最適解
現時点で Claude Code が提供するコンテキスト管理機能は限定的である。
しかし、改善方向性は明確である。
- コンテキスト長の自動管理・自動再構成
- 必要情報のオンデマンド読み込み
- ファイル粒度のインテリジェントなコンテキスト抽出
これらが将来的に整備されれば、より大規模な開発が安定して行えるようになるだろう。
現状での最適運用
- 途中経過を保持する必要のない処理をサブエージェントへ委譲する
- メインエージェントには必要最小限の情報のみ保持させる
- 文脈汚染を避け、コンテキストの寿命を延ばす
YouTube の参考動画：
I was using sub-agents wrong...