CASTA — 要件定義書 兼 Claude Code 実装指示書

版数 1.0（DBレス構成 / 記事埋め込み型デモ）／ 作成日 2026-08-17 ／ 発行 ソウゾウ合同会社 用途 SEO記事「【デモで試せる】Claude Codeで動画配信アプリを開発する方法と費用｜動画つき資料【2026年】」に組み込む実演デモ

このドキュメントの使い方（Claude Code へ）

これ1枚が、規約・仕様・タスクのすべて。リポジトリ直下に CLAUDE.md として置き、毎回読み込むこと。

• 実装は「13. 実装タスク」の順に進める。フェーズを飛ばさない。
• 各タスクの括弧内は要件ID。着手前に該当章を読むこと。
• 仕様がここに書かれていない場合は、推測で実装せず質問する。
• スコープ外（4章 Won't have）は、思いついても実装しない。
• 「デモだから」を理由に品質を落とす判断はしない。

姉妹プロジェクトとの関係 HIREBASE（求人サイト）／ RELATE（顧客管理）に続く3本目。3つ並べて「同じテンプレ」と思われた時点で失敗。 HIREBASE＝明朝・余白・静けさ（読ませる）／ RELATE＝ゴシック・高密度・等幅数字（操作させる）／ CASTA＝ダーク・映像が主役・UIが消える（見せる）。 9章のデザイン要件は意図的に第3の方向に振っている。トークンを流用しないこと。

目次

1. プロジェクト概要
2. 記事への組み込み設計
3. アーキテクチャ方針
4. スコープ定義
5. ロールとデモ切替
6. 画面一覧とユーザーフロー
7. 機能要件
8. データ設計
9. デザイン要件
10. 技術要件・ディレクトリ構成
11. 非機能要件
12. 費用設計
13. 実装タスク
14. 受入基準

1. プロジェクト概要

背景と目的

対象記事のキーワード意図は「動画配信アプリを作りたいが、作り方と費用が分からない」。この検索意図に対し、テキストの説明だけでは以下2点が伝わらない。

1. どこまでのものが作れるのか — プレーヤーの完成度、会員制の作り込み、管理画面の実用性
2. なぜ費用が読みにくいのか — 動画配信は開発費より運用費（配信コスト）の設計が本質。ここを説明できるかが専門性の証明になる

そこで記事内に、実際に動画が再生できるデモを組み込む。動画配信アプリは「モックでは絶対に伝わらない」領域であり、実際に再生が始まった瞬間に信頼が生まれる。

プロダクト定義

プロダクトコンセプト

「アプリを見せない。動画を見せる。」

動画配信サービスのUIは、うまくいっているとき存在に気づかれない。CASTA は、画面を暗く落とし、装飾を削り、サムネイルと映像だけに光を渡す。操作は身体が覚えているもの（スペースで再生、矢印でシーク）をそのまま採用する。

デモとしての成功条件

1. 記事を読んでいる人が、3秒以内に再生を開始できる
2. プレーヤーが本物である — 画質切替、速度、字幕、チャプター、レジューム。ここが安っぽいと全部が嘘になる
3. 有料ゲートが体験できる — 無料会員で有料コンテンツを開くと、プレビュー後にペイウォールが出る
4. 管理側も見られる — 配信管理と視聴分析まで、ロール切替で確認できる
5. 記事に戻れる／問い合わせできる — デモが行き止まりにならない

2. 記事への組み込み設計

この章が本プロジェクト固有の最重要要件。 単体で作って後から埋め込むのではなく、埋め込み前提で設計する。

配置方針

記事内で2段構えにする。

アプリ全体を記事内 iframe に入れない。 理由は3つ。

• 動画を含むアプリ全体は初期ロードが重く、記事本体のCore Web Vitalsを悪化させる
• iframe 内のスクロールと記事のスクロールが競合し、モバイルで操作不能になる
• アプリ内で画面遷移すると、読者が記事のどこにいたか分からなくなる

埋め込みモード（?embed=1）

同一アプリを、URLパラメータで2つのモードで動作させる。別リポジトリに分けない。

<iframe
  src="https://casta.souzoh-demo.com/watch/ep-001?embed=1"
  width="100%" style="aspect-ratio:16/9; border:0"
  loading="lazy"
  allow="fullscreen; picture-in-picture"
  title="CASTA 動画プレーヤーのデモ"></iframe>

記事本体のパフォーマンスを壊さない

「動画つき資料」との一体化（重要な設計判断）

記事タイトルの「動画つき資料」を、別途用意するのではなくデモの中身そのものにする。

• デモに投入するシリーズの1本目を「Claude Codeで動画配信アプリを作る」の解説動画にする
• そのエピソードに、資料PDF（設計図・費用試算シート）を添付ファイルとして紐付ける（FR-208）
• 読者は「デモを触る」と「資料を見る」を1つの体験として行う

これにより、デモ機能（添付資料ダウンロード）と記事コンテンツ（動画つき資料）が同じ実装で成立する。 二重に作らない。

導線と計測

SEO上の扱い

3. アーキテクチャ方針

基本方針

バックエンドとデータベースを持たない。ただし動画ファイルだけは実在させる。

動画だけは実在させる理由

動画配信アプリのデモで動画が再生できないのは、求人サイトのデモで求人が0件なのと同じ。再生が始まるかどうかが、このデモの成否そのもの。

