davepartner/email-automation

Email Automation — 管理パネル構築スキル

ユーザーの既存管理パネル内に、ワールドクラスのメールオートメーションシステムを構築します。ユーザーの行動を監視し、適切なライフサイクルシーケンスに登録し、アプリ自体が設定済みのメール接続を介して、パーソナルで1通ずつのリマインダーメールを、実績のあるファネルタイミングに基づいて送信します。一括送信ではありません。

目標: スパムを送らず、既存の動作を壊さずに、ユーザーの再来訪、購入、継続率を向上させること。

最初に読んでください: このスキルは非破壊的に設計されています。アプリを調査してから変更を加え、新しいテーブル/ルートのみを追加し（既存のフローを書き換えません）、アプリのメール接続を再利用し、一時停止状態で出荷します。管理者が明示的に有効化するまで、何も送信されません。

---

ワークフロー

0. 調査 ─▶ 1. 設計 ─▶ 2. 構築 ─▶ 3. イベント配線 ─▶ 4. 管理UI ─▶ 5. 検証 ─▶ 6. 引き渡し
   アプリと管理パネル   データモデル   新しいテーブル/   トリガー→登録   ダッシュボード+   ドライラン+     一時停止+
   の調査   +シーケンス  ワーカー/ cron                  テーブル+統計  プレビュー     "有効化しますか？"

0. 調査（必須。コード作成前に行う）

アプリを徹底的に調査し、簡潔な統合計画を作成します。references/discovery.mdを参照。

• スタック、フレームワーク、ORM/DB、認証、セッション、管理パネルを特定します（存在しない場合はその旨を記録）。
• 既存のメール接続（SMTP/プロバイダSDK）を見つけ、それを再利用します。二つ目の接続は追加しません。
• 商品、カート/チェックアウト、注文、ユーザー、および必要なイベントをマッピングします。
• プラットフォームの目的とビジネスモデル（Eコマース、SaaS、フィンテック、予約など）、そのアクティベーションイベント、重要なアカウント手順を理解し、それに適合する追加のリマインダーシーケンス（メール確認、プロフィール完了、オンボーディング、KYC、トライアル/請求、予約、更新など）を提案します。
• 管理パネルがない場合、最小限の管理パネルを作成するかどうかをユーザーに尋ねます。

1. 設計

• データモデルを定義します（examples/data-model.md）: シーケンス、ステップ、登録、スケジュール済みメール、送信ログ、設定、抑制リスト。
• シーケンスセットとタイミングを選択します（references/sequences.md）。

2. 構築（追加のみ）

• 新しいテーブル/コレクション、スケジューラジョブ、送信ワーカーを追加します。既存のテーブルは変更しないでください。
• フィーチャーフラグ/マスタ一時停止スイッチ（デフォルトOFF）とグローバルキルスイッチを追加します。

3. イベントの配線

• アプリの既存イベント（登録、ログイン、カート追加、チェックアウト開始、購入、非アクティブ）を登録にフックします。それらの動作は変更せず、監視するだけで介入しません。

4. 管理UI

• トップレベルの**「メールオートメーション」**メニューを追加し、タブを設けます: シーケンス · 受信者 · 統計 · 設定。references/admin-ui.mdを参照。
• 商品ページとチェックアウトページの下部に、管理者専用の購入/放棄テーブルを追加します。

5. 検証

• ドライランモード、プレビュー/テスト送信ツール、冪等性チェック、停止条件監査。

6. 引き渡し

• システムは一時停止状態で出荷されます。管理者に通知し、ワンクリックで「有効化」できるようにする（またはエージェントが支援する）、ロールバック手順を文書化します。

---

シーケンスカタログ（実績のあるファネルタイミング）

詳細、コピーの意図、停止条件は references/sequences.md を参照。概要:

#	シーケンス	トリガー	タイミング（デフォルト）	停止条件
1	ウェルカム / アクティベート	登録	0h ウェルカム → 24h 価値 → 72h 社会的証明	ログイン / 購入
2	登録したがログインなし	登録 + ログインなし	1h → 24h → 72h	ログイン
3	ログインしたが購入/利用なし	ログイン、非アクティブ	1h ナッジ → 24h → 5d	購入 / アクティベーション
4	放棄カート / チェックアウト / 商品	商品閲覧またはチェックアウト開始、購入なし	1h リマインダー（割引なし）→ 24h 社会的証明/反論 → 48–72h 緊急性+割引	購入
5	購入後レビュー	購入（商品タイプを認識）	翌日「調子はどうですか？」→ 2週間後「体験+アップセル」	レビュー / 購読解除
6	アップセル / クロスセル	購入、他の商品が存在する	バリューモーメント後（3–7日）	プロモートされたアイテムの購入
7	再エンゲージメント / 呼び戻し	30 / 60 / 90日非アクティブ	ニュートラル → 価値 → 最終「停止します」	アクティビティ / 購読解除
8	補充	消耗品	約45–60日	再購入

