omar520/system-training-videos

システムトレーニング動画

Webシステムの実際の操作を収録し、完成されたトレーニング動画に変換します。チャプターごとの短い動画と、チャプターマーカー付きの完全版動画を1本生成します。音声はありません。短いコールアウトで何が行われているか、なぜそうするのかを説明します。

この手法は固定されています。なぜなら、各部分が実際の録画における問題を解決するためです。変更されるのはシステムごとの見た目だけです。

すべてのシステムで共通	システム自体から取得
1920 × 1080 動画、30フレーム/秒、MP4	カードとコールアウトの色（ページから読み取り）
タイトルカード：ロゴ、キッカー、タイトル、1行、カラーバンド	ハイライト、矢印、クリックリングの色
矢印付きコールアウトボックス、要素のハイライト	見出しと本文のフォント（Webフォントを含む）
隅の「Step n of N」カウンター	ボタンの角丸
スローカーソル、クリックリング、スムーズズーム、読み込み中のジャンプカット	ロゴ
コード生成の効果音	背景に応じた明るい/暗いコールアウト
完全版動画の黒いチャプターカードとマーカー	言語と右から左へのテキスト

ルールとその理由

• 架空のデータのみを使用したローカルコピー。 スクリプトは実際にクリックして保存を行うため、動画は誰とでも共有できます。エンジンはローカルアドレス以外を拒否します。allowRemote: true を設定できるのはシステムの所有者のみで、実際のデータを含まないテストサーバーに限ります。本番システムには絶対にポイントせず、実際の人物の名前、メールアドレス、ドキュメントを決して表示しないでください。
• アプリケーションは変更しません。 すべてはプロジェクトの video-tour/ フォルダに配置され、独自のパッケージを持ちます。アプリケーションを変更せずにジョブを表示できない場合は、そのジョブを省略して報告してください。
• 動画はリポジトリの外に保存します。 リポジトリ外のフォルダに出力します。
• プロジェクト独自のルールに従います。 最初にプロジェクトの CLAUDE.md または類似のファイルを読みます。所有者が git を実行すると指定されている場合は、git を実行しないでください。小規模なマシンでは、一度に1つの負荷の高いジョブのみを実行します。
• システムができないことを偽造しません。 日付、外部サービス、または回答が変動する機能（チャットボット）に依存するジョブは省略し、報告します。録画前に準備されたデータは、レポートで開示します。

ステップ1：必要なものを一度に収集する

最初にプロジェクト内を確認します：README、package.json、ドキュメント、シードデータ、テストアカウント。その後、不足しているものをすべて1つのリストで質問し、最初の回答が得られるまで再度質問するのを止めないでください。

• システムをローカルで起動する方法とそのアドレス。
• テストデータをリセットする方法。リセットしないと、チャプターが互いのデータと衝突します。
• 動画に必要なロールごとのテストアカウント。
• 動画の視聴者。これにより、どのジョブが重要か、カードに記載する言葉が決まります。
• コールアウトの言語。デフォルト：システム画面の言語。
• 動画の出力先。デフォルト：プロジェクトの隣のフォルダ。

ステップ2：システムを学習し、チャプターを計画する

ルート、メニュー、ユーザードキュメントを読み、実行中のシステムのページを開きます。次にチャプター計画を作成します。各チャプターは、ユーザーが実際に作業するエリアごとに1つずつ、画面のツアーではなくジョブ（「注文を作成して承認に送る」など）を中心に構成します。チャプターは通常2～6ステップで、1～4分の長さです。「はじめに」のチャプターから始めます。省略する予定のものとその理由をリストアップします。

ステップ3：セットアップとシステムの外観の読み取り

node ~/.claude/skills/system-training-videos/scripts/init.mjs <プロジェクトフォルダ> --out "<動画フォルダ>"
cd <プロジェクトフォルダ>/video-tour && npm install && npx playwright install chromium

video-tour/tour.config.mjs 内のすべての TODO を記入します。次のコマンドを実行してサインインが機能することを確認します。

node video-tour/tour.mjs brand

これによりシステムにアクセスし、その外観を読み取り、theme.json とロゴを書き込み、<動画フォルダ>/_work/brand/ に4つのプレビューを保存します：title-card.png、chapter-card.png、callout.png、counter.png。4つすべてを確認します。 色検出は正確な事実ではなく優れた推測に過ぎないため、視聴者の目で判断します：これはシステムのように見えますか？正しいロゴですか？見出しは実際のフォントですか？設定の theme で何かを修正し、その後 brand を再実行します。references/theme-and-config.md を参照してください。

ステップ4：チャプター1、そして1回の承認

チャプター1を記述し（最初に references/writing-chapters.md を読む）、次に以下を実行します。

node video-tour/tour.mjs make 1

make はデータをリセットし、高速リハーサルを行い、再度リセットし、録画、ビルド、チェックを実行します。表示される静止画とコンタクトシートを確認します。

その後、いったん停止し、チャプター計画、省略したジョブ、および静止画を所有者に見せます。これが唯一の承認ポイントです。今の段階でルックや計画を変更するのは安価ですが、シリーズ全体の後に変更するのは高くつきます。承認後は、停止せずにシリーズを完了します。

ステップ5：その他のチャプター

各チャプターについて：記述し、make を実行し、そのコンタクトシートを確認します。check は測定可能な問題を捕捉します：2.5秒未満の画面コールアウト、カメラに映る読み込み画面、ブラウザエラー、サウンドレベル。意味を理解することはできないため、以下の点について自分でフレームを確認します。

• 誤った要素に、または画面端で切れて表示されているコールアウト。
• 視聴者が見る必要のあるものを覆っているコールアウト、カウンター、またはポップアップ。
• エラーメッセージ、空のページ、または架空でないもの。
• 表示すべきものを切り落としているズーム。

シートに疑問がある場合は、完全なフレームを1つ取得します：ffmpeg -ss 20 -i chapter.mp4 -frames:v 1 frame.png。

2回の修正後もチャプターが失敗する場合は、そのチャプターをスキップし、報告し、先に進みます。以前に見られた問題は references/troubleshooting.md にあります。

ステップ6：完全版動画

すべてのチャプターがビルドされ、システムが実行されている状態で：

node video-tour/tour.mjs join

これにより、オープニングカード、各チャプターの前の黒いカード、クロージングカード、チャプターマーカー、および chapters.txt（「00:00 Title」行、YouTube向け）を含む <name>-training.mp4 が書き出されます。長さとマーカーを確認します。

ffprobe -v error -show_entries chapter=start_time:chapter_tags=title -of csv=p=0 <完全版動画>

ステップ7：報告書

技術者ではない人向けに、短い文で作成します。

1. 各チャプターと完全版動画のパスと長さを表形式で。
2. チャプターごとに1つの静止画が含まれるフォルダ。
3. 開始時刻付きのチャプターリスト。
4. 省略またはスキップしたものとその理由。
5. 録画前に準備されたが動画には表示されないデータ。
6. 確認した上で許容した小さな視覚的な欠陥。
7. サウンドは聴覚ではなく測定によって確認したため、共有前に誰かが1チャプターを聴くべきであること。

その後、起動したサーバーを停止します。

参照ファイル

• references/writing-chapters.md：チャプターを記述する前に読むこと。すべてのアクション、動画をクリーンに保つパターン、およびコールアウトの書き方。
• references/theme-and-config.md：設定、brand が読み取る内容、およびルックの修正方法。
• references/troubleshooting.md：録画が失敗した場合やフレームがおかしい場合に読むこと。