Firebase Remote Config と Antigravity Agent で AdMob 配置を実運用しながら微調整する設計

## Remote Config 自動調整の制約
 
このリポジトリの Remote Config キーのうち、`tunable.` プレフィックスを持つキー
だけが Agent による自動調整の対象です。`fixed.` プレフィックスのキーは絶対に
書き換えてはいけません。
 
- 1 回の調整で変更してよいキーは最大 2 個
- 値は元値からの相対変動率 ±15% 以内
- 適用ユーザは「audience: opt_in_experiment」（全体の 10%）に限定
- 1 日に同一キーへの変更は最大 1 回
- 直近 24 時間で Crashlytics の crash-free users が 99.0% を下回っている場合、
  自動調整は一切実行しない（人間の確認が必要）

// scripts/admob-tuning/validate-proposal.ts
import { AGENTS_GUARDRAIL } from "./guardrail";
 
type Proposal = {
  key: string;
  current_value: number;
  proposed_value: number;
  reason: string;
};
 
export function validateProposal(p: Proposal): { ok: boolean; reason?: string } {
  if (!p.key.startsWith("tunable.")) {
    return { ok: false, reason: `non-tunable key: ${p.key}` };
  }
  if (!AGENTS_GUARDRAIL.allowedKeys.includes(p.key)) {
    return { ok: false, reason: `key not in allowedKeys: ${p.key}` };
  }
  const delta = Math.abs(p.proposed_value - p.current_value) / p.current_value;
  if (delta > 0.15) {
    return { ok: false, reason: `delta ${(delta * 100).toFixed(1)}% > 15%` };
  }
  const bounds = AGENTS_GUARDRAIL.bounds[p.key];
  if (p.proposed_value < bounds.min || p.proposed_value > bounds.max) {
    return { ok: false, reason: `out of bounds: ${bounds.min}〜${bounds.max}` };
  }
  return { ok: true };
}

データの新鮮さに関する注意:
- Firebase Analytics: 直近24時間のデータは含まれない（BigQuery export の仕様）
- AdMob API: 当日のデータは午後に確定するため、直近12時間は含まれない
- Crashlytics: 概ねリアルタイム（直近1時間程度の遅延）
 
したがって、本日 02:00 時点で参照できる Analytics データは 5/19 までです。
昨日（5/20）行った Remote Config 変更の効果は、この時点ではまだ判定できません。
昨日の変更がある場合は「効果未測定」として、新たな提案を保留してください。

name: "AdMob nightly tuning"
schedule:
  cron: "0 2 * * *"
  timezone: "Asia/Tokyo"
 
variables:
  app_id: "com.dolice.wallpaper.zen"
  guardrail_path: "scripts/admob-tuning/guardrail.ts"
 
steps:
  - id: fetch_metrics
    run:
      command: "pnpm exec tsx scripts/admob-tuning/fetch.ts"
      env:
        TARGET_APP_ID: "${{ variables.app_id }}"
    timeout: 120
 
  - id: crash_gate
    run:
      command: "pnpm exec tsx scripts/admob-tuning/crash-gate.ts"
    on_failure: abort_workflow
 
  - id: agent_proposal
    agent:
      profile: "tuning-strategist"
      input_from: "fetch_metrics"
      max_iterations: 4
    timeout: 300
 
  - id: validate
    run:
      command: "pnpm exec tsx scripts/admob-tuning/validate.ts --proposal=${{ steps.agent_proposal.output_path }}"
    on_failure: skip_remaining
 
  - id: apply_remote_config
    run:
      command: "pnpm exec tsx scripts/admob-tuning/apply.ts --proposal=${{ steps.validate.output_path }}"
 
  - id: notify
    run:
      command: "pnpm exec tsx scripts/admob-tuning/notify-slack.ts --result=${{ steps.apply_remote_config.output_path }}"

# .antigravity/agents/tuning-strategist.yaml
name: "tuning-strategist"
description: "AdMob と Firebase メトリクスを読んで Remote Config の調整案を出す"
allowed_tools:
  - read_file
  - run_shell: ["pnpm exec tsx scripts/admob-tuning/fetch.ts --help"]
context_files:
  - "AGENTS.md#remote-config-自動調整の制約"
  - "scripts/admob-tuning/playbook.md"
output_schema: "scripts/admob-tuning/proposal.schema.json"
max_proposals: 2

