Claude Codeを自動化パイプラインに組み込むとき、最も気になるのがAPI費用です。想定外の大量リクエストやプロンプトの暴走で、気づいたら高額な請求が来ていた――そんな事態は避けたいものです。--max-budget-usd オプションを使えば、1回の実行あたりの費用上限をドル単位で設定でき、コスト超過を確実に防げます。
この記事では、費用上限の設定方法から、実際のREADME生成スクリプトへの組み込み方までを解説します。
max-budget-usdの基本
--max-budget-usd はprintモード（-p）専用のオプションで、1回の実行で使えるAPI費用の上限をUSドルで指定します。
上限を超えた場合、実行は途中で停止し、is_errorがtrue、subtypeがerror_max_budgetのエラー情報が返されます。
printモードについて詳しく知りたい人は、【Claude Code】printモード入門｜パイプ連携とスクリプト活用の基本 こちらを参考にしてください。
推奨値の目安
| タスク | 推奨範囲 |
|---|---|
| 簡単な解析・要約 | 0.01 – 0.05 |
| README全体の生成 | 0.05 – 0.20 |
| 大規模リポジトリの解析 | 0.20 – 1.00 |
最初は余裕を持った値を設定し、output-format jsonのcost_usdフィールドで実際のコストを確認してから、適切な値に調整していくのがおすすめです。
output-formatについて詳しく知りたい人は、Claude Codeの–json-schemaで構造化出力する方法――スキーマ定義から実践まで こちらを参考にしてください。
よくある落とし穴：上限が小さすぎる
max-budget-usdを極端に小さく設定すると、応答が生成される前に上限に達してしまいます。まずは大きめの値で実行し、cost_usdを確認してから絞り込みましょう。
JSON出力と組み合わせてコストを監視する
output-format jsonと組み合わせると、毎回の実行コストを正確に把握できます。スクリプトに組み込めば、コストのログを自動的に残すことも可能です。
コスト管理のベストプラクティス
段階的に上限を調整する
- まず大きめの値（例: 1.00）で実行し、実際のコストを把握する
- 実際のコストの2～3倍を上限に設定する
- 定期的にコストを確認し、必要に応じて調整する
エラーハンドリングを必ず入れる
バジェット超過はエラーとして返されるため、スクリプトで必ずis_errorを確認してください。確認を忘れると、空の応答で後続処理が壊れる原因になります。
環境変数で上限を管理する
チームで共有するスクリプトでは、上限値を環境変数にしておくと柔軟に運用できます。
次に試してみよう
同じプロンプトをmax-budget-usdの値を0.01、0.05、0.20と変えながら実行し、cost_usdと応答内容の違いを比較してみてください。
さらに深く学びたい方へ
Claude Codeの Skills・MCP・Agent・Hooks・Plugin を体系的に学べる有料教材を Zenn で公開しています。
Claude Code 実践ガイド（Zenn Book）
