feature-video

機能の動画デモ

ブラウザー操作を記録して機能を紹介し、スクリーンショットをつなぎ合わせて MP4 動画を作成し、GitHub に直接アップロードして、PR の説明にインライン動画プレーヤーとして埋め込みます。

前提条件

• ローカル開発サーバーが起動していること（例：bin/dev、npm run dev、rails server）
• agent-browser CLI がインストールされていること（詳細は agent-browser スキルを読み込んでください）
• ffmpeg がインストールされていること（動画変換用）
• リポジトリへのプッシュ権限を持つ gh CLI で認証済みであること
• 機能ブランチにある Git リポジトリであること（PR は任意です。スキルでドラフト PR を作成するか、記録のみ行うことができます）
• GitHub のブラウザー認証を一度済ませていること（認証の確認は手順 6 を参照）

主なタスク

1. 引数を解析して PR を特定する

引数： $ARGUMENTS

入力を解析します：

• 第 1 引数：PR 番号、「current」（現在のブランチの PR がデフォルト）、または既存の .mp4 ファイルへのパス（アップロードのみの再開モード）
• 第 2 引数：ベース URL（デフォルトは http://localhost:3000）

アップロードのみの再開： 第 1 引数が .mp4 で終わり、ファイルが存在する場合は、手順 2〜5 をスキップし、そのファイルを使って手順 6 に進みます。現在のブランチから PR 番号を特定します（gh pr view --json number -q '.number'）。

明示的な PR 番号が指定された場合は、その PR の存在を確認し、直接使用します：

gh pr view [number] --json number -q '.number'

明示的な PR 番号が指定されていない場合（または「current」が指定された場合）は、現在のブランチに PR があるか確認します：

gh pr view --json number -q '.number'

現在のブランチに PR がない場合は、どう進めるかユーザーに尋ねます。プラットフォームのブロッキング質問ツール（Claude Code では AskUserQuestion、Codex では request_user_input、Gemini では ask_user）を使用してください：

No PR found for the current branch.

1. Create a draft PR now and continue (recommended)
2. Record video only -- save locally and upload later when a PR exists
3. Cancel

オプション 1 の場合：ブランチ名から仮のタイトルを作成してドラフト PR を作成し、新しい PR 番号で続行します：

gh pr create --draft --title "[branch-name-humanized]" --body "Draft PR for video walkthrough"

オプション 2 の場合：RECORD_ONLY=true を設定します。手順 2〜5（記録とエンコード）を実行し、手順 6〜7（アップロードと PR の更新）をスキップして、最後にローカル動画のパスと [RUN_ID] を報告します。

アップロードのみの再開： 以前に記録した動画をアップロードするには、既存の動画ファイルのパスを第 1 引数に指定します（例：/feature-video .context/compound-engineering/feature-video/1711234567/videos/feature-demo.mp4）。第 1 引数が .mp4 ファイルのパスの場合は、手順 2〜5 をスキップし、そのファイルを使って手順 6 に直接進みます。

1b. 必要なツールを確認する

続行する前に、必要な CLI ツールがインストールされているか確認します。スクリーンショットを記録した後にワークフローの途中で失敗するのではなく、明確なメッセージを表示して早めに終了してください：

command -v ffmpeg

command -v agent-browser

command -v gh

ツールが不足している場合は、インストールが必要なツールを報告して停止します：

• ffmpeg：brew install ffmpeg（macOS）または同等の方法
• agent-browser：インストール手順については agent-browser スキルを読み込んでください
• gh：brew install gh（macOS）または https://cli.github.com を参照してください

すべてのツールが利用可能になるまで、手順 2 に進まないでください。

2. 機能のコンテキストを収集する

PR がある場合は、PR の詳細と変更されたファイルを取得します：

gh pr view [number] --json title,body,files,headRefName -q '.'

gh pr view [number] --json files -q '.files[].path'

記録のみのモード（PR なし）の場合は、デフォルトブランチを検出し、ブランチの差分からコンテキストを導き出します。変数が保持されるよう、両方のコマンドを単一のブロックで実行します：

DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q '.defaultBranchRef.name') && git diff --name-only "$DEFAULT_BRANCH"...HEAD && git log --oneline "$DEFAULT_BRANCH"...HEAD