## 判断軸の優先順位
 
1. crash-free users が 99.0% を下回っているなら、いかなる調整も提案しない
2. Day 1 リテンションが直近 7 日平均より -1.5pt を超えて低下しているなら、
   広告表示頻度を減らす方向（マイナス側の調整）のみ提案する
3. Day 1 リテンションが安定（直近 7 日平均の ±0.5pt 以内）かつ eCPM が直近 14 日
   最低値を下回っているなら、フォーマット切り替え系のキーのみ提案する
4. 上記いずれにも該当しない場合は「提案なし」を返す
 
## 禁止されている提案
 
- リワード広告の倍率を 1.5 倍より高くする
- App Open の頻度をセッションあたり 1.5 回より高くする
- Day 0 抑制フラグを false に切り替える（Day 0 はリテンション最重要日）

[AdMob nightly tuning] 2026-05-21 02:14 JST
 
📊 評価したメトリクス（5/13〜5/19）
- Day1 retention: 32.8% (-0.3pt vs 7d avg)
- Interstitial eCPM: $4.07 (-2.4% vs 14d min)
- App Open eCPM: $3.21 (-5.6% vs 14d min)
- Crash-free users: 99.62%
 
🤖 Agent 提案（2 件）
1. tunable.interstitial_frequency_cap: 4 → 3 (-25.0%)
   理由: eCPM が 14d 最低値を下回り、頻度を下げて単価を回復させたい
   → 却下: 変動幅 25% が 15% 上限を超過
 
2. tunable.app_open_min_interval_sec: 30 → 35 (+16.7%)
   理由: App Open eCPM が下落傾向。表示間隔を広げて単価を維持
   → 却下: 変動幅 16.7% が 15% 上限を超過
 
✋ 適用された変更: 0 件
 
💡 メモ: 今回は両提案ともガードレール超過で却下されました。
連続却下が 3 日続いたら、playbook.md の判断軸を見直してください。

// functions/src/rollback/significance.ts
 
/** 標準正規分布の 97.5 パーセンタイル（両側 95%） */
const Z_95 = 1.959964;
 
export type BucketCount = { events: number; quits: number };
 
/**
 * experiment バケットの rage-quit rate が fixed バケットより
 * 有意に高いか（差の 95% 信頼区間の下限 > 0 か）を判定する。
 */
export function isSignificantlyWorse(
  experiment: BucketCount,
  fixed: BucketCount,
  minSamplePerBucket = 800,
): { fire: boolean; diffPt: number; ciLowPt: number; reason: string } {
  if (experiment.events < minSamplePerBucket || fixed.events < minSamplePerBucket) {
    return { fire: false, diffPt: 0, ciLowPt: 0, reason: "sample too small" };
  }
 
  const pE = experiment.quits / experiment.events;
  const pF = fixed.quits / fixed.events;
  const diff = pE - pF;
 
  // 差の標準誤差（プールしない版：片側の悪化検出に使うため）
  const se = Math.sqrt(
    (pE * (1 - pE)) / experiment.events + (pF * (1 - pF)) / fixed.events,
  );
  const ciLow = diff - Z_95 * se;
 
  return {
    fire: ciLow > 0,
    diffPt: diff * 100,
    ciLowPt: ciLow * 100,
    reason: ciLow > 0 ? "experiment significantly worse" : "within noise",
  };
}

// functions/src/rollback/revert-key.ts
import { google } from "googleapis";
 
const RC_BASE = "https://firebaseremoteconfig.googleapis.com/v1";
 
export async function revertKey(
  projectId: string,
  key: string,
  previousValue: string,
): Promise<{ reverted: boolean; note: string }> {
  const auth = new google.auth.GoogleAuth({
    scopes: ["https://www.googleapis.com/auth/firebase.remoteconfig"],
  });
  const client = await auth.getClient();
  const token = (await client.getAccessToken()).token;
 
  // 1. 現行テンプレートと ETag を取得
  const getRes = await fetch(`${RC_BASE}/projects/${projectId}/remoteConfig`, {
    headers: { Authorization: `Bearer ${token}` },
  });
  const etag = getRes.headers.get("etag");
  const template = await getRes.json();
 
  if (!etag) {
    return { reverted: false, note: "etag missing; abort" };
  }
  if (!template.parameters?.[key]) {
    return { reverted: false, note: `key disappeared: ${key}` };
  }
 
  // 2. 対象キーだけを前の値に書き戻す（他のキーには触れない）
  template.parameters[key].defaultValue = { value: previousValue };
 
  // 3. If-Match で楽観ロック。競合したら 409 が返る
  const putRes = await fetch(`${RC_BASE}/projects/${projectId}/remoteConfig`, {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json; UTF-8",
      "If-Match": etag,
    },
    body: JSON.stringify(template),
  });
 
  if (putRes.status === 409) {
    return { reverted: false, note: "etag conflict; caller should retry" };
  }
  if (!putRes.ok) {
    return { reverted: false, note: `unexpected status ${putRes.status}` };
  }
  return { reverted: true, note: `reverted ${key} -> ${previousValue}` };
}

