8kコンテキスト対応のコーディングエージェント構築から得た教訓：トークン見積り、並列実行、ファイル単位の分離

ほとんどのAIコーディングツール（Cursor、Aider、Claude Code）は、200kトークンのモデルを使っていることを前提にしています。OllamaやLM StudioでローカルLLMを動かしている場合、あるいはGroqやOpenRouterのような無料枠のクラウドAPIを使っている場合は、使えるのはだいたい8kトークンです。ですがそれでは、プロジェクト全体には全く足りませんし、単一の大きなファイルですらギリギリです。

私はここ数週間、8kという制約に合わせて設計されたCLIのコーディングエージェントを作っていました。制約と戦うのではなく、それ前提で組みました。学んだことを共有したいと思います。いくつかは私にとって意外でした。

核となる洞察：LLMがプロジェクト全体を目にする必要はない。

多くのエージェントは、できるだけ多くのコンテキストを1回の呼び出しに詰め込もうとします。ですが8kトークンでは話が始まりません。私がうまくいったのは、作業を役割に分割するアプローチです：

• 軽量なプロジェクトマップ（各フォルダのMarkdown要約、プロジェクト全体で~300〜500トークン）と、ユーザーの要求だけを見て、タスクリストを出力するプランナーの呼び出し。
• それぞれExecutorの呼び出しは、常に「ちょうど1ファイル」と「ちょうど1タスク」だけを見ます。同じ呼び出しで2つのファイルを扱いません。
• オーケストレーターは純粋にコードで、LLMは一切使いません。タスク同士の依存関係グラフを構築し、並列で実行するか逐次で実行するかを判断します。

この分割によって、LLMは常に、ある時点で考えるコード量が小さく上限付きになります。プランナーはコードをまったく見る必要がなく（ファイル要約だけで十分）、Executorは1ファイルだけを見ます。マルチファイルのリファクタは、コンテキストウィンドウの問題ではなく、スケジューリングの問題になります。

トークンの見積もりは、プロンプトで約束するのではなくコードで強制する必要がある。

すべてのLLM呼び出しは、canFit()チェックを通ります。ここで測るのは「システムプロンプト + 出力として確保したトークン + メモリ + 実際のコード」です。コードが収まらない場合、エージェントは自動的に、（~150行を超えるファイルに対して一度だけ生成される）ファイルごとの行インデックスへフォールバックし、関連するセクションだけを取り出します。

8192トークンの場合の具体的な予算計算：

• システムプロンプト + 指示：~1000
• 応答用に予約：~2000
• 短期メモリ（4エントリ）：~360
• 実際のコードに使える枠：~4800（約140〜190行）

並列実行は、8kを実用にするスピード倍率。

各Executorは1ファイルしか見ないため、ファイルをまたいだ独立した編集は同時に走らせられます。逐次実行であれば時間がかかる5ファイルのリファクタも、最長の1つの編集にかかる時間程度で完了します。依存関係グラフ（プランナーのタスクリストから純粋なコードで構築されます）が、「どのタスクがどれを待つ必要があるか」を決めます。

途中でつまずいたことがいくつかあります：

• 質問形式のリクエストがファイルを上書きしてしまう。 最初のバージョンには「読み取り専用」の概念がありませんでした。そのため「Xには何行ありますか？」のように聞くと、Executorが答えをそのファイルに書き込んでしまいました。これを修正するため、プランナーの出力にaction_type: "query"というフィールドを追加し、ディスクに一切触れない別のコードパスへルーティングするようにしました。
• 古いプロジェクトマップによるサイレントな誤ルーティング。 ユーザーが要求の中で、コンテキストマップに存在しないファイル名を指定していた場合（リネームしたばかり、あるいはリフレッシュしていない）、プランナーは最も近い一致にサイレントにルーティングしていました。そこでオーケストレーター側で、言及されたファイルパスが実際にディスク上に存在するかを検証し、存在しなければ明確なエラーを投げるようにしました。
• Executor出力内のMarkdownフェンス。 明示的にやらないよう指示していても、小さめのモデルはコードを三連バッククォートで囲みたがります。プロンプトと格闘するのではなく、ポスト処理でそれらを取り除きます。
• メモリのトークンコスト。 当初はそれを予算に入れていませんでした。永続メモリは便利ですが、コード予算から差し引かれる別の~80〜90トークン／エントリが発生します。今は、予算が厳しいときはまずフォルダのコンテキストを落としてからメモリを落とし、その後で実際のコードを切り詰めています。

まだ検討中のこと：

プランナー／Executorの分割が、50ファイルを超えるコードベースでもきれいにスケールするかどうかです。依存関係グラフ自体は管理し続けられますが、フォルダ数が増えるとプロジェクトマップのコストが実トークンとして効いてきます。現状は予算が厳しいときにまずフォルダコンテキストを落としていますが、その結果、深い編集ではコンテキストが減ってしまいます。同じような問題に遭遇した人がいるか、そしてどう対処しているか気になっています。

掘り下げたい人向けに実装をオープンソースにしました：https://github.com/razvanneculai/litecode