rainearcher/quiver

Perplexity 심층 리서치

Perplexity Agent API(POST /v1/agent)를 호출하여 인용문과 함께 다단계 브라우징 리서치를 수행합니다. API를 호출하기 전에, 이 스킬은 구조화된 정보 수집 및 계획 승인 루프를 요구하여 에이전트가 올바른 출처와 컨텍스트를 사용하고, 스캔하기 쉬운 형식의 보고서를 반환하도록 합니다.

방법론

이 스킬은 GTM(Go-to-Market)을 위한 Growth Unhinged 딥 리서치 플레이북을 프로그래밍 방식으로 구현한 것입니다: https://www.growthunhinged.com/p/deep-research-for-gtm. 해당 글의 다섯 가지 권장 사항은 아래 단계와 1:1로 매핑됩니다:

글의 권장 사항	구현 방식
포괄적인 컨텍스트 제공 (목표, GTM/제품, 제약 조건, 선호 출처)	1단계 — 5차원 정보 수집
먼저 리서치 계획을 요청하고, 승인 후 실행	2단계 — 계획 승인 게이트 (승인 없이 API 비용 발생 없음)
고품질 출처 사용; 2차 출처보다 1차 출처 선호; 모든 내용 인용	형식 블록 — 출처 표, 1차 출처 우선, 인라인 인용 필수
보고서 형식 지정; 산문보다 요약 및 표 선호 (피라미드 원칙)	형식 블록 — 먼저 TL;DR, 비교 표, 배경보다 결론 우선
프롬프트 구조화 (<goal>, <context>, <sources>, <instructions>)	--instructions 블록 레이아웃

호출별 출력 예산 확인(2.5단계) 및 다중 호출 시퀀싱(2.6단계)은 해당 글에 추가된 기능으로, 대규모 GTM 계획(훅 라이브러리, 30일 일정, 벤더 매트릭스)에서 자주 발생하는 자동 잘림 오류를 방지합니다.

사전 요구 사항

