Persona Panel Kr — Development skill for Claude Code

persona-panel-kr

**한국어 가상 페르소나 설문 패널** — NVIDIA [Nemotron-Personas-Korea](https://huggingface.co/datasets/nvidia/Nemotron-Personas-Korea)(통계청 KOSIS 실분포 기반, 한국어 100만 레코드, CC BY 4.0)에서 층화 표집한 페르소나에게 Claude가 설문 응답을 시뮬레이션합니다. 제품·서비스 아이디어의 **가설 정제용** 도구입니다.

설문 JSON 작성 → 층화 표집(일반 70 + 타깃 30) → Claude 배치 응답 → 자동 집계

• 비용: Claude Code 구독이 있으면 API 결제 없이 돕니다(구독 무과금 CLI 모드). 앱 하나(99명·문항 11개) ≈ 10콜·약 5분.
• 재현성: 시드 고정 — 같은 설정이면 같은 표본.
• 반(反)아부 설계: "무관심·거절 응답이 자연스럽게 나와야 한다"를 프롬프트 규칙으로 강제합니다. 전원이 호의적이면 실패한 시뮬레이션입니다.

⚠️ 이것은 실사용자 조사가 아닙니다

LLM 페르소나의 응답은 **태도 시뮬레이션**이지 실제 행동 예측이 아닙니다. 관련 연구에서 태도 문항은 실응답과 상관이 높지만 행동 예측력은 크게 떨어집니다. 이 도구의 정직한 용도:

• ✅ 가설·설문 문항의 사전 테스트, 세그먼트 간 상대 비교, 우선순위 판단
• ❌ "사용자 N명이 검증했다"는 주장, 수요 예측 절대값, 실조사 대체

결과를 문서에 인용할 때는 "AI 페르소나 시뮬레이션 N건"으로 명기하세요. 집계 JSON에도 면책 문구가 자동 포함됩니다.

빠른 시작

pip install pandas pyarrow huggingface_hub
python3 scripts/download.py                                  # 데이터 ~2GB (최초 1회)
cp examples/survey.example.json my_survey.json               # 설문 작성
python3 scripts/sample.py    my_survey.json myapp            # 층화 표집
python3 scripts/run_sim.py   my_survey.json myapp            # 응답 시뮬 (claude CLI 필요)
python3 scripts/aggregate.py my_survey.json myapp            # 집계 → out/agg_myapp.json

• run_sim.py는 Claude Code CLI(claude)를 사용합니다. 구독 로그인 상태면 ANTHROPIC_API_KEY를 자동으로 제거해 무과금으로 돌고, 중단해도 재실행하면 이어받습니다.
• 파일럿 권장: --limit 10으로 10명 먼저 돌려 응답 품질을 눈으로 확인한 뒤 전체 실행.

Claude Code 스킬로 쓰기 (선택)

루트의 `SKILL.md`는 사람용 문서가 아니라 **Claude Code 에이전트에게 주는 실행 매뉴얼**입니다. 이 저장소를 클론하고 Claude Code에서 "가상 패널 설문 돌려줘"라고 하면 그 절차대로 설문 설계→표집→시뮬→집계를 대신 진행합니다. 스크립트를 직접 돌릴 거라면 위의 빠른 시작만 보면 되고, `SKILL.md`는 무시해도 됩니다.

설문 JSON

`examples/survey.example.json` 참조. 문항 타입은 `single`(택1) / `multi`(복수) / `likert5`(1~5) / `open`(단문). `sampling.target_filter`로 타깃 오버샘플 조건(나이·혼인·성별·지역·취미 정규식)을 지정합니다.

한계 (데이터셋 기인)

• Nemotron-Personas-Korea에는 소득·소비지출·지불의사 필드가 없습니다 — 가격 관련 문항은 근거가 약하니 실조사로 확인하