コンテキストエンジニアリングは棚卸しから始まる: 一覧にできないコンテキストウィンドウは予算化できない

コンテキストエンジニアリングには定番のテキストがあります。Anthropic が 2025 年 9 月に公開したもので、その定義はいまも引用され続けています。

Context engineering refers to the set of strategies for curating and
maintaining the optimal set of tokens (information) during LLM inference,
including all the other information that may land there outside of the prompts.

最後の一節をもう一度読んでください。そこに入り込むかもしれない情報、とあります。この定義は、ウィンドウのかなりの部分は自分で入れたものではない、とさりげなく言っています。ガイドはそのことをよく分かっています。自分でデータを取りに行くエージェントや、ひとりでに伸びていく履歴について、まるごと節を割いています。それへの答えとしてガイドが教えるのは、選び方です。

コンテキストエンジニアリングのガイドが教えるのはウィンドウの整え方で、見方ではない

実践はどれも「選ぶ」動詞です。システム指示は、望む挙動を過不足なく記述できる最小限の情報にとどめる。重複の少ない、必要最小限のツールセットに絞る。エッジケースを山ほど並べず、典型的な例を少数選ぶ。ジャストインタイムで取得し、文書そのものではなくパスやリンクを持っておく。長い作業では履歴を圧縮し、エージェントにウィンドウの外でメモを取らせ、範囲のはっきりしたタスクはまっさらな状態で始まるサブエージェントに渡す。そのすべての土台になっている考え方は、ガイドの 2 つの言い回しに表れています。

a finite resource with diminishing marginal returns
the smallest possible set of high-signal tokens

これらの実践には、ひとつ残らず賛成です。異論があるのは順番です。どれも編集であり、編集には対象があります。何を削るのか。圧縮する履歴は、誰の書いた文章でできているのか。ガイドは、ある時点でモデルが使える状態の全体を考えるよう求めますが、その状態を目の前に出す手順は持っていません。つまり、点検の手順を持たないまま整え方を説くガイドなのです。しかもエージェントのハーネスでは、ウィンドウのうち自分のものだと見分けられる部分はわずかです。

入力する前の Claude Code のコンテキストウィンドウに入っているもの

どれほど小さいかを、私の知るかぎり最もはっきり説明しているのが Claude Code のドキュメントです。セッションを順に追う解説は、最初のプロンプトより前に読み込まれるものを挙げています。ハーネス自身のシステム指示、自動メモリのインデックス、環境情報、MCP ツールの名前、スキルの 1 行説明、ユーザーレベルの CLAUDE.md、プロジェクトの CLAUDE.md。そのどれにも、ターミナルには表示されないという印が付いています。解説中のトークン数はあくまで例だという断り書きがありますが、大事なのは比率です。起動時のブロックは合計でおよそ 7,850 トークン、そのあとユーザーが入力するプロンプトは 45 トークンです。解説は結論も自分で述べています。

Your prompt is tiny compared to what's already loaded.

同じことは、作業が始まってからも続きます。ファイルの読み込みはターミナルには 1 行の通知として出るだけで、2,400 トークンのファイル内容はモデルにだけ渡ります。パス指定のルールは、一致するファイルにエージェントが触れた時点で読み込まれます。見えるのは読み込まれたという事実で、中身ではありません。フォーマット用のフックは、コンテキストには入るのに画面には決して出ないフィールドを通じて結果を返します。どれも秘密ではありません。すべてドキュメントに書いてあります。ただ、どれひとつとして、届いた時点で自分が選んだものではなかったというだけです。

つまりウィンドウには、セッション開始から 1 分も経たないうちに、もう何種類もの書き手がいます。プロンプトと、しばらく前に書いた指示ファイルは自分が書きました。システム指示はベンダーが書きました。それぞれの MCP サーバーやスキルの説明は、それを公開した誰かが書きました。読み込まれるファイルは、リポジトリに最後にコミットした誰かが書いたものです。以前にも論じましたが、見知らぬ人が編集できるファイルは、信頼の水準が別物です。自分にしか書けないルールとは違います。メモリのインデックスは、以前の実行でモデルが書いたものです。

Claude Code の /context は、すでにコンテキスト棚卸しの半分になっている

当然の反論は、一覧ならもうある、というものです。あります。しかも、ガイドがにおわせるより出来がいいのです。/context はウィンドウの内訳をカテゴリごとにトークン数つきで出力し、/context all はそれを項目単位まで展開します。v2.1.296 で claude -p '/context' として実行すると、レポートには設定の種類ごとに表がひとつあります。模式的に書くと、左がセクション名、右がその列見出しです。

