x-research

X/Twitter リサーチ

追跡対象アカウントの高パフォーマンスなツイートを調査し、外れ値を特定します。必要に応じて、動画コンテンツのフックや構成も分析します。

前提条件

• APIFY_TOKEN 環境変数、または .env 内の設定
• GEMINI_API_KEY 環境変数、または .env 内の設定（動画分析用）
• Python パッケージ apify-client と google-genai
• .claude/context/x-accounts.md でアカウントを設定済み

セットアップを確認します：

python3 -c "
import os
try:
    from dotenv import load_dotenv
    load_dotenv()
except ImportError:
    pass
from apify_client import ApifyClient
assert os.environ.get('APIFY_TOKEN'), 'APIFY_TOKEN not set'
" && echo "Prerequisites OK"

ワークフロー

1. 実行フォルダーを作成する

RUN_FOLDER="x-research/$(date +%Y-%m-%d_%H%M%S)" && mkdir -p "$RUN_FOLDER" && echo "$RUN_FOLDER"

2. ツイートを取得する

python3 .claude/skills/x-research/scripts/fetch_tweets.py \
  --days 30 \
  --max-items 100 \
  --output {RUN_FOLDER}/raw.json

パラメーター：

• --days：検索対象の日数（デフォルト：30）
• --max-items：アカウントごとのツイート最大数（デフォルト：100）
• --handles：特定のハンドルを指定してアカウントファイルを上書き

API 制限： クエリごとに最低 50 件のツイートが必要です。実行の間隔を数分空けてください。

3. 外れ値を特定する

python3 .claude/skills/x-research/scripts/analyze_posts.py \
  --input {RUN_FOLDER}/raw.json \
  --output {RUN_FOLDER}/outliers.json \
  --threshold 2.0

出力 JSON には以下が含まれます：

• total_posts：分析したツイート数
• outlier_count：見つかった外れ値の数
• topics：上位のハッシュタグ、メンション、キーワード
• content_patterns：パフォーマンスの高い形式の分析
• accounts：分析したアカウントの一覧
• outliers：エンゲージメント指標を含む外れ値ツイートの配列

4. AI で動画を分析する（任意）

外れ値に動画コンテンツが含まれる場合：

python3 .claude/skills/video-content-analyzer/scripts/analyze_videos.py \
  --input {RUN_FOLDER}/outliers.json \
  --output {RUN_FOLDER}/video-analysis.json \
  --platform x \
  --max-videos 5

注：X/Twitter は主にテキストベースです。動画分析は任意であり、外れ値に動画投稿が含まれる場合にのみ有用です。

5. レポートを生成する

{RUN_FOLDER}/outliers.json（および任意で {RUN_FOLDER}/video-analysis.json）を読み込み、{RUN_FOLDER}/report.md を生成します。

レポートの構成：

# X/Twitter Research Report

Generated: {date}

## Summary

- **Total tweets analyzed**: {total_posts}
- **Outlier tweets identified**: {outlier_count}
- **Outlier rate**: {percentage}%

## Top Performing Tweets (Outliers)

### 1. @{username} ({name})

> {tweet_text}

- **URL**: {url}
- **Date**: {created_at}
- **Engagement**: {likes} likes | {retweets} RTs | {replies} replies | {bookmarks} bookmarks
- **Engagement Score**: {score}
- **Engagement Rate**: {rate}%
- **Followers**: {followers}

[Repeat for top 15 outliers]

## Top Performing Hooks (if video analysis available)

### Hook 1: {technique} - @{username}
- **Opening**: "{opening_line}"
- **Why it works**: {attention_grab}
- **Replicable Formula**: {replicable_formula}
- [Watch Video]({url})

## Trending Topics

### Top Hashtags
[From outliers.json topics.hashtags]

### Top Keywords
[From outliers.json topics.keywords]

### Top Mentions
[From outliers.json topics.mentions]

## Content Patterns in Outliers

| Pattern | Count | Percentage |
|---------|-------|------------|
| Contains media | {count} | {pct}% |
| Contains external link | {count} | {pct}% |
| Thread format | {count} | {pct}% |
| Quote tweet | {count} | {pct}% |
| Asks a question | {count} | {pct}% |
| List/numbered format | {count} | {pct}% |
| Short (<100 chars) | {count} | {pct}% |
| Medium (100-200 chars) | {count} | {pct}% |
| Long (>200 chars) | {count} | {pct}% |

## Actionable Takeaways

[Synthesize patterns into 4-6 specific recommendations]

## Accounts Analyzed

[List accounts]

実行可能なインサイトに重点を置きます。X/Twitter のリサーチでは、コンテンツの傾向とトレンドのトピックが重要です。

クイックリファレンス

パイプライン全体：

RUN_FOLDER="x-research/$(date +%Y-%m-%d_%H%M%S)" && mkdir -p "$RUN_FOLDER" && \
python3 .claude/skills/x-research/scripts/fetch_tweets.py -o "$RUN_FOLDER/raw.json" && \
python3 .claude/skills/x-research/scripts/analyze_posts.py -i "$RUN_FOLDER/raw.json" -o "$RUN_FOLDER/outliers.json"

動画分析あり（任意）：

python3 .claude/skills/video-content-analyzer/scripts/analyze_videos.py -i "$RUN_FOLDER/outliers.json" -o "$RUN_FOLDER/video-analysis.json" -p x

続いて JSON ファイルを読み込み、レポートを生成します。

エンゲージメント指標

エンゲージメントスコア（加重）：

• ブックマーク：4 倍（最も重要な指標。後で参照するために保存）
• 返信：3 倍（積極的な会話）
• リツイート：2 倍（拡散）
• 引用：2 倍（コメントを伴うエンゲージメント）
• いいね：1 倍（受動的な賛同）

外れ値の検出： エンゲージメント率が平均 +（しきい値 x 標準偏差）を超えるツイート

エンゲージメント率：（スコア / フォロワー数）x 100

出力先

すべての出力は、タイムスタンプ付きの実行フォルダーに保存されます：

x-research/
└── {YYYY-MM-DD_HHMMSS}/
    ├── raw.json            # Raw tweet data from Apify
    ├── outliers.json       # Outliers with metadata and topics
    ├── video-analysis.json # AI video analysis (optional)
    └── report.md           # Final report