• 환경에 PERPLEXITY_API_KEY가 설정되어 있어야 함 (https://www.perplexity.ai/account/api 에서 발급 가능)
• curl 및 jq가 설치되어 있어야 함

처음 사용 시 사전 확인 스크립트를 한 번 실행하여 모든 것이 제대로 연결되었는지 확인합니다:

bash ./scripts/check-setup.sh

이 스크립트는 각 요구 사항에 대해 ✓/✗를 출력하고 누락된 사항에 대한 복사-붙여넣기 수정 방법을 제공합니다. 준비가 완료되면 0으로 종료됩니다. 어떤 검사라도 실패하면 출력을 사용자에게 보여주고 중단하세요 — 사전 확인이 통과할 때까지 API 스크립트를 실행하려고 시도하지 마십시오.

사용 시기

• 사용자가 "심층 리서치", "고급 리서치" 또는 "perplexity 리서치"를 명시적으로 요청할 때
• 사용자가 출처가 있는 브리핑(회사, 인물, 이벤트, 기술, 규제)이 필요할 때
• 여러 출처에 걸친 다단계 브라우징 및 종합이 필요한 질문
• 인라인 인용과 함께 최신 정보가 필요한 질문

다음 경우에는 사용하지 마십시오:

• 간단한 사실 확인("X의 현재 가격은 얼마인가") — WebSearch/WebFetch 사용 (더 저렴하고 빠름)
• 간단한 이진 비교("도구 A와 B 중哪个가 더 나은가") — 일반적으로 단일 WebSearch 라운드로 해결 가능
• 인증이 필요하거나 유료화된 콘텐츠 (Perplexity는 로그인할 수 없음)
• 코드베이스에서 답변 가능한 빠른 코드 편집 또는 질문 — 인라인이 더 빠름
• 이미 컨텍스트를 알고 있는 특정 사실 확인 — WebFetch로 충분히 정확함

워크플로우 (필수 — 단계를 건너뛰지 마십시오)

심층 리서치는 실제 비용이 발생하고 2~5분이 소요됩니다. 잘못된 실행은 비용 낭비입니다. 항상 다음 루프를 따르세요:

0단계 — 설정 확인 (최초 실행 시에만)

프로젝트에서 이 스킬을 처음 호출하는 경우 bash ./scripts/check-setup.sh를 실행하고 0으로 종료될 때만 계속 진행하십시오. 도구 누락 또는 키가 설정되지 않은 문제가 보고되면 해결 방법을 알리고 중단하십시오. 동일 세션에서 이후 실행 시 이 단계는 건너뜁니다.

1단계 — 초기 질문 감사 후, 누락된 부분만 질문

먼저 사용자의 초기 질문을 읽고 아래 다섯 가지 컨텍스트 차원 중 이미 답변된 것, 부분적으로 답변된 것, 완전히 누락된 것을 판단합니다. 사용자가 이미 알려준 내용을 다시 묻지 마십시오.

다섯 가지 차원:

1. 목표 및 동기 — 달성하려는 목표, 출력물 사용 방법(의사 결정, 문서, 피치, 전략), 이미 수행된 사전 작업.
2. 제품/상황 컨텍스트 — 회사/제품/역할, 운영 방식, 관련 설정 세부 정보(규모, 단계, GTM, 대상).
3. 제약 조건 — 예산, 마감일, 인력, 법률/규정 준수, 제외된 옵션, 양보할 수 없는 사항.
4. 선호 출처 — 지정된 전문가/제작자, 출판 유형(학술, 1차/정부 데이터, 포럼, 분석가, SEC 서류, GitHub 등), 허용/차단 도메인, 최신성 기간.
5. 범위 경계 — 명시적으로 범위에서 제외된 사항, 에이전트가 가정해서는 안 되는 사항.

질문 여부 결정:

• 다섯 가지 차원 모두 충분히 답변된 경우 → 설명을 건너뛰고 바로 2단계(계획 초안)로 이동합니다. 이미 알고 있는 내용을 확인하기 위해 질문하지 마십시오.
• 하나 이상의 차원이 누락되었거나 모호한 경우 → AskUserQuestion을 사용하여 누락된 부분만 하나의 통합 블록으로 질문합니다. 이미 이해한 내용을 명시적으로 나열하여(사용자가 수정할 수 있도록) 아직 필요한 내용을 함께 제시합니다.
• 사용자가 "그냥 진행" / "판단에 맡김"이라고 말하는 경우 → 2단계로 건너뛰고 계획에 누락된 각 차원에 대한 가정을 나열하여 사용자가 수정할 수 있도록 합니다.

질문을 최소화하는 방향으로 진행합니다. 잘 작성된 한 문단짜리 질문은 설명이 필요 없는 경우가 많습니다 — 바로 계획으로 넘어가십시오.

2단계 — 리서치 계획 초안 작성 및 승인 받기

API를 호출하기 전에 응답에 리서치 계획을 초안으로 작성하고 사용자에게 승인 또는 편집을 요청합니다. 계획에는 다음이 포함되어야 합니다:

• 리서치 질문 — 에이전트가 답변할 구체적인 하위 질문
• 방법론 — 옵션을 평가/비교하는 방법, 사용할 프레임워크
• 출처 전략 — 우선시할 출처 유형, 피할 출처 유형, 도메인 필터 또는 최신성 기간
• 보고서 구조 — 최종 보고서에 포함될 섹션 제목
• 산출물 — 산문 외에도 표, 비교 매트릭스, 템플릿, 체크리스트, 코드 스니펫 등이 포함될지 여부
• 공개 가정 — 추측 중인 내용 중 사용자가 수정해야 할 사항

명시적 승인("좋아요", "진행", "실행", 계획 수정 등)을 기다렸다가 진행합니다. 사용자가 계획을 수정하면 실행 전에 다시 확인합니다.

2.5단계 — 출력 예산 확인 (필수 — 잘림 방지)

advanced-deep-research 프리셋은 응답당 실질적인 출력 상한이 약 ~16k 토큰 / ~10k 단어입니다. 이 상한을 초과하는 계획은 자동으로 잘려서 TOC에 나열된 섹션이 나타나지 않고, 대규모 산출물(훅 라이브러리, N일 일정, 안티패턴 카탈로그)이 테이블 중간에서 잘립니다. 실행 전에 이 상한에 맞게 예산을 책정해야 합니다.

호출별 출력 예산(하드 제한):

항목	호출당 최대
주요 섹션(H2)	8
대형 표(6행 이상, 4열 이상)	4
항목화된 라이브러리/카탈로그(훅, 템플릿, 예제, 아이디어)	모든 라이브러리 합계 10개 항목
장문 산출물(N일 일정, 샷별 스크립트, 전체 플레이북)	1
총 산문(표 제외)	~4,000 단어

계획이 한 번 호출에 너무 크다는 것을 나타내는 위험 신호:

• TOC에 8개 이상의 섹션이 있음
• 계획이 여러 매트릭스와 함께 "25개 이상의 훅" / "30일 일정" / "20개의 템플릿"을 약속함
• 계획이 동일한 호출에서 여러 대규모 산출물을 요청함(예: 훅 라이브러리 AND 콘텐츠 일정 AND 샷별 템플릿 AND 안티패턴 카탈로그)
• 계획이 1개 이상의 별도 대상 세그먼트 또는 1개 이상의 별도 목표를 심층적으로 다룸

계획이 예산에 맞는 경우 → 3단계로 진행합니다.

계획이 예산을 초과하는 경우 → 순차적 다중 호출 계획으로 분할하고(아래 "다중 호출 시퀀싱" 참조) 대신 사용자에게 승인을 요청합니다.

2.6단계 — 다중 호출 시퀀싱 (대규모 범위 또는 종속 리서치의 경우)

두 가지 별도 이유로 여러 순차적 호출로 분할할 수 있으며, 두 경우 모두 동일한 메커니즘을 사용합니다:

(A) 예산 기반 분할 — 계획이 2.5단계의 호출별 출력 상한을 초과합니다. 각각 하나의 기본 산출물에 초점을 맞춘 호출로 분할합니다.

(B) 종속성 기반 분할 — 호출 N의 범위가 호출 N-1의 결과에 따라 달라집니다. 예: 벤더의 랜드스케이프 조사(호출 1)를 통해 심층 분석할 3개 벤더를 결정(호출 2~4). 이는 규모 문제가 아닙니다 — 이후 호출이 이전 호출에서 발견된 내용에 반응할 수 있도록 하는 것입니다. 호출 1을 실행하기 전에 모든 것을 미리 계획하려고 하지 마십시오.

다중 호출 분할 규칙:

1. 호출을 순차적으로 실행하고, 병렬로 실행하지 마십시오 — 각 호출은 이전 출력을 인용하거나 기반으로 할 수 있어야 합니다.
2. 각 호출은 하나의 기본 산출물에 초점을 맞춰야 합니다.
3. 각 호출은 2.5단계의 호출별 예산을 준수해야 합니다.
4. 각 호출은 개별적으로 가치가 있어야 합니다 — 조합해야만 의미가 있는 호출을 만들지 마십시오.
5. 각 후속 호출의 --instructions에 PRIOR FINDINGS (do not re-research) 헤더 아래 이전 호출의 핵심 결과(전체 보고서가 아닌 약 200~400단어 분량의 주요 결론)를 붙여넣어 에이전트가 중복 작업을 낭비하지 않도록 합니다.
6. 각 호출이 완료된 후 Read하여 출력을 확인하고, 잘린 내용이 없는지 확인(해당 호출의 TOC에 있는 모든 섹션이 존재하고 표가 중간 행에서 끝나지 않는지 확인)하고, 다음 호출을 시작하기 전에 사용자에게 간략히 요약합니다.

분할을 다음과 같이 제시합니다:

이 계획은 <예산/종속성 이유>로 인해 N번의 순차적 호출이 필요합니다:
  호출 1 — <초점>  (~$X, ~3분)
  호출 2 — <초점>  (~$X, ~3분)
  ...
총 예상 비용: $X. 분할을 승인하거나, 제외할 항목을 알려주세요.

호출을 실행하기 전에 분할에 대한 명시적 승인을 기다립니다. 사용자가 분할을 수정하면 다시 확인합니다.

3단계 — 리서치 실행

승인 후 스크립트를 호출합니다. 승인된 계획 + 컨텍스트 + 형식 요구 사항을 --instructions로 전달합니다. 사용자가 지정한 경우 --domains 및 --recency 플래그를 사용합니다.

항상 --topic <slug>를 전달하여 출력이 ./docs/research/ 아래의 주제 하위 디렉토리에 저장되도록 합니다. 호출 전에 기존 하위 디렉토리(ls docs/research/)를 확인하고 리서치 영역과 일치하는 기존 slug를 재사용하거나 새 짧은 케밥 케이스 slug를 생성합니다. 새 주제를 생성하는 경우, 현재 질문에서 한 번만 사용할 문구가 아니라 동일 영역의 향후 3~5개 보고서에도 사용할 수 있는 내구성 있는 slug를 선택하십시오. 좋은 slug 형태: vendor-comparison, competitor-analysis, regulation-update, <product-area>. 나쁜 slug 형태: doppler-vs-vault-2026 (너무 구체적이고 날짜에 종속됨).

스크립트는 ./scripts/research.sh에 있습니다(SKILL.md 기준 상대 경로). 에이전트가 호출할 때 해당 스킬 기준 상대 경로를 사용하십시오 — npx skills 설치 및 Claude Code /plugin 설치 모두에서 올바르게 해석됩니다.

bash ./scripts/research.sh \
  --preset advanced-deep-research \
  --output ./docs/research \
  --topic <topic-slug> \
  --instructions "$(cat <<'EOF'
<승인된 계획 + 컨텍스트 + 형식 요구 사항을 여기에 붙여넣기>
EOF
)" \
  "<승인된 계획에서 정제된 리서치 질문>"

