非対話モードとは?Claude Codeを1回きりで動かす

「会話しないClaude Code」があるって知ってますか

Claude Codeというと、ターミナルで claude と打って、Claudeとチャットしながらコードを書いてもらう——そんなイメージが強いと思います。実際その使い方が基本です。

でも、それとは別に「一言だけ投げて、答えが返ってきたら終わり」という使い方が用意されています。これが非対話モード(Non-interactive mode)です。以前は「ヘッドレスモード(headless mode)」と呼ばれていた機能で、今でもその呼び名を見かけますが、現在の正式名称は非対話モードです。

自動販売機みたいなもの

対話モードのClaude Codeは、カウンター越しに注文するカフェの店員さんに近い存在です。「コーヒーで」「あ、やっぱりラテに変えて」「ミルク多めで」と、やり取りを重ねながら注文を詰めていける。相手はさっきの会話を覚えているので、話が積み上がります。

一方の非対話モードは自動販売機です。ボタンを1回押す。缶が出てくる。終わり。相談はできないし、続きの注文もできません。その代わり、押せば必ず同じ手順で動くし、人がそばにいなくても機械的に処理できます。

この「人がそばにいなくても動く」という点が、非対話モードの最大の価値です。

どうやって使うのか

コマンドを実行するときに -p(または --print)というオプションを付けます。

claude -p "このプロジェクトの構成を3行で説明して"

これを実行すると、チャット画面が立ち上がることはありません。プロンプトが処理され、結果がそのまま出力されて、コマンドが終了します。普段ターミナルで使う ls や grep のような、ごく普通のコマンドと同じ感覚です。

何が嬉しいのか

普通のコマンドと同じように振る舞う、というのは意外と大きな意味を持ちます。

スクリプトに組み込める。 シェルスクリプトの一行として書けるので、他の処理と混ぜて自動化の一部にできます。人が画面を見て返事をする必要がないからです。

CI(自動テストなどの仕組み)から呼べる。 コードをリポジトリに送ったタイミングで自動的にClaudeにチェックさせる、といった使い方ができます。CIの中では誰もキーボードを触っていないので、対話が必要なコマンドはそもそも動きません。

パイプでつなげる。 ターミナルには、あるコマンドの出力を次のコマンドの入力に渡す「パイプ」という仕組み(| の記号)があります。非対話モードはこれに乗せられるので、他のツールと組み合わせた処理の一部として使えます。

使い分けの感覚

最初のうちは「じゃあ全部非対話モードでいいのでは」と思うかもしれませんが、実際に触ると向き不向きははっきりしています。

	対話モード	非対話モード
起動	claude	claude -p "..."
やり取り	何度でも続けられる	1回で終わり
人の同席	必要	不要
向いている場面	試行錯誤しながらの開発	自動化・定型処理

まだ何をどう直すか固まっていない、探りながら進めたい——そういう作業は対話モードのほうが圧倒的に楽です。逆に、やることが毎回決まっていて、それを繰り返し自動で回したいなら非対話モードの出番になります。

プログラムから使いたい場合

シェルコマンドではなく、PythonやTypeScriptのコードの中からClaude Codeの機能を呼びたい、というケースもあります。その場合は同等の機能として Agent SDK が用意されています。アプリケーションに組み込むならこちらを検討することになります。

最初につまずきやすいところ

非対話モードで一番戸惑うのは、やはり「続きが話せない」ことだと思います。対話モードの癖で、返ってきた答えに対して追加で質問しようとしてしまうんですが、そこにはもうセッションがありません。聞きたいことがあれば、最初のプロンプトに全部盛り込んでおく必要があります。

裏を返せば、非対話モードで良い結果を出すコツは「プロンプトを1回で完結させる書き方に慣れること」です。何を見てほしいのか、どういう形式で答えてほしいのか、あいまいさを残さず書く。この感覚は対話モードでも役に立つので、練習と思って触ってみるといいと思います。

より詳しい仕様は公式ドキュメントにまとまっています。