Claude Code AskUserQuestion 도구로 만드는 대화형 스킬 — 사용자 스토리 작성 자동화

들어가며

최근 Claude Code의 AskUserQuestion 도구를 사용해서, 사용자 스토리를 대화형으로 작성하는 스킬을 만들어 봤어요.

실제로 사용해 보니 "몇 건 만드시겠어요?", "버그 수정인가요? 기능 추가인가요?" 같은 질문을 버튼 선택 방식으로 차례차례 제시해 줘서, 텍스트를 이것저것 입력하지 않아도 사용자 스토리가 척척 완성됐어요. 대화형으로 정보를 수집하면서 산출물을 만드는 작업과 AskUserQuestion 도구의 궁합이 매우 좋다고 느꼈어요.

이 글에서는 AskUserQuestion 도구가 무엇인지부터 실제 사용법, 스킬 만드는 방법까지 차례로 소개해요.

AskUserQuestion 도구란

AskUserQuestion 도구는 Claude Code가 사용자에게 선택지를 곁들인 질문을 건넬 수 있게 해 주는 도구예요.

보통 Claude Code는 자유로운 텍스트로 대화하지만, AskUserQuestion 도구를 사용하면 사용자가 버튼 형식의 선택지를 눌러 답하는 방식으로 바뀌어요. 덕분에 모호함이 사라지고 의도도 빠르게 전달되죠.

AskUserQuestion 도구를 이용하는 장점: "AI에게 필요한 입력을 빠짐없이 전달하고 있는가"를 사람 혼자 고민하는 대신 AI도 함께 고민하게(직접 정보를 수집하게) 만드는 셈이라, 결과적으로 AI가 작업을 훨씬 높은 완성도로 마칠 수 있어요.

AskUserQuestion 도구의 특징

• 선택지 제시: 사용자에게 2~4개의 선택지를 보여 준다
• 단일 선택·복수 선택 지원: multiSelect: true를 지정하면 복수 선택도 가능하다
• 1턴에 최대 4문항까지: 한 번에 여러 질문을 묶어서 제시한다
• "Other" 자동 추가: 사용자는 선택지 밖의 내용을 자유 텍스트로 입력해도 된다

실제로 보이는 모습

예를 들어 Claude Code가 이런 식으로 질문을 던져요:

질문: 몇 건의 사용자 스토리를 작성하시겠습니까?
  ○ 1건
  ○ 2~5건
  ○ 6건 이상
  ○ 아직 정해지지 않았다

사용자는 버튼만 클릭하면 답변이 끝나니, 채팅을 여러 번 주고받는 과정을 건너뛸 수 있어요.

AskUserQuestion 도구의 2가지 사용법

AskUserQuestion 도구에는 크게 2가지 사용법이 있어요.

사용법 1: 프롬프트에 한마디만 덧붙이기

가장 간편한 사용법이에요. 일반적인 프롬프트 끝에 "모르는 것이 있으면 물어봐 줘" 또는 "AskUserQuestion 도구를 사용해서 물어봐 줘" 등을 덧붙이기만 하면, Claude Code가 선택지가 있는 질문을 제시해 줘요.

스킬 작성 같은 사전 준비가 전혀 필요 없으니, "이번에만 대화형으로 해 줬으면 좋겠다" 싶은 상황에 딱이에요.

프롬프트 예시:

사용자 스토리를 1건 만들고 싶어.
모르는 게 있으면 물어봐 줘.

사용자 스토리를 1건 만들고 싶어.
필요한 정보는 AskUserQuestion 도구를 사용해서 물어봐 줘.

AskUserQuestion 도구를 확실히 호출하게 하려면 두 번째 프롬프트처럼 도구 이름을 콕 집어 지시하는 편이 좋아요.

한 걸음 더 나아가, 어떤 질문을 할지와 선택지 내용까지 프롬프트로 지정해 둘 수도 있어요:

프롬프트 예시:

사용자 스토리를 1건 만들고 싶어.
필요한 정보를 AskUserQuestion 도구를 사용해서 수집해 줘.

처음에 다음 2가지를 물어봐 줘:
- 스토리 유형 (기능 추가 / 버그 수정 / 개선·리팩터링)
- 인수 조건 포맷 (Given/When/Then 형식 / 불릿 목록 형식)

매번 비슷한 질문을 손으로 쓰기 귀찮아지면, 다음 "사용법 2"처럼 스킬로 만들어 두면 편해요.

사용법 2: 스킬에 통합해서 반복 사용하기

AskUserQuestion을 사용한 절차를 스킬로 정의해 두면, 매번 프롬프트로 세세하게 지정하지 않아도 같은 질문 흐름이 그대로 재현되거든요.