4단계 — 보고서 읽고 요약

스크립트는 마크다운 경로를 출력합니다. 보고하기 전에 항상 해당 파일을 Read하십시오.

잘림 확인(필수):

1. 보고서 자체 TOC에 나열된 모든 섹션이 본문에 실제로 존재하는지 확인합니다.
2. 어떤 표도 중간 행에서 끝나지 않고, 어떤 항목 목록도 중간 항목에서 끝나지 않는지 확인합니다.
3. 마지막에 "출처", "출처 간 불일치", "신뢰도 및 격차" 섹션이 있는지 확인합니다.

잘림 복구 워크플로우. 위 항목 중 누락된 것이 있으면 → 출력이 잘린 것입니다. 다음을 수행하십시오:

1. 정확히 무엇이 누락되었는지 파악합니다. 보고서 TOC와 본문을 비교합니다. 누락된 섹션, 불완전한 표(마지막 완료된 행 기록), 중단된 목록 항목(마지막 완료된 항목 기록)을 나열합니다.
2. 남은 작업을 정량화합니다. "X개 섹션, Y개 항목, Z개 행이 아직 필요합니다."
3. 초점을 맞춘 후속 호출을 제안하고, 그 범위가 호출별 예산에 맞는지 확인합니다. 동일한 범위를 재시도하지 마십시오 — 다시 잘릴 것입니다.
4. 후속 호출의 --instructions에 PRIOR FINDINGS를 포함 — 완료된 섹션의 약 200~400단어 요약을 붙여넣어 에이전트가 재조사하지 않도록 합니다. 명시적으로 "X, Y, Z를 다시 다루지 말고 A, B, C에만 초점을 맞추십시오"라고 말합니다.
5. 사용자에게 무엇이 잘렸는지 알리고 후속 계획을 실행 전에 보여줍니다.

