심층 연구 스킬
목적
이 스킬은 OpenAI의 Deep Research API(o4-mini-deep-research 모델)를 사용하여 모든 주제에 대해 인터넷을 활용한 포괄적인 연구를 수행할 수 있게 해줍니다. 대화형 질문을 통해 사용자의 연구 프롬프트를 지능적으로 개선하고, 연구 매개변수를 재현 가능하도록 저장하며, 웹 검색 기능을 갖춘 심층 연구를 실행합니다.
이 스킬을 사용해야 하는 경우
다음과 같은 상황에서 이 스킬을 실행하세요:
- 사용자가 특정 주제에 대한 연구를 요청할 때
- 사용자가 분석, 조사 또는 포괄적인 정보 수집을 요청할 때
- 사용자가 웹 검색과 추론을 사용한 주제 탐색을 원할 때
- 사용자가 개선될 수 있는 간단한 연구 질문을 제공할 때
- 사용자가 특정 분야의 현재 상태, 트렌드 또는 비교를 이해하려고 할 때
사용자 요청 예시:
- "벤치마크 성능이 높은 가장 효과적인 오픈소스 RAG 솔루션을 조사해줘"
- "2025년 최신 AI 발전 현황은?"
- "분산 데이터베이스 시스템에 대한 포괄적인 분석이 필요해"
- "벡터 검색 구현을 위한 모범 사례를 찾아줘"
- "AI가 소프트웨어 엔지니어링 산업에 미치는 영향을 조사해줘"
워크플로우 개요
사용자 입력
↓
평가: 프롬프트가 너무 짧은가?
↓
예 → 개선 질문하기 → 답변 수집
↓ ↓
└───────→ 개선된 프롬프트 구성 ←──┘
↓
타임스탬프 파일에 저장
↓
deep_research.py 실행
↓
보고서 + 출처 출력
↓
사용자에게 제시
Claude가 이 스킬을 사용하는 방법
토큰 효율성 중요 사항: 심층 연구는 완료하는 데 10~20분이 걸립니다. 이 스킬은 중간 상태 확인 없이 동기식(차단)으로 실행되도록 설계되었습니다. 이 접근 방식은 대기 중 토큰 사용을 최소화합니다. Claude는 다음을 수행해야 합니다:
- 연구 시작
- 완료 대기(서브프로세스가 자동으로 차단됨)
- 완료되면 최종 결과 제공
실행 중에 주기적인 폴링이나 상태 업데이트가 필요하지 않습니다.
1단계: 연구 요청 수락
사용자의 연구 프롬프트를 받습니다. 이는 간단한 것("최신 AI 트렌드")부터 매우 상세한 것("2024-2025년에 초점을 맞춘 개발자 생산성에 대한 언어 모델의 영향")까지 다양할 수 있습니다.
2단계: 오케스트레이션 스크립트 실행
사용자의 연구 프롬프트와 함께 스킬의 메인 오케스트레이션 스크립트를 실행합니다:
python3 scripts/run_deep_research.py "여기에 연구 프롬프트를 입력하세요"
스크립트는 스킬 설치 디렉토리 내의 scripts/run_deep_research.py에 있습니다.
3단계: 스크립트 실행 흐름
스크립트는 자동으로 다음을 수행합니다:
-
프롬프트 완전성 평가: 프롬프트가 너무 짧거나 일반적인지 확인합니다(15단어 미만 또는 "무엇인가요", "방법" 등으로 시작).
-
필요한 경우 명확화 질문:
- 연구 유형에 맞는 2-3개의 집중된 질문 제시
- 키워드 기반으로 연구가 기술적인지 일반적인지 감지
- 사전 정의된 옵션(1-4) 선택 또는 사용자 정의 텍스트 입력 허용
- 질문 범위: 범위/기간, 깊이 수준, 초점 영역
-
프롬프트 개선: 원본 프롬프트와 사용자 답변을 결합하여 구조화된 연구 매개변수 생성
-
프롬프트 파일 저장: 개선된 프롬프트를
research_prompt_YYYYMMDD_HHMMSS.txt에 저장하여 재현성 확보 -
심층 연구 실행: 핵심
deep_research.py스크립트를 다음 설정으로 실행:- 모델: o4-mini-deep-research (
--model로 설정 가능) - 타임아웃: 1800초 / 30분 (
--timeout으로 설정 가능) - 도구: 웹 검색 기본 활성화
- 모델: o4-mini-deep-research (
4단계: 결과를 사용자에게 제시
스크립트는 자동으로:
- 마크다운 파일 저장: 출처가 포함된 연구 보고서가
research_report_YYYYMMDD_HHMMSS.md에 저장됩니다. - 터미널에 출력: 마크다운 형식의 완전한 연구 보고서 출력
- 웹 출처 목록: 연구에서 참조된 번호가 매겨진 URL 목록
- 완료 확인: 연구 파일이 저장된 경로
토큰 효율성 참고: 심층 연구는 10~20분이 소요됩니다. 스크립트는 중간 폴링 없이 동기식(차단)으로 실행되어 대기 중 토큰 사용을 최소화합니다.
번들 리소스
스크립트
scripts/run_deep_research.py (메인 진입점)
다음을 처리하는 오케스트레이션 스크립트:
- 프롬프트 품질 평가
- 대화형 개선 질문(기술 연구와 일반 연구를 스마트하게 구분)
- 프롬프트 저장 및 타임스탬프
- 핵심 심층 연구 실행
주요 기능:
- 스마트 개선: 프롬프트가 짧거나 일반적인 경우에만 질문
- 템플릿 기반 질문: 기술 연구와 일반 연구에 대해 다른 질문 세트
- 유연한 입력: 번호 옵션 + 사용자 정의 텍스트 입력
- 오류 처리: deep_research.py가 없을 경우 도움말 메시지 출력
사용 가능한 옵션:
python3 run_deep_research.py <프롬프트> [옵션]
--no-enhance 개선 질문 건너뛰기
--model <모델> 사용할 모델 (기본값: o4-mini-deep-research)
--timeout <초> 타임아웃 (초) (기본값: 1800)
--output-dir <경로> 프롬프트 파일을 저장할 위치
assets/deep_research.py
OpenAI Deep Research API와 인터페이스하는 핵심 스크립트. 다음을 처리합니다:
- OPENAI_API_KEY를 통한 API 인증
- 요청 생성 및 실행
- 자동 마크다운 저장: 기본적으로 타임스탬프가 포함된 보고서 파일 저장
- 출력 형식 지정 (메타데이터가 포함된 보고서 + 출처)
- 오류 처리 및 재시도
새로운 명령줄 옵션:
--output-file <경로> 사용자 정의 출력 파일 경로
--no-save 자동 마크다운 저장 비활성화
참조 자료
references/workflow.md
다음을 포함한 상세 워크플로우 문서:
- 예제가 포함된 완전한 스킬 워크플로우
- 프롬프트 개선 전략
- 연구 매개변수 설명
- Claude를 위한 통합 가이드
- 명령줄 인터페이스 참조
- 오류 처리 및 문제 해결
- 효과적인 연구를 위한 팁
주요 동작
스마트 프롬프트 개선
스킬은 개선이 필요한지 지능적으로 판단합니다:
- 개선 트리거: 15단어 미만이거나 일반적인 시작으로 시작하는 프롬프트
- 개선 건너뛰기: 상세하고 구체적인 프롬프트인 경우
- 사용자 허용:
--no-enhance플래그로 비활성화 가능 - 템플릿 인식: 기술 연구와 일반 연구에 대해 다른 질문 사용
연구 매개변수
개선된 프롬프트에는 다음이 포함됩니다:
- 전체 컨텍스트가 포함된 원래 사용자 질의
- 범위 및 기간 선호도
- 원하는 깊이 수준 (요약, 기술적, 구현, 비교)
- 특정 초점 영역 (성능, 비용, 보안 등)
이러한 매개변수는 심층 연구 모델이 보다 타겟팅되고 관련성 높은 결과를 제공하도록 돕습니다.
재현성
모든 연구 실행:
- 사용된 정확한 프롬프트를 타임스탬프 파일에 저장
- 연구 결정 추적 가능
- 동일하거나 수정된 프롬프트를 사용한 후속 연구 허용
- 연구 매개변수의 감사 추적 유지
예제
개선이 있는 간단한 프롬프트
사용자: "가장 효과적인 오픈소스 RAG 솔루션을 조사해줘"
스크립트 동작:
- 간단한 프롬프트(12단어) + 기술 키워드("오픈소스", "RAG") 감지
- 기술 연구 질문 제시:
- 기술 범위: 오픈소스만? (사용자: 예)
- 주요 지표: 성능/벤치마크? (사용자: 속도와 정확도)
- 사용 사례: 프로덕션 배포? (사용자: 여러 측면)
- 매개변수를 포함한 상세 프롬프트로 개선
- 저장 후 심층 연구 실행
- 비교 벤치마크와 출처 URL이 포함된 포괄적인 보고서 반환
개선이 없는 상세 프롬프트
사용자: "2024-2025년에 대규모 언어 모델이 소프트웨어 개발자 생산성에 미치는 영향을 분석하되, 코드 생성 도구, 페어 프로그래밍 및 생산성 지표에 초점을 맞춰줘."
스크립트 동작:
- 상세한 프롬프트(24단어)와 구체적인 범위/초점 감지
- 개선 질문 건너뛰기
- 저장 후 즉시 심층 연구 실행
- 사용자 사양에 맞춰진 집중 분석 반환
요구 사항
- Python 3.7+
- OpenAI API 키 (
OPENAI_API_KEY환경 변수 또는.env파일로 설정) - 인터넷 연결 (웹 검색용)
- 연구 완료를 위한 30분 이상 (설정 가능한 타임아웃)
토큰 효율적인 워크플로우
장기 실행 작업 최적화
심층 연구 쿼리는 일반적으로 10~20분이 소요됩니다. 이 스킬은 긴 대기 시간 동안 토큰 사용을 최소화하도록 최적화되었습니다:
작동 방식:
- 동기식 실행: 스크립트는 차단 서브프로세스로 실행됩니다 (백그라운드 폴링 없음)
- 중간 검사 없음: Claude는 상태 업데이트 없이 조용히 완료를 기다립니다
- 단일 출력: 결과는 끝에 한 번만 제공됩니다
- 자동 저장: 마크다운 파일이 자동으로 저장되며 수동 개입이 필요하지 않습니다
토큰 절약:
- 기존 방식: 30초마다 상태 확인 = 약 40회 확인 × 500토큰 = 약 20,000토큰 낭비
- 이 방식: 단일 대기 = 총 약 1,000토큰
자동 파일 관리
스킬은 자동으로 파일을 생성하고 저장합니다:
생성된 파일:
research_prompt_YYYYMMDD_HHMMSS.txt- 매개변수가 포함된 개선된 연구 프롬프트research_report_YYYYMMDD_HHMMSS.md- 다음을 포함한 완전한 마크다운 보고서:- 연구 섹션 (역사적, 인지적, 문화적 등)
- 번호가 매겨진 출처 인용
- 메타데이터 바닥글 (날짜, 모델)
사용자 정의 옵션:
# 사용자 정의 출력 위치
python3 deep_research.py --prompt-file prompt.txt --output-file my_research.md
# 자동 저장 비활성화 (터미널 출력만)
python3 deep_research.py --prompt-file prompt.txt --no-save
문제 해결
OPENAI_API_KEY 누락
오류: "Missing OPENAI_API_KEY"
해결 방법:
- 환경 변수 설정:
export OPENAI_API_KEY="your-key" - 또는 작업 디렉토리에
.env파일을 만들고OPENAI_API_KEY=your-key입력
deep_research.py를 찾을 수 없음
오류: "Could not find deep_research.py"
해결 방법:
- 스킬이 assets와 함께 올바르게 설치되었는지 확인
- 스크립트는 다음 위치에서 검색: 스킬 assets 폴더 → 현재 디렉토리 → 상위 디렉토리
연구 타임아웃
오류: 30분 후 요청 시간 초과
해결 방법:
- 타임아웃 증가:
--timeout 5400(90분) - 연구 범위를 줄이기 위해 프롬프트 단순화
- 잠재적으로 더 빠른 API 응답을 위해 비성수기에 실행