uga.dev - A Front-end Engineer's shed

現在のテーマは「ライトモード」です。

../１つ上のページへ戻る

【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トークン
→ 約85%減		約350トークン
→ 約88%減
コード編集約900トークン
→ 約70%減		約500トークン
→ 約83%減
コンポーネント作成約1,900トークン
→ 約37%減		約1,150トークン
→ 約62%減

ちなみに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   # 表記揺れ

参考：AGENTS.md (GitHub)

英語化・冗長な記述の削除

一部のファイルが英語になり、単純に文字数が削減されました[3]。

あとテーブル（表）よりも箇条書きリストのほうがトークンが少なく済むらしく、一部がリストになっていました。シンタックス的にも文字数が少なく済むのでそれはそうか。

ファイル変更前変更後削減率
AGENTS.md9行5行約44%減
code-style.md104行55行約47%減
component-structure.md101行64行約37%減
writing-guideline.md17行14行約18%減

Skillsにも有効

調査・圧縮依頼プロンプト
このSKILL.mdの1回あたりのトークン消費量を教えてください。
また、SKILL.mdのトークン量を圧縮できそうな場合は圧縮してください。
英語の方が少ないトークン量ですみそうなら英語にしても構いません。

コミットコメントを考えるのが面倒なので、git-commitというスキルを普段使っているのですが、これも半分以下に削減できました。

項目As-IsTo-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利用者として、トークンのコストパフォーマンスを意識した設計をしていこうと思います。

脚注

  • [^1]:正確な測定ではなく、ファイルサイズから概算した結果。
  • [^2]:ChatGPT調べ。Claude Codeは時間あたりの制限はなく、「5時間ローリング枠のトークン総量」と「週間トークン上限」で制限される仕組み。トークン消費量はリクエスト内容と、その時点で送信されるコンテキスト（会話履歴や読み込まれたファイルなど）の量に大きく依存する。
  • [^3]:英語は単語単位でトークン化されやすく、日本語よりも少ないトークン数で表現できるケースが多いらしい。

𝕏拍手する