なぜトークン消費の話を今書くのか
結論を先に書きます。Claude Code 系のエージェントでトークンを半減させたいなら、「Claude に何でも読ませる」設計をやめる のが一番効きます。圧縮ではなく分離。1 つの大きな指示書を、責務ごとに小さく割る。これだけで、私の AetherEchoes auto-publish は 1 セッションあたりの入力トークンが体感で半分になりました。
2026 年 5 月、Zenn で Kagent のコンテキストエンジニアリング事例（ukrocksre さんの記事）を読みました。systemMessage を 8 万字から 400 字 に削り、入力トークンを 15.5 万から 7.5 万 に減らした、という具体的な数字付きの記録です。読み終えて、自分の auto-publish パイプラインで似た無駄をしていないかが気になりました。今日はその点検の記録です。
Kagent の事例から学んだこと
削減の手段が「圧縮」ではなく「分離」だった、というのが Kagent 事例の核です。プロンプトの文字を縮める話ではなく、プロンプトに載せる責務を減らす 話でした。
記事から読み取れる具体策は 4 つです:
- systemMessage を「6 ステップの手順書」から「目標を 1 文で宣言する形」に書き換えた
- 「日本語で回答」のような重複指示を 7 箇所から 1 箇所に集約した
- しきい値ロジック（CPU 80% 超でアラート）を PrometheusRule（Prometheus のアラート設定）に 外に出した
- 出力フォーマットの厳密定義を「テーブル形式・簡潔に」程度の方針に緩めた
一番効くのは 3 です。判定ロジックをプロンプトの外に逃がす。LLM はロジックの実行装置ではなく、自然言語の生成装置だ、という当たり前の役割分担に戻す話です。私はここで一度本を閉じて、自分のターミナルを開きました。
私の auto-publish が一枚岩だった頃
恥ずかしい話を書きます。2026 年 3 月、AetherEchoes の auto-publish スキルは 1 つの大きな SKILL.md に全部詰まっていました。トピック選定 → 重複検出 → アウトライン → 本文 → 画像 → 公開 → 検証、この 7 工程を 1 セッションで通す設計です。
1 回回した時の入力トークンは、私の手元の Claude Code セッションで概算 12 万トークン前後でした。CLAUDE.md と doc/ を 5 ファイル読ませて、既存記事 50 件を JSON で受け取って、本文 2000 字を draft、公開後の curl 検証を 6 件、これを 1 つのコンテキストで連続実行する。
問題はトークン量そのものではなく、コンテキストの「集中力」が落ちる ことでした。長い指示書を読まされた Claude は、検証フェーズで「アウトラインに戻って refs を増やす」のような往復が増えます。プロンプトキャッシュ（同じ前方プロンプトを 2 回目以降は安く済ませる仕組み）が効いているはずなのに、なぜか結果がブレる。
3 段パイプラインに割り直した
2026 年 5 月の連休に、auto-publish を 3 段に分けました。以前 Claude Skills + CONTENT_GUIDELINES の組み合わせ で書いた skill 設計の、自然な延長です。
- article-pick — トピック選定だけ。出力:
pick.json - article-write — 執筆と公開だけ。入力:
pick.json、出力:write.json - article-verify — 公開後の curl 検証だけ。入力:
write.json
各段は別の claude -p セッションで起動するので、コンテキストは段ごとに完全リセットされます。読み込むドキュメントも段ごとに必要最小限に絞りました。article-write は SHARED_LOGIC.md のうち §5（品質）/ §6（リトライ）/ §7（文体）の 3 章だけを必読指定にしています。
数字で言うと、1 セッションあたりの入力トークンは概算で次のように変わりました:
- 旧（一枚岩）: 12 万トークン
- 新（article-write のみ）: 5.5 万トークン
- 新（pick + write + verify 合計）: 8.5 万トークン
合計でも約 3 割減です。Kagent のような劇的な半減には届きませんが、1 セッションあたりは半減 しました。出力の安定度はセッションが短いほど上がるので、合計より 1 セッションの数字の方が体感に直結します。
CLAUDE.md と doc/ を「全部読ませない」設計
副次効果として、CLAUDE.md の構成も変わりました。以前は CLAUDE.md に「Skill を呼ぶ前に doc/CONTENT_GUIDELINES.md を読め」「DATA_MODEL.md も読め」と全部書き並べていました。Claude が起動時にすべて読みに行く前提です。
今は CLAUDE.md には 見出しレベルの分類だけ を置き、各 skill の SKILL.md 冒頭で「自分の責務に必要な doc/ だけを Read する」と指定しています。CLAUDE.md 自体は 200 行を切る薄さに整理し、doc/ は 17 ファイルに分割しました。
これは Kagent 記事の「systemMessage を 8 万字から 400 字に」と同じ発想です。読ませる必要のないドキュメントは、コンテキストに載せないことが正解 でした。指示書を充実させるほど性能が上がる、という直感は、トークン経済の前ではきれいに裏返ります。
半分にするための、私の 5 観点
ここまでの話を、再利用できる 5 観点に整理します。
- 責務単位で skill を割る: 1 セッションで複数フェーズを跨がない。pick / write / verify は別プロセスにする
- 必読 doc を skill ごとに絞る: 「Read するファイル」を 3〜5 個に絞り、それ以外は意図的に載せない
- 重複指示を 1 箇所に集約する: 「ですます調で」を 7 章書かない。SHARED_LOGIC §7 に 1 回だけ書いて全 skill が参照する
- 判定ロジックはコードに逃がす: 重複検出 / 品質判定 / リトライ判定は bash + jq で書き、プロンプトには判定結果だけを渡す
- 段間の状態は JSON ファイルに置く: pick.json / write.json で段間連絡。プロンプト内で過去会話を引きずらない
特に 4 と 5 は、Claude を「判断者」ではなく「執筆者」として使う ための工夫です。判断は決定的なコード、執筆は確率的な LLM、と役割を分けるとブレが減ります。これは Kagent が PrometheusRule にしきい値を逃がしたのと、構造的には同じ操作です。
やってみて気付いた副作用
副作用も正直に書いておきます。3 段に割った最初の週、pick.json のスキーマを 2 回変更しました。連携先である article-write が古い形式を期待していて、初日に 1 本だけエラーで draft 化されたまま放置されました（draft-only の人間レビュー必須運用にしておいて助かった）。
段間の契約（スキーマ）が壊れると、一枚岩より復旧が面倒 という事実は覚悟しておくべきです。それでも、各段が独立にデバッグできる利点の方が大きいと私は判断しています。ちなみに、初日のエラーを Slack に通知しておけば良かったと反省しました。launchd（macOS の cron 的なやつ）任せだけだと夜気付けません — 余談ですが、当時その夜に公開が止まっていることに気付かず、翌朝 git pull で初めて気付きました。エラーは寝ている間に静かに溜まるものです。
まとめ — 「読ませない」ことの効き目
コンテキストエンジニアリングという言葉は、私には少し大げさに聞こえていました。けれど Kagent の 8 万字 → 400 字を読んで、自分の auto-publish の 12 万トークン → 5.5 万トークンを並べてみると、効き目は確かにあります。
要点は 1 つだけです。Claude に読ませる必要のないものは、読ませない。これでトークン消費は半分になり、出力の安定度も上がります。次に試したいのは、品質判定の self-check ループを Haiku 系の小さいモデルに逃がす設計です。これも結局「判断者ではなく執筆者」の延長線上にあります。