AskUserQuestion（アスクユーザークエスチョン）

Claude Codeでサブエージェントやスキルを設計し始めた人向け

Claude Code が会話の途中で「これ、どっちにします？」とこちら（ユーザー）に選択肢を投げてくるためのツールです。自由入力のフォームではなく、Claude 側があらかじめ用意した2〜4個の選択肢の中から、ボタンを押す感覚で選ばせる仕組みになっています。

名前だけ読むと「ユーザーが Claude に質問するツール」と勘違いしやすいですが、向きは逆。Claude → ユーザー の方向に選択肢が飛んできます。

噛み砕くと

居酒屋の店員さんがオーダーを取る時に「飲み物、生ビールにします？それともハイボール？」と二択で聞いてくれる、あの動きに近いです。「お好きなものをどうぞ」と丸投げされるより、選択肢を絞って聞かれた方が早いし、誤解も少ない。

AskUserQuestion は、Claude が判断に迷った時に「丸投げ自由記述」ではなく「選択肢付きの確認」を投げてくる役割を担っています。

大事な前提：これは Claude 側がこちらに聞くツール

名前の語感に引きずられて「私が Claude に質問する時に使うやつ？」と読みがちですが、違います。Claude Code が自分の判断で「人間に確認を取りたい」と思った時にだけ発火する仕組みです。私たちが直接このツール名を打ち込んで呼び出すことはありません。

スキルや通常会話の中から Claude の判断で呼び出されます。なお、現時点ではサブエージェントの内側からは呼び出せない制限が公式に明記されています。許可ダイアログは出ません。

「料理ブログを始めたい人にCMSを選ばせる」を例に、実際の動きを見る

料理写真を毎日撮りためている人が、Claude Code に「料理ブログを始めたい。サイトの土台どれにしよう」と相談したとします。普通の AI なら「WordPress がおすすめです」と1つに決めうちしてしまいがちですが、AskUserQuestion を備えた Claude は、迷いポイントを見つけた瞬間にこちらへ選択肢を投げてきます。

ステップ1: 雑談から要望を引き出す

最初の数往復は普通の会話。「写真メインで月10記事くらい」「スマホで隙間時間に更新したい」「将来的にアフィリエイトもやりたい」あたりを Claude が拾います。

あなた: 料理ブログ始めたくて。週末に作り置き写真撮ってるから、それを並べたい
あなた: スマホ更新できて、できれば無料がいい
あなた: 1年後くらいにはアフィリエイトも貼れるとうれしい

ステップ2: Claude が「ここは選ばせるべき」と判断する

3つの候補が頭に浮かんだ Claude は、ここでこちら任せにせず AskUserQuestion を発火させます。Claude Code のターミナル画面ではこんな質問パネルが現れます。

┌──────────────────────────────────────────────┐
│ ブログ基盤、どれで進めましょうか？           │
├──────────────────────────────────────────────┤
│ ○ WordPress                                  │
│   無料・スマホアプリあり・SEOプラグイン豊富  │
│ ○ Ghost                                      │
│   月$9〜・デザイン綺麗・課金会員機能あり     │
│ ○ Notion                                     │
│   無料・スマホ更新最強・SEOは弱め            │
│ ○ Other（自分で書く）                        │
└──────────────────────────────────────────────┘

Claude Code のターミナル画面では「Other」が末尾に表示されます。ただし Agent SDK でアプリを作る場合は、アプリ側でこの選択肢をUIに追加し、自由記述の回答をそのまま Claude に返す実装が必要です。仕組み側で必ず自動表示されるのは Claude Code のインタラクティブモード限定、と覚えておくのが安全です。

ステップ3: ボタンを1つ押す

「WordPress」を選んで送信。Claude は次のステップに進みます。テーマ選び、初期プラグイン設計、最初の記事構成、といった順番で作業が走り出します。

ここで重要なのは、Claude が一方的に「WordPress で進めますね」と決めうちせず、こちらに最終判断を握らせた点です。

ステップ4: 1つのパネルで複数質問を並べることもある

AskUserQuestion は1回の呼び出しで最大4問まで並べられます。料理ブログの例だと、CMS選びと一緒に「ドメインどうする？」「アフィリ参加の優先度は？」もまとめて聞いてくることがあります。

