--verbose（ヴァーボース）

Claude Codeを自動化スクリプトやCIから叩いていて、裏で何が起きているか見えにくいと感じている人向け

--verbose は、Claude Code を呼び出すときにくっつけるオン・オフ指定の1つ。つけて起動すると「Claude がどのファイルを読んだか、どう判断したか、どんな手順で動いたか」を1ターンごとに全部画面へ出す表示モードに切り替わる。公式の説明はそのまま「Enable verbose logging, shows full turn-by-turn output」。日本語にすると、詳細ログを有効にしてターンごとの全出力を見せる、という意味。

裏方の動きが見えるようになる、それだけ。

print mode と対話モードのどちらでも有効。print mode は claude -p "○○して" の形でコマンドの後ろに指示を書いて結果だけ返してもらう非対話の使い方、対話モードは claude だけ叩いて画面が立ち上がる普通の使い方を指す。CI や自動レビュー用のスクリプトに組み込んだとき「動いてるはずなのに途中経過が見えなくて怖い」という詰まりを解消するために生まれた指定だと思っていい。

噛み砕くと

料理屋のキッチンを思い浮かべると分かりやすい。普段は壁で仕切られていて、客席からは料理ができて出てくるところしか見えない。--verbose をつけるのは、その壁を取っ払って厨房の中を全部見せるオープンキッチンに切り替える操作に近い。

素材をどこから取り出したか、火加減をどう変えたか、味見で何回直したか、全部見える。料理の味自体は変わらないけど、出来上がりまでの判断が追える。

裏で何やってるか怖い、を解消する道具。

そもそも「ターンごとの出力」って何のこと？

Claude Code は1回の指示に対して、内部で何往復もやり取りしている。たとえば「このファイルを直して」とお願いすると、内部では「ファイルを Read で読む → 中身を確認する → 直す箇所を判断する → Edit で書き換える → 結果を報告する」という流れで動く。この1往復を「1ターン」と呼ぶ。

普段の表示はこの中で「最終的にユーザーに見せたい結果」だけを抜き出して出している。--verbose をつけると、その途中の Read 内容・判断・Edit 内容を、1ターンごとに区切って全部画面に流す。

「料理ブログのレシピを Claude にレビューさせる」を例に、実際の手順を見る

世界の魚を紹介する料理ブログで、新しいレシピ原稿を投稿前に Claude Code に校正させたい、というケースで動かしてみる。原稿ファイルは recipe-draft.md としておく。

ステップ1: まず --verbose なしで叩く

print mode で、原稿を流し込みながらレビューを頼む。これが普段の使い方。

$ cat recipe-draft.md | claude -p "誤字脱字と分量の表記ゆれをチェックして"

返ってくるのは「誤字○件、分量の単位が大さじ/Tbsp混在しています」みたいな結果テキストだけ。途中で Claude が原稿のどこを何回読み直したかは見えない。CI のログ画面で見ると「呼び出した・結果出た」しか分からないので、不安だけが残る。

ステップ2: --verbose をつけて同じ指示を叩く

$ cat recipe-draft.md | claude -p --verbose "誤字脱字と分量の表記ゆれをチェックして"

画面の流れがガラッと変わる。Claude が「Read で原稿全文を読み込んだ」「冒頭の材料セクションを精査している」「中盤の手順で『大さじ』と『Tbsp』が混在しているのを発見」と、判断の足取りを順番に出してくる。最後にいつものレビュー結果が来る。結果自体は同じだけど、どこを見てそう判断したかが追える。

ステップ3: 対話モードでも有効なことを確認する

--verbose は print mode 専用じゃない。普通に画面を立ち上げる使い方でも効く。

$ claude --verbose

これで対話画面に入ると、以後の1ターンごとに詳細表示モードで動く。「会話の途中で Claude が裏で何のツールを呼んだか見たい」ときはこれ。

ステップ4: ここで初心者がやりがちな勘違い

「verbose をつければトークンの使用量や料金が見える」と思って --verbose を叩く人がいる。これは違う。コストや消費量を見たいなら、対話モード中の /usage や /cost 系の方を使う。--verbose はあくまで「Claude のターンごとの判断を見せる」表示モード指定で、お金の話とは別系統。

ステップ5: --debug とも別物

似た名前で --debug という指定もある。これは API 通信・hooks・MCP の内部ログを開発者向けに吐き出させる方で、目的が違う。--verbose は「読者・人間が Claude の判断を追える表示モード」、--debug は「開発者が API のやり取りを追えるログ出力」。間違えると欲しい情報が出てこない。

ステップ6: 永続化したいなら settings.json の方を触る

--verbose はその場限り。コマンド起動のたびにつけ直す必要がある。常に詳細表示で動かしたいなら、設定ファイル settings.json の viewMode を書き換える方を選ぶ。--verbose はこの設定値を「このセッションだけ上書きする」動きをする。

つまり --verbose は何をしてくれるのか