割引: アップセルには割引が付く場合があります。放棄カートには緊急性+割引が付きます。デフォルトは0% — 0の場合、メールで割引に一切言及してはいけません。最小カートガードにより、非常に低価値のカートではインセンティブをスキップします（references/sequences.md）。

優先順位: ユーザーは最大1つのプロモーションシーケンスに所属します — 購入 > カート > 閲覧 > ウェルカム > ログインなし > 非アクティブ > 呼び戻し。追加シーケンス: 閲覧放棄、再入荷、値下げ、督促、紹介。references/sequences.mdを参照。

さらに、プラットフォームの目的から導き出されたシーケンス — 例: メール確認、プロフィール完了、オンボーディングセットアップ、KYC、請求/トライアル終了、予約リマインダー、更新。プラットフォームが検出および対応できるもののみ追加します（references/sequences.md）。

---

譲れないルール

1. 構築前に調査すること。 既存の認証、カート、チェックアウト、注文、ユーザーフローを変更しないでください。新しいテーブル/ルートのみを追加します。
2. 既存のメール接続を再利用すること。 2つ目のSMTP/プロバイダ設定は不要。大量/一括送信は行わず、メールはユーザー単位かつイベント駆動で送信されます。
3. 一時停止状態で出荷すること。 マスタースイッチOFF。管理者は有効化するように通知されます（エージェントが支援することも可能）。
4. スパム禁止。 頻度制限（デフォルト ≤1通のマーケティングメール/ユーザー/24時間、≤4通/週）、静音時間、グローバル抑制リスト（購読解除、バウンス、苦情）を設けます。同意と興味を尊重します。
5. 停止条件が常に優先されること。 送信前に毎回目標（購入/ログイン/アクティベーション）を再確認し、購入者がカートリマインダーを受け取らないようにします。
6. パーソナルで1対1のコピーであること。 「差出人」は実在の人物（ブランド名の名前）、個人的な言葉遣いで、実際の商品に言及し、1つの明確なCTA、メールごとに**「管理者に連絡」リンク**を含めます。
7. 配信性+法的要件。 SPF/DKIM/DMARC、ブランド送信ドメイン、HTML+プレーンテキスト、購読解除+住所、スパムトリガーワードなし。references/sending-and-compliance.mdを参照。
8. すべてが監査可能であること。 すべての送信が記録され（誰が、どのシーケンス/ステップを、いつ、なぜ）、すべてのスケジュール済みメールが管理者から見えること。
9. 美しさ+シームレスさ。 アプリのデザイントークンに合わせて、管理セクションがネイティブに見えるようにします。reviews-to-featuresスタイルの厳密さ: 明確な階層、44pxターゲット、アクセシブルなコントラスト。
10. メール本文用の無料WYSIWYGエディタ。 管理者は各メールテンプレートを無料のセルフホスト型WYSIWYGエディタ（TinyMCE Community、またはQuill / TipTap / Summernote / GrapesJS）で編集します。出力はメールセーフ（インラインCSS、テーブル、約600px、JSなし）で、サニタイズされ、マージトークン、条件付き割引ブロック、自動生成されたプレーンテキストの双子を含む必要があります。

---

非破壊契約（強制）

「非破壊的」であることは検証され、想定されるものではありません。完全なチェックリスト: references/non-disruption.md。最低限:

• マイグレーション前にデータベースをバックアップ。マイグレーションは追加+リバーシブル（既存テーブルを変更しない）。
• フックは監視専用であり、try/catchでラップされている — 失敗したオブザーバーが登録/ログイン/チェックアウト/支払いを壊すことは決してない。
• 一時停止状態で出荷し、グローバルキルスイッチを備え、既存のメール接続を再利用する。
• インストール後に5つのコアフローすべてをスモークテストし、ロールバック訓練を実行する（無効化→テーブル削除→影響なしを確認）。

管理画面（管理者が得るもの）