変更されたファイルを、デモで表示するルートやページに対応付けます。プロジェクトのルーティング設定（例：routes.rb、next.config.js、app/ ディレクトリ構造）を調べ、変更されたファイルに対応する URL を特定します。

3. 動画の流れを計画する

録画する前に、ショットリストを作成します。

1. オープニングショット：ホームページまたは開始地点（2～3 秒）
2. ナビゲーション：ユーザーが機能にたどり着くまでの手順
3. 機能のデモ：中核となる機能（メインの見どころ）
4. エッジケース：エラー状態、検証など（該当する場合）
5. 成功状態：完了した操作や結果

録画を始める前に、提案する流れをユーザーに提示し、確認を得てください。

利用可能な場合は、プラットフォームのブロッキング質問ツールを使用してください（Claude Code の AskUserQuestion、Codex の request_user_input、Gemini の ask_user）。利用できない場合は、番号付きの選択肢を提示し、先に進む前にユーザーの返答を待ってください。

Proposed Video Flow for PR #[number]: [title]

1. Start at: /[starting-route]
2. Navigate to: /[feature-route]
3. Demonstrate:
   - [Action 1]
   - [Action 2]
   - [Action 3]
4. Show result: [success state]

Estimated duration: ~[X] seconds

1. Start recording
2. Modify the flow (describe changes)
3. Add specific interactions to demonstrate

4. ウォークスルーを録画する

一意の実行 ID（タイムスタンプなど）を生成し、実行ごとの出力ディレクトリを作成します。これにより、前回の実行で作成された古いスクリーンショットが新しい動画に混在するのを防げます。

**重要：**シェル変数は、別々のコードブロック間では保持されません。実行 ID を生成したら、このワークフロー内の以降のすべてのコマンドに、具体的な値を代入してください。たとえば、タイムスタンプが 1711234567 の場合、以下のすべてのパスでその値を直接使用し、後続のブロックで [RUN_ID] が展開されることに頼らないでください。

date +%s

出力を RUN_ID として使用します。具体的な値を指定してディレクトリを作成します。

mkdir -p .context/compound-engineering/feature-video/[RUN_ID]/screenshots
mkdir -p .context/compound-engineering/feature-video/[RUN_ID]/videos

計画した流れを実行し、各手順を agent-browser でキャプチャします。フレームの順序が正しくなるよう、スクリーンショットには連番を付けてください。

agent-browser open "[base-url]/[start-route]"
agent-browser wait 2000
agent-browser screenshot .context/compound-engineering/feature-video/[RUN_ID]/screenshots/01-start.png

agent-browser snapshot -i
agent-browser click @e1
agent-browser wait 1000
agent-browser screenshot .context/compound-engineering/feature-video/[RUN_ID]/screenshots/02-navigate.png

agent-browser snapshot -i
agent-browser click @e2
agent-browser wait 1000
agent-browser screenshot .context/compound-engineering/feature-video/[RUN_ID]/screenshots/03-feature.png

agent-browser wait 2000
agent-browser screenshot .context/compound-engineering/feature-video/[RUN_ID]/screenshots/04-result.png

5. 動画を作成する

手順 4 と同じ [RUN_ID] を使って、スクリーンショットを結合し、MP4 を作成します。

ffmpeg -y -framerate 0.5 -pattern_type glob -i ".context/compound-engineering/feature-video/[RUN_ID]/screenshots/*.png" \
  -c:v libx264 -pix_fmt yuv420p -vf "scale=1280:-2" \
  ".context/compound-engineering/feature-video/[RUN_ID]/videos/feature-demo.mp4"

補足：

• -framerate 0.5 は 1 フレームあたり 2 秒です。再生速度を上げたり下げたりする場合は調整してください。
• scale の -2 は、高さが 2 で割り切れるようにします（H.264 で必要です）。

6. GitHub で認証してアップロードする

アップロードによって user-attachments/assets/ の URL が生成されます。この URL は、PR エディターに動画を手動で貼り付けた場合と同様に、GitHub 上でネイティブのインライン動画プレーヤーとして表示されます。