(보충) Claude Code의 스킬이란

스킬은 ~/.claude/skills/<스킬명>/SKILL.md에 절차를 적어 두면 Claude Code가 상황에 맞춰 자동으로 불러와 실행하는 구조예요. SKILL.md에는 스킬의 메타 정보(name·description)와 Claude Code에 대한 지시를 기술해요.

~/.claude/skills/
  user-story-writer/
    SKILL.md          # 스킬의 본체 (프롬프트)
    references/       # 참조 파일 (템플릿이나 예시 등)
      templates.md
      examples.md

~/.claude/skills/는 개인용 스킬 위치입니다. 팀과 공유하고 싶은 스킬은 프로젝트 저장소의 .claude/skills/ 디렉터리에 두고 버전 관리에 커밋하면 팀원 모두가 같은 스킬을 사용할 수 있습니다.

description에 "어떤 문구로 실행되게 하고 싶은지"를 적어 두면, Claude Code가 적절한 타이밍에 스킬을 호출해 줘요.

---
name: user-story-writer
description: |
  사용자 스토리를 대화형으로 작성하는 스킬.
  "사용자 스토리를 써 줘", "인수 조건을 만들어 줘"
  등의 문구로 실행할 것.
---

스킬 만드는 방법: /skill-creator

Claude Code에는 /skill-creator라는 스킬 작성 전용 스킬이 있어요. 만들고 싶은 스킬의 개요를 전달하기만 하면 SKILL.md를 생성해 줘요.

[최신 정보] skill-creator는 Anthropic 공식 플러그인으로도 배포되고 있습니다(claude.com/plugins/skill-creator). 환경에 설치되어 있지 않다면 플러그인으로 추가한 뒤 /skill-creator로 호출할 수 있습니다.

프롬프트 예시:

/skill-creator

다음 사양으로 스킬을 작성해 주세요.

스킬명: user-story-writer

개요:
사용자 스토리를 대화형으로 작성하는 스킬입니다.
"사용자 스토리를 써 줘", "인수 조건을 만들어 줘" 등의 문구로 실행됩니다.

주요 기능:
- AskUserQuestion 도구를 사용해 대화형으로 필요한 정보를 수집한다
- 스토리 문장은 As a / I want / So that 형식으로 출력한다
- 인수 조건은 Given/When/Then 형식 또는 불릿 목록 형식을 선택할 수 있다
- 생성 후 리뷰와 수정 대응을 수행한다

처리 흐름:
1. 초기 정보 수집 (스토리 유형·인수 조건 포맷)
2. 스토리의 정보 수집
3. 사용자 스토리 생성
4. 리뷰와 다음 액션 확인

제약:
- AskUserQuestion 도구는 1턴에 최대 3문항까지
- 생성한 스토리에는 AI 이용 주의 문구를 붙인다

생성된 SKILL.md를 확인해 보고 부족한 부분이 있으면 추가 지시로 다듬으면 돼요:

스토리 유형 선택지에 이모지를 추가해서 시각적으로 알기 쉽게 해 주세요.

작성되는 SKILL.md의 이미지 (간단한 예)

위 프롬프트로 생성되는 SKILL.md는 대략 이런 모습이에요. AskUserQuestion을 호출하는 지점이 절차 안에 콕 집혀 있다는 게 포인트예요.

---
name: user-story-writer
description: |
  사용자 스토리를 대화형으로 작성하는 스킬.
  "사용자 스토리를 써 줘", "인수 조건을 만들어 줘"
  등의 문구로 실행할 것.
---

# User Story Writer 스킬

AskUserQuestion 도구로 정보를 수집하면서 사용자 스토리를 작성한다.

## Step 0: 초기 정보 수집

스킬이 실행되면 즉시 AskUserQuestion 도구를 호출해 확인한다 (최대 2문항).

질문 1 (single_select):
"몇 건의 사용자 스토리를 작성하시겠습니까?"
- 1건
- 2~5건
- 아직 정해지지 않았다

질문 2 (single_select):
"바탕이 되는 정보가 있습니까?"
- 사양 메모·요구사항이 있다 (나중에 붙여넣어 주세요)
- 제목이나 개요만 있다
- 백지에서 함께 생각하고 싶다

→ 원본 정보가 있는 경우 그 내용을 붙여넣게 한다.

## Step 1: 스토리별 정보 수집

각 스토리를 작성하기 전에 AskUserQuestion 도구를 호출해 확인한다 (최대 2문항).

질문 1 (single_select):
"스토리 유형을 선택해 주세요"
- 🆕 기능 추가
- 🐛 버그 수정
- ✨ 개선·리팩터링

