コンテンツにスキップ

Claude Code 完全ガイド

Claude Code AskUserQuestionツール完全解説：曖昧な指示のやり直しを劇的に減らす

この記事の対象者

  • Claude Codeで曖昧な指示によるやり直しを減らしたい中級開発者

この記事のポイント

  1. AskUserQuestionツールの仕組みと利点を理解できる
  2. やり直しループを50〜80%削減する活用パターンを習得できる
  3. Plan Modeとの組み合わせで生産性を最大化できる

問題の核心：なぜAIコーディングは「やり直し地獄」に陥るのか

従来のAIコーディングアシスタントの最大の弱点は「曖昧なプロンプトに対する勝手な仮定」です。「この機能を追加して」と指示すると、AIは自分で仮定してコードを書き、意図とズレる → 修正指示 → またズレる…という無限ループが発生します。

AskUserQuestionツールは、この問題を根本から解決します。

AskUserQuestionとは

Claude Code v2.0.21以降で追加されたAskUserQuestionツールは、Claudeがタスク実行中に不明点や選択肢を構造化された質問形式でユーザーに投げかける機能です。

動作の仕組み

1. ユーザーが曖昧な指示を出す
2. Claudeが不明点を検知
3. 実行を一時停止し、選択肢付きの質問を表示
4. ユーザーがキーボードで選択
5. 正確な方向で実装を再開

実践のコツ

質問には「(Recommended)」マークで推奨オプションが示されることがあります。迷ったら推奨を選べば、Claudeの分析に基づいた選択ができます。

核心的な利点：構造化質問の威力

AskUserQuestionが単なる「何が欲しいですか？」と違う点は、Claudeがコードベースやコンテキストを分析して適切な選択肢を自動生成することです。

実例：APIエラーハンドリングの選択

Claudeからの質問:
「APIのエラーハンドリングはどれにしますか？」

A) 即時失敗（シンプル、デバッグしやすい）
B) リトライ付き（3回まで自動再試行）(Recommended)
C) カスタムハンドラー（独自ロジックを実装）

ユーザーは長文で説明する必要がなく、数秒で正確に意図を伝えられます。これが積み重なると、1回のセッションで完成度が段違いに上がります。

トレードオフの可視化

質問を通じて「この選択だとパフォーマンスが…」「こっちだと保守性が…」という議論が自然に発生し、アーキテクチャ決定の質が向上します。

Plan Modeとの相乗効果

Plan Mode（Shift+Tab x2で起動）とAskUserQuestionを組み合わせると、spec-based developmentが実現します。

推奨ワークフロー

ステップ操作結果
1「このアプリ作って」と投げるタスク開始
2Claudeが10個の質問を投げる要件の明確化
3ユーザーが選択で回答仕様確定
4Claudeが計画を立てて実行高品質なコード完成

効果

「計画段階で9割決まる」状態になり、ソロ開発の生産性が劇的に向上します。まるで優秀なPM/テックリードが隣にいる感覚です。

よくあるトラブルと対処法

症状原因解決策
質問が表示されない指示が明確すぎるより抽象的に指示する
選択肢が多すぎる複雑なタスクタスクを分割して再指示
タイムアウトで失敗60秒以内に回答できずすぐに回答、または「わからない」を選択
タイムアウト対策

AskUserQuestionには60秒のタイムアウトがあります。選択肢が多い場合は、最初に表示された推奨オプションを選んで先に進み、後から調整する方法が効果的です。

制限事項

  • サブエージェントからは使用不可：メインのClaudeのみが質問を投げられます
  • タイムアウト60秒：長時間考えると失敗する可能性があります
  • 質問数の上限：1回のセッションで4〜6問程度に抑えられます

注意点

これらの制限はありますが、利点を圧倒的に上回ります。

次のステップ

結論：AskUserQuestionを使わないのは、AIのポテンシャルを半分しか引き出していない状態です。曖昧さを嫌うClaudeの本質を最大限活かし、今日から積極活用を始めましょう。