メインコンテンツまでスキップ

claude CLI:結果を左右するフラグ

中級

Claude Code のコマンドラインについて、多くの人は claude、claude -c、claude -p の 3 つを覚えたところで止まります。画面の前に座って使うだけなら、それで十分です。しかし Claude Code をスクリプト、CI ジョブ、バックグラウンドのキュー、あるいはチームメイトの手に委ねた途端、フラグは単なる便利機能ではなくなります。1 ドルで終わる実行と、1 時間ハングし続ける実行を分けるものになるのです。

このページはリファレンス表の写しではありません。この領域をどの順番で学ぶか、実際に結果を変えるフラグ、そして実害の出やすい 4 つの落とし穴をまとめています。

What you'll learn
  • 開始できる 6 種類のセッションと、それぞれを選ぶフラグ
  • 無人実行に上限、応答、パース可能性をもたらす 5 つのフラグの契約
  • --append-system-prompt を編集して --continue で再実行しても何も変わらないように見える理由(記録済みプロンプトのルール)
  • --bare、--safe-mode、--restricted の違いと、それぞれを使う場面
  • シェルからバックグラウンドセッションを操作する方法:agents、attach、logs、respawn、rm、daemon
  • 混同されがちなフラグの組:--tools、--allowedTools、--disallowedTools

まず問いから始める:これはどんな種類のセッションか​

ほかの判断はすべて、この一点から決まります。Claude Code は実質的に異なる 6 種類のものを開始でき、それを選ぶフラグが最初に打つものになることがほとんどです。

やりたいことフラグ得られるもの
画面を見ながら進める会話(なし)このターミナルでのインタラクティブセッション
1 回答えて終了-p / --print非インタラクティブ実行、出力は stdout
このターミナルより長く続く作業--bg / --backgroundバックグラウンドセッション。ID と管理方法を表示します
試行用に隔離したブランチ-w / --worktree<repo>/.claude/worktrees/<name> 配下の git worktree
Anthropic のマシン上での作業--cloudクラウドセッション、または既存のセッションにキューされるフォローアップ
スマートフォンからこのセッションを操作する--rc / --remote-controlclaude.ai や Claude アプリからも操作できるインタラクティブセッション

このうち --bg と -p は組み合わせられません。片方はすぐに戻り、もう片方は答えを待つためです。バックグラウンドで動かしたいのが Claude セッションではなくシェルコマンドなら、--bg を --exec と組み合わせます。

テストスイートを Claude セッションではなくバックグラウンドジョブとして実行する

claude --bg --exec 'pytest -x'

また --bg は開始前にそのディレクトリのワークスペース信頼(workspace trust)を確認します。そのため、信頼されていないリポジトリでのバックグラウンドセッションは、途中ではなく最初の段階で失敗します。

無人実行のための 5 つのフラグの契約​

このページで最も価値の高い内容です。無人の claude -p 実行には、インタラクティブセッションにはない 3 つの失敗パターンがあります。答える人が誰もいない権限プロンプトで止まる、想定よりはるかに長くループする、スクリプトがデータを必要としているのに文章を出力する、の 3 つです。5 つのフラグでこの 3 つすべてを防げます。

Guided walkthrough1 of 5
  1. `claude -p "query"` は答えを出力して終了します。以下はすべて print モード専用なので、このフラグが残りの入口になります。

ハングせず、無限ループせず、使いすぎない CI ステップ

claude -p "Review the staged diff and list bugs" \
--permission-prompts none \
--allowedTools "Read" "Bash(git diff *)" \
--max-turns 6 \
--max-budget-usd 2.00 \
--output-format json
--max-budget-usd は見積もりであり、請求額ではありません
  • Claude Code は上限を自身のクライアント側コスト見積もりと照合します。この見積もりは、実際の請求額と異なる場合があります。
  • --continue や --resume で会話に戻る場合、以前の実行から復元された合計は上限に算入されません。そのため、2 ドルの上限でも、再開した 3 回の実行の合計は 2 ドルを超えることがあります。
  • 1 回の実行に対する遮断器と考えてください。アカウントやプロジェクト全体に対する本当の上限については、「Hard Spend Caps」を参照してください。

人が介在しない実行を許可する際の全体的な方針(何を許可し、何をマスクし、何を記録するか)については、自律実行の堅牢化とヘッドレスモードと Agent SDKを参照してください。プロバイダーレベルの上限については、Hard Spend Capsを参照してください。

システムプロンプト系フラグと、その落とし穴​

システムプロンプトを形作るフラグは 5 つあります。4 つはその文面を設定し、5 つ目は会話が開始時のテキストを保持し続けるかどうかを決めます。