• 落ち着いた、すっきりしたレイアウト — タブは最大4つ、ビューごとに1つのプライマリアクション、詳細はドロワー、セカンダリ/破壊的アクションはオーバーフローメニュー（⋯）内、詳細設定は折りたたみ、ヘルスバナーは必要なときのみ表示。
• すべてのタブの上部にヘルスバナー（問題がある場合のみ）: メールトランスポートが設定されていません、スケジューラ/cronが実行されていません（理由と修正方法の詳細を含む）、オートメーションは一時停止されています。references/health-checks.mdを参照。
• メールオートメーションメニュー（トップレベル）、タブ:
  • シーケンス — シーケンスごとの開始 / 一時停止 / 削除（削除は確認後、論理削除/復元可能、⋯内に配置）、遅延、割引、停止条件、無料WYSIWYGエディタ、ステップの追加/並び替え/削除。
  • ユーザーと受信者 — メールアドレスでユーザーを検索。下矢印でメールシーケンスを展開。特定のメールをキャンセルまたはユーザーを完全に除外。さらに、完全な送信ログを100件ごとにページネーションして、いつと理由を表示。
  • 統計 — リマインダーを受け取ったユーザーのうち、コンバージョンした人数、収益、日/週/月ごとのチャート。
  • 設定 — 送信者（送信者名/送信者メールアドレス/返信先/住所）、マスター一時停止、制限、静音時間。
• 商品ページとチェックアウトページの下部にある管理者専用テーブル:
  • タブ 購入済み / 放棄 — 「管理者専用」と明記。
  • 列: メールアドレス（→ユーザーパネルへ）、登録/ログイン/放棄日時、支払い予定額、電話番号（→ tel: 通話へ）、下矢印で受信済み + スケジュール済みメールを表示し、ユーザーパネルにリンクしてキャンセル/除外可能。
  • メールオートメーション → 設定から無効化可能。テーブルタイトル下とリンクに説明文を表示。

完全なUI仕様: references/admin-ui.md。

---

使用すべきでない場合

• マーケティングメールの合法的な同意基盤がない場合（先に同意フローを提供すること）。
• オートメーションのノイズが価値を上回るような非常に小規模なユーザーベースの場合 — 手動で送信すること。
• メールが適切なチャネルではない製品の場合（SMS/プッシュがメイン） — エンジンを適応させ、メールを強制しないこと。
• より厳格なレビューが必要な規制対象コンテキスト（医療/金融） — コピーとデータフローの承認を得ること。
• 高保証のトランザクションニーズ — 領収書やセキュリティメールをこのシステム経由でルーティングしないでください。

エージェントが作成する成果物

1. references/discovery.md — 特定のアプリ向けの統合計画。プラットフォームの目的から導き出された提案シーケンスのショートリストを含む。
2. 新しいテーブル/マイグレーション + スケジューラ + 送信ワーカー（追加のみ）。
3. イベントフック（監視専用）。
4. 管理画面「メールオートメーション」ページ + タブ + 統計チャート。無料WYSIWYGエディタ、ステップの追加/並び替え/削除、ユーザー検索+メールごとのキャンセル/除外、ヘルス警告（一時停止、cron未実行、メールトランスポートなし）を含む。
5. 管理者専用の購入済み/放棄テーブル。
6. プレビュー/テスト送信ツール + ドライラン + ロールバック手順。
7. 簡潔な引き渡しドキュメント: 何が追加されたか、有効化方法、一時停止方法、ロールバック方法。

---

リファレンス

• references/discovery.md — アプリの調査、管理パネルの発見、統合パスの選択。
• references/non-disruption.md — 強制される非破壊契約（バックアップ、リバーシブルマイグレーション、フック分離、スモークテスト、ロールバック訓練）。
• references/triggers.md — すべてのトリガー（カート放棄、非アクティブなど）の正確な検出ルール。
• references/sequences.md — 完全なシーケンスカタログ、優先順位、タイミング、コピーの意図、停止条件。
• references/email-copy.md — パーソナルな「一人からの」コピー基準、件名、テンプレート。
• references/sending-and-compliance.md — スケジューラ、冪等性、制限、配信性事前チェック。
• references/compliance.md — 同意、署名付き購読解除、プリファレンスセンター、バウンス/苦情ウェブフック。
• references/admin-ui.md — ダッシュボード、ユーザータブ（検索/キャンセル/除外）、ログ（100件/ページ）、統計、管理者専用テーブル、WYSIWYG、ステップ追加/編集。
• references/health-checks.md — 一時停止 / cron未実行 / トランスポートなしの警告と修正ガイダンス。
• references/reference-implementation.md — 疑似コード+SQLによるエンジン（ロック、リーパー、アトリビューション）。
• examples/worker.mjs + examples/worker.test.mjs — 実行可能でテスト済みのスケジューラ/ワーカーコア。
• examples/data-model.md — DBスキーマ。
• examples/sequence-config.json — 具体的で編集可能なシーケンス設定。
• examples/email-templates.md — レンダリングされたメールのサンプル。