주요 인사이트, 보고서의 USD 비용, 주목할 만한 출처 불일치, 그리고 해당되는 경우 잘림 플래그를 표시합니다.

강력한 패턴

다음 패턴은 출력 품질을 안정적으로 향상시킵니다. 계획을 작성할 때 2단계에서 사용하십시오.

질문에 특정 전문가 또는 프레임워크 인용

질문에 3~6명의 관련 전문가, 저자, 제작자 또는 명명된 프레임워크를 지정하면 에이전트가 검색하고 비교할 구체적인 출처를 제공합니다. 보고서는 익명의 종합이 아니라 알려진 관점의 비교가 됩니다.

질문 조각 예시:

• "<전문가 A>, <전문가 B>, <전문가 C>의 프레임워크를 ...에 대해 비교"
• "<명명된 프레임워크> 방법론에 따라 평가..."
• "<저자 A>(<책/블로그>에서)와 <저자 B>가 권장하는 접근 방식 조정..."

전문가가 정기적으로 출판(논문, 비디오, 게시물, 발표)하는 경우 가장 잘 작동하며, 에이전트가 그들의 1차 자료를 가져올 수 있습니다.

정량화된 산출물 지정

"적절한 수의 예제"를 요청하는 대신 정확한 수와 형태를 명시합니다. 이렇게 하면 범위가 고정되고, 표류를 방지하며, 예산 초과 여부를 알 수 있습니다(2.5단계와 교차 참조).