ただし「実在させる」のは配信であって、バックエンドではない。HLS は .m3u8 プレイリストと .ts セグメントというただの静的ファイルなので、オブジェクトストレージに置くだけで配信できる。サーバーは不要。

動画素材の方針

エンコード仕様

入力: 1080p mp4
出力: HLS（fMP4 / CMAF）
  ├ 1080p  H.264 High  3,500kbps  ─┐
  ├  720p  H.264 Main  1,800kbps   ├ master.m3u8 に3レンディション
  └  360p  H.264 Base    600kbps  ─┘
  セグメント長 4秒 / GOP 2秒 / 音声 AAC 128kbps
  サムネイル: 各動画から3枚（ポスター / ホバープレビュー用スプライト / OGP用）

エンコードは ffmpeg のスクリプト（scripts/encode.sh）としてリポジトリに含める。これ自体が記事の「方法」パートの説明材料になる。

配信先

差し替え可能性の担保

データアクセスは必ず lib/repo/ のリポジトリ層を経由すること。 コンポーネントからストアを直接触らない。

[ コンポーネント ]
        ↓  呼ぶのはこの層だけ
[ lib/repo/*.ts ]   ← 全メソッドを async
        ↓
[ lib/store/*.ts ]  ← Zustand + persist（localStorage）
        ↓
[ lib/seed/*.ts ]   ← 初期データ（動画URLはR2を指す）

リポジトリの各メソッドは、中身が同期処理でも async で定義する。実案件へ転用する際、リポジトリの実装だけをAPI呼び出しに差し替えれば、UI層は変更不要。

永続化の範囲

擬似ディレイ は 150〜400ms。ただし再生開始に関わる操作にはディレイを入れない（動画配信で待たされるのは致命的な体験のため）。

4. スコープ定義

視聴者向け機能

配信管理（運営）向け機能

共通・基盤

対象外（Won't have）

スコープリスク： 動画配信は「ライブ配信も」「DRMも」と広がりやすい。どちらも単体で数週間〜の領域。要望が出た場合は12章の費用表を使って別見積として提示し、この文書のスコープは変えない。

5. ロールとデモ切替

ロール定義

ロールを跨ぐ体験（必ず動くようにする）

1. 未ログインで有料エピソードを再生 → 3分でペイウォール → 有料会員に切替 → 同じ位置から続きが再生される
2. 無料会員で途中まで視聴して離脱 → リロード → 「続きから見る」に表示され、停止位置から再開する
3. 運営でエピソードを「非公開」に変更 → 視聴者に切替 → カタログから消えている
4. 運営で新規エピソードを公開予約（1分後） → 待つ → 視聴者側のカタログに出現する
5. 視聴した動画が、運営の視聴分析にカウントされ、離脱ヒートマップに反映される

デモ切替バー（F-S01）

画面上部に常時表示する固定バー。ただし埋め込みモードでは非表示。

• 現在のロール表示と4ロールの切替
• 「デモをリセット」ボタン（確認ダイアログ付き）
• 元記事へ戻るリンク
• 「これはデモです」の明示

デザイン上の扱い： アプリ本体がダークテーマなので、切替バーは逆に明るいグレーにして区別する。プロダクトのトークンを使わない。

6. 画面一覧とユーザーフロー

全28画面。画面IDはディレクトリ構成と 1:1 で対応させる。

視聴者画面

管理画面

主要フロー

フローA：記事の読者が動画に触れる（最重要）

SEO記事を読んでいる
   ↓
記事内の埋め込みプレーヤー（ポスター画像 + 再生ボタンのみ表示、まだ何も読み込んでいない）
   ↓
再生ボタンを押す ── ここで初めて hls.js とマニフェストを取得
   ↓
再生開始（3秒以内）── 画質切替・速度・字幕を触ってみる
   ↓
「全画面でデモを開く」→ 別タブでアプリ本体へ
   ↓
SC-001 トップ ── ガイドツアーが3ステップで「試せること」を案内
   ↓
SC-004 シリーズ詳細 → SC-002 視聴
   ↓
デモ切替バーで「運営」に切替 → SC-140 視聴分析
   ↓  ★ たった今自分が見た再生が、グラフに反映されている
問い合わせ導線 or 元記事に戻る

フローB：ペイウォールの体験

SC-001 トップ（未ログイン）── 有料バッジ付きのエピソードを選ぶ
   ↓
SC-002 視聴 ── 再生開始。プレーヤー上部に「無料プレビュー 残り2:47」
   ↓
3分経過 ── 再生が停止し、ペイウォールがオーバーレイ表示
   「続きを見るには有料プランへの登録が必要です」＋ プラン概要 ＋ CTA
   ↓
SC-020 プラン比較 → SC-021 申込フォーム → SC-022 完了
   ↓  ※ 決済処理は行わない。ロールが premium に変わる
SC-002 に戻る ── ★ 停止した3分00秒の位置から、そのまま続きが再生される

フローC：運営がエピソードを公開する

SC-111 アップロード ── ファイルをドロップ
   ↓
エンコード進捗の再現
   待機中 → 変換中（0〜100%、解像度ごとに段階表示）→ サムネイル生成 → 完了
   ※ 一定確率で「変換失敗」を再現し、リトライ導線を見せる
   ↓
SC-112 エピソード編集
   タイトル・説明・サムネイル選択（3候補から）
   シリーズへの割当、無料／有料の区分
   公開設定：下書き／即時公開／公開予約（日時指定）
   ↓
SC-114 チャプター編集 ── 再生しながらチャプターを打つ
   ↓
SC-115 添付資料 ── PDFを紐付け、公開範囲を「有料会員のみ」に
   ↓
公開
   ↓
【ロール切替：無料会員】
SC-001 トップの「新着」に出現。★ 添付資料はロックされている
   ↓
【ロール切替：有料会員】
★ 添付資料がダウンロード可能になっている

7. 機能要件

7.1 プレーヤー（このデモの心臓部）

7.2 埋め込みモード

7.3 カタログ・視聴体験

7.4 会員・ペイウォール

7.5 配信管理

7.6 視聴分析

7.7 デモ基盤

8. データ設計

型定義（lib/types/）

// ---- コンテンツ ----
type Series = {
  id: string
  title: string
  slug: string
  description: string
  categoryId: string
  tagIds: string[]
  coverUrl: string              // 縦長（カタログ用）
  heroUrl: string               // 横長（トップのヒーロー用）
  episodeIds: string[]          // 並び順を保持
  isPublished: boolean
  publishedAt: string
  createdAt: string
}

type Episode = {
  id: string
  seriesId: string
  number: number                // 第N話
  title: string
  description: string
  durationSec: number
  // --- 配信情報（実在するファイルを指す） ---
  hlsUrl: string                // master.m3u8 のURL
  posterUrl: string
  spriteUrl: string             // シークプレビュー用スプライト
  spriteMeta: { cols: number; rows: number; interval: number; w: number; h: number }
  captions: Caption[]
  chapters: Chapter[]
  // --- 公開・課金 ---
  access: 'free' | 'paid'
  previewSec: number            // 有料時のプレビュー秒数（既定180）
  status: 'draft' | 'scheduled' | 'published' | 'unlisted' | 'private'
  scheduledAt?: string          // 公開予約日時（FR-408）
  publishedAt?: string
  // --- 付随 ---
  attachmentIds: string[]
  tagIds: string[]
  createdAt: string
  updatedAt: string
}

type Caption = { id: string; lang: 'ja' | 'en'; label: string; vttUrl: string; isDefault: boolean }
type Chapter = { id: string; startSec: number; title: string }

type Attachment = {
  id: string
  episodeId: string
  name: string
  fileType: 'pdf' | 'slide' | 'zip' | 'other'
  sizeBytes: number
  url: string
  visibility: 'public' | 'member' | 'premium'   // FR-412
}

type Category = { id: string; name: string; slug: string; sortOrder: number }
type Tag = { id: string; name: string }

// ---- 会員・プラン ----
type Plan = {
  id: string
  name: string                  // 無料 / スタンダード / プレミアム
  priceMonthly: number
  description: string
  features: string[]
  accessScope: 'free_only' | 'all'
  sortOrder: number
}

type Member = {
  id: string
  name: string
  email: string
  avatarUrl: string
  role: 'guest' | 'free' | 'premium' | 'admin'
  planId: string
  subscribedAt?: string
  status: 'active' | 'suspended' | 'cancelled'
  lastWatchedAt?: string
  watchedCount: number
  createdAt: string
}

// ---- 視聴 ----
type WatchProgress = {
  episodeId: string
  memberId: string
  positionSec: number           // 5秒ごとに更新（FR-109）
  durationSec: number
  percent: number               // 派生値だが検索性のため保持
  isCompleted: boolean          // 95%以上（FR-110）
  lastWatchedAt: string
}

type WatchEvent = {              // 分析の元データ
  id: string
  episodeId: string
  memberId: string
  type: 'start' | 'progress' | 'complete' | 'abandon' | 'quality_change' | 'seek'
  positionSec: number
  quality?: '1080p' | '720p' | '360p'
  device: 'desktop' | 'mobile' | 'tablet'
  occurredAt: string
}

type Note = { id: string; episodeId: string; memberId: string; positionSec: number; body: string; createdAt: string }
type ListItem = { id: string; memberId: string; targetType: 'series' | 'episode'; targetId: string; addedAt: string }

// ---- 分析（集計値。ストアには保存せず lib/calc で算出） ----
type RetentionPoint = { positionSec: number; retainedRatio: number }   // 離脱ヒートマップ（FR-502）
type EpisodeStats = {
  episodeId: string
  plays: number
  uniqueViewers: number
  totalWatchSec: number
  avgCompletionRate: number
  retention: RetentionPoint[]
  byDevice: Record<'desktop'|'mobile'|'tablet', number>
  byQuality: Record<'1080p'|'720p'|'360p', number>
}

// ---- アップロード（擬似） ----
type UploadJob = {
  id: string
  fileName: string
  sizeBytes: number
  stage: 'uploading' | 'queued' | 'transcoding' | 'thumbnailing' | 'done' | 'failed'
  progress: number              // 0-100
  transcodeProgress: Record<'1080p'|'720p'|'360p', number>
  errorReason?: string
  linkedEpisodeId?: string      // 完了時に既存素材へ紐付け（FR-403）
  createdAt: string
}

シードデータ（lib/seed/）

シード作成のルール（品質を左右する）

• シリーズ構成は実在しそうな講座にする。 例：「Claude Code入門」「業務システムの作り方」「AI活用の基礎」等。タイトルの使い回し禁止
• エピソードの説明文を書き分ける。 「第N話の説明です」のようなダミーを残さない
• 視聴イベントは自然な離脱曲線で生成する。 冒頭30秒で15%落ち、以降なだらかに減衰、終盤で微増（まとめ部分）。均等分布だと分析画面が無意味になる
• エピソードごとに離脱パターンを変える。 途中に大きな離脱がある回を意図的に作る（分析の価値が伝わる）
• 日付は現在日時からの相対で生成する。固定日付を埋め込まない
• 「続きから見る」が最初から表示されるよう、ペルソナに視聴途中のエピソードを持たせる。 トップが空だとデモとして成立しない
• 公開予約されたエピソードを1本含める（フローCの実演用）

ストアとリポジトリ

lib/
├── types/          # 上記の型定義
├── seed/
├── store/
│   ├── session.ts  # ロール、操作中の会員
│   ├── content.ts  # series / episodes / attachments / categories
│   ├── watch.ts    # progress / events / notes / list
│   └── ui.ts       # 再生設定、ガイドツアー表示済みフラグ
└── repo/           # ★ コンポーネントが触るのはここだけ
    ├── _delay.ts _scope.ts
    ├── episodes.ts series.ts attachments.ts
    ├── watch.ts members.ts plans.ts uploads.ts analytics.ts

リポジトリ層の規約（厳守）

• 全メソッドを async で定義。中身が同期でも例外なく
• 戻り値は { ok: true; data: T } | { ok: false; error: string } に統一
• コンポーネントから Zustand ストアを直接参照しない
• 視聴可否の判定（canWatch(episode, role)）は lib/repo/_scope.ts に集約する。 コンポーネント側で role === 'premium' のような分岐を書かない（FR-608）
• 派生値（進捗率、離脱率、完了率）はストアに保存せず lib/calc/ で算出する
• 再生開始に関わるメソッドには擬似ディレイを入れない

// lib/repo/_scope.ts — 実案件では署名付きURL発行・DRM に置き換わる箇所
export function resolveAccess(ep: Episode, role: Role): AccessResult {
  if (ep.access === 'free') return { kind: 'full' }
  if (role === 'premium' || role === 'admin') return { kind: 'full' }
  return { kind: 'preview', limitSec: ep.previewSec }   // guest / free
}

9. デザイン要件

アートディレクション

「画面を暗くして、映像に光を渡す」

動画配信のUIは、うまくいっているとき存在に気づかれない。CASTA は暗い背景に沈み、サムネイルと再生中の映像だけが明るい。装飾・グラデーション・不要な枠線を持たない。

• ダークテーマを既定とする。 ライトテーマは実装しない（切替を作らない）
• サムネイルが唯一の色。 UI自体はほぼ無彩色。彩度はコンテンツ側にある
• アクセントは1色だけ。 再生・進捗・現在地にのみ使う
• コントロールは消える。 3秒で自動的に隠れ、必要なときだけ現れる

HIREBASE / RELATE との差別化（重要） HIREBASE：明朝・白・広い余白（読ませる） RELATE：ゴシック・白・高密度・等幅数字（操作させる） CASTA：ダーク・映像優先・UIが消える（見せる） 3つ並べたとき、別の会社が作ったように見えることが理想。トークンをコピーしない。

カラートークン

:root {
  /* 背景は3段階の黒で奥行きを作る */
  --bg-base:    #0A0B0D;   /* ページ背景 */
  --bg-raised:  #131519;   /* カード・パネル */
  --bg-overlay: #1C1F25;   /* モーダル・ドロップダウン */

  --fg-high:    #F2F3F5;   /* 見出し・本文 */
  --fg-mid:     #A0A6B0;   /* 補助テキスト */
  --fg-low:     #6B7280;   /* ラベル・非活性 */

  --accent:     #E8503A;   /* 再生・進捗・現在地。★これ以外の色を持ち込まない */
  --accent-dim: rgba(232,80,58,.18);

  --border:     #24272E;   /* 罫線。極めて控えめに */
  --border-hi:  #343943;   /* フォーカス時 */

  /* シグナル（管理画面のみで使用） */
  --ok: #3FA37A; --warn: #C8933A; --danger: #D0544A;
  /* プレーヤー内グラデーション（コントロールの視認性確保） */
  --scrim: linear-gradient(to top, rgba(0,0,0,.85) 0%, rgba(0,0,0,0) 100%);
}

