# 会話ログを実測して「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リクエストが何行に分かれるか** ```bash # 例: 最大のログを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 で元の呼び出しに突き合わせ、「どのツールの・どの引数の呼び出しが貼ったか」まで出す。 シグネチャは**可変部を伏せて**正規化する（日付 → ``、3桁以上の数値 → ``、 パスは**ディレクトリだけ伏せて basename は残す**）。 ⚠️ パスを丸ごと `` にすると全ファイル読み取りが1グループへ潰れ、 「どれを置き換えるか」が読めなくなる。 - **増幅**: その行より後に現れるリクエスト数を掛ける。 - **集約**: `(種別, ツール, シグネチャ)` でまとめ、**増幅後トークンの降順**で並べる。 トークン推定は `ASCII文字数 / 4 + 非ASCII文字数 / 1.6` 程度の簡易式で十分（相対比較が目的のため）。 ただし**置換前後は必ず同じ推定器で測る**。別々の数え方で比べた数字は比較にならない。 --- ## 4. 出力を読むときの鉄則 **上位を1件ずつ「本当にそれか」と疑う。** 上位が直感と違うときは、発見ではなく**検出器のバグ**であることが多い。 実際この手順では、公開できる数字を出すまでに検出器の欠陥が2件（前述の行数カウントと行番号プレフィックス）見つかった。 どちらも「気づかなければ置換対象を完全に外していた」種類の誤りだった。 --- ## 5. 最大の1件だけを置き換える 全部やろうとしない。増幅後トークンの上位1件が全体の3割を占めることは珍しくない。 置換ツールの設計（この形が汎用的に効く）: - **要約だけを標準出力へ返す**: 件数、作成者・カテゴリ別の内訳、時間範囲、直近 N 件 - **1件あたりの本文に上限を設ける**（例: 200文字 + `…(全N字)`）。 ⚠️ これが無いと、**巨大な1件が予算を食い潰して「直近10件」が実質1件になる** - **全体の出力予算**（例: 6,000文字）を設け、超えたら削るが**省略件数を必ず明示する**。黙って切り捨てない - **全文は `--raw-out ` でファイルへ**。標準出力には出さない。 「全文が要るときだけ読んでください」と一言添える - 絞り込みオプション（`--since` / `--grep` / `--limit`）を持たせ、**取得段階で減らす** ### 回帰テストで「安いこと」を機械的に守る 要約ツールは放っておくと出力が育つ。**圧縮率そのものをテストにする。** ``` テスト: 実データ相当（例: 60件、本文200〜400字）を渡したとき、 要約出力の文字数が JSON 全文の 25% 未満であること ``` さらに、**上限値を無効化するとテストが落ちること**を一度確認する（変異テスト）。 落ちないテストは書いていないのと同じ。 --- ## 6. 置き換えを「実際に使われる状態」にする ツールを作っただけでは何も変わらない。**チームの運用ルールに1行入れる**まで含めて完了とする。 - チーム共通のルールファイル（エージェントが毎回読む設定ファイル等）に 「まとめ読みは一覧系ツールでなく要約ツールを使う」と書く - **用途を分けて書く**のが重要: 「まとめ読み＝要約ツール」「少数を正確に読む＝従来どおり」。 一律禁止にすると精度が要る場面で品質が落ちる - 実測値（何 tok → 何 tok）を根拠として併記する。数字が無いルールは守られない --- ## 7. 完了条件（これを満たすまで「やった」と言わない） 1. 一括データの貼付箇所を**実測で列挙**した（推測で書いていない） 2. 上位1件を置換し、**置換前後の入力トークンを同じ推定器で実測比較**した 3. 圧縮率の回帰テストがあり、**変異させると落ちる**ことを確認した 4. 運用ルールに反映し、**次に同じ作業をする人が自然に新しい経路を通る**状態になった --- ## 付録: よくある誤りチェックリスト - [ ] リクエスト数を「行数」で数えていないか（2〜3倍ずれる） - [ ] ファイル読み取りの行番号プレフィックスを剥がしたか - [ ] パス正規化で全部を1グループに潰していないか - [ ] 置換前後を**同じ**推定器で測ったか - [ ] 1件あたりの本文上限があるか（巨大な1件が予算を食う） - [ ] 省略したとき、省略件数を明示しているか - [ ] テストが空でない（変異させると落ちる）ことを確認したか - [ ] 長い指示文を**コマンドライン引数**で渡していないか （シェルがバッククォートをコマンド置換として実行し、指示の一部が消える。 Windows は引数長の上限も短い。**ファイル経由で渡す**） ---