フラグ動作
--system-promptデフォルトのプロンプト全体を、指定したテキストで置き換えます
--system-prompt-fileファイルの内容で置き換えます
--append-system-promptデフォルトのプロンプトに、指定したテキストを追加します
--append-system-prompt-fileデフォルトのプロンプトに、ファイルの内容を追加します
--system-prompt-snapshotoff は毎回のリクエストでプロンプトを再構築し、on(デフォルト)は記録済みのものを再利用します

追加にするか置換にするかは、アイデンティティをどうするかという選択です。追加は Claude Code のデフォルトのツールガイダンス、安全性に関する指示、コーディング規約を維持したまま、その上にあなたのルールを重ねます。実行ごとの指示、出力フォーマット、プロジェクトのコンテキストに適しています。置換はツールガイダンスを含めてそのすべてを捨てるため、そのサーフェスが本当にコーディングアシスタントではない場合、つまり誰も見ていないパイプライン内の非コーディングエージェントのような場合にのみ適切です。置換する場合、タスクがなお必要とするものはすべて自分で用意することになります。

両者は組み合わせられます。追加フラグと置換フラグを一緒に渡すと、デフォルトを置き換えたうえでテキストが追加されます。v2.1.283 以降では、フラグとそのファイル形式、たとえば --append-system-prompt と --append-system-prompt-file を同時に渡すこともでき、Claude Code は両方を使います。その際、入力した順序に関係なく、ファイルの内容が先に置かれます。

落とし穴:再開した会話は、生まれた時のプロンプトを再利用する
  • Claude Code はシステムプロンプトを会話の最初のリクエストで一度だけ構築し、セッションに記録します。
  • 会話がコンパクトされるまで、以降のリクエストはすべて、--resume や --continue の後も含めて、その記録済みプロンプトを使います。
  • そのため、--append-system-prompt のテキストを編集して claude --continue を再実行しても、何も変わりません。フラグが壊れているのではなく、会話がまだ記録を使っているのです。
  • 新しいテキストは、会話がコンパクトされたとき、または新しい会話で有効になります。
  • --continue の実行をまたいで文言を試行錯誤するには、--system-prompt-snapshot off を渡すと、リクエストごとにプロンプトが再構築されます。v2.1.257 以降が必要です。

安定した指示と実行ごとのコンテキストが混在する置換プロンプトでは、もう一つ知っておくと役立つ工夫があります。両者の間に __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__ だけを含む行を置いてください。Claude Code は最初のそのような行で分割してその行を取り除くため、上側の部分はキャッシュされたままとなり、下側の部分だけが変わります。v2.1.275 以降が必要です。これが請求額にどう効くかは、プロンプトキャッシュで扱っています。

さらに、複数ユーザーでスクリプト化されたワークロードでは、--exclude-dynamic-system-prompt-sections が、自動メモリの場所のようなユーザーごとのコンテキストをシステムプロンプトから最初のユーザーメッセージへ移します。これにより、異なるマシン上の同じタスクが 1 つのキャッシュ済みプレフィックスを共有できます。デフォルトのプロンプトにのみ適用され、--system-prompt や --system-prompt-file を指定した場合は無視されます。

何かをオフにする 3 つのフラグ、そしてそれらは同じではない​

これらは同じ意味で使われがちで、その後、症状が改善しないことに首をかしげることになります。3 つはそれぞれ異なる問題を解決します。

--bare--safe-mode--restricted
解決する問題スクリプトからの呼び出しには起動が遅すぎる設定が壊れているが、どの部分か分からない評価用ハーネスが、この共有マシンに触れてはならない
CLAUDE.md、スキル、コマンド、サブエージェント、プラグイン、MCP、自動メモリ検出されない読み込まれないマネージド設定と --settings のみ読み込まれる
組み込みツールBash、ファイル読み取り、ファイル編集通常どおり動作コマンド/コードを実行するツールと WebFetch は、--tools で個別に指定しない限り削除される
ファイルアクセス通常どおり通常どおり作業ディレクトリ内に限定
bypassPermissions許可許可拒否
マネージドポリシー適用される引き続き適用(ポリシーフックとステータスラインを含む)適用される
副作用CLAUDE_CODE_SIMPLE を設定CLAUDE_CODE_SAFE_MODE を設定クラウドセッションの作成を拒否

この表は意図の段階的な違いとして読んでください。--bare は速度、--safe-mode は診断、--restricted は封じ込めのためのものです。一つ役立つ細かい点として、--add-dir で渡したディレクトリ内のスキルは --bare でも読み込まれます。これを使えば、ほかをすべて削ぎ落とした実行に、ちょうど一つの機能だけを残せます。