配色ルール

• アクセント --accent は「再生・進捗・現在地」にのみ使う。 有料バッジ・エラー・装飾に使わない
• 有料バッジは色ではなく枠線とアイコンで表現する。カタログが赤いバッジだらけになると台無しになる
• カード同士は影ではなく背景の明度差で分ける（--bg-base の上に --bg-raised）
• プレーヤーのコントロールは、映像の明暗に負けないよう必ず --scrim の上に置く

タイポグラフィ

ダーク背景では文字が太って見える。 ライト背景と同じウェイトを使わず、本文は 400、見出しは 700 で明確に差をつける（500・600 を多用しない）。

レイアウトとスペーシング

プレーヤーUI仕様（最重要コンポーネント）

┌──────────────────────────────────────────────┐
│  [無料プレビュー 残り2:47]        ← 有料時のみ、上部左  │
│                                              │
│                   映像                        │
│                                              │
│  ┌──── scrim グラデーション ────────────────┐ │
│  │  ● チャプター名（現在地）                  │ │
│  │  ━━━━━━━╋━━━━┃━━━━━━━━━━━━━━  ← シークバー│ │
│  │   ▶  ⏭  🔊━━  1:24 / 8:15   ⚙ CC ⛶ ⧉  │ │
│  └────────────────────────────────────────┘ │
└──────────────────────────────────────────────┘