Estimated usage by category    Category   | Tokens | Percentage
MCP Tools                      Tool       | Server | Tokens
Custom Agents                  Agent Type | Source | Tokens
Memory Files                   Type       | Path   | Tokens
Skills                         Skill      | Source | Tokens

これは設定についての本物の棚卸しです。先ほどの 8 月のエッセイでは、層になった構成を読める状態に保つとは、ひとつの狭い問いに答えられることだと書きました。どの指示がどのエージェントに届くのか、そして誰がそれをそこに置くことを許されていたのか。このレポートは、ディスク上のファイルについては前半に答えます。コストの列があります。Source、Server、Path の列は出どころの手がかりです。ブロックがどこから読み込まれたのか、プラグインからか自分のディレクトリからか、このファイルかあのファイルかを示します。誰がそれを変更できるのかは示しません。信頼にとって重要なのは問いのその後半ですが、これらの列は出発点にはなります。ツール定義は予算だと書いたときに論拠にした数字を、自分のセッションで確かめる道具でもあります。

この一覧そのものも、履歴のあるソフトウェアです。v2.1.196 より前は、Skills の行がすべてのスキル説明の全文を数えていて、モデルが実際に受け取る量の数倍の数字を表示することがありました。v2.1.280 より前は、Claude Code が直接読んだ AGENTS.md はウィンドウに入っているのに一覧には出ませんでした。AGENTS.md 対応が入ったときに書いた抜けがこれです。どちらもいまは直っています。あえて触れるのは、一覧とはウィンドウについての主張であり、その主張をしているのは間違うこともあるコードだからです。一覧に載っていなかったスパン (ウィンドウ内のひとまとまりのテキスト) が、コンテキストに入っていなかったわけではありません。

Claude Code の /context の Messages 行で、棚卸しは止まる

このレポートについてもうひとつ言えるのは、構造の問題です。会話そのものは、同じ出力のなかで、カテゴリ表の 1 行です。

Messages

1 行に、数字がひとつ。その中には、自分の発言、モデルの返答、モデルが読んだすべてのファイル、すべてのコマンド出力、各サーバーから返った個々のツール結果、フックが差し込んだもの、途中で読み込まれたパス指定のルールが入っています。コンパクションのあとなら、それら全部をモデルが書き直した要約も入ります。レポートのうち項目化されている部分は、ディスクにあって、どのみち自分で開いて確かめられるものを扱っています。合算されている部分こそ、出どころが混ざっている場所です。取得したページと自分が打ったひとことが、同じ Messages 行のトークンとして数えられていますが、両者に同じ重みを持たせるべきではありません。

元の材料が消えたわけではありません。ディスク上のセッショントランスクリプトは、すべてのメッセージ、ツール呼び出し、ツール結果を保持しています。トランスクリプトビューアはツールの動きを詳しく見せます。InstructionsLoaded フックを使えば、指示ファイルが読み込まれるたびに、その理由つきで記録できます。ただ、そのどれも、いまのウィンドウの棚卸しとして読める形にはなっていません。このスパンは何トークンで、誰が書き、どの出来事まで残るのか、という形です。再構成はできます。ただ、誰も手渡してはくれません。そして、ウィンドウからはまったく再構成できないスパンがひとつあります。コンパクションの要約は触れたものすべてを書き直します。出どころのラベルが付いた十数件の結果として入ったものが、モデルの声で書かれたひとつのブロックになって出てきます。スパンの書き手についての議論で懸念していたのは、まさにこの場合です。取り込み時に付けたラベルは、ウィンドウの中で残り続けなければ意味がないのに、残りません。

コンテキストウィンドウの棚卸しには、トークン数だけでなく寿命の列が要る

欠けているもうひとつの列は時間です。トークン数は、そのスパンがいまどれだけ場所を取っているかを示します。何がそれを終わらせるのかは示しません。そして同じセッションの中でも、スパンの終わり方は大きく違います。

Claude Code はこの点を、コンテキストエンジニアリングのどのガイドよりも丁寧に文書化しています。コンパクションのとき各仕組みに何が起きるかをまとめた表です。プロジェクトルートの CLAUDE.md と自動メモリは、ディスクから再注入されます。パス指定のルールと入れ子の CLAUDE.md はメッセージ履歴に読み込まれたものなので、履歴と一緒に要約され、一致するファイルにもう一度触れたときにだけ読み込み直されます。フックが以前に追加したコンテキストは、残りと一緒に要約されます。呼び出したスキルの本文は、1 件あたり 5,000 トークン、合計 25,000 トークンを上限に戻され、古いものから落とされます。解説はさらに、起動時のスキル説明の一覧はコンパクション後に再注入されないと付け加えています。エージェントが読んだり編集したりしたファイルは最大 5 件まで読み直され、5,000 トークンを超えるものは中身なしのパスとして戻ります。消えた指示についてのトラブルシューティングの注記は、寿命の列を文章に書き下したように読めます。

