【Claude Code】AGENTS.mdを最適化してトークン使用量を80%削減した話
公開日：
- #Claude
- #生成AI
- #雑記
このところ頻繁にClaude Codeの利用上限に到達するので、トークン消費量について見直すことにしました。
ClaudeのことはClaudeに頼むのが一番なので、調査と改善を依頼した結果をまとめておきます。
あなたには、スラッシュコマンドの運用、ブログ記事のレビュー、コードレビュー、機能の作成をお願いしています。AGENTS.mdの内容にしたがうようにCLAUDE.mdには書かれていますが、毎回必ず読まないといけない内容と、必要に応じて読む内容でドキュメントを分割して欲しいです。
また、いつも読み込んでいるけど実際のところトークンを無駄に消費している情報、設計があれば指摘してください（~/.claude配下含む）
CLAUDE.md は AGENTS.md のシンボリックリンクにしてほしいです。
AGENTS.md の中身にはこのタスクをするときはこのドキュメントを参照すること、というふうに分岐させるだけにして、分岐先は .agents/rules/writing-guideline.md のようにドキュメントを分けておきたいです。AGENTS.md および .agents 配下のファイルについて、トークン量を圧縮できそうな場合は圧縮してください。
英語の方が少ないトークン量ですみそうなら英語にしても構いません。結論：トークン使用量が激減
今まで何かしら話しかけるたびに、およそ3,000トークンを消費していたようです[1]。
ファイル | サイズ | 概算トークン |
|---|---|---|
CLAUDE.md | 約600バイト | 約200トークン |
AGENTS.md（全文） | 約8,000バイト | 約2,800トークン |
合計 | 約3,000トークン |
筆者はClaude Code Proユーザなのですが、1時間あたりに使えるトークン数を無理やり計算すると、約8,800 tokens / 時間らしく[2]、細かいことを抜きにすると3回挨拶するだけで9,000トークンが消費されるような状況だった模様。そりゃすぐ5時間制限に到達するよ…。
それがClaudeにチューニング依頼した結果、いままでとてつもない量のトークンをムダにしていたことがわかり、大変つらい結果が明らかになりました。
タスク | 分割のみ | 分割＋圧縮 |
|---|---|---|
記事のレビュー | 約450トークン | 約350トークン |
コード編集 | 約900トークン | 約500トークン |
コンポーネント作成 | 約1,900トークン | 約1,150トークン |
ちなみにClaudeがOpenAI系のトークナイザ（cl100k_base）を使って計測した結果、読み込むファイルは英語化することでさらに圧縮率が上がるみたいです。
何が変わったのか
もともと雑にCLAUDE.mdとAGENTS.mdだけ作っていて、必要に応じてClaudeにAGENTS.mdを更新させて、気が向いたらコミットしようかな、みたいな運用をしていました。
コミットするタイミングを逃し続けて、いつの間にかAGENTS.mdは8,000バイトになっていたようです😇
ファイル構成の変更
AGENTS.md # 全ルール
CLAUDE.md # ルール抜粋＋ AGENTS.md への参照冒頭のプロンプトで、毎回読む必要のない情報の切り出しと、CLAUDE.mdをAGENTS.mdのシンボリックリンクにすることをお願いしました[3]。
AGENTS.md # どのタスクならどのファイルを読め
CLAUDE.md -> AGENTS.md # シンボリックリンク
.agents/rules/
code-style.md # コーディングスタイル
component-structure.md # コンポーネント設計指針
writing-guideline.md # 表記揺れ英語化・冗長な記述の削除
一部のファイルが英語になり、単純に文字数が削減されました[3]。
あとテーブル（表）よりも箇条書きリストのほうがトークンが少なく済むらしく、一部がリストになっていました。シンタックス的にも文字数が少なく済むのでそれはそうか。
ファイル | 変更前 | 変更後 | 削減率 |
|---|---|---|---|
| 9行 | 5行 | 約44%減 |
| 104行 | 55行 | 約47%減 |
| 101行 | 64行 | 約37%減 |
| 17行 | 14行 | 約18%減 |
Skillsにも有効
このSKILL.mdの1回あたりのトークン消費量を教えてください。
また、SKILL.mdのトークン量を圧縮できそうな場合は圧縮してください。
英語の方が少ないトークン量ですみそうなら英語にしても構いません。コミットコメントを考えるのが面倒なので、git-commitというスキルを普段使っているのですが、これも半分以下に削減できました。
項目 | As-Is | To-Be |
|---|---|---|
言語 | 日本語主体（一部英語・コード） | 英語に統一 |
文字数 | 1,560文字 | 1,292文字 |
トークン数 | 約1,095（cl100k_base） | 約371（cl100k_base） |
削減量 | - | 約724削減（約66%） |
まとめ
単純計算で1回にかかるトークン消費量を50％削減できていれば、同じ期間でだいたい2倍Claude Codeが使えるということになります。
1回のプロンプトごとに、それまでの会話ログ（コンテキスト）も含めて処理されるClaude Codeの仕様を考えると、心苦しいですが挨拶やお礼だけのやり取りも避けた方がお財布には優しいかもしれません…。
今後もSkillやAGENTS.mdなどを用意する場合は、次のことを意識しようと思います。
常時読み込まれるドキュメントは最小限にする
タスクごとにドキュメントを分割し、必要なものだけ参照させる
長ければ長いだけ財布にも痛いし精度も落ちる
必要に応じて英語化し、最小表現で構成するように伝える
フロントエンドで表示パフォーマンスを考えるような感覚で、AI利用者として、トークンのコストパフォーマンスを意識した設計をしていこうと思います。