主要コンポーネント仕様

モーション

prefers-reduced-motion: reduce 時は全アニメーションを無効化し、ホバープレビューの自動再生も停止すること。

アクセシビリティ（WCAG 2.1 AA）

動画プレーヤーは a11y の要求が特に高い領域。ここを作り込めることが差別化になる。

ライティング規約

10. 技術要件・ディレクトリ構成

技術スタック（固定・勝手に変更しない）

上記以外のライブラリを入れる前に必ず提案し、承認を得ること。特にプレーヤーライブラリの導入は禁止。

ディレクトリ構成

/
├── CLAUDE.md
├── app/
│   ├── layout.tsx
│   ├── page.tsx                    # SC-001 トップ
│   ├── watch/[episodeId]/page.tsx  # SC-002 / SC-003（?embed=1）
│   ├── series/[seriesId]/page.tsx  # SC-004
│   ├── browse/                     # SC-005, 007
│   ├── search/                     # SC-006
│   ├── my/                         # SC-010〜014
│   ├── plans/                      # SC-020〜022
│   ├── admin/                      # SC-100〜140
│   └── dev/components/             # コンポーネントカタログ
├── components/
│   ├── player/                     # ★ 最重要
│   │   ├── VideoPlayer.tsx         # ルート。hls.js の生存管理
│   │   ├── ControlBar.tsx
│   │   ├── SeekBar.tsx             # チャプター区切り・プレビュー
│   │   ├── SettingsMenu.tsx        # 画質・速度
│   │   ├── CaptionMenu.tsx
│   │   ├── ChapterList.tsx
│   │   ├── NextEpisodeCard.tsx
│   │   ├── Paywall.tsx
│   │   └── useHls.ts / useKeyboardShortcuts.ts / usePlaybackProgress.ts
│   ├── catalog/                    # ContentCard, Lane, Hero, HoverPreview
│   ├── domain/                     # EpisodeRow, AttachmentCard, UploadStepper, RetentionChart
│   ├── demo/                       # RoleSwitcher, ResetButton, GuideTour, BackToArticle
│   └── layout/
├── lib/
│   ├── types/ seed/ store/ repo/
│   ├── calc/                       # 進捗率、離脱率、完了率、継続率
│   ├── query/                      # 検索・絞り込み
│   ├── validation/
│   └── utils/
├── scripts/
│   └── encode.sh                   # ffmpeg エンコードスクリプト
├── docs/
│   └── assets-license.md           # ★ 動画・画像素材の取得元とライセンス（VID-02）
├── e2e/
└── public/

