Data Collector

데이터 수집 → 분석 → 트렌드 리서치 보고서

관심 분야의 데이터를 자동 수집하고, 분석하여 과거 → 현재 → 미래 예측 구조의 트렌드 리서치 보고서를 생성한다.

사용자 확인 → Domain 감지 → 데이터 수집 → 분석 → .md 보고서 생성 → viewer 제공

아키텍처: 컨테이너 환경 대응

이 스킬은 컨테이너 기반 Desktop 환경에서 실행된다. 컨테이너 내부에서는 외부 네트워크 접근이 제한될 수 있으므로, 모드별로 수집 전략이 다르다.

모드 1: 즉시 실행 (기본) — Claude 내장 도구 사용

• 데이터 수집: Claude의 web_search, WebFetch 도구를 직접 사용하여 수집한다.
• Python 스크립트의 requests/feedparser 등 HTTP 라이브러리를 절대 사용하지 않는다.
• 수집된 데이터를 JSON 파일로 저장한 뒤, Python analyzer.py로 분석하고, report_generator.py로 보고서를 생성한다.
• Python은 로컬 파일 처리(분석, 보고서 생성)에만 사용한다.

[Claude web_search / WebFetch] → 데이터 수집 (Claude가 네트워크 접근)
        ↓ JSON으로 저장
[Python analyzer.py]           → 분석 (로컬 파일 처리, 네트워크 불필요)
        ↓
[Python report_generator.py]   → .md 보고서 생성 (로컬 파일 처리)
        ↓
[present_files]                → viewer 제공 + 다운로드

모드 2: 자동화 시스템 구축 (요청 시) — 독립 실행 코드 생성

• 사용자 환경(로컬 PC, GitHub Actions)에서 실행될 독립적인 Python 스크립트를 생성한다.
• 이 코드는 컨테이너 밖에서 실행되므로 requests, feedparser 등 HTTP 라이브러리를 자유롭게 사용한다.
• automation_builder.py가 zip 패키지를 생성한다.

[automation_builder.py] → 독립 실행 가능한 Python + GitHub Actions 코드 zip 생성
                          (사용자 PC / GitHub Actions에서 실행 → 네트워크 자유)

중요: scripts/collector.py는 모드2 자동화 패키지의 레퍼런스 코드이다. 모드1에서는 절대 실행하지 않는다.

핵심 동작 방식

모드 1: 즉시 실행 (기본)

사용자가 키워드를 던지면 그 자리에서 수집 → 분석 → .md 보고서 생성 → viewer 제공.

• 예: "요즘 화장품 트렌드 검색해줘" → 바로 보고서 생성
• 수집은 반드시 Claude의 web_search / WebFetch 도구를 사용한다.

모드 2: 자동화 시스템 구축 (요청 시)

사용자가 "이걸 자동화하고 싶어", "매일 돌리게 해줘" 같은 요청을 하면:

• Python 수집/분석 스크립트 (독립 실행 가능, requests/feedparser 사용)
• GitHub Actions workflow yaml
• config.yaml 템플릿
• README.md (설치/실행 가이드) 를 zip으로 묶어서 제공.

절대 규칙

코드 생성, 파일 생성, 스크립트 실행 전에 반드시 아래 확인을 완료하라.

1. 사용자의 분야/키워드를 반드시 확인한다.
   • $ARGUMENTS가 있으면 그것을 사용.
   • 없으면 반드시 질문한다.
2. 사용자가 "알아서 해줘"라고 해도, 최소한 키워드 1개는 반드시 확인한다.
3. config.yaml 내 API 키가 비어있는 소스는 절대 호출하지 않는다.
4. 웹 스크래핑 시 robots.txt를 반드시 확인하고, 공개 데이터만 수집한다.
5. 부동산/금융 보고서에서 "매수/매도 추천" 같은 투자 조언은 절대 하지 않는다.
   • 대신 "현재 시장 신호", "데이터가 보여주는 것" 중심으로 작성한다.
6. 모드1에서 Python으로 HTTP 요청(requests, feedparser, urllib 등)을 절대 실행하지 않는다.
   • 데이터 수집은 반드시 Claude 내장 도구(web_search, WebFetch)를 사용한다.
   • Python은 수집된 데이터의 분석과 보고서 생성에만 사용한다.

Step 1: 사용자 확인 (반드시 먼저 실행)

스킬 호출 즉시 아래를 확인한다. $ARGUMENTS가 있으면 해당 항목은 건너뛴다.

질문 목록 (한 번의 메시지로 모두 질문):