Q1: ブログ基盤 → WordPress / Ghost / Notion / Other
Q2: ドメイン   → 独自ドメイン買う / サブドメインで様子見 / Other
Q3: アフィリ   → 最初から導入 / 半年後検討 / 当面なし / Other

ここで初心者がやりがちな勘違いがあります。「全部質問されるって、つまり Claude が考えてないってこと？」と感じる人がいるんですが、逆。取り違えると後でやり直しになる判断ポイントを Claude が見抜いて、先に聞いてくれているわけです。

ステップ5: 「複数選択していい」モードもある

「Q3 アフィリの提携先を選んでください」のような、複数選んでよい質問はチェックボックス式になります。これが multiSelect モード。料理ブログなら「楽天・Amazon・もしも、どれと提携する？」を1問で複数選ばせる、といった使い方です。

ステップ6: 質問の横にちょっとした下書きが出る場合も

単一選択の質問では、各選択肢の下に「これを選んだらどんな画面になるか」のちょっとした下書きや差分プレビューが添えられることがあります。Ghost を選んだら月課金が発生する、Notion を選んだら検索流入が弱まる、といった注意点を、選ぶ前に視覚的に確認できる仕組みです。これが公式仕様の preview フィールド。ただし複数選択モードでは使えません。

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

• やってくれる: Claude が判断に詰まった時、ボタン式の選択肢でこちらに最終判断を握らせる。1パネルで最大4問・各2〜4択。複数選択にも対応
• やってくれる: Claude Code のターミナル画面では「Other」がパネル末尾に表示される。Agent SDK で自前アプリを作る場合は、この選択肢をUI側で自前実装する必要がある
• やってくれない: こちらから Claude に質問を送る用途。向きが逆なので、これは普通にチャット欄に打ち込むだけ
• やってくれない: Yes/No の単純承認。プランを承認するか/しないかの判断は ExitPlanMode という別ツールがあるので、AskUserQuestion を流用すべきではない
• やってくれない: サブエージェントの内側から呼び出すこと。公式に「現時点では利用不可」と明記されている
• 意味が薄い場面: claude -p のように人間が画面の前にいない無人実行モード。質問パネルを出しても答える人がいないので、無人で回す前提のスクリプトでは呼ばないように指示する

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

シナリオ1: 料理ブログのCMS選定（実演で扱った例）

趣味で料理写真を貯めている人が「ブログ始めたい」と相談した時、Claude が WordPress / Ghost / Notion の3択をパネルで投げてくる場面。料金・スマホ更新のしやすさ・検索流入の強さといった判断材料が下書きとして横に並ぶので、開設前に「Notion は無料だけど検索流入は弱い」が分かったうえで選べます。3ヶ月後に「やっぱり別の方が良かった」と作り直す手戻りを潰せる場面です。

シナリオ2: 家計簿アプリを Claude Code に作らせる初日

家計簿アプリを自作したい時、Claude が「データ保存先、ローカルファイル / SQLite / クラウド同期 のどれにします？」と聞いてくる場面。最初に決めないと後でデータ移行が面倒になる選択を、最初の30分のうちに済ませられます。私自身も似た場面で「とりあえず進めて」と Claude に任せて、後で SQLite から PostgreSQL に作り直す羽目になったことがあるので、ここで聞いてくれるのは正直ありがたい。

シナリオ3: OSSの clone 直後、開発スタイルを決める

GitHub から取ってきた既存プロジェクトを Claude に読ませた直後、「テスト駆動で進める / 最小実装で動かしてから整える / 既存の書き方に揃える、どれにします？」と聞かれる場面。プロジェクトに正解は1つではなく、こちらの好みや時間配分で決まるので、Claude が勝手に1つに寄せると2時間後に書き直しになります。ここで選択肢として並べてくれるのは、3択それぞれの落とし穴が事前に見えるという意味でも便利です。

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

