token-efficiency

トークン効率のエキスパート

このスキルでは、あらゆるプロジェクトで Claude Code をコスト効率よく使うためのトークン最適化戦略を紹介します。これらのガイドラインに従うことで、支援の品質を維持しながらトークン消費を最小限に抑えられます。

基本原則

ユーザーが明示的に冗長な出力やファイル全体の内容を求めない限り、常にこれらの最適化ガイドラインに従ってください。

デフォルトの前提：ユーザーは効率的で費用対効果の高い支援を望んでいます。

---

モデル選択戦略

コストとパフォーマンスを最適化するため、タスクに適したモデルを使います。

Opus — 学習と深い理解に使用

次の場合に Opus を使用します。

• 新しいコードベースの学習 — アーキテクチャ、コード構造、設計パターンの理解
• 幅広い調査 — 重要なファイルの特定、リポジトリ構成の理解
• 深い分析 — 複雑なアルゴリズム、パフォーマンス最適化の分析
• 読解と理解 — 変更を加える前に既存のコードを理解する必要がある場合
• 非常に複雑なデバッグ — Sonnet で解決できない場合、または問題がアーキテクチャに関わる場合のみ

Sonnet — 通常の開発タスクに使用（デフォルト）

次の場合は Sonnet（デフォルト）を使用します。

• コードの作成、編集と修正、デバッグ、テスト、ドキュメント作成、デプロイ、一般的な質問

一般的なセッションの進め方：

1. Opus から開始 — コードベースの理解に 10～15 分をかけます（一度だけの投資です）
2. Sonnet に切り替え — すべての実装、デバッグ、定型作業に使用します
3. Opus に戻る — 深いアーキテクチャ理解が明示的に必要な場合のみ使用します

すべて Opus を使う場合と比べ、トークンコストを約 50％削減できます。

---

スキルとトークン効率

誤解： .claude/skills/ にスキルがたくさんあると、トークン使用量が増える。

実際： スキルは段階的開示を採用しているため、Claude がセッション開始時に確認するのはスキルの説明だけです（4 つのスキルで約 155 トークン）。スキルの内容全体は、有効化されたときにのみ読み込まれます。

複数のスキルをプロジェクトにシンボリックリンクしても問題ありません。 トークンの無駄はスキルを利用可能にしておくことではなく、大きなファイルを不必要に読むことから生じます。

---

トークン最適化ルール（クイックリファレンス）

1. 静音／最小出力モードを使う

デフォルトで --quiet、-q、--silent フラグを使用します。ユーザーから明示的に求められた場合のみ、詳細な出力を使います。

2. ログファイル全体を絶対に読まない

読む前に必ず絞り込みます。tail -100、grep -i "error"、特定の時間範囲などを使います。

3. まず軽量な情報源を確認する

大きなファイルを読む前に、git status --short、package.json、requirements.txt を確認します。

4. ファイルを読む代わりに Grep を使う

ファイル全体を読むのではなく、Grep ツールで特定の内容を検索します。

5. 範囲を指定してファイルを読む

offset と limit パラメーターを使います。まず wc -l でファイルサイズを確認します。

6. ファイルを読む代わりに Bash コマンドを使う

純粋な変換や調査では、極めて重要な最適化です。ファイルを読むとトークンを消費しますが、Bash コマンドでは消費しません。

操作	非効率	効率的
ファイルをコピー	Read + Write	cp source dest
テキストを置換	Read + Edit	sed -i '' 's/old/new/g' file
追記	Read + Write	echo "text" >> file
行を削除	Read + Write	sed -i '' '/pattern/d' file
ファイルを結合	Read + Read + Write	cat file1 file2 > combined
行数を数える	ファイルを読む	wc -l file
内容を確認	ファイルを読む	grep -q "term" file
JSON を調べる	読んで頭の中で解析	python3 -c "import json; ..." または jq

このルールを適用せず、Read + Edit を優先する場合：

• コードの編集（.py、.js、.xml、.ga、.tsx など）。ユーザーがレビュー可能な差分を確認できるメリットがある場合。小さなファイルを読むコストは、レビューのしやすさに見合います。
• 検証が重要な場合 — 構文ミスによってファイルが破損するおそれがある場合（ワークフロー JSON、設定スキーマなど）。
• 対話的なレビュー — ユーザーが変更内容を明示的に確認したい場合。

