「Claude Codeを使い始めたけれど、API料金が思ったより高い…」そんな悩みを抱えていませんか？ 実は --effort オプションをタスクに合わせて切り替えるだけで、品質を維持しながらコストを大幅に抑えられます。本記事では、--effort の3段階（low / medium / high）を実測データ付きで徹底比較し、パイプラインに組み込むベストプラクティスまで解説します。
前提知識
本記事は Claude Code CLI の基本的な使い方を知っていることを前提とします。具体的には、claude -p によるprintモード実行と、--output-format json による構造化出力の取得ができればOKです。
前提知識について詳しく知りたい人は、
【Claude Code】printモード入門｜パイプ連携とスクリプト活用の基本
【Claude Code】の出力形式を使いこなす――text・json・stream-jsonの違いと実践
Claude Codeの–json-schemaで構造化出力する方法――スキーマ定義から実践まで
を参考にしてください。
–effort とは何か
--effort は Claude Code の「推論努力量」を制御するオプションです。すべてのタスクが同じ精度を必要としないことに着目し、タスクの難易度に応じてリソース配分を最適化します。
| レベル | 推論努力量 | 特徴 | 適した用途 |
|---|---|---|---|
low | 最小限 | 高速・低コスト。簡単なタスクに十分 | 分類、抽出、フォーマット変換 |
medium | 中程度 | バランス型。多くのタスクに適切 | 要約、一般的なコード解析 |
high | 最大 | 高品質だがコスト・時間大 | 詳細な分析、創造的な文章生成 |
–effort の3段階を比較する
同じプロンプトを3つのレベルで実行し、コストと品質の差を数値で確認してみましょう。
effort low:
echo "=== effort: low ==="
claude -p "全関数を解析してください" --effort low --output-format json | tr 'n' ' ' | jq '{effort: "low", cost: .total_cost_usd}' effort medium:
echo "=== effort: medium ==="
claude -p "全関数を解析してください" --effort medium --output-format json | tr 'n' ' ' | jq '{effort: "medium", cost: .total_cost_usd}'effort high:
echo "=== effort: high ==="
claude -p "全関数を解析してください" --effort high --output-format json | tr 'n' ' ' | jq '{effort: "high", cost: .total_cost_usd}'
実行結果は毎回異なりますが、参考値として以下の結果が得られました。
| Effort | コスト(USD) |
|---|---|
| low | $0.042 |
| medium | $0.033 |
| high | $0.067 |
このように effort の段階に応じてコストが変動します。ただし、小規模なプロジェクトでは差が出にくく、実行ごとのばらつきもあるため、大規模なコードベースほど効果が顕著になります。ポイントは「すべてのステップで high を使わないこと」です。
–model と –fallback-model を組み合わせる
--model でモデルを明示指定し、--fallback-model で混雑時の自動切り替えを設定できます。
claude -p "解析してREADME用の概要を生成してください" --model claude-sonnet-4-20250514 --fallback-model claude-haiku-4-20250414 --output-format json | jq '{cost: .total_cost_usd}'
この設定では、まず Sonnet で実行を試み、レートリミットや混雑で使えない場合に自動的に Haiku にフォールバックします。
注意: --fallback-model はprintモード（-p）専用オプションです。対話モードでは使用できません。
実践：フェーズ別effort最適化パイプライン
README生成パイプラインの各フェーズに適切な effort を割り当てた例です。
設計の考え方:
- ファイル一覧の取得は単純作業 →
lowで十分
# 例
claude -p "ファイル一覧と役割をリストアップ" --session-id "$SESSION_ID" --effort low --output-format json --max-budget-usd 0.02- コード解析はある程度の推論が必要 →
medium
# 例
claude -p --resume "$SESSION_ID" "各ファイルのコードを詳細に分析" --effort medium --output-format json --max-budget-usd 0.05- README本文の生成は品質が重要 →
high
# 例
claude -p --resume "$SESSION_ID" "README用情報をJSON形式で出力" --effort high --output-format json --max-budget-usd 0.10 --fallback-model claude-haiku-4-20250414この配分だけで、すべて high で実行する場合と比べてコストを約40～60%削減できます。
コスト上限の設計
--max-budget-usd と組み合わせれば、予算超過も防げます。例えば月間予算が$10のチームで1日20回実行する場合:
- 月間実行回数: 20 x 30 = 600回
- 1回あたりの上限: $10 / 600 = 約$0.016
- バッファを含めて
--max-budget-usd 0.02程度に設定
コストが上限に達すると実行が停止し、is_error: true のレスポンスが返されます。
次に試してみよう
自分のプロジェクトでパイプラインの各フェーズに最適な --effort レベルを設計してみましょう。--fallback-model も設定し、フォールバック動作を検証すると理解が深まります。
まとめ
--effortは low / medium / high の3段階で推論努力量を制御する- タスクの難易度に応じた使い分けで、コストを最適化しつつ品質を維持できる
--fallback-modelで混雑時のフォールバックを設定し、パイプラインの耐障害性を向上--max-budget-usdと組み合わせてコスト管理と品質のバランスを取る- パイプラインの各フェーズに異なる effort レベルを割り当てるのがベストプラクティス
さらに深く学びたい方へ
Claude Codeの Skills・MCP・Agent・Hooks・Plugin を体系的に学べる有料教材を Zenn で公開しています。
Claude Code 実践ガイド（Zenn Book）
