intent-clarifier

Intent Clarifier

사용자 요청을 첫 턴에 분해하여, 의사결정 분기와 맥락 공백을 찾아내고, AskUserQuestion 도구로 사용자에게 직접 질문한다. 충분한 맥락이 확보될 때까지 질문 루프를 돌린 뒤에만 다음 단계(리서치·계획·수정)로 넘어간다.

이 스킬을 호출해야 하는 요청 유형

• 새로운 기능·모듈·화면·서비스·파일 생성
• 포팅·마이그레이션·리라이트·대규모 리팩터링
• 아키텍처·라이브러리·프레임워크·배포 모델·의존성 선택이 필요한 요청
• 외부 리서치(Web/Context 검색, 문서 조사)를 수반할 가능성이 있는 요청
• 스코프가 모호한 요청: "X 도와줘", "Y 개선해줘", "Z 최적화", "뭔가 해줘"
• 사용자 요청에서 대명사(이/그/저, it/this) 가 가리키는 대상이 모호한 경우

호출하지 않아도 되는 요청 (자명한 단순 실행)

• 명시된 단일 파일의 명시적 편집: "이 함수의 이름을 Y 로 바꿔줘"
• 단순 정보 조회: "이 파일 보여줘", "이 로그 해석해줘"
• 결정론적 실행 명령: 테스트 실행, 빌드, git status, lint, format
• 이전 턴에서 이미 모든 맥락이 확보되었고 사용자가 "이어서 진행" 만 지시한 경우

면제 여부가 애매하면 호출하는 쪽을 기본으로 삼는다.

작업 절차

Step 1 — 요청 정제 (1~2문장으로 내면화)

사용자 문장을 그대로 따라 읽지 말고, 아래 3요소로 재구성한다:

• 목표(goal): 사용자가 궁극적으로 얻고 싶은 결과 1문장
• 대상(subject): 그 목표가 적용되는 대상(파일/모듈/서비스/프로젝트)
• 제약 단서(constraints, if any): 문장에 이미 담긴 제약·선호

재구성이 불가능하면 Step 2 로 건너뛰지 말고, Step 3 의 첫 질문으로 요청 자체 재확인 을 넣는다.

Step 2 — 의사결정 분기 열거

목표를 달성하는 경로에 존재하는 갈림길을 모두 꺼낸다. 각 분기에 대해 "사용자가 암묵적으로 A/B/C 중 하나를 가정했을 것" 이라고 지나치지 말고, 선택지를 명시적으로 나열한다. 최소 다음 카테고리를 점검:

1. 결과물의 형태·배포 모델 — standalone / monorepo 통합 / 기존 파일에 병합 / 공개 여부
2. 기존 자원과의 관계 — 임포트 / 복사 / 참조 / 대체 / 폐기 / 병행 유지
3. 생명주기·유지보수 주체 — 장기 유지 / 실험적 / 특정 시점 폐기 예정 / 본인 / 팀
4. 성공의 측정 기준 — "완료" 의 정의, 필수 수용 조건, 제외 조건
5. 제약 — 기술 스택·언어·프레임워크·라이브러리·성능·보안·호환성·일정
6. 대상 사용자·사용 시나리오 — 내부 도구 / 팀원 / 외부 개발자 / 최종 사용자
7. 외부 리서치 수반 시 — 어떤 소스를 권위로 삼을지, 결과를 어느 수준에서 확정으로 볼지

Step 3 — 맥락 공백 식별

위 분기 중 다음 출처에 명시적 답이 이미 존재하는 항목은 제외한다:

• 사용자의 이번 메시지 문장
• 직전 대화 턴의 합의된 결정
• 프로젝트의 CLAUDE.md · README.md · docs/ 의 관련 문서

남은 미확인 분기 = 질문 대상. 최대 4개로 압축한다 (중요도 순). 4개를 넘으면 가장 상류·의존성 많은 분기를 우선.

Step 4 — 질문 실행

AskUserQuestion 도구를 사용한다. 텍스트로 질문을 나열하고 응답을 기다리지 않는다.

• 한 번의 호출에 4개 이내 질문
• 각 질문은 question(본문), header(12자 이내 헤더), options(2~4개 label + description), multiSelect(해당 시) 구조
• 권장 선택지가 있으면 첫 번째에 (권장) 표기
• 옵션 간 트레이드오프를 description 에서 1줄로 설명 — "A: 간단하나 확장 어려움 / B: 구조 크지만 장기 유지 용이"