질문 2 (single_select):
"인수 조건 포맷은 어느 쪽을 희망하십니까?"
- Given/When/Then (BDD 형식)
- 불릿 목록 (체크리스트 형식)

## Step 2: 사용자 스토리 생성

수집한 정보를 바탕으로 다음 포맷으로 출력한다.

> ⚠️ 이 사용자 스토리는 AI를 활용해 작성된 것입니다.

사용자 스토리:

- **As a** [사용자 유형],
- **I want to** [실현하고 싶은 조작·기능],
- **So that** [얻고 싶은 가치·목적].

인수 조건:

[Step 1에서 선택한 유형·포맷으로 기술]

## Step 3: 리뷰와 다음 액션

생성 후에는 반드시 AskUserQuestion 도구로 확인한다.

질문 (single_select):
"생성한 스토리는 어떠십니까?"
- 이대로 OK
- 일부 수정하고 싶다 (어디인지 알려 주세요)
- 다른 스토리도 이어서 만들고 싶다

"최대 2문항", "반드시 확인한다" 같은 제약을 명시해 두면 Claude Code가 헤매지 않고 움직여요.

실제로 직접 작성한 스킬의 예

앞서 소개한 SKILL.md는 간단한 예시이고, 실제로는 조금 더 상세한 스킬을 작성했어요.

가령 스토리 유형은 5종류(기능 추가·버그 수정·조사·개선·비기능 요구사항)로 늘렸고, 유형별로 템플릿 파일이 준비되어 있어요. 또한 "몇 건 만들 것인가", "바탕이 되는 정보가 있는가"를 Step 0에서 묶어서 확인하는 등 더 많은 질문 단계가 있어요.

이처럼 스킬에는 references/ 디렉터리에 보충 자료(템플릿이나 예시 등)를 두고 읽어 들이게 하는 방법도 있어요.

~/.claude/skills/user-story-writer/
  SKILL.md
  references/
    templates.md  # 스토리 유형별 출력 포맷
    examples.md   # 좋은 예·나쁜 예

덕분에 사용자 스토리를 전부 손으로 쓰던 시절에 비해 훨씬 빠르게 작성할 수 있게 됐어요.

AskUserQuestion 도구를 사용할 때의 포인트

스킬에 AskUserQuestion을 넣을 때 신경 쓰면 좋은 점을 정리했어요.

1문항당 선택지는 2~4개로 좁힌다

선택지가 너무 많으면 고르기가 오히려 어려워요. 기본적으로는 2~4개의 선택지로 좁히고, "기타(텍스트로 입력)"는 AskUserQuestion 도구가 자동으로 추가하므로 쓸 필요가 없어요.

1턴에 질문을 묶어서 물어본다

SKILL.md에 "1턴에 최대 3문항까지" 같은 제약을 명시해 두면, Claude Code가 몇 번이고 되묻는 일이 사라져요. 특히 첫 정보 수집은 한꺼번에 묻도록 프롬프트를 써 두면 쓰기 편해져요.

추측할 수 있는 정보는 확인만으로 끝낸다

모든 정보를 AskUserQuestion으로 물어볼 필요는 없죠. "〇〇라는 이해가 맞습니까?"처럼, 추측 가능한 정보는 확인만 하고 넘어가게 하면 주고받는 횟수가 줄어들어요.

분기 처리는 SKILL.md에 명시한다

선택지별로 처리가 나뉘는 경우에는 SKILL.md에 분기 내용을 명시해 둬요. 예를 들어 "커스텀 템플릿을 선택한 경우에는 텍스트 입력을 유도한다", "미선택인 경우에는 기본 포맷으로 진행한다" 같은 조건 분기예요.

마무리

AskUserQuestion 도구의 2가지 사용법과 스킬에 통합하는 방법을 소개했어요.

• 사용법 1 (프롬프트에 한마디 덧붙이기): 사전 준비 없이 바로 쓴다
• 사용법 2 (스킬에 통합하기): /skill-creator로 SKILL.md를 생성해, 반복 사용할 수 있는 스킬에서 AskUserQuestion 도구를 이용한다
• 대화형으로 사용자 스토리를 작성하는 것 같은 작업에는 AskUserQuestion 도구가 적합하다

스킬 활용에 익숙해질수록 반복 작업이 자동화되면서 효율이 눈에 띄게 올라가요. 꼭 AskUserQuestion 도구를 조합해서 더 사용하기 편한 스킬을 만들어 보시기 바랍니다.

©2024-2026 ClaudeCode.to, Hand-crafted & made with Jaewoo Kim.

• 이메일문의: jaewoo@claudecode.to
• AI 에이전트 만드는 사람
• 기업 AI 강의 · 에이전트 개발 · 기술자문
• "AI한테 일 시키는 법, 제대로 알려드립니다"