8Kコンテキスト用コーディングエージェントの構築：プランナー/エグゼキュータ分割、トークン予算、並列実行

ほとんどのAIコーディングツールは200kトークンのモデルを前提としていますが、Ollama、LM Studio、またはGroqやOpenRouterのような無料API経由でローカルLLMを実行している場合、約8kトークンに制限されます。これではプロジェクト全体は収まらず、1つの大きなファイルすらかろうじて入る程度です。ある開発者は、この制約に特化したCLIエージェントの構築に数週間を費やし、実践的な教訓を共有しました。

コアアーキテクチャ: プランナー/エグゼキュータ分割

エージェントはプロジェクト全体をLLMに提示しません。代わりに、作業を3つの役割に分割します:

• プランナー: 軽量なプロジェクトマップ（各フォルダのMarkdown要約、合計約300～500トークン）とユーザーリクエストのみを参照し、タスクリストを出力します。
• エグゼキュータ: 1回の呼び出しにつき1ファイルと1タスクのみを参照し、2つのファイルを同時に見ることはありません。
• オーケストレーター: 純粋なコード（LLM不使用）で、タスクリストから依存関係グラフを構築し、並列実行可能なタスクと逐次実行が必要なタスクを決定します。

これにより、複数ファイルのリファクタリングをコンテキストウィンドウの問題からスケジューリング問題に変換します。プランナーはコードを見る必要がなく、エグゼキュータは一度に限られた量のコードしか見ません。

コードで強制するトークン予算

すべてのLLM呼び出しは、システムプロンプト + 出力予約トークン + メモリ + 実際のコードを計測するcanFit()チェックを通過します。コードが収まらない場合、エージェントはファイルごとの行インデックス（約150行以上のファイル用に一度生成）にフォールバックし、該当セクションのみを取得します。

8192トークンの予算計算:

システムプロンプト + 指示: ~1000
応答予約: ~2000
短期メモリ（4エントリ）: ~360
実際のコードに利用可能: ~4800（約140～190行）

予算が厳しい場合、まずフォルダコンテキストが削除され、次にメモリが削除され、最後に実際のコードが削減されます。

並列実行による高速化

各エグゼキュータは1つのファイルのみを参照するため、ファイル間の独立した編集は同時に実行されます。5ファイルのリファクタリングは、最も長い単一編集とほぼ同じ時間で完了します。（プランナーのタスクリストからコードで構築された）依存関係グラフが実行順序を決定します。

問題点と修正

• 質問形式のリクエストがファイルを上書きする: 「Xの行数は？」と尋ねると、エグゼキュータが回答をファイルに書き込んでしまいました。修正: プランナーの出力にaction_type: "query"フィールドを追加し、ディスクに触れないコードパス経由でルーティング。
• 古いプロジェクトマップによる誤ったルーティング: ユーザーがマップにないリネーム済みファイルに言及した場合、プランナーが最も近い一致に静的にルーティングしていました。現在はオーケストレーターが言及されたファイルパスがディスク上に存在するか検証し、存在しない場合は明確なエラーをスローします。
• エグゼキュータ出力のMarkdownコードブロック: 小規模モデルは指示に反してトリプルバッククォートでコードを囲むことがあります。修正: プロンプト戦略ではなく、後処理で削除。
• メモリのトークンコスト: 永続メモリはエントリあたり約80～90トークンを追加します。予算が厳しい場合、まずフォルダコンテキストが削除され、次にメモリ、最後に実際のコードが削減されます。

未解決の課題

プランナー/エグゼキュータ分割が50ファイル以上のコードベースにスケールするかどうか。依存関係グラフは管理可能ですが、プロジェクトマップのトークンコストが増加します。現在はフォルダコンテキストを最初に削除していますが、深い編集ではコンテキストが失われます。実装はオープンソース化されているので、ご確認ください。