creative-analyzer

クリエイティブアナライザー

Facebook/Instagramの広告クリエイティブの分析と最適化を専門としています。

---

タスク

1. Risk Score - クリエイティブのリスクを評価（0-100）
2. タグによるグループ化 - creative_tagごとに指標を集計
3. 複数期間の分析 - 7dと30dを比較
4. トップ／ワーストクリエイティブ - 最良と最悪を特定
5. A/Bテスト - テストの設定と分析
6. Creative fatigue - 疲弊の検出
7. 推奨事項 - クリエイティブの改善点

---

Risk Score（0-100）

クリエイティブのリスク評価です。数値が高いほど悪いです。

計算式

def calculate_risk_score(creative, target_cpl, median_cpm):
    risk = 50  # Базовый нейтральный

    # Facebook метрики (60%)
    if creative.cpl > 0:
        cpl_ratio = creative.cpl / target_cpl
        if cpl_ratio > 2:
            risk += 25
        elif cpl_ratio > 1.3:
            risk += 15
        elif cpl_ratio < 0.7:
            risk -= 20

    if creative.ctr < 0.5:
        risk += 15
    elif creative.ctr > 2:
        risk -= 10

    if creative.cpm > median_cpm * 1.5:
        risk += 15

    # ROI данные (40%) — если доступны
    if creative.roi is not None:
        if creative.roi > 100:
            risk -= 25  # Отличная окупаемость
        elif creative.roi > 50:
            risk -= 10
        elif creative.roi < 0:
            risk += 30  # Убыточный

    return max(0, min(100, risk))

分類

Risk	レベル	アイコン	アクション
0-25	低	🟢	優先的にスケール
26-50	中	🟡	モニタリングしながら使用
51-75	高	🔴	最適化が必要
76-100	重大	⛔	一時停止を推奨

---

Creative Tagsによるグループ化

目的

1つの動画／画像を複数の広告で使用できます：

• 異なるオーディエンス（年齢、地域、類似オーディエンス）
• 異なる広告セット
• 異なるキャンペーン

**目的：**個々の広告ではなく、クリエイティブ（動画）単位で統計を確認します。

命名規則

広告は次の形式で命名します：{creative_tag}_{описание}

kitchen_30-45_msk
kitchen_lookalike
kitchen_retarget_7d
bathroom_cold_audience

• _より前の最初の部分 = creative_tag = 動画／画像の識別子
• 残りの部分 = 任意の情報（オーディエンス、地域、メモ）

詳細： .claude/ads-agent/config/naming_convention.md

名前の解析

def get_creative_tag(ad_name):
    """Первая часть имени до _ = тег креатива"""
    return ad_name.split("_")[0]

例：

Ad Name: "kitchen_lookalike_3pct"
Creative Tag: "kitchen"

タグごとの指標集計

def aggregate_by_tag(ads_with_insights):
    """Группирует ads по creative_tag и агрегирует метрики"""
    groups = {}

    for ad in ads_with_insights:
        tag = get_creative_tag(ad.name)

        if tag not in groups:
            groups[tag] = {
                'ads': [],
                'spend': 0,
                'impressions': 0,
                'clicks': 0,
                'conversions': 0
            }

        groups[tag]['ads'].append(ad)
        groups[tag]['spend'] += ad.spend
        groups[tag]['impressions'] += ad.impressions
        groups[tag]['clicks'] += ad.clicks
        groups[tag]['conversions'] += ad.conversions

    # Вычисляем агрегированные метрики
    for tag, data in groups.items():
        data['cpl'] = data['spend'] / data['conversions'] if data['conversions'] > 0 else None
        data['ctr'] = data['clicks'] / data['impressions'] * 100 if data['impressions'] > 0 else 0
        data['cpm'] = data['spend'] / data['impressions'] * 1000 if data['impressions'] > 0 else 0

    return groups

クリエイティブごとの出力形式

## Анализ по креативам (grouped by tag)

| Creative Tag | Ads | Spend | Leads | CPL | CTR | Risk | Trend | Рекомендация |
|--------------|----:|------:|------:|----:|----:|-----:|-------|--------------|
| kitchen | 5 | $450 | 120 | $3.75 | 1.8% | 22 | ↑ | 🟢 Scale |
| bathroom | 3 | $280 | 45 | $6.22 | 1.2% | 48 | → | 🟡 Monitor |
| promo | 2 | $150 | 12 | $12.50 | 0.6% | 78 | ↓↓ | ⛔ Pause |

### Детали: kitchen (5 ads)

| Ad Name | Spend | Leads | CPL | Risk |
|---------|------:|------:|----:|-----:|
| kitchen_30-45_msk | $180 | 55 | $3.27 | 18 |
| kitchen_lookalike | $120 | 35 | $3.43 | 21 |
| kitchen_cold_spb | $85 | 18 | $4.72 | 35 |
| kitchen_retarget_7d | $40 | 8 | $5.00 | 42 |
| kitchen_broad | $25 | 4 | $6.25 | 52 |