1. 키워드/분야 — "어떤 분야의 트렌드를 분석할까요? (예: 화장품, 반도체, AI Agent, 부동산, 인디게임)"
2. 깊이 — "간단 요약 vs 심층 분석 중 어떤 걸 원하세요?" (기본: 심층 분석)
3. 추가 관심사 — "특별히 더 알고 싶은 세부 주제가 있나요? (예: 특정 브랜드, 특정 지역, 특정 기술)"

Step 2: Domain 감지 + Config 로드

1. 사용자 키워드로 가장 적합한 domain profile을 자동 매칭한다.
   • 매칭 로직: 키워드 → domain_profiles/*.yaml의 keywords 필드와 비교
   • 매칭 안 되면 "general" 모드로 동작 (웹검색 중심)
2. config.yaml을 로드하여 사용 가능한 API 키를 확인한다.
3. API 키가 있는 소스만 sources 목록에 포함한다.
   • 키가 하나도 없어도 무료 소스(RSS, 웹검색)만으로 동작해야 한다.

Domain Profile 위치: 이 스킬 디렉토리의 domain_profiles/ 폴더

Step 3: 데이터 수집 (Claude 내장 도구 사용)

반드시 Claude의 web_search / WebFetch 도구로 수집한다. Python HTTP 라이브러리 사용 금지.

수집 순서:

1. domain profile의 sources.free 목록을 읽는다.

2. web_search 소스 수집:

   • domain profile의 sources.free 중 type: web_search인 항목의 query_template에서 {keyword}를 실제 키워드로 치환한다.
   • Claude의 web_search 도구로 검색하고 결과를 수집한다.
   • 키워드 확장(keyword_expansion 규칙)에 따라 연관 키워드로도 추가 검색한다.

3. RSS 소스 수집:

   • domain profile의 sources.free 중 type: rss인 항목의 URL을 WebFetch 도구로 가져온다.
   • WebFetch가 RSS XML을 가져오면, Claude가 직접 파싱하거나, 내용을 JSON으로 정리한다.

4. 유료 API 소스 (config에 API 키가 있는 경우만):

   • config.yaml의 api_keys에 값이 있는 소스만 호출한다.
   • Bash(curl ...) 명령으로 API를 호출한다. (Python requests 사용 금지)
   • 예: curl -s "https://newsapi.org/v2/everything?q=keyword&apiKey=KEY"

5. 수집 결과 저장:

   • 수집된 모든 데이터를 아래 JSON 형식으로 /mnt/user-data/outputs/collected_data.json에 저장한다.

[
  {
    "source": "소스명",
    "status": "success",
    "data": [
      {
        "title": "기사/글 제목",
        "link": "URL",
        "summary": "요약 또는 본문 일부",
        "published": "YYYY-MM-DD",
        "source_type": "web_search | rss | api"
      }
    ]
  }
]

에러 핸들링:

• 각 소스는 독립적으로 수집. 하나가 실패해도 나머지는 계속 수집.
• web_search/WebFetch 실패 시 해당 소스를 skip하고 다음 소스로 진행.
• 수집 결과가 3건 미만이면 보고서에 "데이터 불충분 - 키워드를 조정해보세요" 안내 포함.
• 보고서 말미에 "제외된 소스: [소스명] (사유: 연결 실패 / 키 미설정)" 명시.

Step 4: 분석 (Python 로컬 실행)

Step 3에서 저장한 collected_data.json을 Python analyzer.py로 분석한다.

python analyzer.py /mnt/user-data/outputs/collected_data.json [keyword]

분석 결과는 analysis_result.json으로 저장된다.

공통 분석 항목:

• 키워드 빈도 분석: 수집된 데이터에서 가장 많이 언급된 키워드/엔티티 추출
• 시점별 분류: 과거(6개월1년), 현재(최근 13개월), 미래(전망)
• 센티먼트 판단: 긍정/부정/중립 논조 비율
• 이상 신호 탐지: 급격한 변화, 이례적 패턴

분야별 추가 분석은 각 domain profile의 framework를 따른다.

Step 5: 보고서 생성 (Python 로컬 실행)

분석 결과 JSON과 수집 데이터 JSON을 기반으로 보고서를 생성한다.

python report_generator.py /mnt/user-data/outputs/collected_data.json /mnt/user-data/outputs/analysis_result.json [keyword] [domain]

반드시 아래 템플릿 구조를 따른다. (templates/report_template.md 참조)

보고서 구조:

# [키워드] 트렌드 리서치 보고서
> 생성일 / 분석 키워드 / 데이터 소스 / 제외된 소스

## 핵심 요약 (Executive Summary)
## 1. 과거 동향 (Past Trends) — 최근 6개월~1년
## 2. 현재 트렌드 (Current Trends) — 최근 1~3개월
## 3. 향후 전망 (Future Outlook) — 향후 3~6개월
## 4. 분야별 심화 분석 — domain profile 기반 동적 생성
## 참고 자료 및 출처
## 분석 메타데이터

보고서 저장 및 제공:

1. /mnt/user-data/outputs/ 에 {keyword}_trend_report_{YYYYMMDD}.md 형태로 저장
2. present_files 도구로 viewer 제공 + 다운로드 가능하게
3. config.yaml에 output_dir이 설정되어 있으면 해당 경로에도 추가 저장

Step 6: (모드2) 자동화 코드 생성 — 사용자 요청 시에만

사용자가 "자동화", "매일 돌려줘", "파이프라인 만들어줘", "GitHub Actions" 등을 언급하면 실행.

이 모드에서 생성되는 코드는 사용자 환경(로컬 PC, GitHub Actions)에서 실행되므로 requests, feedparser 등 HTTP 라이브러리를 자유롭게 사용한다.

automation_builder.py를 사용하여 zip 패키지를 생성한다. 또는 Claude가 직접 파일을 생성하는 경우에도 아래 명세를 반드시 준수한다.

6.1 필수 생성 파일 목록

zip 패키지(data_pipeline/)에는 아래 9개 파일이 반드시 모두 포함되어야 한다. 하나라도 빠지면 독자/사용자 환경에서 정상 동작하지 않는다.

⚠️ .github/workflows/daily_collect.yml이 누락되면 GitHub에 push해도 자동 실행이 되지 않는다. zip 생성 후 반드시 이 파일이 포함되었는지 확인한다.

6.2 daily_collect.yml 필수 내용

templates/github_actions_template.yml을 참조하되, 아래 요소가 반드시 포함되어야 한다:

on:
  schedule:
    - cron: '0 0 * * *'   # UTC 0시 = KST 9시. 반드시 UTC 기준으로 작성.
  workflow_dispatch:        # 수동 실행 버튼. 반드시 포함.

# ...

    - name: Run data collection pipeline
      env:
        NEWSAPI_KEY: ${{ secrets.NEWSAPI_KEY }}
        SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
      run: python run_pipeline.py    # 엔트리포인트는 반드시 run_pipeline.py

    - name: Upload report artifact
      uses: actions/upload-artifact@v4
      with:
        name: trend-report-${{ github.run_number }}
        path: reports/*.md
        retention-days: 30

6.3 slack_notifier.py 필수 패턴

Slack Webhook URL은 환경변수를 우선 읽고, 없으면 config.yaml에서 폴백한다. 이 패턴을 지키지 않으면 GitHub Actions에서 Secrets → 환경변수로 주입된 URL을 읽지 못한다.

import os

# 필수 패턴: 환경변수 우선, config.yaml 폴백
webhook_url = os.environ.get("SLACK_WEBHOOK_URL") or slack_config.get("webhook_url", "")

6.4 config.yaml 보안 규칙

• slack.webhook_url은 반드시 빈 문자열("")로 생성한다.
• 사용자의 실제 Webhook URL을 config.yaml에 하드코딩하면 GitHub push 시 URL이 노출되는 보안 사고가 발생한다.
• 주석으로 반드시 아래 안내를 포함한다:

  webhook_url: ""  # GitHub Secrets 또는 환경변수로 주입. 여기에 직접 URL을 넣지 마세요.
  

6.5 zip 생성 및 제공

1. automation_builder.py를 호출하거나, 직접 파일을 생성한다.
2. data_pipeline/ 디렉토리를 zip으로 압축한다.
3. /mnt/user-data/outputs/에 저장한다.
4. present_files 도구로 viewer 제공 + 다운로드 가능하게 한다.
5. zip 생성 후 검증: .github/workflows/daily_collect.yml이 zip에 포함되어 있는지 확인한다.

기존 스킬과의 관계

• content-research: 콘텐츠 아이디어/주제 추천에 특화. data-collector는 "시장 분석", "트렌드 리서치", "데이터 기반 보고서" 요청에 트리거.
• content-repurpose: 이미 만들어진 콘텐츠를 다른 플랫폼용으로 변환. 역할이 완전히 다르므로 충돌 없음.
• doc-automation: PPT/이메일 자동 생성. data-collector의 보고서 결과를 doc-automation으로 넘겨 PPT로 만드는 워크플로는 가능하지만, 별도 요청 시에만.