• 名前の向きを取り違える。AskUserQuestion は「ユーザーが Claude に聞く」のではなく「Claude がユーザーに聞いてくる」ツール。ターミナルでこちらが直接 AskUserQuestion と打って呼び出すものではない
• Yes/No の承認に流用してしまう。プランの承認は ExitPlanMode という別ツールが用意されている。AskUserQuestion を「進めていいですか？はい/いいえ」みたいな承認ボタン代わりにしない
• サブエージェントから呼び出そうとする。公式ドキュメントは「AskUserQuestion は Agent ツール経由で起動したサブエージェントの中では現時点で使えない」と明記している。サブエージェントの作業手順書（説明書 Markdown）に「ここで AskUserQuestion を呼ぶ」と書いても発火しないので、判断分岐はメイン側の Claude に戻す設計にする
• 無人実行モードでも呼ばれる設計にしてしまう。答える人間がいない夜間バッチや CI/CD の中で AskUserQuestion が発火すると、そこで止まったまま延々と待つ。スキルやサブエージェントの説明書に「claude -p では呼ばないこと」を明記しておく
• 選択肢を5個以上並べたくなる。仕様上、1問あたり最大4択まで。それ以上は読者が選びきれずに「Other」に逃げる。設計時点で3〜4択に絞る
• 1回の発火で5問以上聞こうとする。1呼び出しで最大4問まで。それを超えるなら2回に分けるか、本当に聞く必要があるかを設計し直す
• 複数選択モードで preview を期待する。下書きプレビューは単一選択モード専用。チェックボックス式の質問では使えないので、複数選んでよい質問の選択肢には「短い説明文」を1行で添えるしかない
• Agent SDK 製アプリで「Other」が自動で出てくると思い込む。Claude Code のターミナル画面では末尾に自動表示されますが、Agent SDK で自前アプリを組む場合は、アプリのUI側で「Other」選択肢と自由記述入力欄を実装し、ユーザーが書いた文字列を Claude に戻す配線が必要です
• 毎ターンこのツールを呼びたがる Claude を放置する。判断ポイントごとに毎回確認されると読者が疲れる。スキルやサブエージェントの説明書で「本当に分岐が分かれる時だけ呼ぶ」と縛っておく

書き方

（ユーザーが直接打つコマンドではない。Claude Code がスキルや通常会話の流れの中で、判断を分岐させたい場面で自動で呼び出す内蔵ツール）

設計者が記述する場合は、スキルやサブエージェントの説明書（Markdown）に「分岐ポイントでは AskUserQuestion を使って2〜4択でユーザーに選ばせる」と日本語で書く。

仕様の上限:
- 1呼び出しで最大4問まで並列可能
- 1問あたりの選択肢は2〜4個
- multiSelect: true で複数選択モード
- 単一選択モードのみ preview（下書きプレビュー）を添えられる
- 「Other（自分で書く）」は Claude Code のターミナル画面では末尾に自動表示される。Agent SDK で自前アプリを組む場合は、アプリのUI側で自由記述の選択肢と入力欄を自前実装し、ユーザーが書いた文字列を Claude に戻す配線が必要
- サブエージェント（Agent ツール経由で起動した分身 Claude）の内側からは現時点で呼び出せない
- 許可ダイアログは出ない（permission required: No）

やってみるとこうなる

入力

あなた: 料理ブログ始めたくて。週末に作り置き写真撮ってるから、それを並べたい
あなた: スマホ更新できて、できれば無料がいい
あなた: 1年後くらいにはアフィリエイトも貼れるとうれしい

出力例

（Claude Code 側が AskUserQuestion を発火させると、ターミナル画面にこんなパネルが現れる）

┌──────────────────────────────────────────────┐
│ ブログ基盤、どれで進めましょうか？           │
├──────────────────────────────────────────────┤
│ ○ WordPress                                  │
│   無料・スマホアプリあり・SEOプラグイン豊富  │
│ ○ Ghost                                      │
│   月$9〜・デザイン綺麗・課金会員機能あり     │
│ ○ Notion                                     │
│   無料・スマホ更新最強・SEOは弱め            │
│ ○ Other（自分で書く）                        │
└──────────────────────────────────────────────┘

ボタンを1つ押すと Claude が次の手順に進む。「Other」を選ぶと自由記述で答えられる（Claude Code のターミナルでは自動表示、Agent SDK でアプリを作る場合は自前実装）。

関連項目

• /agents（エージェンツ）
• Skills（スキルズ）
• /exitplanmode（準備中）
• CLAUDE.md
• /subagents（準備中）

公式ドキュメント

https://code.claude.com/docs/en/agent-sdk/user-input