Universal Claude.md - Claudeの出力トークン削減
(github.com/drona23)- Claudeモデルの不要な導入・締め・言い換えを削除し、出力トークンの無駄を減らす設定ファイル
- プロジェクトルートに
CLAUDE.mdを追加すると、コード修正なしですぐに適用され、平均63%のトークン削減効果 - ASCII専用出力、推測禁止、要求範囲内に応答を制限など12個のルールで応答を簡潔化
- 自動化パイプライン・コード生成・エージェントループなど大量出力環境でコスト削減効果が大きく、単一クエリには非効率な場合もある
- MITライセンスで公開されており、チーム別・作業別のプロファイルベースのルール管理とコミュニティ貢献が可能
問題の概要
- Claude Codeは生成されるすべての単語でトークンコストが発生し、デフォルト設定ではユーザーが応答形式を制御しにくい
- デフォルトでは"Sure!", "Great question!"のような丁寧な導入、"I hope this helps!"のような形式的な締め、質問の言い換え、不要な提案が自動で含まれる
- また、em dash、スマートクォート、Unicode文字などパーサーを壊しうる文字を使い、過剰なコード抽象化や誤った同意表現も含む
- これによりトークンの無駄が発生し、実質的な情報価値はほとんどない
解決方法
- プロジェクトルートに
CLAUDE.mdファイルを追加すると、Claude Codeがこれを自動で読み取り、出力の挙動を即座に変更 - コード修正や追加設定なしで動作し、出力トークン使用量を約63%削減
- 構成例
your-project/ └── CLAUDE.md
適用が有利な場合と不利な場合
-
有利な場合
-
自動化パイプライン、エージェントループ、コード生成など出力量の多い作業
- 反復的で構造化された作業で、Claudeの冗長なデフォルト応答が積み重なる場合
- セッション間で一貫した出力形式が必要なチーム環境
-
-
不利な場合
- 単一の短いクエリや一回限りの利用では、
CLAUDE.md自体が毎回入力トークンを消費するため、かえってコストが増える - ハルシネーションの修正やアーキテクチャ上の誤りの是正など、深い問題解決には効果がない
- 作業ごとに新しいセッションを開くパイプラインでは、継続セッションベースの削減効果が失われる
- 大規模なパーサー信頼性の確保には、JSONモードやスキーマベースのツール利用のほうが適している
- 探索的・議論中心の作業では制約が強く感じられることがある
- 単一の短いクエリや一回限りの利用では、
-
実際のトレードオフ
CLAUDE.md自体が入力トークンを消費するため、出力量が十分に多い場合にのみ純利益が生じる- 低使用量では、削減額よりコスト増のほうが大きい
ベンチマーク結果
- 同一の5つのプロンプトでテスト
テスト 基本 最適化 削減率 async/awaitの説明 180語 65語 64% コードレビュー 120語 30語 75% REST APIの説明 110語 55語 50% ハルシネーション修正 55語 20語 64% 合計 465語 170語 63% - 約295語削減、情報損失なし
- ただし、これは方向性の指標であり、統計的統制や反復実験は実施されていない
- 出力量が多い場合にのみ純削減効果が発生
-
大規模利用時の削減例
利用量 1日の削減トークン 月間削減額 (Sonnet基準) 100回/日 約9,600 約 $0.86 1,000回/日 約96,000 約 $8.64 3プロジェクト 約288,000 約 $25.92
前後比較の例
-
基本のコードレビュー応答 (120語)
- 冗長な称賛、説明、提案を含む
-
CLAUDE.md適用後 (30語)- "Bug: <= causes an off-by-one error..." のように要点のみを伝達し、75%のトークン削減
修正される項目
| 番号 | 問題 | 修正方法 |
|---|---|---|
| 1 | お世辞的な導入 | 禁止 - 1行目から回答開始 |
| 2 | 中身のない締め | 禁止 - "I hope this helps!" を削除 |
| 3 | 質問の言い換え | 禁止 - 即時実行 |
| 4 | em dash・スマートクォート・Unicode | ASCII専用出力を強制 |
| 5 | "As an AI..." 文言 | 禁止 |
| 6 | 不要な免責文 | 実際の安全リスクがある場合のみ許可 |
| 7 | 要求外の提案 | 禁止 - 要求範囲のみ実行 |
| 8 | 過度なコード抽象化 | 最も単純に動くコードのみ許可 |
| 9 | 不確かな事実のハルシネーション | 「不明」と明記し、推測禁止 |
| 10 | ユーザー修正の無視 | 修正内容をセッション基準の事実として固定 |
| 11 | 重複ファイル読み込み | 同一ファイルの再読込禁止 |
| 12 | 範囲拡張 | 要求外のコード修正禁止 |
コミュニティのヒント
- 実際の失敗パターンに合わせたルール作成が最も効果的
- 例: パイプラインエラーをClaudeが握りつぶす場合 → 「ステップ失敗時は直ちに停止し、完全なエラーとtracebackを報告」ルールを追加
-
CLAUDE.mdファイルは階層的にマージ可能- グローバル(
~/.claude/CLAUDE.md): 一般ルール(トーン、ASCIIなど) - プロジェクトルート: プロジェクト別制約(例:
/configの修正禁止) - 下位ディレクトリ: 作業別の詳細ルール
- これによりルールを分散管理し、ファイルの肥大化を防止
- グローバル(
プロファイル構成
- プロジェクト種別ごとに異なる圧縮レベルを選択可能
プロファイル 適した対象 CLAUDE.md汎用 profiles/CLAUDE.coding.md開発・コードレビュー・デバッグ profiles/CLAUDE.agents.md自動化・マルチエージェントシステム profiles/CLAUDE.analysis.mdデータ分析・リサーチ・レポーティング
使用方法
- オプション 1 (汎用)
curl -o CLAUDE.md https://raw.githubusercontent.com/drona23/claude-token-efficient/… - オプション 2 (プロファイル選択)
git clone https://github.com/drona23/claude-token-efficient cp claude-token-efficient/profiles/CLAUDE.coding.md your-project/CLAUDE.md -
オプション 3 (手動)
- リポジトリの
CLAUDE.md内容を直接コピー
- リポジトリの
オーバーライドルール
-
ユーザー命令が常に優先
- ユーザーが「詳しく説明してほしい」など明示した場合、Claudeはそのまま従う
CLAUDE.mdはユーザーの意図を抑制しない
貢献方法
- 修正可能な挙動を見つけた場合はIssueを登録
- 問題のあるデフォルト挙動
- それを引き起こしたプロンプト
- 提案する修正ルール
- コミュニティ提案は次期バージョンに反映され、貢献者クレジットが付与される
検証と参考
- 全ベンチマーク結果は
BENCHMARK.mdで確認可能 - プロジェクトはClaudeコミュニティの実際の不満事例をもとに制作
- 関連参考ソースを多数収録 (GitHub Issue, The Register, DEV Community, Medium, Anthropic Docs など)
ライセンス
- MITライセンス、自由に利用・修正・配布可能
1件のコメント
Hacker Newsの意見
ここのベンチマークは単一の説明型タスクに偏っていて、コード生成のようなエージェントループには適していないと思う
プロジェクトが進行中のとき、Claudeの冗長な説明がむしろセッションの一貫性と集中力の維持に役立つのか気になる
「重複したコンテキストを繰り返すな」というルールは良いが、私はむしろ目標指向の推論トークンをより多く使うほうが役立つと思う
このアプローチが実際のエージェント型コーディングで効果的かどうかは、まだデータが不足している
/handoffというスキルを作って、セッションが圧縮限界に達する前にMarkdownレポートを自動生成させているこのファイルはセッションの永続的な記録であり、「日報」の役割も果たすので、後で参照したりマネージャーに共有したりしやすい
長期的な一貫性を保つには、こうした要約ドキュメント化の方式のほうが良いと思う
インストール方法はこちらに載せてある
最近の研究によると、重複した推論経路（self-consistency）とモデルアンサンブリングが性能向上に役立つという
最小の長さにこだわるのはRLの学習目標と食い違う
テストコードはこちらにある
Claude Codeのplanning modeがまともに機能しないので、.mdファイル方式には懐疑的だ
私の考えでは、planning modeは単にファイル書き込みを無効にする機能であるべきだ
「答えは常に1行目、推論はその後」というルールは、LLMの自己回帰的特性を無視している
答えを先に固定すると、その後の推論が確証バイアスに陥る危険が大きい
**Compressed Chain of Thought（CCoT）**論文のように、推論を圧縮する方式のほうが効率的だ
品質低下は多少あるが、速度とコストの面で利点がある（論文リンク）
つまり、「答え先出し」ルールは出力順序を変えるだけで、実際の推論順序を変えるわけではない
このベンチマークは精度を考慮せず出力トークン数だけを比較しているので無意味だ
「常に一語で答えろ」というプロンプトでも簡単にスコアを上げられる
「ユーザーが事実誤認を指摘したら無条件で受け入れろ」のようなルールは危険だ
こうした万能ソリューション系は、すぐに興味を失われるかCCに吸収される可能性が高いと思う
頻繁にワークフローを変えるのはあまりに疲れる
現時点では、デフォルトのClaude Code設定が最も安定している
Skillsは好きだが、MCPやworktreeはほとんど使わない
CLAUDE.mdは賢い同僚に送る下書きメモのように扱えば、十分うまく機能する
Anthropicが直接入れていない機能なら、おそらく性能向上が証明されていないからだろう
一時的に有用でも、すぐに基本機能に吸収されるか消えていく
したがって、こうした実験的スクリプトを使う場合でも、mdファイルを頻繁に更新すれば最新状態を保てる
「ファイルがメッセージごとにコンテキストへ読み込まれるなら、トークンの無駄では？」という質問に対しては、
Claudeのpersonalization機能がすでにその役割を果たしていると思う
私は簡潔さが品質を高めるときにだけ意味があると考える
Redditで見た関連ツールも興味深い:
Headroomはコンテキストを34%圧縮し、
RTKはCLI出力を60〜90%圧縮し、
MemStackは持続的メモリを提供して不要なファイル再読込みを防ぐ
こうした試みはむしろLLMの基本原理を誤解した結果のように感じる
「答え先、推論後」はtransformerの自己回帰構造を無視している
RL学習がすでに最適な長さと品質を調整しているのだから、過度な修正は性能低下につながりうる
モデルは英語ベースで多段階推論を行うよう学習されている
品質より効率を狙った実験的アプローチだ
だから私はOpenCodeのようなサードパーティより1st-partyツールしか使わない
Karpathyの動画で見たように、モデルがより多くのトークンを使うほど正確性が高まる傾向がある
このアプローチはむしろモデルを悪くするかもしれない
しかし、推論なしで即座に答えさせると早期確定バイアスが生じる危険がある
なぜこんな意味のないプロジェクトがHNでトレンドになるのかわからない
本当にトークン使用量を減らすツールはclaude-memやlumenのようなものだ
昔は新しいハッシュ、暗号化、圧縮アルゴリズムを研究していたのに、
今ではAIに黙れと指示する方法を研究しているという現実が皮肉だ