좋은 산출물 사양:

• "비교 매트릭스: 8행(벤더당 하나), 5열(가격, 지연 시간, 인증, SDK, 규정 준수)"
• "정확히 10개의 템플릿으로 구성된 라이브러리, 3개 카테고리로 그룹화"
• "항목당 하루씩 14일 시퀀스"

피해야 할 표현: "포괄적인 라이브러리", "여러 예제", "많은 옵션" — 이러한 표현은 잘림 또는 변동을 초래합니다.

--instructions에 컨텍스트 사전 로드, 질문에는 포함하지 않음

질문은 간결한 1~2문장으로 유지해야 합니다. 사용자의 상황, 제약 조건, 사전 결정, 출처 선호도에 관한 모든 내용은 --instructions에 넣습니다. 이렇게 하면 에이전트의 검색 쿼리는 집중된 상태를 유지하면서 종합은 사용자 컨텍스트에 기반을 둡니다.

필수 형식 지침 (항상 --instructions에 포함)

모든 실행은 다음 형식 요구 사항을 --instructions 문자열에 포함하여 보고서를 스캔 가능하고 신뢰할 수 있게 만들어야 합니다:

SCOPE & SIZE CONSTRAINT (read first — this call must stay under ~16k tokens / ~10k words)
  - Max 8 H2 sections
  - Max 4 large tables (6+ rows, 4+ columns)
  - Max 10 total items across all itemized libraries/lists
  - Max 1 long-form deliverable
  - Total prose: ~4,000 words max

FORMAT (always)
  1. TL;DR (3 bullet points, no jargon) — first thing after the introduction
  2. Key findings (3-5 numbered points, each with a clear conclusion, no "further research needed" caveats)
  3. Body sections (H2), each section ending with a concise takeaway (1-2 sentences)
  4. Comparison table(s) where alternatives are discussed (rows = alternatives, columns = dimensions)
  5. Conclusions & recommendations (numbered, actionable, with优先级)
  6. Sources table
      | Source | Type (primary/secondary/tertiary) | Relevance | Key finding used |
  7. Where sources disagree (describe each disagreement, note confidence level for each source)
  8. Confidence & gaps (what's well-established, what's speculative, what wasn't found)

SOURCING
  - Prefer primary sources: official docs, filings, firsthand accounts, original research
  - Use secondary sources sparingly and only when primary isn't available (industry roundups, analyst reports)
  - Avoid tertiary sources: Wikipedia (use for background only, never as a finding source), forum threads, most blogs unless the blog IS the primary material (e.g., an expert's personal blog)
  - Every factual claim needs an inline citation [source N]
  - If two sources conflict, include both and explain the disagreement in the "Where sources disagree" section

PROHIBITED
  - No fabricated citations — if you can't find a source for a claim, mark it as "unverified" in the report
  - No sections beyond what's in the TOC — if TOC lists 6 sections, the report must have exactly 6 sections (no extra, no fewer)
  - No "X is important" without saying why — every conclusion must be grounded in a specific finding