AskUserQuestion（アスクユーザークエスチョン）とは、Claude Codeに組み込まれたツールで、Claudeが作業中に自分では決められない分岐に突き当たったとき、選択肢形式の質問をユーザーに提示して判断を仰ぐ仕組みです。 曖昧な指示のまま推測で突き進んで手戻りを生むのではなく、要件が固まっていない箇所を「聞く」ことで、意図とズレたまま実装が進むのを防ぎます。
このページでは、公式仕様（Claude Code / Agent SDK）で確認できる範囲に絞って、AskUserQuestionの役割・発動条件・表示のしくみ・実務での使いどころをまとめます。
AskUserQuestionが解決する問題
AIコーディングで最も無駄が生まれるのは、曖昧な指示をAIが勝手に解釈して、間違った方向に走り切ってしまうパターンです。「認証を追加して」と頼んだら、想定と違うライブラリで実装が完了していた、というような手戻りです。
AskUserQuestionは、この「暴走」を止めるための仕組みです。Claudeは判断に迷ったとき、黙って仮定を置くのではなく、選択肢を提示してユーザーに決定権を返します。
いつ発動するのか（発動条件）
AskUserQuestionは、いつでも質問するわけではありません。 公式の指針では、次の条件をすべて満たすときにのみ使うことになっています。
- 依頼内容から答えが読み取れない
- コードを見ても決められない
- 妥当なデフォルト（慣例的な選び方）が存在しない
- かつ、それがユーザーが決めるべき判断である
逆に、次のような場面では使いません。
| 使わない場面 | 理由 |
|---|---|
| 慣例的なデフォルトがある選択 | Claudeが妥当な既定を選んで進める |
| コードを読めば分かる事実の確認 | 自分で調べれば済む |
| 「この方針で進めていい？」の確認 | 判断が本当にユーザー依存のときだけ聞く |
つまり、確認の乱発でユーザーの手を止めないよう、本当にユーザーにしか決められないことだけを聞くように設計されています。
表示のしくみ
AskUserQuestionは、単なる自由記述の問いかけではなく、構造化された選択式UIとして表示されます。仕様上のポイントは次のとおりです。
- 1回で1〜4問まとめて質問できる
- 各質問は2〜4個の選択肢を持つ
- 各選択肢には「ラベル（短い見出し）」と「説明（選ぶと何が起きるか）」が付く
- 質問には短いヘッダー（チップ表示、最大12文字程度）が付く
「その他」で自由入力できる
すべての質問には、自動で 「その他（Other）」 が用意されます。提示された選択肢がどれもしっくりこない場合、ユーザーは自由入力で独自の回答を返せます。選択肢に縛られない設計です。
複数選択とおすすめ表示
- 複数選択（multiSelect）：排他でない選択肢（有効化したい機能を複数選ぶ等）では、複数回答を許可できる
- 推奨オプション：Claudeが特定の選択肢を勧めたいときは、それを先頭に置き、ラベルに「（推奨）」を付けて提示する
プランモードとの相性が良い
AskUserQuestionが特に活きるのがプランモードです。プランモードでは、Claudeが実装に入る前にコードベースを調べ、計画を提案します。この「実装前」の段階で要件のヒアリングを行うことで、方針が固まってから手を動かせます。
- 探索 → 不明点をAskUserQuestionで確認 → 計画を提示 → 承認 → 実装
要件を固めてから作業に入りたいインタラクティブな進め方に、プランモードとAskUserQuestionの組み合わせは向いています。
Agent SDKでの扱い
自分でエージェントを組む場合、AskUserQuestionは Agent SDK から扱えます。要点は次のとおりです。
- AskUserQuestionは既定で利用可能
- SDK側では
canUseToolコールバックにAskUserQuestionとして通知が届き、選択肢をユーザーに表示して選択結果を返す tools配列でツールを制限する場合（例：Read / Glob / Grep だけの読み取り専用エージェント）は、AskUserQuestionを配列に明示的に含めないと使えなくなる点に注意
読み取り専用エージェントでも「ユーザーに聞く」機能を残したいなら、ツール制限リストにAskUserQuestionを入れ忘れないようにします。
実務での使いどころ
このサイトを運用しているようなローカルCMS環境でも、AskUserQuestionは効きます。たとえば「SEO記事を書いて」のような依頼では、対象キーワード・想定読者・トーンなど、決めないと書き出せない要素があります。こうした要素を推測で埋めずに選択肢で確認すれば、書き直しの往復を減らせます。
要は、指示が曖昧なほど価値が出るツールです。プロンプトを完璧に書ききれないときの安全弁として機能します。
Google検索・AI検索の両方を意識するなら
AskUserQuestionは執筆フローそのものにも関わります。記事制作でこのツールに要件（キーワード・対象エンジン）を答えておくと、Google検索向けの構造化（見出し・FAQ）と、ChatGPTやPerplexityなどAI検索（GEO）向けの「引用されやすい一文」の両立を、方針のブレなく進めやすくなります。曖昧なまま書き始めて後から直すより、最初に分岐を潰しておくほうが速いという考え方です。
まとめ
- AskUserQuestionは、Claudeが自分では決められないユーザー判断を選択式で聞くツール
- 発動は本当に必要なときだけ。デフォルトで済む選択やコードで分かる確認には使わない
- 1〜4問／各2〜4択、「その他」で自由入力、複数選択・推奨表示に対応
- プランモードで要件ヒアリングに活躍
- Agent SDKでは既定で有効。ツール制限時は明示的に含める必要がある
曖昧な指示による手戻りを減らす仕組みとして、AIに「聞かせる」ことを前提にした使い方を覚えておくと運用が安定します。