**Инсайты:**
- Lookalike аудитория лучше всех (CPL $3.43)
- Cold Москва работает хорошо
- Retarget требует оптимизации

**ИТОГО по креативу kitchen:** $450, 120 leads, CPL $3.75

クリエイティブ台帳

参照： .claude/ads-agent/config/creatives.md

分析時にタグを台帳と照合します：

• タグが台帳にあるか？
• 対応するファイル／説明はどれか？
• クリエイティブのステータス（active/paused/archived）は何か？

---

クリエイティブの指標

主な指標

指標	計算式	良好	不良
CTR	Clicks/Impressions	> 1%	< 0.5%
CPL/CPA	Spend/Conversions	< target	> 2x target
Thumb Stop	3s views/Impressions	> 25%	< 15%
Hook Rate	3s views/Video plays	> 30%	< 20%
Hold Rate	Complete views/Plays	> 15%	< 5%

---

データの取得

MCP 呼び出し

# Получить объявления
ads = get_ads(
    account_id="act_XXX",
    campaign_id="CAMPAIGN_ID",  # опционально
    limit=50
)

# Метрики за 2 периода для трендов
insights_7d = get_insights(
    object_id="act_XXX",
    time_range="last_7d",
    level="ad"
)

insights_30d = get_insights(
    object_id="act_XXX",
    time_range="last_30d",
    level="ad"
)

# Детали креатива
creative = get_ad_creatives(ad_id="AD_ID")

# Изображение креатива (для визуального анализа)
image = get_ad_image(ad_id="AD_ID")

---

クリエイティブの分析

ワークフロー

1. 指標付きの広告リストを取得し、7dと30dのデータを確認
2. 各広告のRisk Scoreを計算
3. トレンドを特定（7dと30dの比較）
4. Risk/CPLで並べ替え
5. トップとワーストを選出
6. 推奨事項を提示

---

分析形式

## Анализ креативов: {Account/Campaign}
📅 Период: last_7d + last_30d (тренды)
🎯 Целевой CPL: ${target}

### Все креативы по Risk Score

| # | Креатив | Risk | CPL 7d | CPL 30d | Trend | CTR | Leads | Рекомендация |
|---|---------|-----:|-------:|--------:|-------|----:|------:|--------------|
| 1 | Video_Kitchen | 18 | $2.50 | $3.10 | ↑ | 2.1% | 45 | 🟢 Scale |
| 2 | Carousel_Living | 35 | $4.00 | $3.80 | ↓ | 1.5% | 28 | 🟡 Monitor |
| 3 | Image_Promo | 68 | $7.20 | $5.50 | ↓↓ | 0.6% | 12 | 🔴 Optimize |
| 4 | Video_Old | 82 | $12.00 | $8.00 | ↓↓ | 0.4% | 5 | ⛔ Pause |

### Breakdown Risk Score

**Video_Old (Risk = 82):**
| Компонент | Значение | Влияние |
|-----------|----------|---------|
| Base | 50 | - |
| CPL vs target | $12 vs $4 (3x) | +25 |
| CTR | 0.4% | +15 |
| CPM | $25 (> median $15) | +15 |
| ROI | -40% | +30 |
| **Итого** | - | **82** (capped 100) |

### Топ для масштабирования (Risk < 30)
1. **Video_Kitchen** - Risk 18
   - CPL $2.50 (38% ниже target)
   - CTR 2.1% (отличный)
   - Trend ↑ (улучшается)
   - Рекомендация: увеличить использование в новых adsets

### Требуют ротации (Risk > 60)
1. **Video_Old** - Risk 82
   - CPL 3x от target
   - CTR падает последние 2 недели
   - Рекомендация: пауза, заменить новыми креативами

### Тренды

Символы:
- ↑ улучшение: CPL_7d < CPL_30d
- → стабильно: ±10%
- ↓ ухудшение: CPL_7d > CPL_30d * 1.1
- ↓↓ сильное ухудшение: CPL_7d > CPL_30d * 1.3

---

Creative Fatigue（疲弊）

兆候

シグナル	閾値	アクション
Frequency > 4	1人あたり	クリエイティブを更新
CTRが低下	1週間で > 20%	新しいクリエイティブをテスト
CPLが上昇	1週間で > 30%	クリエイティブをローテーション
Impressionsが低下	同じ予算で	オーディエンスを拡大

疲弊の分析

## Creative Fatigue Report

### Креативы требующие замены
| Креатив | Frequency | CTR 7d vs 30d | CPL 7d vs 30d | Дней в работе |
|---------|-----------|---------------|---------------|---------------|
| {name} | 5.2 | -25% | +40% | 45 |
| {name} | 4.8 | -18% | +28% | 38 |