手順：既存の agent-browser セッションがあれば終了し、保存済みの GitHub 認証情報を使って Chrome エンジンのセッションを開始します。PR ページに移動し、コメントフォームの非表示ファイル入力に動画ファイルを設定します。GitHub がアップロードを処理するまで待ち、生成された URL を取得したら、送信せずにテキストエリアをクリアします。

既存のセッションを確認する

まず、保存済みの GitHub セッションがあるか確認します。

agent-browser close
agent-browser --engine chrome --session-name github open https://github.com/settings/profile
agent-browser get title

ページタイトルにユーザーの GitHub ユーザー名または「Profile」が含まれている場合は、セッションがまだ有効です。「動画をアップロードする」に進んでください。ログインページにリダイレクトされる場合は、セッションの有効期限が切れているか、まだ作成されていません。「認証の設定」に進んでください。

認証の設定（初回のみ）

GitHub の認証済みセッションを確立します。--session-name フラグによってセッション Cookie が実行間で保持されるため、これは一度だけ行えば十分です。

現在のセッションを終了し、画面表示ありの Chrome ウィンドウで GitHub のログインページを開きます。

agent-browser close
agent-browser --engine chrome --headed --session-name github open https://github.com/login

ユーザーはブラウザーウィンドウで手動ログインする必要があります（2FA、SSO、OAuth など、あらゆるログイン方法に対応します）。プラットフォームのブロッキング質問ツールを使用してください（Claude Code の AskUserQuestion、Codex の request_user_input、Gemini の ask_user）。利用できない場合はメッセージを提示し、先に進む前にユーザーの返答を待ってください。

GitHub login required for video upload.

A Chrome window has opened to github.com/login. Please log in manually
(this handles 2FA/SSO/OAuth automatically). Reply when done.

ログイン後、セッションが機能することを確認します。

agent-browser open https://github.com/settings/profile

プロフィールページが読み込まれれば、認証は確認済みです。github セッションが保存され、再利用できるようになりました。

動画をアップロードする

PR ページに移動し、コメントフォームまでスクロールします。

agent-browser open "https://github.com/[owner]/[repo]/pull/[number]"
agent-browser scroll down 5000

アップロードする前に、既存のテキストエリアの内容を保存します（コメントボックスに未送信の下書きが残っている場合があります）。

agent-browser eval "document.getElementById('new_comment_field').value"

この値を SAVED_TEXTAREA として保存します。空でない場合は、アップロード URL を抽出した後に復元します。

非表示のファイル入力欄から動画をアップロードします。アップロードのみの再開モードでは呼び出し元から渡された .mp4 パスを使用し、それ以外では現在の実行でエンコードされた動画を使用します。

agent-browser upload '#fc-new_comment_field' [VIDEO_FILE_PATH]

ここで、[VIDEO_FILE_PATH] は次のいずれかです。

• 最初の引数として渡された .mp4 パス（アップロードのみの再開モード）
• .context/compound-engineering/feature-video/[RUN_ID]/videos/feature-demo.mp4（通常の録画フロー）

GitHub がアップロードを処理するまで待ち（通常は 3～5 秒）、その後テキストエリアの値を読み取ります。

agent-browser wait 5000
agent-browser eval "document.getElementById('new_comment_field').value"

抽出した URL を検証します。 アップロードが正常に完了したことを確認するため、値に user-attachments/assets/ が含まれている必要があります。テキストエリアが空の場合、プレースホルダーテキストのみが含まれている場合、または URL が一致しない場合は、ステップ 7 に進まないでください。代わりに、次の操作を行います。

1. agent-browser get url を確認します。github.com/login と表示される場合は、セッションの有効期限が切れています。認証のセットアップをもう一度実行してください。
2. まだ PR ページにいる場合は、さらに 5 秒待ってからテキストエリアを再度読み取ります（GitHub の処理に時間がかかることがあります）。
3. 再試行後も検証に失敗した場合は、失敗したこととローカルの動画パスをユーザーに伝え、手動でアップロードできるようにします。

元のテキストエリアの内容を復元するか、空だった場合はクリアします。JSON エンコードされた文字列も有効な JavaScript 文字列リテラルなので、JSON.parse を使わずにそのまま代入します。