コーディング規約

• TypeScript strict。any 禁止
• ファイル名は kebab-case、コンポーネントは PascalCase
• コンポーネントから Zustand ストアを直接参照しない。必ず lib/repo/ 経由
• 視聴可否の判定を role === 'premium' のようにコンポーネントに書かない。 resolveAccess() を使う
• 計算ロジックは lib/calc/ に置き、コンポーネントに埋め込まない
• hls.js のインスタンスは必ず破棄する。 エピソード遷移・アンマウント時に hls.destroy() を呼ぶ。メモリリークはこのアプリで最も起きやすい不具合
• <video> のイベントリスナーも同様に確実に解除する
• コミットは1タスクごと。メッセージに要件IDを含める 例：feat(player): 画質切替時の再生位置維持を実装 (FR-103)

11. 非機能要件

セキュリティ・権利（実案件への注記を含む）

実案件への転用時の注意（デモ本体の要件ではない。商談で聞かれた際に説明できるよう記録）

• 本デモの動画URLは公開されており、URLを知る第三者が直接再生できる。実サービスでは署名付きURL（有効期限付き）またはDRMが必要
• 有料コンテンツを扱う場合、特定商取引法に基づく表記、解約条件の明示、資金決済法の観点（前払式支払手段に該当するか）の確認が必要
• 会員情報は個人情報保護法の対象。利用目的の明示と安全管理措置が必要
• 本デモは会員情報をサーバーに送信しないため、これらの義務は発生しない。「デモである」旨は画面上に常時明示する

12. 費用設計

記事の主題の半分は「費用」。この章は実装要件であると同時に、記事本文の原稿素材でもある。

費用は3層に分けて説明する

動画配信アプリの費用相談で最も多い失敗は、③を計算せずに始めること。 記事ではここを主軸に据える。

変動運用費の計算式（記事に載せる中核）

月間転送量(GB) = 平均ビットレート(Mbps) ÷ 8 × 平均視聴秒数 × 月間再生数 ÷ 1024

例：720p（1.8Mbps）／ 平均視聴 6分（360秒）／ 月間 10,000再生
  = 1.8 ÷ 8 × 360 × 10,000 ÷ 1024
  ≈ 791 GB/月

この 791GB に、各サービスの単価を掛けたものが月額の配信コストになる。

配信先の選択が費用構造を決める