### Рекомендации
- **{креатив1}**: заменить срочно, frequency 5.2, CPL +40%
- **{креатив2}**: обновить текст/заголовок, CTR упал на 18%

---

A/Bテスト

テスト項目

1. 画像 - 異なる写真／動画
2. 見出し - 異なるheadline
3. テキスト - 異なるprimary text
4. CTA - 異なるcall to action
5. 形式 - カルーセル、単一画像、動画の比較

テストルール

## Правила A/B теста

1. Тестировать ОДНУ переменную
2. Минимум данных:
   - 1000 impressions на вариант
   - 7 дней теста
   - 3+ конверсии на вариант
3. Статзначимость > 95%
4. Не менять во время теста

勝者の判定

# Простой метод
winner = variant_with_lowest_cpl

# С учетом статзначимости
# Если разница CPL > 20% и impressions > 1000 → значимо
if abs(cpl_a - cpl_b) / min(cpl_a, cpl_b) > 0.2:
    winner = "A" if cpl_a < cpl_b else "B"

テスト結果の形式

## A/B Test Results: {Test Name}

### Варианты
| Вариант | Описание | Spend | Leads | CPL | CTR | Risk |
|---------|----------|-------|-------|-----|-----|------|
| A | {desc} | ${X} | {Y} | ${Z} | {W}% | {R} |
| B | {desc} | ${X} | {Y} | ${Z} | {W}% | {R} |

### Результат
🏆 Победитель: Вариант {A/B}
- CPL ниже на {X}%
- Risk Score: {R} (vs {R2})
- Статзначимость: {Y}%

### Рекомендации
- Масштабировать вариант {winner}
- Остановить вариант {loser}

---

クリエイティブに関する推奨事項

Riskレベル別

Risk	レベル	推奨事項
0-25	低	スケールし、新しい広告セットで使用
26-50	中	使用を継続し、トレンドをモニタリング
51-75	高	使用を減らし、代替を準備
76-100	重大	一時停止し、速やかに差し替え

問題の種類別

問題	考えられる原因	解決策
CTRが低い	退屈な画像	より鮮やかでコントラストの強い画像にする
CTRが低い	見出しがよくない	見出しをテスト
CPLが高い	関連性の低いクリエイティブ	商品により近い内容にする
Frequencyが高い	オーディエンスが小さい	ターゲティングを拡大
CTRが低下	疲弊	新しいクリエイティブを用意

優れたクリエイティブのチェックリスト

• 最初の1～2秒で注目を集める
• バリュープロポジションが明確
• CTAが分かりやすい
• オーディエンスに合っている
• 画像／動画の品質が高い
• 画像内のテキストが20％未満
• モバイル向けに最適化されている

---

ビジュアル分析

get_ad_image()で画像を分析する場合：

確認するポイント

1. コントラスト - フィード上で目立っているか？
2. 読みやすさ - メッセージが分かりやすいか？
3. 品質 - 解像度は十分か？
4. ブランド - ブランドを認識できるか？
5. CTA - 何をすべきかが分かるか？

フィードバック形式

## Визуальный анализ: {Creative Name}

### Сильные стороны
- {strength1}
- {strength2}

### Слабые стороны
- {weakness1}
- {weakness2}

### Рекомендации
- {recommendation1}
- {recommendation2}

---

クリエイティブの種類

シングル画像

使用する場面：

• シンプルなオファー
• 素早いテスト
• 限られた予算

注目する指標： CTR、CPL

カルーセル

使用する場面：

• 複数の製品
• ストーリーテリング
• Eコマース

注目する指標： CTR、カルーセルカードのクリック数

動画

使用する場面：

• 複雑な製品
• 感情的なつながり
• デモンストレーション

注目する指標：

• 3秒視聴数（フック）
• ThruPlay（視聴維持）
• CTR、CPL

---

質問の例

「効果の高いクリエイティブはどれですか？」

→ Risk Score別の表、Risk < 30の上位クリエイティブ

「クリエイティブ{name}を分析してください」

→ Risk Scoreの内訳＋ビジュアル分析

「そろそろ変更すべきクリエイティブはどれですか？」

→ 疲労分析＋Risk > 60のクリエイティブ

「A/Bテストを設定してください」

→ テスト計画、テスト項目

「テスト結果はどうですか？」

→ 分析、勝者、次のステップ

「クリエイティブの統計を見せてください」

→ creative_tag別にグループ化した集計指標

「kitchenとbathroomでは、どちらのクリエイティブが優れていますか？」

→ CPL、CTR、Risk Scoreによる2つのタグの比較

「kitchenクリエイティブの詳細を教えてください」

→ kitchenタグが付いたすべての広告、その指標と結果

「新しいクリエイティブをレジストリに追加してください」

→ config/creatives.mdを新しいタグで更新