適切な考え方は「常に Bash」でも「常に Read+Edit」でもなく、作業範囲に基づいて選ぶことです（次のセクションを参照）。詳しい戦略やパターンについては、strategies.md をご覧ください。

7. コマンド出力を絞り込む

範囲を限定します：head -50、find . -maxdepth 2、tree -L 2。

8. 出力をそのまま表示せず、要約する

ディレクトリの内容、コード構造、コマンド出力を構造化して要約します。

9. 大量の出力には Head/Tail を使う

head -100、tail -50、途中のサンプルには head -500 | tail -100 を使います。

10. JSON／データツールを効率よく使う

特定のフィールドを抽出します：jq '.metadata'、jq 'keys'。CSV には head -20、wc -l を使います。

11. コードの読み取りを最適化する

まず概要を把握し（find、クラス／関数を grep で検索）、構造だけを読み、特定のコードを検索して、関連する部分だけを読みます。

12. 探索的な検索には Task ツールを使う

広範囲なコードベースの探索には、Task／Explore サブエージェントを使います。複数ファイルを直接調べる場合と比べて、トークンを 70～80％節約できます。

13. 科学文献の検索を効率化する

関連する検索を 3～5 件まとめて並列実行します。結果はすぐに保存し、「見つからなかった」項目も記録します。

詳しい方法、bash のパターン、豊富な例については、strategies.md を参照してください。

---

スコープに応じたツールの選択

bash と Read+Edit の使い分けは、トークンコストだけで決まるものではありません。ユーザーが変更内容を確認できることに価値があるかどうかが重要です。作業のスコープに合わせてツールを選びます。

スコープ	推奨ツール	理由
構造化データ（JSON、YAML、JSONL、大きなログ）の読み取り専用の確認	python3 -c、jq、grep、awk	bash の出力はフィルタリングでき、ソースファイルを誤って編集するリスクがありません。JSON の確認には、インラインの python3 -c のほうが Read+parse より高速で低コストです。
コード（.py、.js、.xml、.ga、.tsx）の直接編集	Read + Edit	ユーザーがレビュー可能な差分を確認でき、構文上のミスを早期に検出できます。
大きなデータファイル（CSV、大きな JSON、BAM 由来の TSV）の変換	sed、awk、python3 スクリプト	ファイル全体を読むと、数千トークンを消費します。
新規ファイルの作成	Write ツール	1 回の往復で済みます。bash のヒアドキュメントを使っても利点はなく、レビューもできません。

簡単なルール：ユーザーが変更内容を確認して承認したい場合は、Read+Edit を使います。純粋なデータ加工や確認の場合は、bash／python を使います。

ファイル操作の判断フロー

自問してください：

1. 新しいファイルを作成する？ -> Write ツール
2. 低コストな操作（出力が 100 行未満）？ -> Claude のコンテキスト内で直接処理
3. コードファイル（.py、.js、.xml）を変更する？ -> Read + Edit（必ず）
4. 小さなデータファイル（100 行未満）を変更する？ -> Read + Edit で問題ありません
5. 重要なデータ（ゲノム統計、拡張済みテーブル）を変更する？ -> bash + ログファイル
6. 大きなデータファイルを変更する？ -> sed／awk
7. ファイルをコピー／移動する？ -> cp／mv

---

これらのガイドラインを適用しない場合

次の場合は、効率化のルールを適用しないでください：

1. ユーザーが出力全体を明示的に求めている（「ログファイル全体を表示してください」）
2. フィルタリングした出力では必要なコンテキストが不足している（エラーが行番号の欠落を参照している）
3. ファイルが小さいと分かっている（200 行未満）
4. コード構造やアーキテクチャを学ぶ場合 - 効率より理解を優先する

学習モードでは：

• 理解を深めるため、主要なファイルを 2～5 個、全体を通して読みます
• grep を使って、関連するほかの例を探します
• 多数のファイルから見つかったパターンを要約します
• 学習フェーズの後は、実装時に効率的なモードへ戻ります
• 学習モードの詳しい方法については、learning-mode.md を参照してください

1～3 の場合は、トークンコストをユーザーに説明し、先にフィルタリングした表示を提案してください。

---

クイックリファレンスカード

モデルの選択（最優先）：

