コントロールプレーンと責務分担

automedia は AWS 上の中央サービスだが、業務の操作起点 (コントロールプレーン) はテーマリポ <key>-hubspot-theme の Claude Code セッションに置く。本章はこの構造の根拠と、関係者ごとの役割境界、automedia への指示経路、Backlog 承認フローを定義する。

関連:

• Claude Code ランタイムモデル — AWS 中央サービスの実装構造
• Webhook 受信 (API Gateway + Lambda) — 受信側 Lambda 群
• LINE follow フロー — 個別フローの例
• Issue #104

TL;DR

• automedia = 実行レイヤ (Webhook / 配信 / Claude 呼び出し / HubSpot upsert)
• テーマリポ = 業務の操作起点 (コントロールプレーン)。Claude Code セッションでコンテンツ・コミュニケーション・automedia への指示を一気通貫
• Backlog = 業務 SoT (承認・監査・タスクキュー)
• automedia への指示は read 系 = 直接 / write 系 = Backlog 承認経由必須
• 承認は Backlog の 3 つの新規 status (automedia承認 / automedia実行済み / automediaエラー) で表現

なぜテーマリポをコントロールプレーンにするか

メディア運営者 (spin-dd 社内の運営担当) の 既存の作業の中心が HubSpot とテーマリポ にある:

• コンテンツ管理: HubSpot がコンテンツの中心。サイトのデザイン・テンプレートはテーマリポで管理されており、メディア運営者はそこで Claude Code を使ってデザイン / コンテンツ修正 / アンケートフォーム作成を行い、HubSpot に反映する
• コミュニケーション管理: HubSpot CRM がリードの SoT。コンテンツ変更を該当リードに通知するためのチャネルとして LINE (主) と Email (HubSpot 経由) を使う

つまり「コンテンツを変更したから関連リードに通知する」「アンケートを追加したから対象顧客に送る」という一連の操作は、同じ Claude Code セッション内で完結する のが自然である。automedia をテーマリポの作業環境から呼び出せる形にすることで、運営者は「テーマリポ Claude Code = 業務の入口」として運用できる。

関係者と役割境界

automedia の運用フレームは spin-dd がメディア運営を全面的に請け負う 前提に立つ。顧客社 (HubSpot ポータルの所有者) はメディア運営の意思決定者ではあるが、日々の Backlog 課題操作・テーマリポ編集・配信オペレーションは spin-dd 社内のメディア運営担当 が担う。

関係者	主責任 (= できること)	境界 (= 触らない)
メディア運営者 (spin-dd 社内 / 運営担当)	テーマリポで Claude Code セッションを開き .automedia/ 編集・PR 作成 / HubSpot テーマ・コンテンツ・アンケート編集 / Backlog 課題起票・承認・配信プレビュー / LINE OA Manager 操作	Lambda コード / OpenTofu / IAM ロール
automedia 開発者 (spin-dd 社内 / エンジニアリング)	automedia リポのコード・OpenTofu・スキル定義 / 全テナント横断の機能追加 / Secrets Manager 運用 / トラブル対応時の AWS CLI 経由 Lambda invoke	テナント固有のテンプレ・運用判断 (= メディア運営者の領分)
automedia (AWS 中央サービス)	Webhook 受信 / 配信実行 / Claude 呼び出し / HubSpot upsert / EventBridge schedule / Backlog 承認確認	テナント固有のテンプレ判断 (設定 SoT に従う)
テーマリポ <key>-hubspot-theme	HubSpot テーマ実装 (本来用途) / .automedia/ 設定 SoT 保持 / .claude/skills/automedia-* の保持	Lambda コード / OpenTofu / 他テナントへの影響

顧客社の位置付け: 顧客は HubSpot ポータルの所有者であり、運営戦略・キャンペーン承認などの上位意思決定者だが、本ドキュメントの「関係者」(= 日々のオペレーションを行うアクター) には含めない。spin-dd の運営者がアウトプットを顧客に共有・確認する経路は automedia の管轄外 (例: 月次レポート、配信前の事前確認など)。

Backlog 承認の意味: spin-dd 社内のメディア運営者自身が起票・承認する自己承認モデル (顧客社の権限は別途、運営チームの内部レビューが Backlog status 遷移として可視化される)。チーム内で起票者と承認者を分ける運用 (= 4-eyes principle) を採るかは運用ルール側で決める。

automedia への指示経路: 2 階層ポリシー

副作用の有無で経路を分ける:

操作	副作用	経路	認証
automedia preview <issue>	なし	テーマリポ Claude Code → automedia 直接 (read endpoint)	テーマリポ専用の read-only IAM Role
automedia status	なし	同上	同上
automedia audience-query <tag>	なし	同上 (HubSpot CRM 経由のリード抽出結果を返す)	同上
automedia send <issue>	LINE 配信	Backlog 承認経由必須	webhook-backlog Lambda のみ
automedia notify-leads <content>	LINE / Email 配信	Backlog 承認経由必須	同上
HubSpot CMS デプロイ	サイト変更	Backlog 承認経由必須 (テーマリポ運用に従う)	テーマリポ側の HubSpot Token
.automedia/*.yml 編集	テナント設定変更	Backlog 承認 + GitHub PR レビュー	GitHub Push → Sync Lambda

不変条件

1. 顧客に対する送信操作 (LINE / Email / HubSpot CRM 変更) は必ず Backlog 課題に紐づく
2. automedia の write エンドポイントは「対応する Backlog 課題キー + 承認済み状態」を必須にバリデーション
3. 直接呼び出された write は 400 (not-approved or missing-backlog-reference) で拒否
4. 緊急オーバーライドはなし。トラブル対応は automedia 開発者が AWS CLI / SDK で Lambda を直接 invoke する別経路で対応 (本番フローと分離)

Backlog 承認フロー (新規設計)

Status 設計

TTRTAGSPIN プロジェクトに 3 つの新規 status を追加:

Status	意味	遷移元	遷移先
automedia承認	承認済み、automedia による処理待ち	既存 status (処理中 等) からの人手遷移	automedia実行済み (成功) / automediaエラー (失敗)
automedia実行済み	配信成功 (terminal)	automedia承認 (automedia 自動遷移)	(terminal)
automediaエラー	配信失敗 / 要追加指示 (要人手介入)	automedia承認 (automedia 自動遷移)	automedia承認 (修正後の再承認)

ライフサイクル

主な遷移:

• ① 人手で status 変更 = 承認: 未対応 / 処理中 → automedia承認 (承認者・日時は Backlog の status 変更履歴に組み込みで残る)
• ②a 配信成功: deliver Lambda が automedia承認 → automedia実行済み に自動遷移 + 結果コメント + 配信実行日時の記録 (Backlog の現行プランは customField 非対応のため、配信実行日時は [automedia] dispatched at <iso> コメントで記録する)
• ②b 配信失敗: 全チャネル失敗で automedia承認 → automediaエラー に自動遷移 + [automedia] failed: <理由> コメント (要人手介入。修正後に再承認で再実行)
• ③ 課題修正 → 再実行: 人手で内容を修正してから automedia承認 に戻すと再実行
• invalidate: 承認後に本文 / 投稿日時 / テンプレ参照が変更されたら、Lambda が自動で status を 1 つ戻し Schedule を削除 (再承認必要)

監査ログ

• 承認者・日時は Backlog の status 変更履歴に組み込みで残る (カスタムフィールド不要)
• 配信成否は automedia が Backlog コメントとして書き戻し
• 既存カスタムフィールド「自動配信実行日時」「投稿日時」と二重防御で冪等性を担保

Invalidate ルール

automedia承認 状態の課題が編集された場合、webhook-backlog Lambda の IssueUpdated ハンドラで:

• 本文 / 投稿日時 / テンプレ参照 が変更された場合 → status を 1 つ戻す (= 再承認必要)
• タイトル / コメント追加のみ → 承認維持
• EventBridge Schedule が登録済みなら 削除 (再承認後に再登録)

これで「承認後に勝手に書き換えて配信される」リスクを防ぐ。

緊急オーバーライドなし

• 本番 write endpoint は 厳格に承認必須、例外なし
• automedia 開発者がトラブル対応する場合は AWS CLI / SDK で直接 Lambda invoke (本番フローとは別経路)
• これにより本番経路がシンプルかつ監査が一貫する

テーマリポ Claude Code スキル群

テーマリポ <key>-hubspot-theme の .claude/skills/ に配置する automedia 連携スキル群 (整備状況に応じて新規追加 or 既存拡張):

read 系 (副作用なし、直接呼び出し)

テナント分離を IAM 層で強制できるよう、全 read endpoint は tenant を path に置く (.../api/tenants/<t>/* を per-tenant Role の execute-api:Invoke で resource scope する)。

スキル	役割	呼び先
automedia-preview <issue-key>	Backlog 課題から配信プレビュー生成 (実送信なし)	POST /api/tenants/<t>/preview (#111)
automedia-status	テナントの配信状態確認 / 直近の配信履歴	GET /api/tenants/<t>/status (#111)
automedia-audience-query <tag>	HubSpot CRM からタグ条件でリード抽出	POST /api/tenants/<t>/audience-query (#111)

preview は read-api Lambda が deliver を副作用ゼロの preview モードで同期 invoke し、 配信と同一の AI パイプラインで生成する (request ai:false で AI 無しの軽量レンダリングに縮退)。 audience-query は件数 + マスク済みサンプルのみ返し、生 PII は返さない。

write 系 (Backlog 承認経由)

スキル	役割	呼び方
automedia-send <issue-key>	配信実行	Backlog コメント /automedia send 投稿
automedia-cancel <issue-key>	Schedule 削除	Backlog コメント /automedia cancel 投稿
automedia-notify-leads <content>	コンテンツ変更を該当リードに通知 (LINE / Email)	Backlog 課題起票 → 承認 → 自動実行 (要新規設計)

コンテンツ系 (テーマリポ本来用途、既存)

スキル	役割
HubSpot テーマ編集 (HubL / CSS / JS)	テーマリポ本来用途 (既存)
HubSpot CMS デプロイ	テーマリポ本来用途 (既存、Backlog 承認に統合)
アンケートフォーム作成	テーマリポ本来用途 (既存または新規)

配布方針

スキル定義は automedia リポを SoT とし、テーマリポへは配布 CLI で配る (drift 防止、#113)。

npx github:spin-dd/automedia init      # 初回導入
npx github:spin-dd/automedia upgrade   # 最新へ更新 (automedia-* のみ上書き)

CLI (bin/automedia.mjs、依存ゼロ) は SoT の .claude/skills/automedia-* をテーマリポの .claude/skills/ へ冪等にコピーする。automedia- 接頭辞でないテーマリポ固有スキルには 一切触れないため、カスタムスキルと配布分は自然に分離される。

認証境界

read 系 endpoint の認証は テーマリポ単位の short-lived credential で行う必要がある (Phase 1b の現構成にはない要素):

想定	認証方式	権限
メディア運営者 (spin-dd 運営担当)	GitHub OIDC → 担当テナント群の read-only IAM Role	担当テナントの preview / status / audience-query のみ
automedia 開発者	AWS SSO (既存 spindd profile)	全テナント / 全操作 (本番経路外)

read-api Lambda + route (AWS_IAM 認証) と per-tenant read-only IAM Role (automedia-readonly-<tenant>、GitHub OIDC trust + execute-api 限定) は #111 で実装済み。

read API への経路は 2 つあり独立している: - CI (テーマリポ GitHub Actions) → OIDC で automedia-readonly-<tenant> を assume して叩く。 - SSO 運営者 → #112 の Permission Set 自体が execute-api:Invoke を持つので 直接叩く (readonly role の assume は不要)。

したがって readonly role への SSO trust (var.operator_sso_role_arns) は 既定で空のままでよく、 有効化は「単一ロールに集約したい」場合の任意オプション。詳細は 22-credentials.md。

automedia 側の実装スコープ (このドキュメントが示唆する新規開発)

項目	現状	必要追加
webhook-backlog Lambda の write 受付バリデーション	status / 投稿日時を見る	status === 'automedia承認' のチェックを追加
webhook-backlog の IssueUpdated invalidate ハンドラ	status 戻しで Schedule 削除	本文・投稿日時・テンプレ参照変更で status を戻す ロジック追加
deliver Lambda の完了処理	配信実行	成功時 automedia実行済み に / 失敗時 automediaエラー に status 更新
read 系公開 API (/api/tenants/<t>/preview / /status / /audience-query)	read-api Lambda + route (AWS_IAM) 実装済み (#111)	(済)
テーマリポ用 read-only IAM Role	per-tenant role 実装済み (#111, OIDC trust + execute-api 限定)	SSO 運営者は #112 PS 直叩きで完結 (readonly role の SSO trust は任意)
TTRTAGSPIN プロジェクトの status 追加	なし	Backlog 側で 3 status を手動追加 (またはツールで自動化)

これらは Phase 1b の追加スコープであり、別途 Issue として切り出して段階的に実装する。

未決事項 (Phase 2 以降の検討)

1. content change → notify leads フロー (B1) を MVP に含めるか
   • 「コンテンツデプロイ後の関連リード自動通知」のリード抽出ロジックをどこに置くか (HubSpot List / .automedia/audiences.yml / Claude 判断)
2. 公開 API の認証スキーム詳細 — テーマリポからの assume role を OIDC で行う場合の trust policy 設計
3. チーム内承認分業 (4-eyes principle) — メディア運営チーム内で起票者と承認者を分ける運用にするか、自己承認可とするか
4. automediaエラー 状態の自動 retry ポリシー — 一時障害の場合は automedia 側で自動 retry するか、必ず人手介入を待つか
5. 顧客社への配信前確認・事後レポート経路 — automedia の管轄外として運用ルール側に切り出す範囲を定義

決定事項

• テーマリポ Claude Code セッション = コントロールプレーン (2026-05-25 確定、Issue #104)
• Backlog = 業務 SoT (承認・監査・タスクキュー) (2026-05-25 確定)
• 指示経路 2 階層: read 直接 / write は Backlog 承認経由 (2026-05-25 確定)
• 承認フロー: 3 status (automedia承認 / automedia実行済み / automediaエラー) + 課題編集時の invalidate (2026-05-25 確定)
• 緊急オーバーライドなし: 本番 write は厳格に承認必須、開発者対応は AWS CLI 経由の別経路 (2026-05-25 確定)
• テーマリポスキルは "存在したら更新、なかったら新規整備": automedia リポを SoT として配布 (2026-05-25 確定)