agent-browser eval "const ta = document.getElementById('new_comment_field'); ta.value = [SAVED_TEXTAREA_AS_JS_STRING]; ta.dispatchEvent(new Event('input', { bubbles: true }))"

値を準備するには、SAVED_TEXTAREA 文字列をもとに JS 文字列リテラルを作成します。バックスラッシュ、二重引用符、改行をエスケープしてください（例："text with \"quotes\" and\nnewlines"）。SAVED_TEXTAREA が空だった場合は "" を使用します。結果は代入文の右辺に直接埋め込みます。JSON.parse の呼び出しは不要です。

7. PR の説明を更新する

現在の PR 本文を取得します。

gh pr view [number] --json body -q '.body'

Demo セクションを追加するか、既存のものを置き換えます。動画 URL を独立した行に配置すると、インラインプレーヤーとして表示されます。

## Demo

https://github.com/user-attachments/assets/[uuid]

*Automated video walkthrough*

PR を更新します。

gh pr edit [number] --body "[updated body with demo section]"

8. クリーンアップ

一時ファイルを削除する前に、ユーザーに確認してください。確認が取れたら、現在の実行の作業用ディレクトリのみをクリーンアップします（ほかの実行がまだ進行中、またはアップロード待ちの場合があります）。

動画のアップロードに成功した場合は、実行ディレクトリ全体を削除します。

rm -r .context/compound-engineering/feature-video/[RUN_ID]

録画のみのモードの場合、またはアップロードに失敗した場合は、スクリーンショットのみを削除し、後でユーザーがアップロードできるよう動画を残します。

rm -r .context/compound-engineering/feature-video/[RUN_ID]/screenshots

完了の概要を提示します。

Feature Video Complete

PR: #[number] - [title]
Video: [VIDEO_URL]

Shots captured:
1. [description]
2. [description]
3. [description]
4. [description]

PR description updated with demo section.

使用例

# Record video for current branch's PR
/feature-video

# Record video for specific PR
/feature-video 847

# Record with custom base URL
/feature-video 847 http://localhost:5000

# Record for staging environment
/feature-video current https://staging.example.com

ヒント

• 短くまとめましょう。PR のデモには 10～30 秒が理想的です。
• 変更点に集中し、関係のない UI は含めないでください。
• 変更前と変更後を見せましょう。バグ修正の場合は、可能であれば最初に不具合のある状態を見せてください。
• --session-name github セッションは、GitHub が Cookie を無効にすると有効期限が切れます（通常は数週間）。ログインページにリダイレクトされてアップロードに失敗した場合は、認証のセットアップをもう一度実行してください。
• GitHub の DOM セレクター（#fc-new_comment_field、#new_comment_field）は、GitHub が UI を更新すると変更されることがあります。アップロードが何も表示されずに失敗した場合は、PR ページを確認してセレクターが更新されていないか調べてください。

トラブルシューティング

症状	原因	対処方法
ffmpeg: command not found	ffmpeg がインストールされていません	brew install ffmpeg（macOS）または同等の方法でインストールしてください
agent-browser: command not found	agent-browser がインストールされていません	インストール手順を確認するには、agent-browser スキルを読み込んでください
アップロード待機後にテキストエリアが空です	セッションの有効期限が切れているか、GitHub の処理が遅れています	セッションが有効か確認してください（手順 6 の認証チェック）。有効な場合は、待機時間を延ばして再試行してください。
テキストエリアが空で、URL が github.com/login です	セッションの有効期限が切れています	認証設定を再実行してください（手順 6）
gh pr view が失敗します	現在のブランチに PR がありません	手順 1 で、ドラフト PR を作成するか、記録のみのモードを選択してください
アップロードするには動画ファイルが大きすぎます	GitHub の制限である 10MB（無料プラン）または 100MB（有料プラン）を超えています	再エンコードしてください。フレームレートを下げる（-framerate 0.33）、解像度を下げる（scale=960:-2）、または CRF を上げる（-crf 28）方法があります
アップロード URL に user-attachments/assets/ が含まれていません	アップロード方法が間違っているか、GitHub に変更がありました	PR ページを調べて、ファイル入力セレクターが正しいことを確認してください