判断基準はシンプル： 実装工数を払って変動費を抑えるか、変動費を払って実装工数を抑えるか。月間視聴時間が読めない初期は前者、事業として伸びてDRMや詳細分析が必要になったら後者、という移行が現実的。

記事に載せる際の注意： 各サービスの単価は変動するため、この文書に金額を書き込まない。 記事執筆時点で公式の料金ページを確認し、確認日を明記して掲載すること。古い単価を載せた記事は、それだけで信頼を失う。

開発費の目安（機能スコープ別）

「動画配信アプリ」という言葉の幅が非常に広いことが、費用が伝わらない最大の原因。 記事ではこの3段階を明示し、デモは「標準構成」の実物であることを示す。具体的な金額はLPの価格体系に接続する。

デモ自体の運用コストを実測して記事に載せる

**「私たちのデモは、月にこれだけ再生されて、これだけかかっています」**という一文が、どんな料金表よりも説得力を持つ。

13. 実装タスク

この順に進める。フェーズを飛ばさない。 完了時は [x] に更新する。

Phase 0 — 基盤と動画素材（3日）

0-1. 初期化

• Next.js 15 / TypeScript strict / App Router / Tailwind で初期化
• ESLint / Prettier / husky（pre-commit で lint + typecheck）
• 10章のディレクトリ構成を作成

0-2. 動画素材の準備（先にこれを終わらせる。素材がないとプレーヤーが作れない）

• 使用する動画を確定する（自社YouTube素材を第一候補）(VID-01)
• scripts/encode.sh を作成（HLS 3レンディション、fMP4、4秒セグメント）
• 12〜16本をエンコードし、サムネイル（ポスター／スプライト／OGP）を生成
• 字幕（WebVTT）を3本以上、うち1本は日英2言語 (VID-05)
• チャプター（WebVTT chapters）を5本以上 (VID-06)
• Cloudflare R2 にアップロードし、CDN経由で配信できることを確認
• CORS と Cache-Control を設定（セグメントは長期、マニフェストは短期）(NFR-11)
• docs/assets-license.md に取得元とライセンスを記録 (VID-02, SEC-01)
• 1本目に解説動画と資料PDFを配置（2章の「動画つき資料」との一体化）

0-3. 型とシード

• lib/types/ に8章の型定義をすべて実装
• lib/seed/ の全ファイル。エピソードの説明文を書き分ける。ダミー文言を残さない
• watchEvents.ts を自然な離脱曲線で生成（冒頭落ち→なだらか減衰→終盤微増）。エピソードごとにパターンを変える
• ペルソナに視聴途中のエピソードを持たせる（「続きから見る」が最初から表示されるように）
• 公開予約されたエピソードを1本含める

0-4. ストアとリポジトリ

• lib/store/{session,content,watch,ui}.ts を Zustand + persist で実装
• lib/repo/_scope.ts に resolveAccess() を実装（FR-608）
• lib/repo/ の全モジュール。全メソッド async、Result型、再生系にはディレイを入れない
• lib/calc/ に 進捗率・離脱率・完了率・継続率 を実装
• resolveAccess() と calc の単体テストをこの時点で書く

0-5. デザインシステム

• app/globals.css にカラートークンを CSS 変数で定義（ダークテーマのみ）
• tailwind.config.ts から CSS 変数を参照するよう theme を拡張
• フォント（Noto Sans JP / Roboto Mono）。時間表示に tabular-nums
• shadcn/ui を導入し、ダークトークンに合わせて上書き
• 共通コンポーネント：ContentCard / Lane / Hero / EmptyState / Skeleton（ダーク用シマー）/ Badge
• prefers-reduced-motion の全体対応
• /dev/components にコンポーネントカタログを作成

0-6. デモ基盤

• RoleSwitcher（4ロール）(FR-601)
• デモ切替バー。アプリがダークなので切替バーは明るいグレー
• 「デモをリセット」(FR-602)
• 元記事へ戻るリンク (FR-604)
• ロール権限外アクセス時の案内画面 (FR-606)

Phase 0 完了チェック

• R2 の動画URLをブラウザで直接開いて再生できる
• /dev/components で全コンポーネントがトークン通りに表示される
• resolveAccess() のテストが全パターン通る

Phase 1 — プレーヤー（5日・最重要フェーズ）

1-1. 再生基盤

• useHls.ts：hls.js の初期化・破棄。Safari はネイティブHLS (FR-101)
• hls.destroy() とイベントリスナー解除を確実に行う（メモリリーク対策）
• VideoPlayer.tsx：再生／一時停止／シーク／音量／ミュート／全画面／PiP (FR-102)
• ControlBar.tsx：scrim グラデーション上に配置
• 自動非表示（3秒。一時停止中・メニュー展開中は隠さない）(FR-115)
• バッファリング表示（映像を暗転させない）(FR-113)
• エラー表示（原因を区別 + 再試行）(FR-114)

1-2. シークと進捗

• SeekBar.tsx：再生済み／バッファ済み／チャプター区切り
• role="slider" と aria-valuetext（「1分24秒」）(A11Y-08)
• シークプレビュー（スプライトからサムネイル抽出 + 時刻 + チャプター名）(FR-111)
• usePlaybackProgress.ts：5秒ごとに進捗保存 (FR-109)
• レジューム再生と「最初から見る」(FR-109)
• 95%以上で「視聴済」判定 (FR-110)

