[Claude Code 스킬] AskUserQuestion — 추측 대신 객관식으로 묻는 질문 도구 | DAKER 커뮤니티

무엇

AskUserQuestion은 Claude Code가 작업 도중 갈림길을 만났을 때, 임의로 추측하는 대신 객관식 질문 카드를 띄워 사용자에게 되묻는 내장 도구입니다. 내비게이션에 비유하면, 갈림길에서 말없이 아무 길로나 들어서는 대신 "고속도로로 갈까요, 국도로 갈까요?"를 먼저 묻고 출발하는 셈입니다. 한 번의 호출에 질문을 1~4개 담을 수 있고, 질문마다 2~4개의 선택지(label + description)와 12자 이내의 짧은 header, 복수 선택 여부(multiSelect)가 붙습니다.

언제 쓰나

가장 자주 발동하는 곳은 계획(plan) 모드입니다. Claude가 코드베이스를 탐색한 뒤 계획을 제안하기 전에 요구사항을 인터뷰하듯 물어봅니다. 그 외에도 유효한 설계가 여러 개일 때(DB·프레임워크·출력 형식 선택), 요청이 모호해서 잘못 짚으면 재작업이 커질 때 유용합니다. 반대로 CI처럼 사람이 없는 자동화 환경에서는 질문이 곧 '무한 대기'가 되므로, dontAsk 모드로 자동 거부되게 하거나 deny 규칙으로 도구 자체를 꺼두는 편이 안전합니다.

사용법

질문을 유도하는 프롬프트 한 줄이면 충분합니다.

# 프롬프트 예시
구현 전에 확실하지 않은 점은 추측하지 말고
AskUserQuestion으로 물어본 뒤 진행해줘.

# 질문을 끄고 싶을 때 (.claude/settings.json)
{
  "permissions": {
    "deny": ["AskUserQuestion"]
  }
}

Claude가 만들어 보내는 질문 한 개의 실제 구조는 다음과 같습니다.

{
  "questions": [{
    "question": "출력을 어떤 형식으로 만들까요?",
    "header": "Format",
    "options": [
      { "label": "요약형", "description": "핵심만 간단히" },
      { "label": "상세형", "description": "예시 포함 전체" }
    ],
    "multiSelect": false
  }]
}

터미널에서는 번호나 방향키로 선택지를 고르면 되고, 준비된 선택지가 마음에 안 들면 자유 텍스트를 직접 타이핑해도 그 문장이 그대로 답으로 전달됩니다. Agent SDK에서는 canUseTool 콜백에 toolName이 "AskUserQuestion"으로 들어오고, 질문 텍스트를 키로 선택한 label을 값으로 하는 answers 객체를 돌려주면 됩니다. toolConfig의 askUserQuestion.previewFormat("html"/"markdown")을 켜면 레이아웃·색상 비교처럼 눈으로 봐야 하는 선택지에 시각 미리보기(preview)까지 붙습니다.

팁

1. 계획 모드와 세트로 쓰세요. Shift+Tab으로 plan 모드에 진입해 질문 인터뷰 → 계획 승인 → 구현 순서가 정석입니다. 질문 몇 개에 30초 답하는 비용으로 수십 분짜리 재작업 루프를 지웁니다.

2. 권한 규칙과의 관계를 기억하세요. 이 도구는 성격상 자동 승인이 불가능합니다. allow 규칙을 걸어도, auto나 bypassPermissions 모드여도 질문은 항상 사용자에게 도달합니다 — 답은 사람만 할 수 있기 때문입니다. 유일한 예외가 dontAsk 모드(자동 거부)와 deny 규칙(도구 제거)입니다. 또 서브에이전트(Agent 도구) 내부에서는 쓸 수 없으니, 질문이 필요한 결정은 메인 세션에서 끝내고 서브에이전트에는 확정된 지시만 넘기세요.

출처

Claude Code 공식 문서 — Handle approvals and user input
Claude Code 공식 문서 — Tools reference
Claude Code 공식 문서 — Configure permissions