• やってくれる: 1ターンごとに Claude が何を読み、何を判断し、どの道具を呼んだかを画面に流す。print mode でも対話モードでも有効。viewMode 設定をその場限りで上書きする
• やってくれない: トークン使用量や料金の表示、API 通信ログの吐き出し、MCP/hooks 系の内部ログ。これらは別の指定が担当する
• 意味が薄い場面: 1ターンで終わる単純な質問。たとえば「いまの時刻を教えて」みたいな雑談系。途中経過がそもそも無いので、見ても得るものが少ない

使いどころ3シナリオ（具体題材で再現）

シナリオ1: 料理ブログの新着レシピを CI で自動レビューさせるとき

GitHub Actions で「新しい recipe-*.md が追加されたら Claude に誤字と分量チェックを走らせる」仕組みを組んでいるとする。--verbose なしだと、CI 画面のログには「Claude が呼ばれた」「結果が返ってきた」しか残らない。途中でタイムアウトした時に何が原因か追えない。--verbose をつけておけば、ログに「Read で原稿を読んだ」「途中で材料セクションが想定より長いと判断した」みたいな足取りが残るので、後追いで原因を特定できる。

シナリオ2: 印刷会社に渡す前の最終チェックをスクリプトに任せたいとき

毎週の新着レシピを月1冊にまとめてZINE（小冊子）にしている個人ブログで、入稿前に「全レシピを一気に Claude に読ませて、矛盾や表記ゆれを洗い出す」自動スクリプトを動かす。本番のチェックは --verbose なしで結果だけ受け取り、もし「指摘が0件で返ってきた」とか「妙に短い結果が返ってきた」とき、もう一度 --verbose 付きで走らせて「ちゃんと全レシピを Read したか」を確認する。失敗時の検算用に使う。

シナリオ3: 対話モードで「いま Claude が何を考えてるか」を見ながら作業したいとき

家計簿アプリの実装中に、Claude に「先月の支出データを読んで、外食費が増えてる原因を分析して」と頼む。普段の表示だと結論しか出ないが、claude --verbose で起動しておくと、CSV のどの列をどう集計したか、どの月とどの月を比較したかが順に見える。分析結果に納得いかなかったとき「ああ、3月のデータを除外して比較してたのか」みたいな判断の癖が見えるので、追加の指示を出しやすくなる。

初心者が踏みやすい落とし穴

• 料金やトークン消費量を見るための指定だと勘違いする。--verbose はあくまで「Claude のターンごとの判断を見せる」表示モード。コストを見たいなら /usage や /cost 側を使う
• --debug と混同する。--debug は API/hooks/MCP の開発者向けログを吐き出させる別物。読者向けの詳細表示が欲しいなら --verbose、開発デバッグなら --debug、と用途で使い分ける
• print mode 専用と思い込む。公式の Example は claude --verbose で -p はついていない。対話モードでも有効で、起動時のオン・オフ指定としてくっつければ以後のターンが全部詳細表示になる
• その場限りなのを忘れて毎回つけ忘れる。--verbose はそのセッション限定の上書き。常に詳細表示で動かしたいなら settings.json の viewMode を永続化する方を選ぶ
• トークンストリーミングしたいときに単独で叩く。生成中の文字をリアルタイムに受け取りたい場合、公式の推奨は --output-format stream-json --verbose --include-partial-messages の3点セット。--verbose だけだと、生成完了後にターンごとの記録が出る動きで、リアルタイム性は出ない
• CI のログが膨らんで読みづらくなる。--verbose をつけると出力量が増える。常に付けっぱなしにすると CI 画面のスクロールが地獄になる。失敗時の検算用に分けて使うのが楽
• 1ターンで終わる単純な問いに付けても意味が薄い。雑談系の短い質問だと中間ターンがほぼ無いので、わざわざ --verbose にする旨味が出ない

書き方

claude --verbose
# print mode と組み合わせる場合
cat input.txt | claude -p --verbose "レビューして"
# トークンを生成と同時に流したい場合（公式推奨の3点セット）
claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages

やってみるとこうなる

入力

cat recipe-draft.md | claude -p --verbose "誤字脱字と分量の表記ゆれをチェックして"

出力例

Reading recipe-draft.md ...
(turn 1) 原稿全文を読み込みました
(turn 2) 材料セクションを精査中: 大さじ/Tbsp の混在を1件検出
(turn 3) 手順セクションを精査中: 誤字「煮立っ」→「煮立ち」を1件検出
結果:
- 誤字 1件: 「煮立っ」→「煮立ち」
- 分量の表記ゆれ 1件: 大さじ/Tbsp

関連項目

• --output-format（アウトプットフォーマット）
• --input-format（インプットフォーマット）
• claude -p（クロード・ピー）
• /debug-flag（準備中）
• --bare（ベア）
• --prompt-suggestions（プロンプトサジェスチョンズ）

公式ドキュメント

https://code.claude.com/docs/en/cli-reference