1-3. 設定・字幕・チャプター

• SettingsMenu.tsx：画質（自動／1080/720/360）。切替時に再生位置と再生状態を維持 (FR-103)
• 現在の実効画質の表示（「画質 自動(720p)」）
• 再生速度 5段階 (FR-104)
• CaptionMenu.tsx：オフ／日本語／英語、サイズ・背景の調整 (FR-105, A11Y-03)
• チャプター区切りの表示と現在チャプター名 (FR-106)
• ChapterList.tsx：クリックでジャンプ (FR-107)

1-4. キーボードとモバイル

• useKeyboardShortcuts.ts：Space/K/←→/J/L/↑↓/F/M/C/0-9/? (FR-108)
• ショートカット一覧のオーバーレイ
• モバイル：ダブルタップシーク（波紋アニメーション）、大きめコントロール (FR-116)
• 映像の上でも視認できるフォーカスリング (A11Y-07)

1-5. 視聴画面と埋め込み

• SC-002 視聴画面（エピソード情報、チャプター、添付資料、次の話、同シリーズ）
• NextEpisodeCard.tsx：終了30秒前に表示、カウントダウン、キャンセル可 (FR-112)
• SC-003 埋め込みモード (FR-151〜155)
• ポスター + 再生ボタンのみの初期表示、hls.js の動的import (FR-152, EMB-02, EMB-03)
• 埋め込みモードのバンドルサイズを実測し 80KB以下を確認

Phase 1 完了チェック

• 再生開始まで1.5秒以下（NFR-01）
• 画質を切り替えても再生位置と再生状態が維持される
• キーボードのみでプレーヤーの全操作ができる
• エピソードを10回続けて切り替えてもメモリが単調増加しない（NFR-08）
• 埋め込みモードの初期バンドルが80KB以下

Phase 2 — カタログと会員（4日）

2-1. カタログ

• SC-001 トップ（ヒーロー、続きから見る、カテゴリ別レーン、ランキング、新着）(FR-201)
• Lane.tsx：横スクロール、端で見切れ、矢印、キーボード移動 (FR-202)
• HoverPreview：デスクトップのみ、600ms停留で拡大 + 無音プレビュー (FR-203)
• SC-004 シリーズ詳細（エピソード一覧、各話の進捗、全体進捗率）(FR-204)
• SC-005 カタログ / SC-007 カテゴリ一覧
• SC-006 検索（表記ゆれ吸収）(FR-205)
• 絞り込み（カテゴリ／タグ／再生時間／視聴状態／無料有料）+ URL同期 (FR-206, FR-207)

2-2. マイページ

• SC-010 マイページ / SC-011 視聴履歴 (FR-210) / SC-012 マイリスト (FR-209)
• SC-014 再生設定（既定画質・速度・自動再生・字幕）と再生への適用 (FR-211)

2-3. ペイウォール（デモの見せ場）

• 有料バッジ表示（色ではなく枠線とアイコン）(FR-301)
• プレビュー制限：既定3分で停止 (FR-302)
• 残り時間の常時表示 (FR-303)
• Paywall.tsx：オーバーレイ、プラン概要、CTA、閉じる導線、フォーカストラップ (FR-304, A11Y-10)
• SC-020 プラン比較 (FR-306) / SC-021 申込フォーム (FR-307) / SC-022 完了 (FR-308)
• 加入後、停止位置から続きを再生 (FR-305)
• SC-023 契約状況、変更・解約 (FR-309)

2-4. 添付資料

• AttachmentCard：公開範囲に応じたロック表示 (FR-208, FR-412)
• ロック時は必要プラン名を明示

Phase 2 完了チェック

• フローBが完走する（プレビュー → ペイウォール → 加入 → 続きから再生）
• 5章「ロールを跨ぐ体験」の1が動作する
• 有料バッジがカタログを赤くしていない（9章の配色ルールを満たす）

Phase 3 — 配信管理（4日）

• SC-100 管理ダッシュボード
• SC-111 アップロード：ドロップ、エンコード進捗の段階再現 (FR-401, FR-402)
• 完了後は既存素材に紐付け。デモである旨を明示 (FR-403)
• 変換失敗の再現とリトライ導線 (FR-404)
• SC-112 エピソード編集（基本情報、サムネイル3候補、無料／有料）(FR-405, FR-406)
• 公開設定（下書き／即時／予約／非公開）(FR-407)
• 公開予約日時の到来でカタログに出現（クライアントタイマー）(FR-408)
• 非公開で視聴者側から即座に消える (FR-409)
• SC-113 字幕編集（アップロード、行ごと修正、プレビュー）(FR-410)
• SC-114 チャプター編集（再生位置を見ながら、「現在位置で追加」）(FR-411)
• SC-115 添付資料管理（紐付け、公開範囲）(FR-412)
• SC-120 シリーズ管理（dnd-kit で並び替え、キーボード対応）(FR-413)
• 一括操作（公開／非公開、カテゴリ付与）(FR-414)
• SC-130 会員管理 (FR-415) / SC-131 プラン管理 (FR-416)

Phase 3 完了チェック

• フローCが完走する（アップロード → 編集 → チャプター → 資料 → 公開 → 視聴者側に出現）
• 5章「ロールを跨ぐ体験」の3と4が動作する

Phase 4 — 視聴分析（2日）