何かがおかしな挙動をしていて、Claude Code のせいか自分の設定のせいか分からないとき、最初に試すべきは --safe-mode です。これは、あるカスタマイズが自動モデルフォールバックを引き起こしているかどうかを切り分けたい場合にも当てはまります。claude doctor と組み合わせてください。これはセッションを開始せずに、読み取り専用のインストールおよび設定の診断を出力します。(セッション内の /doctor コマンドは別物で、修正を適用することもできます。)症状から入るデバッグの詳細は、Claude Code のトラブルシューティングにあります。--restricted には v2.1.248 以降が必要です。

シェルからバックグラウンドセッションを操作する​

--bg でセッションを開始すると、ターミナルはコントロールプレーンになります。ライフサイクル全体にコマンドがあり、そのどれもインタラクティブ UI を開く必要がありません。

Guided walkthrough1 of 6
  1. 並列のバックグラウンドセッションを監視・ディスパッチするエージェントビューを開きます。スクリプト用には、`--json` でアクティブなセッションを JSON 配列として出力し、`--json --all` では完了したものも含めます。`--cwd <path>` で、そのディレクトリ配下で開始されたセッションに絞り込めます。ビュー自体を開くにはインタラクティブなターミナルが必要ですが、JSON 形式は不要です。

これに対応するセッション内からの操作、つまり作業がどのようにバックグラウンド化され、そのとき何が引き継がれるかについては、バックグラウンドタスク、/loop、スケジューリングを参照してください。

間違えやすいフラグの組​

先回りして押さえておきたい 6 つの混同
  • --tools は、どの組み込みツールが存在するかを制限します。--allowedTools は、どの呼び出しが権限プロンプトを省略するかを指定します。--disallowedTools は、呼び出しを拒否します。この 3 つは別々の役割であり、間違ったものを渡すことが「なぜまだ確認してくるのか」の最も多い原因です。
  • --tools は MCP ツールにはまったく影響しません。それらも取り除くには、--disallowedTools "mcp__*" を追加します。
  • --disallowedTools に素の名前を指定すると、そのツールは Claude のコンテキストから取り除かれます。Bash(rm *) のようにスコープを付けたルールでは、ツールは利用可能なまま、一致する呼び出しだけが拒否されます。
  • --dangerously-skip-permissions は bypassPermissions で起動します。--allow-dangerously-skip-permissions は、そのモードを Shift+Tab のサイクルに加えるだけなので、plan モードで開始して後から切り替えられます。実際に欲しかったのは、ほぼ間違いなく後者です。
  • --add-dir はファイルアクセスを与えますが、Claude Code はそれらのディレクトリからほとんどの .claude/ 設定を検出しません。ディレクトリを追加することは、その設定を採用することと同じではありません。
  • --desktop はプロンプトも、--verbose と --debug 系フラグ以外のフラグも受け付けません。セッションは Desktop アプリ自身が開始するためです。v2.1.285 以降が必要です。

ちょっとした使い勝手の工夫として、サブコマンドを打ち間違えると、Claude Code は最も近い候補を提案し、セッションを開始せずに終了します。claude udpate は、意図しない会話を開くのではなく Did you mean claude update? と表示します。

理解度チェック​

Check yourself

0/3
  1. 夜間ジョブが、`canUseTool` コールバックが人に確認を求める Agent SDK アプリの中で `claude -p` を実行しており、夜間はタイムアウトまでハングします。最も欠けている可能性が高いフラグはどれですか?
  2. --append-system-prompt のテキストを調整して `claude --continue` を再実行しましたが、挙動が変わりません。なぜですか?
  3. あるカスタマイズがセッションを壊していますが、どれか分かりません。ツールと権限を通常どおり動作させたまま、原因を切り分けられるフラグはどれですか?
Enter キーまたはスペースキーでカードを裏返します。左右の矢印キーでカードを移動できます。用語を表示しました。
1 / 8
Key takeaways
  • 最初にセッションの種類を選ぶ。それを選ぶフラグが、渡せるほかのすべてのフラグを制約します。
  • 無人実行に必要なのは 1 つではなく 5 つのフラグ:-p、--permission-prompts none、--max-turns、--max-budget-usd、そして構造化された出力形式。
  • --max-budget-usd は請求額の上限ではなく、1 回の実行に対する遮断器として扱う。クライアント側の見積もりであり、再開された合計はその網をすり抜けます。
  • 会話は最初のリクエストでシステムプロンプトを記録します。プロンプトの編集が無視されているように見えるなら、それが理由です。試行錯誤の間は --system-prompt-snapshot off を使いましょう。
  • --bare は速度、--safe-mode は診断、--restricted は封じ込め。間違ったものを選ぶと、午後が丸ごと無駄になります。
  • --help は設計上、不完全です。CLI リファレンスが情報源であり、バージョンの下限が重要です。フラグを疑う前に claude -v を確認しましょう。

次に読む​