Claude Code AskUserQuestion Tool Guide: Drastically Reduce Rework from Ambiguous Instructions¶
Target Audience
- Intermediate developers who have started using Claude Code and seek to reduce rework from ambiguous instructions
Key Points¶
- Understand how the AskUserQuestion tool works and its benefits
- Master usage patterns that reduce rework loops by 50-80%
- Maximize productivity by combining with Plan Mode
The Core Problem: Why AI Coding Falls into "Rework Hell"¶
The biggest weakness of traditional AI coding assistants is "making assumptions about ambiguous prompts." When you instruct "add this feature," the AI makes its own assumptions and writes code → misses the intent → you give correction instructions → it misses again... creating an endless loop.
AskUserQuestion tool fundamentally solves this problem.
What is AskUserQuestion?¶
The AskUserQuestion tool, added in Claude Code v2.0.21 and later, is a feature where Claude presents unclear points or options as structured questions (mainly multiple choice) during task execution.
How It Works¶
1. User gives an ambiguous instruction
2. Claude detects unclear points
3. Pauses execution and displays question with options
4. User selects with keyboard
5. Resumes implementation in the correct direction
Practical Tip
Questions may show a "(Recommended)" mark for suggested options. When in doubt, choosing the recommended option gives you a selection based on Claude's analysis.
Core Advantage: The Power of Structured Questions¶
What makes AskUserQuestion different from a simple "what do you want?" is that Claude analyzes the codebase and context to auto-generate sensible options.
Example: Choosing API Error Handling¶
Question from Claude:
"How should API errors be handled?"
A) Immediate failure (Simple, easy to debug)
B) With retry (Auto-retry up to 3 times) (Recommended)
C) Custom handler (Implement custom logic)
Users don't need to write long explanations—they can convey their intent accurately in seconds. When this accumulates, the completion quality per session becomes dramatically different.
Visualizing Trade-offs¶
Through questions, discussions like "this choice affects performance..." or "that one affects maintainability..." naturally occur, improving the quality of architecture decisions.
Synergy with Plan Mode¶
Combining Plan Mode (activate with Shift+Tab x2) with AskUserQuestion enables spec-based development.
Recommended Workflow¶
| Step | Action | Result |
|---|---|---|
| 1 | Request "build this app" | Task starts |
| 2 | Claude asks 10 questions | Requirements clarification |
| 3 | User answers with selections | Specifications finalized |
| 4 | Claude plans and executes | High-quality code complete |
Effect
You reach a state where "90% is decided at the planning stage," dramatically improving solo development productivity. It feels like having an excellent PM/tech lead beside you.
Common Issues and Solutions¶
| Symptom | Cause | Solution |
|---|---|---|
| Questions don't appear | Instructions too clear | Give more abstract instructions |
| Too many options | Complex task | Split and re-instruct the task |
| Timeout failure | Can't answer within 60 seconds | Answer immediately or select "don't know" |
Timeout Countermeasures
AskUserQuestion has a 60-second timeout. When there are many options, selecting the initially displayed recommended option to proceed first and adjusting later is an effective approach.
Limitations¶
- Cannot be used from sub-agents: Only the main Claude can ask questions
- 60-second timeout: Long deliberation may cause failure
- Question limit: Limited to about 4-6 questions per session
Note
These limitations exist, but the benefits overwhelmingly outweigh them.
Next Steps¶
- Claude Code Plan Mode Advanced Guide: Detailed usage of Plan Mode
- Claude Code Hooks Implementation: Further automation methods
Conclusion: Not using AskUserQuestion means you're only harnessing half of AI's potential. Make the most of Claude's preference for clarity and start actively using this feature today.