• SC-140 視聴分析：再生数・総視聴時間・平均完了率、期間指定 (FR-501)
• RetentionChart：離脱ヒートマップ。大きな離脱区間を強調 + 注釈 (FR-502)
• 完了率のエピソード別ランキング (FR-503)
• デバイス別・画質別の比率 (FR-504)
• シリーズ継続率ファネル (FR-505)
• デモ中の視聴が分析に反映されること (FR-506)
• CSVエクスポート (FR-507)

Phase 4 完了チェック

• 自分が今見た動画の視聴が、離脱ヒートマップに反映される（5章の体験5）
• シードの離脱曲線が自然で、分析画面が意味を持って見える

Phase 5 — 記事統合と仕上げ（3日）

5-1. 記事統合

• 記事側の埋め込みコードを作成し、実際の記事ページで動作確認 (EMB-01〜05)
• 埋め込みが記事の LCP 要素になっていないことを確認 (EMB-04)
• 記事の Core Web Vitals を埋め込み前後で比較し、悪化していないことを確認
• 「デモを開く」カードの設置
• 元記事へ戻るリンク、問い合わせ導線 (EMB-10, EMB-11)
• GA4 イベント設定（demo_open / video_play / video_progress / paywall_view / role_switch / form_click / line_click）(EMB-12, EMB-13)
• ?embed=1 を noindex に (EMB-21)
• デモ本体の title / description / OGP (EMB-20)
• 記事側に VideoObject 構造化データ (EMB-23)

5-2. 体験の総点検

• 5章「ロールを跨ぐ体験」の5パターンをすべて手動で確認
• 全28画面を開き、空の画面が1つもないことを確認
• 空状態・ローディング・エラー状態を全画面で確認
• ガイドツアーを実装 (FR-605)
• localStorage 上限時の処理 (NFR-12)

5-3. アクセシビリティ監査

• axe-core を全画面に実行し、Critical / Serious を0件に
• ダーク背景でのコントラスト比を実測（特に --fg-mid）(A11Y-01)
• キーボードのみで全画面・全プレーヤー操作を完遂
• スクリーンリーダーでプレーヤーの状態変化が読み上げられることを確認 (A11Y-09)

5-4. パフォーマンス

• hls.js / Recharts を動的import に切り出し、初期バンドルを200KB以下に (NFR-06)
• 再生開始1.5秒以下を実測 (NFR-01)
• シークバー操作の60fpsを実測 (NFR-07)
• 5分連続再生でのメモリ推移を計測 (NFR-08)
• Lighthouse で Performance 90 / Accessibility 95 (NFR-09)

5-5. 公開と記録

• Playwright で フローA・B・C の E2E
• Vitest：_scope calc query のカバレッジ80%以上
• /dev/components を本番で非公開に
• Vercel へデプロイ、R2 の転送量アラートを設定 (COST-03)
• 転送量・費用の記録を開始 (COST-01)
• 各フェーズのキャプチャを整理し、記事の「方法」パートの素材にまとめる

合計 21営業日（約4週間）／1名専任 + レビュー体制。 Phase 1（プレーヤー）に5日を割いているのは、ここの完成度がデモの成否そのものだから。既製プレーヤーを貼れば1日で済むが、それでは「Claude Codeで動画配信アプリが作れる」の証明にならない。

14. 受入基準

1. 7章の優先度 P1 の要件がすべて実装されていること
2. 6章の主要フローA・B・Cが、エンドツーエンドで完走すること
3. 5章「ロールを跨ぐ体験」の5パターンがすべて動作すること
4. 再生ボタン押下から1.5秒以内に最初のフレームが表示されること
5. 画質・速度・字幕・チャプターのすべてが動作し、画質切替で再生位置と再生状態が維持されること
6. プレーヤーの全操作がキーボードのみで完遂できること
7. レジューム再生が動作し、リロード後も停止位置から再開できること
8. ペイウォールが動作し、加入後に停止位置から続きが再生されること
9. エピソードを10回連続で切り替えてもメモリが単調増加しないこと
10. 埋め込みモードの初期バンドルが80KB以下で、記事のCore Web Vitalsを悪化させないこと
11. デモ中の視聴が視聴分析に反映され、離脱ヒートマップが意味のある形状で表示されること
12. 全28画面のいずれにも空の状態がなく、リアルなコンテンツが表示されていること
13. axe-core で Critical / Serious の指摘が0件であること
14. 動画・画像素材のライセンスが docs/assets-license.md にすべて記録されていること
15. データアクセスがすべて lib/repo/ を経由し、視聴可否の判定が resolveAccess() に集約されていること
16. HIREBASE / RELATE と並べたときに、明確に別のプロダクトとして見えること

判断に迷ったときのルール

1. 仕様がこの文書にない場合は、実装せずに質問する。 推測で作らない
2. プレーヤーの品質と、キーボード操作、空の画面を作らないことは削減対象外
3. 既製のプレーヤーライブラリ（video.js / Plyr 等）を導入しない。 自前実装であることがこのデモの価値
4. スコープ外（4章 Won't have）は、思いついても実装しない。特にライブ配信とDRM
5. 「デモだから」を理由に品質を落とす判断はしない
6. hls.js とイベントリスナーの破棄を忘れない。このアプリで最も起きやすい不具合はメモリリーク
7. HIREBASE / RELATE のトークン・コンポーネントをコピーしない