<essential_principles>
이 스킬의 작동 방식
주제에 따라 자동 라우팅되는 두 가지 모드 (라우팅 테이블 참조):
- 모드 A — 리포지토리 / 개념 / 문서 (저렴한 경로): 연구 → 복제 (리포지토리인 경우) → 탐색 → 종합 → 출력. 느슨한 병렬 에이전트 사용 가능.
- 모드 B — 라이브 웹 제품 / 경쟁사 / 데이터 제품 / 알고리즘 / 환경 (완전 패키지): 정찰 → 확인 → 워크플로우 기반 심층 정찰 → 실제 브라우저 캡처 → 검증된 코드로 역공학 → 종합.
@references/competitor-teardown.md를 읽고 따르세요.
주제 유형 라우팅
| 주제 | 신호 | 모드 | 주요 단계 |
|---|---|---|---|
| GitHub 리포지토리 | github.com | A | 복제 + 탐색 에이전트 |
| 개념 / 기술 | URL 없음 | A | 연구 에이전트 |
| 문서 / 정적 사이트 | URL, 정보 제공 | A | 연구 + WebFetch |
| 라이브 제품 / 앱 / SaaS / 경쟁사 | URL이 제품임; "경쟁사/분석/vs us/어떻게 하는지" | B | 브라우저 + 워크플로우 + 주제별 스키마 |
| 계산기 / 추정기 / 예측기 / 가격 / 순위 | 분석해야 할 공식/알고리즘 | B | 라이브 프로브 그리드 → 실행 가능한 참조 구현 → 검증 |
| 전체 환경 | "다른 모든 것 찾기 / 이 분야의 모든 것" | B | 네임스페이스 발견 → YES 세트 분석 |
동점 해결: URL이 제품이면서 문서도 있는 경우, B를 기본값으로 합니다. 정찰 패스는 저렴하며, 분석할 대상이 없으면 A로 다운그레이드됩니다.
실행 규칙
- 규모에 맞는 올바른 도구: 모드 A = 병렬 Task/Agent 호출. 모드 B = 워크플로우 도구 (파이프라인, 구조화된 출력 스키마, 재개) (주제가 3개 이상이거나 다단계 작업인 경우).
- 근거 기반 후 확인: 모드 B는 저렴한 정찰 패스 + 확인 게이트 (범위 + 정찰 경계 + 브라우저)를 고비용 분석 전에 수행합니다. 단, 사용자가 이미 "전체 분석 / 깊게 파기 / 모든 것"을 요청한 경우는 제외.
- 계산기/알고리즘의 경우 실행 가능하고 검증된 코드로 역공학하고, 경쟁사의 주장이 아닌 권위 있는 실제 값과 벤치마킹합니다.
- 시각 자료 중심: 모든 주요 개념에 다이어그램이나 테이블을 포함합니다.
- 이중 출력: 대화에는 실행 요약 + 파일 인덱스를 표시하고, 전체 문서 세트는
~/.claude/explanations/<날짜>_<슬러그>/에 저장합니다. - 복원력: 무거운 모드 B 연구는 백그라운드 워크플로우로 실행됩니다. 아티팩트를 점진적으로 유지하고, 중단 시 재개합니다 (
resumeFromRunId). - 정리: 완료 시 복제된 리포지토리/저장된 파일 삭제를 제안합니다. </essential_principles>
<scope_boundary>
모드 B 정찰 경계 (중요 — 실제 프로빙 전에 읽을 것)
경쟁사 정찰은 공개 표면에서 합법적이며 정상적입니다. 전체 규칙은 @references/competitor-teardown.md에 있습니다. 불변 규칙:
- 허용됨: 공개 페이지/자산, 공개 OpenAPI/
/docs, 공개 JS 번들, 공개 엔드포인트에 대한 적절한 예의를 갖춘 소규모 그리드(~15-40, 낮은 비율)의 일반 사용자 수준 요청 (공식 도출용), 헤더 핑거프린팅, WHOIS/DNS. - 절대 금지: CAPTCHA/봇 챌린지 우회, 인증 우회, 전체 데이터셋 대량 수집 (샘플만 가능), 스트레스 테스트, 관리자/변경/파괴적 엔드포인트 호출 (문서화만 하고 호출하지 마세요). 노출된 부분을 관찰하되, 악용하지 마세요. 사용자의 실제 데이터를 경쟁사 양식에 제출하지 마세요. 확실하지 않으면 하지 말고, 그 이유를 설명하세요. </scope_boundary>
<intake_gate>
<no_context_handler> $ARGUMENTS가 비어 있는 경우: → AskUserQuestion 사용:
- header: "설명"
- question: "무엇을 설명해 드릴까요?"
- options:
- "GitHub 리포지토리" - GitHub의 코드베이스 분석
- "웹사이트 또는 문서" - 웹사이트, 문서 또는 API 이해
- "경쟁사 / 라이브 제품 / 환경" - 라이브 제품 분석, 계산기 역공학, 또는 경쟁 환경 전체 파악 (모드 B)
- "개념 또는 기술" - 개념, 프레임워크 또는 도구 설명
그 후 context_analysis로 진행합니다. </no_context_handler>
<context_analysis> $ARGUMENTS를 분석하여 다음을 추출:
- 유형: GitHub 리포지토리, 웹사이트, 개념 또는 기타
- URL/주제: 설명할 특정 대상
- 암묵적 목표: 사용법 학습? 평가? 아키텍처 이해? 기여?
유형 자동 감지:
github.com포함 → GitHub 리포지토리 (모드 A)- 모드 B 신호 → "경쟁사", "분석", "역공학", "vs us", "어떻게 하는지", "다른 모든 것 찾기", 또는 URL이 제품/앱/계산기인 경우 → 모드 B
http포함 (정보 제공/문서) → 웹사이트 (모드 A)- 그 외 → 개념 (모드 A) </context_analysis>
<initial_questions> 진정한 정보 격차가 있는 경우에만 AskUserQuestion 사용 (최대 2-3개 질문):
목표 (불명확한 경우):
- "목표가 무엇인가요?" 옵션:
- "작동 방식 이해" - 아키텍처, 흐름, 구현
- "도입 평가" - 장단점, 대안, 사용 사례 적합성
- "사용법 학습" - 설정, API, 시작 가이드
- "기여 방법 학습" - 코드베이스 구조, 개발 워크플로우
집중 분야 (광범위한 주제인 경우):
- "특정 집중 분야가 있나요?" 옵션:
- "모든 것" - 전체 종합 분석
- "아키텍처만" - 높은 수준의 구조와 패턴
- "특정 기능" - 한 가지 특정 측면 (지정)
배경 지식 (도움이 되는 경우):
- "기술 수준은 어떻게 되시나요?" 옵션:
- "비기술적" - 기본 원리부터 비유를 들어 설명
- "기술적이지만 이 분야는 처음" - 기본 생략, 세부 사항 집중
- "전문가" - 깊은 기술적 내용, 지식 가정 </initial_questions>
<decision_gate> 답변 후 AskUserQuestion 사용 (모드 A):
- question: "심층 분석을 시작할 준비가 되셨나요?"
- options:
- "네, 시작하세요" - 다단계 분석 시작
- "먼저 더 질문이 있습니다" - 명확히 할 사항이 있음
- "컨텍스트를 추가하겠습니다" - 세부 정보를 추가하고 싶음
모드 B는 이 게이트를 B2 (스냅샷 + 범위 + 정찰 경계 + 진행/깊이/브라우저)로 대체합니다 — 둘 다 묻지 마세요. B2가 분석을 위한 유일한 권위 있는 게이트입니다. </decision_gate>
</intake_gate>
모드 선택
<intake_gate>를 실행한 후 주제 유형 테이블에 따라 라우팅합니다. 모드 B (라이브 제품 / 경쟁사 / 데이터 제품 / 계산기 / 환경) → @references/competitor-teardown.md를 로드하고 정찰 → 확인 → 심층 → 종합 흐름(아래 뼈대)을 따릅니다. 모드 A (리포지토리 / 개념 / 문서) → 아래 1-7단계를 따릅니다.
모드 B — 라이브 제품 / 경쟁사 / 데이터 제품 분석
전체 플레이북은 references/competitor-teardown.md에 있습니다. 뼈대:
- B0 근거 확인: 메모리 +
~/.claude/explanations/에서 이전 분석 확인; 확장, 재작성 금지. - B1 정찰: 대상당 하나의 가벼운 수동 정찰 에이전트 (WebFetch + 헤더 + WebSearch) → 근거 기반 스냅샷 + 브라우저가 필요한 항목 파악.
- B2 확인 게이트: 스냅샷 + 범위 + 정찰 경계 (
<scope_boundary>) 제시;AskUserQuestion으로 진행/깊이/브라우저 확인 — 사용자가 이미 "깊게 파기 / 전체 분석"을 말한 경우에만 건너뜀. - B3 심층 정찰 (워크플로우): 주제당 하나의 구조화된 에이전트, 모두 공유 주제별 스키마 사용 (참조 파일). 기본적으로
pipeline()사용; 큰 출력은 디스크에 분할 저장. - B4 브라우저 (Claude-in-Chrome): 로드 시 네트워크 캡처, SPA 렌더링, 입력 그리드에 걸쳐 추정기 라이브 프로빙, 보안 헤더, 페이월/인증 복사 — 경계 내에서 수행 (CAPTCHA/인증 우회 금지, 변경 엔드포인트 금지, 사용자 데이터 제출 금지). 진행하면서 캡처 유지.
- B5 역공학: 모든 계산기 → 실행 가능한 TypeScript 참조 구현 → 라이브 그리드와 비교 검증 → 권위 있는 실제 값과 벤치마킹.
- B6 네임스페이스 ("다른 것?"인 경우): DNS+curl+검색 후보 도메인, 분류, 운영자 클러스터 찾기, 방어적 구매 도메인 플래그 지정, 진정으로 구별되는 YES 세트만 분석.
- B7 종합: 팬아웃 종합 에이전트 →
DETAILED-<슬러그>.md×N +ESTIMATORS.md+COMPARISON.md(데이터 무결성 + 운영자 클러스터 섹션 포함) +REPLICATION-BLUEPRINT.md+ARCHITECTURE.md+NAMESPACE.md+SOURCES-*.md+SUMMARY.md(실행 요약 + 파일 인덱스). 그런 다음 7단계 출력/정리.
모드 A — 리포지토리 / 개념 / 문서
1단계: 병렬 웹 연구 (5개 연구 에이전트)
모두 한 메시지에 생성:
Task(subagent_type="general-purpose", prompt="[주제] 연구: 무엇인가요? 누가 만들었나요? 언제? 왜?")
Task(subagent_type="general-purpose", prompt="[주제] 연구: 기술 스택, 아키텍처, 주요 기술")
Task(subagent_type="general-purpose", prompt="[주제] 연구: 기사, 리뷰, 커뮤니티 토론, 의견")
Task(subagent_type="general-purpose", prompt="[주제] 연구: 대안, 비교, 사용 시기 vs 사용하지 않을 시기")
Task(subagent_type="general-purpose", prompt="[주제] 연구: 문서, 튜토리얼, 시작 가이드")
2단계: 리포지토리 복제 (GitHub인 경우)
REPO_DIR=~/.claude/explanations/$(date +%Y%m%d_%H%M%S)_$(basename [URL] .git)
git clone [URL] $REPO_DIR
cd $REPO_DIR
3단계: 병렬 코드베이스 탐색 (6개 탐색 에이전트)
모두 한 메시지에 생성 (thoroughness="very thorough"):
Task(subagent_type="Explore", prompt="아키텍처: 전체 구조, 모듈, 관계")
Task(subagent_type="Explore", prompt="진입점: 주요 파일, CLI, API 엔드포인트, 시작 방법")
Task(subagent_type="Explore", prompt="핵심 로직: 주요 알고리즘, 패턴, 추상화")
Task(subagent_type="Explore", prompt="설정: 설정, 환경, 확장 지점")
Task(subagent_type="Explore", prompt="의존성: 주요 패키지, 통합, 외부 서비스")
Task(subagent_type="Explore", prompt="테스트 및 품질: 테스트 패턴, 커버리지, CI/CD")
4단계: 병렬 Claude Code 컨텍스트 (2-3개 범용 에이전트)
Claude/AI/에이전트와 관련된 경우:
Task(subagent_type="general-purpose", prompt="이해를 위한 관련 Claude Code 개념 설명")
Task(subagent_type="general-purpose", prompt="해당되는 경우 Claude 도구/SDK와 비교")
5단계: 중간 점검 (복잡한 경우)
발견 사항이 복잡성을 드러내는 경우 AskUserQuestion 사용:
- "[X]를 발견했습니다. 특정 부분에 집중할까요?"
- 발견 사항에 기반한 옵션
6단계: 종합
모든 발견 사항을 다음을 포함한 포괄적인 설명으로 결합:
- 서두 비유 (비기술적 비교)
- 정의 (1-2문장)
- 아키텍처 다이어그램 (ASCII)
- 작동 방식 (단계별 다이어그램 포함)
- 주요 구성 요소 테이블 (이름, 목적, 작동 방식)
- 특별한 점 (차별점)
- 기능 목록 (할 수 있는 일)
- 비교 테이블 (대안과 비교)
- 기술 심층 분석 (구현 세부 사항)
- 주의 사항 및 고려 사항
7단계: 출력
대화에 표시
모든 시각 자료와 함께 완전한 형식의 설명.
파일로 저장
OUTPUT_DIR=~/.claude/explanations/$(date +%Y%m%d_%H%M%S)_[주제-슬러그]
mkdir -p $OUTPUT_DIR
# 저장 파일:
# $OUTPUT_DIR/SUMMARY.md - 빠른 참조 (30초 버전)
# $OUTPUT_DIR/DETAILED.md - 전체 분석
# $OUTPUT_DIR/ARCHITECTURE.md - 모든 다이어그램
# $OUTPUT_DIR/COMPARISON.md - 대안 분석
후속 질문
표시 후 질문:
- "더 깊이 탐구하고 싶은 측면이 있나요?"
- "설명에 대해 질문이 있나요?"
- 후속 질문 장려
정리
AskUserQuestion을 사용하여 정리 (둘 다 해당되면 결합):
리포지토리를 복제한 경우:
- question: "복제된 리포지토리를 삭제할까요?"
- options:
- "네, 삭제하세요" - $REPO_DIR 자동 제거
- "아니요, 유지하세요" - 경로 표시: "리포지토리 위치: $REPO_DIR"
예인 경우: rm -rf $REPO_DIR
아니오인 경우: 수동 접근을 위한 경로 표시
항상 (설명 파일):
- question: "저장된 설명 파일을 삭제할까요?"
- options:
- "네, 삭제하세요" - $OUTPUT_DIR 자동 제거
- "아니요, 유지하세요" - 경로 표시: "설명 파일 위치: $OUTPUT_DIR"
예인 경우: rm -rf $OUTPUT_DIR
아니오인 경우: 수동 접근을 위한 경로 표시
결합 질문 (리포지토리와 파일 모두 있는 경우):
- question: "분석이 완료되었습니다. 무엇을 정리할까요?"
- options:
- "리포지토리와 설명 파일 모두 삭제"
- "리포지토리만 삭제, 설명 파일은 유지"
- "설명 파일만 삭제, 리포지토리는 유지"
- "모든 것 유지"
선택에 따라 삭제 실행, 유지된 항목의 경로 표시.
<visual_formats>
표준 다이어그램 형식
아키텍처:
┌─────────────┐ ┌─────────────┐
│ 구성 요소 │────►│ 구성 요소 │
└─────────────┘ └─────────────┘
흐름:
시작 → 단계1 → 단계2 → 결정?
├─ 예 → 경로 A
└─ 아니오 → 경로 B
비교 테이블:
| 측면 | 옵션 A | 옵션 B | 승자 |
|------------|----------|----------|------|
| 속도 | 빠름 | 느림 | A |
구성 요소 분석:
┌──────────────────────────────────────┐
│ 시스템 이름 │
├──────────────────────────────────────┤
│ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │모듈 A │ │모듈 B │ │모듈 C │ │
│ └───┬────┘ └───┬────┘ └───┬────┘ │
│ └──────────┴──────────┘ │
│ 공유 계층 │
└──────────────────────────────────────┘
</visual_formats>
<success_criteria> 두 모드 공통:
- 시작 전 명확한 질문/근거 확인; 올바른 모드로 라우팅
- 모든 주요 개념에 대한 시각적 다이어그램 생성; 재현 가능한 기술적 깊이 포함
- 대화에 실행 요약 표시 AND 문서 세트를 파일로 저장
- 후속 질문 + 정리 제공; 사용자의 유지/삭제 선택 존중
모드 B (라이브 제품 / 경쟁사 / 데이터 제품 / 환경):
- 정찰 패스 + 확인 게이트 수행 (또는 명시적인 "깊게 파기" 요청 존중) 및 정찰 경계 명시
- 경계를 엄격히 준수: CAPTCHA/인증 우회 금지, 대량 수집 금지, 변경/관리자 엔드포인트 호출 금지, 사용자 데이터 제출 금지; 노출 관찰, 악용 금지
- 3개 이상 주제/다단계 시 공유 주제별 스키마와 함께 워크플로우 도구 사용; 아티팩트 유지; 중단 시 복원력 (재개)
- 모든 계산기 라이브 프로빙 및 관찰된 출력과 N/N 일치하는 실행 가능한 참조 구현 제공, 권위 있는 실제 값과 벤치마킹
- 환경 분석의 경우: 전체 네임스페이스 발견, 각각 분류, 운영자 클러스터 찾기, 방어적 구매 도메인 플래그 지정, 구별되는 것만 분석
- 종합에는 데이터 무결성 섹션 + 운영자 클러스터 섹션 포함 </success_criteria>