TL;DR

• Claude Code의 AskUserQuestion은 터미널 UI이기 때문에, 선택지를 비교하며 읽어야 하는 질문에는 적합하지 않습니다. 도표 같은 것도 나타나지만, 선 조각과 ASCII 아트로는 한계가 있습니다.
• 이번에 제작한 review-wizard는 AI 에이전트가 인간에게 던지는 질문을 브라우저의 위저드 화면(한 번에 한 문제씩 표시, 스텝퍼 포함)으로 보여주는 플러그인입니다. 질문 내용에 따라 비교표나 인라인 SVG 도표로 설명되어 질문을 이해하기 쉬워집니다.
• 구현은 일시적인 로컬 HTTP 서버 방식으로, 외부 npm 의존성이 전혀 없습니다. 답변을 받으면 닫히고 종료되며, 상주하지 않습니다.
• 도입하면 질문이 3개 이상이거나 선택지의 비교 검토가 필요할 때 Claude Code가 자동으로 이것을 사용하며, 1~2개의 즉답은 AskUserQuestion 그대로 유지됩니다 (SKILL.md 기준에 따름).
• 리포지토리: https://github.com/uehaj/review-wizard

서론

NTT 테크노크로스의 우에하라입니다. 영화 '마이클'을 보고 다시금 '스릴러'라는 게 정말 대단한 MV구나 싶어 영상을 다시 보고 있습니다.

자, Claude Code에는 AskUserQuestion이라는 매우 편리한 메커니즘이 있습니다. AI가 인간에게 필요한 일련의 질문을 던지는 기능입니다. 1~2개 질문이라면 이것으로 아무런 불만도 없습니다. 손을 멈추지 않고 답하고 바로 작업으로 돌아갈 수 있습니다.

하지만 질문이 3~4개로 이어지거나 질문 내용이 다소 복잡해지면 상황이 달라집니다.

이는 AI가 생성하는 자료를 Markdown이 아닌 HTML로 만들려는 흐름과 마찬가지로, 폰트나 도표를 활용해 정보를 제시하면 인지 부하 (Cognitive Load)를 낮출 수 있습니다. 같은 생각으로, HTML로 질문을 제시하는 것이 review-wizard라는 플러그인입니다. 우선 화면을 봐주세요.

화면 살펴보기

화면 예시 1은 채팅 앱의 UI 안을 고르는 질문입니다. 질문문 아래에 3가지 안의 와이어프레임(Wireframe)과 비교표가 그려지고, 그 아래에 선택지가 나열됩니다. 이해하기 쉽고 눈이 편안합니다.

다음 화면 예시 2는 표를 사용한 것입니다. 일목요연합니다. 질문은 앞뒤로 돌아갈 수도 있습니다.

내부 작동 원리

구조적으로는 로컬 용도로 한정된 웹 서버를 세웁니다.

질문을 사용자에게 제시하기 위해 Claude Code는 127.0.0.1에 일시적인 HTTP 서버를 세웁니다. URL에는 매번 랜덤한 원타임 토큰 (One-time Token)을 삽입하며, 해당 경로에서만 위저드 화면을 반환합니다. 브라우저가 URL을 열고 답변이 전송되면, 서버는 답변을 JSON으로 기록하고 그대로 닫습니다. 실행되어 답을 기다리고, 닫힙니다. 폴링 (Polling)도 상주도 없는 단명하는 프로세스입니다.

도입 및 사용법

마켓플레이스를 통한다면 다음 두 줄입니다.

claude plugin marketplace add https://github.com/uehaj/review-wizard.git
claude plugin install review-wizard@review-wizard-marketplace

개발 중이거나 도입 전 확인 시에는 로컬 디렉토리를 직접 읽게 합니다.

claude --plugin-dir /path/to/review-wizard

Claude Code에서 사용할 때는 질문 JSON을 임시 파일에 쓰고, 백그라운드에서 실행합니다. 답변이 전송될 때까지 프로세스가 끝나지 않으므로, 포그라운드 (Foreground)에서 기다리면 Claude Code 자체가 멈춰버립니다.

node "${CLAUDE_PLUGIN_ROOT}/scripts/review_wizard.ts" \
--questions <in.json> --out <out.json> --timeout 1800

실행하면 표준 출력에 review_wizard: <URL>

이 나타나며, 해당 URL이 자동으로 열립니다. 프로세스가 끝나면 종료 코드로 결과를 판별하고, --out의 답변 JSON을 읽습니다. 종료 코드는 답변 수령이 0, 입력 에러가 1, 타임아웃 또는 서버 실행 실패가 2, 중단이 130입니다.

실행 조건

스킬 정의에는 "질문이 3개 이상이거나, 선택지의 비교 검토가 필요할 때 AskUserQuestion 대신 사용한다. 1~2개의 즉답은 AskUserQuestion을 그대로 유지한다"라는 실행 조건이 적혀 있으며, Claude Code는 이 설명문을 읽고 실행 여부를 판단합니다. 즉, 도입해 두면 상황에 따라 자동으로 사용됩니다. 기준을 바꾸고 싶을 때는 CLAUDE.md에 자신만의 규칙을 작성하여 덮어쓸 수 있습니다.

참고로, 편집이나 명령 실행을 자동 승인하는 모드(mode=auto)로 장시간 실행하는 방식이라면, 애초에 도중에 질문을 받을 기회 자체가 줄어듭니다. review-wizard가 효과를 발휘하는 것은, 판단을 질문을 통해 확인하며 진행하는 대화형 방식으로 사용할 때입니다.

요약

인지 부하 (Cognitive Load)를 낮춤으로써 신속한 개발을 가능하게 한다는 것입니다.

참고

Discussion