If an instruction disappeared after compaction, it was given only in
conversation, lives in a nested CLAUDE.md that hasn't reloaded yet, or is
a path-scoped rule that hasn't matched a file since.

文言もトークンコストもまったく同じ 3 つのルールが、先ほどの表のうち 3 つの別々の場所に置かれていることがありえます。1 つ目は毎回ディスクから読み込み直されます。2 つ目は、一致するファイルがもう一度開かれたときにだけ戻ってきます。3 つ目は、要約がたまたま残した場合にだけコンパクションを生き延びます。残っても残らなくても、セッションの見た目は以前とまったく変わりません。トークンの表には、この 3 つを区別するものが何もありません。

寿命の問題は、ウィンドウをまたぐ方向にもあります。会話のフォークではない新規のサブエージェントは、独自のウィンドウで始まります。CLAUDE.md はそこでもう一度読み込まれます。ただし、組み込みの調査用エージェントの場合と、読み込まないよう設定されている場合は別です。メインセッションの自動メモリは読み込まれません。常にあると数えているルールも、あるかどうかはウィンドウごとに決まるのです。すべての行を自分で選んで書いた指示書のほうが、引き継いだトランスクリプトより把握しやすい理由が、ここにもうひとつあります。

トークン数から決めたコンテキストウィンドウの予算が、削るスパンを間違える理由

トークンの表から予算を立てると、大きいものを削ることになります。Claude Code のセッションで、手を出せる大きな行は 2 つ、ツール定義と自分の指示ファイルです。前者を削るのは正しく、そのことは以前に論じました。後者を削ること、つまり細部を CLAUDE.md からパス指定のルールやスキルへ移すことも、コストの面ではよい助言です。ただしそれは寿命とトークンの交換であり、この 2 つが同じ文の中で語られることはめったにありません。移したルールは、これからは引き金があって初めて読み込まれます。コンパクションのあとに残るのは要約が残した分だけで、引き金がもう一度引かれるまではそのままです。

逆向きの誤りは、さらに目立ちにくいものです。安いスパンが、実行全体を決定づけるスパンであることがあります。指示の形で書かれた一文を含む数百トークンのツール結果は、どのメーターで見てもほとんど何もかかっていません。予算は大きさで順位をつけますが、重みも持続性も大きさとは相関しません。

だから主張したい順番は、まず棚卸し、それも 1 スパンにつき 3 つの列を持つ棚卸しで、予算はそのあとです。書き手。そのテキストを書きえたのは誰か、自分抜きで変更できるのは誰か。それを出力した当事者と同じとは限りません。コスト。何トークンを占め、それが何回のリクエストにわたってかかるのか。寿命。何がそれを終わらせるのか。コンパクションか、リセットか、サブエージェントの終了か、あるいは自分がファイルを編集しないかぎり何も終わらせないのか。このセルに「条件付き」と書いてあってもかまいません。予算化が答えるのは、スパンについての問いのひとつ、占めている場所に見合う価値があるかどうかだけです。棚卸しをすれば、残りの 2 つをすべてのスパンに問えます。自分で書いた大きなスパンにもです。エージェントはここで誰の言葉に従って動いているのか。そしてこれは 1 時間後にもまだ有効なのか。

コンテキストウィンドウの棚卸しでは分からないこと

棚卸しは、動いているもののスナップショットです。ウィンドウに何があるかは教えてくれますが、モデルがそれをどう扱ったかは教えてくれません。一覧に載り、書き手が特定され、いつからあるかが分かっているスパンでも、無視されることがあります。矛盾する別のスパンと比べられて負けることもあります。どんな一覧にもそれは表れません。また棚卸しはウィンドウ単位です。複数のエージェントからなるシステムには棚卸しが複数あり、それらを合算する場所はありません。

API の上に直接作っているなら、自分がハーネスであり、棚卸しとはリクエストを組み立てる自分のコードです。こちらのほうが楽な立場です。各スパンの出どころと想定する寿命を、追加するその瞬間に記録できます。これ以上よいタイミングはありません。あとからでは、どちらも推測するしかなくなります。

コンテキストエンジニアリングは普通、モデルに何を見せるかを決めることだと説明されます。その決定は確かにあります。ただ、それは 2 番目です。1 番目は、モデルがすでに何を見ているのか、誰がそれを置いたのか、どれだけ残るのかを突き止めることです。Claude Code は、ディスク上のファイルについては、このうち最初の問いに答えます。長いセッションの大半を占める会話については、いま用意されている答えは相変わらず、ひとつの数字と、自分で読みに行けるトランスクリプトだけです。