会話ログを実測して「context を太らせている一括データ」を特定し、要約ツールへ置き換える

AI コーディングエージェント（Claude Code / Cursor / Cline など、会話ログを JSONL で保存するもの）を チームで使っていると、トークン費用の大半が出力ではなく入力になる。原因は「一度 context に入った 大きなデータが、以降の全リクエストで再送され続ける」こと。この指示書は、それを推測せず実測で特定し、 最大の発生源だけを置き換える手順をまとめたもの。

実際にこの手順を回した結果、置換対象1件で 同一データの入力トークンが 23,209 → 774（96.7%削減） になった。

---

0. 前提と考え方

• コストは「貼った大きさ」でなく「貼った位置」で決まる。 会話の序盤に貼った 2,000 tok の表が、 終盤に貼った 15,000 tok より高くつく。以降のリクエスト数だけ再送されるため。 これを本書では 増幅後トークン = 生トークン × 以降のリクエスト数 と呼ぶ。
• したがって最適化の対象は「大きい応答」ではなく「早い段階で入った、大きくて構造化されたデータ」。
• 置き換えの方針は1つ: 取得して全文を context に貼るのをやめ、スクリプト側で集計・抽出して少量だけ返す。 全文はファイルへ落としておき、必要になった時だけ範囲を指定して読む。

---

1. 会話ログの構造を先に確認する（決め打ちしない）

多くのエージェントは 1 行 1 JSON の JSONL で会話を保存する。まず実物を見て、次の3つを特定する。

1. アシスタントの発話行（ツール呼び出しを含む）の形
2. ツール結果が入る行の形と、呼び出しと結果を結ぶ ID
3. 1リクエストが何行に分かれるか

# 例: 最大のログを1本選び、行の型を数える
head -400 <ログ.jsonl> | \
  jq -r '[.type, ([.message.content[]?.type] | join(","))] | join("/")' | sort | uniq -c

⚠️ ここが最初の罠。 多くのエージェントは 1 リクエストの応答を thinking / text / tool_use の複数行に分けて保存する。行数をリクエスト数として数えると 2〜3倍の過大評価になる。実測例では assistant 250行 = 実リクエスト 107。 リクエスト単位の ID（requestId や message.id 等）の変化で数えること。

---

2. 「一括データ」の判定器を書く

大きいだけでは対象にならない。長いソースコードや散文は「必要な文脈」であって置換対象ではない。 表形式・構造化データに見えるものだけを拾う。

判定の順序と条件（閾値は 2,000 文字程度から）:

種別	条件
CSV	カンマ区切りで3列以上の行が5行以上、かつ最頻列数の行が全非空行の70%以上
TSV	タブ区切りで2列以上、同上
Markdown 表	| で始まり | で終わる行が5行以上連続し、区切り行 |---| を含む
JSON 配列	パースできて配列・要素5個以上・過半がオブジェクト（巨大時は },{ の出現回数で近似）

⚠️ 2つ目の罠。 ファイル読み取りツールの出力は多くの場合 「行番号 + タブ（または矢印）+ 本文」（cat -n 形式）。剥がさずに判定すると すべてのファイル読み取りが TSV と誤検出される。実測では最初の集計で上位10件中8件がこれで、 「一括データの話」が「ファイルを読んだ話」にすり替わっていた。

判定前に: 非空行の70%以上が /^\s*\d+(\t|→)/ に一致するなら、その前置きを全行から除去する

---

3. 帰属・増幅・集約

• 帰属: ツール結果は呼び出し ID で元の呼び出しに突き合わせ、「どのツールの・どの引数の呼び出しが貼ったか」まで出す。 シグネチャは可変部を伏せて正規化する（日付 → <DATE>、3桁以上の数値 → <N>、 パスはディレクトリだけ伏せて basename は残す）。 ⚠️ パスを丸ごと <PATH> にすると全ファイル読み取りが1グループへ潰れ、 「どれを置き換えるか」が読めなくなる。
• 増幅: その行より後に現れるリクエスト数を掛ける。
• 集約: (種別, ツール, シグネチャ) でまとめ、増幅後トークンの降順で並べる。

トークン推定は ASCII文字数 / 4 + 非ASCII文字数 / 1.6 程度の簡易式で十分（相対比較が目的のため）。 ただし置換前後は必ず同じ推定器で測る。別々の数え方で比べた数字は比較にならない。

---

4. 出力を読むときの鉄則

上位を1件ずつ「本当にそれか」と疑う。 上位が直感と違うときは、発見ではなく検出器のバグであることが多い。 実際この手順では、公開できる数字を出すまでに検出器の欠陥が2件（前述の行数カウントと行番号プレフィックス）見つかった。 どちらも「気づかなければ置換対象を完全に外していた」種類の誤りだった。

---

5. 最大の1件だけを置き換える

全部やろうとしない。増幅後トークンの上位1件が全体の3割を占めることは珍しくない。

置換ツールの設計（この形が汎用的に効く）:

• 要約だけを標準出力へ返す: 件数、作成者・カテゴリ別の内訳、時間範囲、直近 N 件
• 1件あたりの本文に上限を設ける（例: 200文字 + …(全N字)）。 ⚠️ これが無いと、巨大な1件が予算を食い潰して「直近10件」が実質1件になる
• 全体の出力予算（例: 6,000文字）を設け、超えたら削るが省略件数を必ず明示する。黙って切り捨てない
• 全文は --raw-out <path> でファイルへ。標準出力には出さない。 「全文が要るときだけ読んでください」と一言添える
• 絞り込みオプション（--since / --grep / --limit）を持たせ、取得段階で減らす

回帰テストで「安いこと」を機械的に守る

要約ツールは放っておくと出力が育つ。圧縮率そのものをテストにする。

テスト: 実データ相当（例: 60件、本文200〜400字）を渡したとき、
       要約出力の文字数が JSON 全文の 25% 未満であること

さらに、上限値を無効化するとテストが落ちることを一度確認する（変異テスト）。 落ちないテストは書いていないのと同じ。

---

6. 置き換えを「実際に使われる状態」にする

ツールを作っただけでは何も変わらない。チームの運用ルールに1行入れるまで含めて完了とする。

• チーム共通のルールファイル（エージェントが毎回読む設定ファイル等）に 「まとめ読みは一覧系ツールでなく要約ツールを使う」と書く
• 用途を分けて書くのが重要: 「まとめ読み＝要約ツール」「少数を正確に読む＝従来どおり」。 一律禁止にすると精度が要る場面で品質が落ちる
• 実測値（何 tok → 何 tok）を根拠として併記する。数字が無いルールは守られない

---

7. 完了条件（これを満たすまで「やった」と言わない）

1. 一括データの貼付箇所を実測で列挙した（推測で書いていない）
2. 上位1件を置換し、置換前後の入力トークンを同じ推定器で実測比較した
3. 圧縮率の回帰テストがあり、変異させると落ちることを確認した
4. 運用ルールに反映し、次に同じ作業をする人が自然に新しい経路を通る状態になった

---

付録: よくある誤りチェックリスト

• リクエスト数を「行数」で数えていないか（2〜3倍ずれる）
• ファイル読み取りの行番号プレフィックスを剥がしたか
• パス正規化で全部を1グループに潰していないか
• 置換前後を同じ推定器で測ったか
• 1件あたりの本文上限があるか（巨大な1件が予算を食う）
• 省略したとき、省略件数を明示しているか
• テストが空でない（変異させると落ちる）ことを確認したか
• 長い指示文をコマンドライン引数で渡していないか （シェルがバッククォートをコマンド置換として実行し、指示の一部が消える。 Windows は引数長の上限も短い。ファイル経由で渡す）