// scripts/admob-tuning/validate.ts
import { AGENTS_GUARDRAIL } from "./guardrail";
import { readWeeklyBaseline } from "./baseline";
 
type Proposal = {
  key: string;
  current_value: number;
  proposed_value: number;
  reason: string;
};
 
type Verdict = { ok: true } | { ok: false; reason: string };
type Baseline = Record<string, { value: number; frozenAt: string }>;
 
// 1 回の実行で受け取った提案を「まとめて」検証します。
// 一件ずつの検証では、同一キーの二重適用と週次ドリフトを見逃します。
export function validateBatch(proposals: Proposal[]): Array<{ p: Proposal } & Verdict> {
  if (proposals.length > AGENTS_GUARDRAIL.maxProposalsPerRun) {
    return proposals.map((p) => ({
      p,
      ok: false as const,
      reason: `batch size ${proposals.length} > ${AGENTS_GUARDRAIL.maxProposalsPerRun}`,
    }));
  }
 
  const baseline = readWeeklyBaseline(); // 月曜 02:00 に凍結した値
  const applied = new Set<string>();
  const out: Array<{ p: Proposal } & Verdict> = [];
 
  for (const p of proposals) {
    const v = validateOne(p, baseline, applied);
    out.push({ p, ...v });
    if (v.ok) applied.add(p.key);
  }
  return out;
}
 
function validateOne(p: Proposal, baseline: Baseline, applied: Set<string>): Verdict {
  if (!p.key.startsWith("tunable.")) {
    return { ok: false, reason: `non-tunable key: ${p.key}` };
  }
  if (!AGENTS_GUARDRAIL.allowedKeys.includes(p.key)) {
    return { ok: false, reason: `key not in allowedKeys: ${p.key}` };
  }
  if (applied.has(p.key)) {
    return { ok: false, reason: `duplicate key in same run: ${p.key}` };
  }
 
  const bounds = AGENTS_GUARDRAIL.bounds[p.key];
  if (!bounds) {
    return { ok: false, reason: `no bounds registered for ${p.key}` };
  }
  if (!Number.isFinite(p.current_value) || !Number.isFinite(p.proposed_value)) {
    return { ok: false, reason: "non-finite value" };
  }
  // 旧実装はここで 0 除算を許し、NaN > 0.15 が false になって通過していました
  if (p.current_value === 0) {
    return { ok: false, reason: "current_value is 0; relative delta undefined" };
  }
 
  // 比較は「範囲内であること」を書きます。NaN を渡されたときに false へ倒れます
  const nightly = Math.abs(p.proposed_value - p.current_value) / Math.abs(p.current_value);
  if (!(nightly <= AGENTS_GUARDRAIL.nightlyDelta)) {
    return {
      ok: false,
      reason: `nightly ${(nightly * 100).toFixed(1)}% > ${AGENTS_GUARDRAIL.nightlyDelta * 100}%`,
    };
  }
 
  const base = baseline[p.key];
  if (!base) {
    return { ok: false, reason: `no weekly baseline for ${p.key}` };
  }
  const weekly = Math.abs(p.proposed_value - base.value) / Math.abs(base.value);
  if (!(weekly <= AGENTS_GUARDRAIL.weeklyDelta)) {
    return {
      ok: false,
      reason: `weekly drift ${(weekly * 100).toFixed(1)}% from ${base.value} (frozen ${base.frozenAt})`,
    };
  }
 
  if (p.proposed_value < bounds.min || p.proposed_value > bounds.max) {
    return { ok: false, reason: `out of bounds: ${bounds.min}-${bounds.max}` };
  }
  return { ok: true };
}