• 学習／理解 -> Opus を使用
• 開発／デバッグ／実装 -> Sonnet を使用（デフォルト）

ファイル操作を行う前に、必ず自問してください：

1. 新しいファイルを作成しますか？ -> Write ツールを直接使用
2. 低コストの操作ですか？（100 行未満） -> Claude コンテキストを直接使用
3. コードファイルを変更しますか？ -> Read + Edit を使用（常に）
4. 小さなデータファイルを変更しますか？（100 行未満） -> Read + Edit で問題ありません
5. 重要なデータを変更しますか？ -> bash + ログファイルを使用
6. 大きなデータファイルを変更しますか？ -> bash コマンドを使用（99％以上の節約）
7. ファイルをコピー／マージしますか？ -> Read/Write ではなく、cp/cat を使用
8. 先にメタデータを確認できますか？（ファイルサイズ、行数）
9. 読み込む前に絞り込めますか？（grep、head、tail）
10. 構造だけを読み込めますか？（最初の 50 行、関数名）
11. 生データを表示する代わりに要約できますか？
12. ユーザーは本当に全内容を必要としていますか？

---

コストへの影響

方法	トークン／週	備考
非効率（すべてを Read/Edit/Write）	500K	不必要なファイルの読み込み
標準的（絞り込んで読み込む）	200K	Grep/head/tail の使用
効率的（bash コマンド + フィルター）	30-50K	Read の代わりに cp/sed/awk を使用

これらのルールを適用すると、平均でコストを 90～95％削減できます。

---

実装

このスキルは、次の場合にこれらの最適化を自動的に適用します：

• ログファイルの読み込み
• 大量の出力を伴うコマンドの実行
• コードベースの確認
• エラーのデバッグ
• システムステータスの確認

次のように指示すれば、いつでも上書きできます：

• 「出力をすべて表示して」
• 「ファイル全体を読み込んで」
• 「詳細モードにして」
• 「トークンは気にしないで」

---

関連ファイル

ファイル	内容	読み込むタイミング
strategies.md	bash コマンドの詳細な戦略、ファイル操作のパターン、sed/awk の例、Jupyter ノートブックの操作、安全な glob パターン、macOS/Linux との互換性	特定のファイル操作を実装する場合や、bash の詳細なパターンが必要な場合
learning-mode.md	戦略的なファイル選択、対象を絞ったパターン学習のワークフロー、リポジトリの幅広い調査戦略、リポジトリタイプの特定	学習モードに入る場合や、新しいコードベースを調査する場合
examples.md	前後の比較を含む豊富なトークン節約の例、対象を絞った学習例（Galaxy ラッパー、API パターン）、コスト計算	トークン節約を説明する場合や、例から学ぶ場合
project-patterns.md	分析ファイルの整理、TodoWrite によるタスク管理、バックグラウンドプロセスの管理、リポジトリの整理、MANIFEST システム、効率的なファイル操作	プロジェクトを整理する場合、長時間実行タスクを管理する場合、またはナビゲーションパターンを設定する場合

---

まとめ

基本方針：適切なモデル。適切なツール。まず絞り込む。選択的に読む。賢く要約する。

モデルの選択（最も大きな効果）：

• 学習／理解には Opus を使用（一度限りの投資）
• 開発／デバッグ／実装には Sonnet を使用（デフォルト）

ツールの選択（主な最適化）：

• 新しいファイルの作成 -> Write ツールを直接使用
• 低コストの操作（100 行未満） -> Claude コンテキストを直接使用
• コードファイルの変更 -> Read + Edit を使用（常に）
• 小さなデータファイルの変更（100 行未満） -> Read + Edit で問題ありません
• 大きなデータファイルの変更 -> bash コマンド（sed、awk、grep）を使用
• 重要なデータの変更 -> bash コマンド + ログファイルを使用
• 複雑な編集 -> Read + Edit ツールを使用

その他のルール：

• 読み込む前に絞り込む（grep、head、tail）
• 必要に応じて読み込み量を制限する
• 生の出力を表示する代わりに要約する
• コマンドでは静音モードを使用する
• 学習では戦略的にファイルを選択する

これらのガイドラインに従うことで、質の高いアシスタンスを維持しながら、Claude のサブスクリプションから 5～10 倍の価値を得られます。