動画制作ワークフロー
これは、このリポジトリ内で新しい動画を制作するための唯一の制作ワークフローです。video-directorが最終結果とステータスを所有します。リサーチとライティング技法については.claude/skills/viral-tech-video-creator/SKILL.mdを、ショット、モーション、サウンドのリファレンスについては.claude/skills/video-shotcraft/SKILL.mdを参照してください。これらのリソースが本ファイルと矛盾する場合は、本ファイルに従ってください。作業を開始する前にCLAUDE.mdと選択したリファレンスを読んでください。返答はベトナム語で、コードは英語で記述してください。
このワークフローは完全自動です。エージェントが自ら制作、レビュー、承認を行い、どのステップもユーザーの手動承認を待ちません。「gửi bạn nghe thử / duyệt giúp / OK chưa」でターンやエージェントレポートを終了しないでください。最適なオプションを選択し、決定事項をdocs/<vid>/に記録して先に進んでください。クリティカルな入力が不足しており安全に推測できない場合、またはユーザーが明示的に決定ゲートを要求した場合のみ、ユーザーに問い合わせてください。人間によるリスニング（音声、最終MP4）はオプションの記録であり、質問やブロッカーではありません。独立したレビュアーはクリーンなコンテキストを使用します。ユーザーが必須とマークした行のみをそのまま保持し、それ以外はストーリーのために脚色または書き換えても構いません（よくある失敗ポイントのゲートAの教訓を参照）。公開には別途ユーザーリクエストが必要です。
軽量モード。 短いstory動画の場合、またはユーザーがスクリプト/音声を提供した場合、ディレクターは各ゲートを省略せずにステップを統合できます。research-agent1つ、ユーザーアカウントがソースの場合はリサーチファイルなし、フェーズ3の3つのブランチを1つの並列メッセージで、task-plannerと3～4ショットにつき1つのscene-agent。ゲートA、D、E、B、C、コンテンツと音声ブランチのレビュー、修正ループの規律、ファイル所有権は常に維持されます。
パイプラインマップ
ゲートAの後、作業は3つの並列ブランチ（コンテンツ、音声、デザイン）に分岐し、各ブランチは独自のプロデューサー→クリーンコンテキストレビュアループを持ちます。3つすべてが合格すると、video-directorがそれらを結合し、ゲートEが結合計画をレビューしてからビルドに入ります。
flowchart TD
P0["0 インテーク<br/>intake-agent ×2-3"] --> P1["1 リサーチ<br/>research-agent ×N"]
P1 --> P2["2 スクリプト<br/>script-agent"]
P2 --> A{"ゲートA ≥ 9<br/>script-reviewer"}
A -- "修正 (≤3ラウンド)" --> P2
A -- 合格 --> FORK(("分岐"))
subgraph BR["3 · 3つの並列ブランチ"]
direction LR
subgraph B1["3a コンテンツ"]
CA["content-agent<br/>content-pack.md"] --> CR{"content-reviewer ≥ 9"}
CR -- 修正 --> CA
end
subgraph B2["3b 音声"]
VA["voice-agent + audio-agent<br/>sN.mp3, BGM/SFX, ミックス計画"] --> AR{"audio-reviewer ≥ 9"}
AR -- 修正 --> VA
end
subgraph B3["3c デザイン"]
DA["design-agent<br/>プロト、スタイルフレーム、カバー、ボード"] --> DR{"ゲートD ≥ 9<br/>design-reviewer"}
DR -- 修正 --> DA
end
end
FORK --> CA
FORK --> VA
FORK --> DA
CR -- 合格 --> J
AR -- 合格 --> J
DR -- 合格 --> J
J["4 結合<br/>video-director: voice.json, timeline.ts,<br/>タイミング/テキスト/ムードの調整"] --> E{"ゲートE ≥ 9<br/>integration-reviewer"}
E -- "チケット → 所有ブランチ" --> BR
E -- 合格 --> P6["6 タスク<br/>task-planner"]
J -.->|早期スキャフォールド| P7
P6 --> B{"ゲートB ≥ 8<br/>task-reviewer"}
B -- 合格 --> P7["7 ビルド<br/>scene-agent ×N"]
P7 --> P8["8 QA<br/>qa-agent ×N"]
P8 --> P9["9 レンダリング<br/>render-agent"]
P9 --> C{"ゲートC ≥ 8 · 最終バリア<br/>MP4の完全再テスト<br/>final-check.md すべて✓ + video-reviewer ×3"}
C -- "修正 → 所有者、再レンダリング、全て再テスト" --> P7
C -- 合格 --> P10["10 納品<br/>video-director"]
テキスト代替: 0 インテーク → 1 リサーチ → 2 スクリプト ⇒ A → 分岐[ 3a content-agent ⇒ content-reviewer | 3b 音声+オーディオ ⇒ audio-reviewer | 3c design-agent ⇒ D ] → 4 結合 → E → 6 タスク ⇒ B → 7 ビルド → 8 QA → 9 レンダリング ⇒ C → 10 納品。
契約と命名規則
- 動画には一意の小文字ケバブケースのトピックID
<vid>、音声スラッグ<voice>、docs/<vid>/、src/<vid>/、public/audio/<vid>/、out/qa/<vid>-*.pngが存在します。 - 唯一の最終動画は
out/<vid>-<voice>-reel.mp4です。例:out/cam-on-phien-ban-minh-anh-khoi-reel.mp4。音声スラッグは実際に聞こえる音声を説明します。音声が変わった場合は、レンダリング前にpython3 -I scripts/pipeline.py voice <vid> <new-voice>を実行してください。以前のファイルはそのまま残ります。 - カタログプレビューが解決することを確認するために、
python3 -m unittest scripts.test_voice_catalogから開始してください。vietnamese-voice-samples/previews/から候補を選択します（フォルダがカタログです。ファイル名は短縮された音声名です）。カタログの説明とユーザーのリクエストに基づいて選択し、プロバイダーとその音声IDをbrief.mdに記録してください。プレビュー自体は商用権やクローン権を付与するものではありません。 - フェーズ0の重複トピックチェックがクリアされた後、一度だけ初期化します:
python3 -I scripts/pipeline.py init <vid> --comp <CompId> --voice <voice> --profile story|product|knowledge|news。新規制作には--voiceが必須です。最良の現時点での推測を渡し、ルートが決定次第pipeline.py voice <vid> <slug>を実行してください（スラッグは実際に聞こえる音声を指定する必要があります）。--outはレガシーな出力名のためだけに使用します。制作エージェントをディスパッチする前に、ポート4180でパイプラインモニターを起動または再利用してください。status.jsonを手動で編集しないでください。 - 各作業ステージの前後に
pipeline.py set <vid> <stage> in_progressを呼び出し、その後done、blocked、またはfailedを呼び出します。ステージはresearch, brief, script, content, voice, design, build, audio, qa, renderです（contentはワークフローv3から存在し、initが作成します。ゲートAのみレビュー済みの進行中のv2動画はpipeline.py upgrade <vid>でv3に移行します）。renderコマンドは自身のステージを更新します。レビューゲートは A → [content · audio · D] → E → B → C の順序で実行されます。2つのブランチレビューはゲートと同様に記録され（review <vid> content|audio …、gate <vid> content|audio、上限3でoverride）、ゲートEはコンテンツ、audio、Dのすべてが承認されるまで拒否します。ゲートA、content、audio、D、Eは 9/10、BとCは8で合格です（pipeline.pyがスコアを強制します）。 - エージェントアクティビティ（モニターを駆動）。
video-directorがエージェントをディスパッチするたびに、pipeline.py agent <vid> <agent-name> running --stage <stage> --note "<task>"を実行します。完了通知が届いたら、pipeline.py agent <vid> <agent-name> done（またはfailed）を実行します。並列コピーには番号付きの名前を使用します（scene-agent-1、research-agent-2）。これらの記録がないと、モニターはステージ状態から推測するしかなく、レビュアーが表示されません。ゲートは、スコアがしきい値に達し、かつCao/Trungチケットが開いていない場合にのみ合格します（修正ループの規律を参照）。pipeline.pyはチケットを確認できないため、レビュアーはチケットが開いている間は--verdict reviseを設定します。
| フェーズ | 設定するステージ | ゲート/チェックポイント |
|---|---|---|
| 0 インテーク | — (init) | — |
| 1 リサーチ | research | — |
| 2 スクリプト | brief, script | A |
| 3a コンテンツブランチ | content | review content (content-reviewer) |
| 3b 音声ブランチ | voice, audio | review audio (audio-reviewer, 機械判定) |
| 3c デザインブランチ | design | D |
| 4 結合 | — (ディレクター統合) | — |
| 5 統合 | (所有ステージが修正で再開) | E |
| 6 タスク | build → in_progress | B |
| 7 ビルド | build, audio (ミックス統合) | — |
| 8 QA | qa | — |
| 9 レンダリング | render (自動) | C (人間のリスニング = オプションの記録) |
ステージを再開する（in_progress/blocked/failed）と、以下からのレビューが無効になります: research/brief/script → A（および両方のブランチレビュー）、content → review content + E以降、voice → review audio + E以降、design → D以降、build/audio/qa/render → C。新しいレビューエントリはそれ以降のすべてを無効にします（ブランチレビューはE、B、Cを再開します）。無効になったすべてのゲートを順番に再実行してください。
- 異なる動画は、異なるID、音声フォルダ、QAプレフィックス、出力を使用する場合、同時に実行できます。1つの動画で作業するエージェントは互いに重複しないシーンファイルを所有します。
video-directorのみがkit、timeline、Reel、Root、音声JSONを編集します。パイプラインは1つのステータスと1つの出力名への書き込みを直列化します。
エージェント一覧とハンドオフ
video-director はパイプラインの所有者兼情報マネージャーです。ステータスを初期化し、現在のブリーフ/スクリプト/ソースの決定を唯一の真実の情報源として保持し、プロファイルを選択し、ファイルを割り当て、作業を統合し、ゲートコマンドを実行し、結果を納品します。各スペシャリストには、承認されたブリーフ、正確な入力、期待される出力パス、および受入チェックを提供してください。ハンドオフ時に、video-director は返されたアーティファクトをこれらの入力と照合し、決定事項または未解決の質問を docs/<vid>/ に記録し、ステータスを更新し、承認されたバージョンのみを次のスペシャリストに渡します。レビュアーはクリーンなコンテキストを持ち、スコアを付けるアーティファクトを生成したエージェントであってはなりません。video-director は自身の作業をスコアリングしません。
video-director はメインの会話スレッド（あなた）であり、サブエージェントではありません。 以下のすべてのエージェントを管理します。ディスパッチ、承認された入力の受け渡し、修正のルーティング、共有ファイルの統合、ステータス/ゲートの記録、ユーザーとの対話を行います。各フェーズは独自の名前付きエージェントによって実行されます。レビュアーエージェントは独立しており、クリーンなコンテキストを持ち、各ラウンドで新しく作成されます。
| フェーズ | プロデューサーエージェント | レビュアーエージェント（ゲート） | 所有し返却するもの |
|---|---|---|---|
| 0 インテーク | intake-agent（読み取り専用） | — | 重複トピックレポート、事前チェック結果。ディレクターが brief.md ヘッダーを書き込みます。クリティカルな入力が不足している場合のみユーザーに問い合わせます |
| 1 リサーチ | research-agent（ソースグループごとに×N） | — | research.md または research-<group>.md: ソース、視聴者の言語、事実/推論/不明点、5つのフック候補 |
| 2 スクリプト | script-agent | script-reviewer (A) | brief.md、script.md、voice.proposed.json / script-review.md |
| 3a コンテンツ | content-agent | content-reviewer (ブランチ) | content-pack.md: ショットごとのオンスクリーンテキスト、キャプションチャンク、アクセントワード、カバー/リフック/CTAテキスト、主張→ソーステーブル、minh hoạ ラベル / content-pack-review.md |
| 3b 音声 | voice-agent + audio-agent | audio-reviewer (ブランチ、機械判定) | sN.mp3 + 継続時間 + ASR (voice-report.md); BGM/SFX + ビートグリッド + ミックス計画 + assets-manifest.md / audio-review.md |
| 3c デザイン | design-agent | design-reviewer (D) | design-spec.md + プロトタイプ + 3スタイルフレーム + カバー + ストーリーボード + フックモーションストリップ / design-review.md |
| 4 結合 | video-director | — | voice.json、timeline.ts ドラフト、docs/<vid>/join-notes.md（タイミング/テキスト/ムードの調整） |
| 5 統合 | (修正は所有ブランチのプロデューサーへ) | integration-reviewer (E) | integration-review.md、フルビルド前に判定 |
| 6 タスク | task-planner | task-reviewer (B) | task-review.md: ツール、ショット→ファイルの所有権、依存関係、チェック |
| 7 ビルド | scene-agent-1..N（並列、各1ファイル） | — | src/<vid>/scenes*.tsx + 静止画、ディレクターが timeline/kit/Reel/Root/音声を統合 |
| 8 QA | qa-agent | — | qa-report.md: tsc、決定論、フレーム/トランジション/キャプションチェック、ショットごとのデザイン適合スコア、修正は所有者にルーティング |
| 9 レンダリング | render-agent | video-reviewer (C、最終バリア) | 確認済みMP4 + final-check.md（MP4の完全回帰テスト） + render-evidence.md（コンタクトシート、高密度フレーム、ラウドネス、ASR） / video-review.md |
| 10 納品 | video-director | — (人間のリスニング = オプションの記録) | ディレクターが check を実行し、納品レポートを作成 |
video-director のみが共有の kit、timeline、Reel、Root、voice.json を書き込みます。スペシャリストはハンドオフ時にこれらのファイルへの変更を提案します。シーンエージェントは、動画の SHOTS マップから継続時間を読み取り、モーションを測定された音声スパンにアンカーします。2つのエージェントに同じ書き込み可能ファイルを割り当てないでください。ユーザーが作業を停止した場合は、バックグラウンドエージェントも停止してください。ゲートCはコンタクトシート、高密度フレーム、ffprobe/ラウドネスデータ、ASRのAIレビューです。Cの後の人間によるリスニング（pipeline.py listen）はオプションの記録であり、納品のブロッカーではありません。
スピードルール: デフォルトで並列ディスパッチ
video-director は、作業が許す限り多くのサブエージェントを並列にディスパッチし、動画を可能な限り高速かつ高品質に仕上げなければなりません。一緒に実行できるステップを順次実行することは欠陥です。
- すべての独立したAgent呼び出しを1つのメッセージで送信し（1つのツールブロック）、ターンごとに1つずつ送信しないでください。
- 入力が承認され、書き込み可能ファイルが重複しない場合は常に並列化:
research-agent× N（ソースグループごとに1つ）。フェーズ3の3つのブランチ（content-agent、voice-agent+audio-agent、design-agent）をまとめて。scene-agent× N（各1ファイルと1つのショットIDリスト）。ショットクラスターごとに分割されたqa-agent。動画作業と並行したワークフロー/スキル/ドキュメントの修正。同じラウンドで異なる所有者への独立した修正のルーティング。 - 独立したステージは並列実行（ステージマップ）:
- フェーズ0:
intake-agentチェック（重複トピック、ツール事前チェック、音声カタログテスト）を1メッセージで。フェーズ1: すべてのresearch-agentソースグループ。 - フェーズ3: Aが合格した直後に、3つのブランチプロデューサーすべてを1メッセージで。各ブランチはプロデューサー→自身のレビュアーのループを独立して実行します。合格したブランチは結合ポイントで待機し、他のブランチは修正を続けます。ブランチが他のブランチのレビューを待つことはありません。
- フェーズ5–6: Eがレビューしている間に、
task-plannerが計画をドラフトし、scene-agentが早期スキャフォールドをビルドします。BのレビューはEの合格を待ちます（Eが何かを変更した場合、計画が変更されます）。 - フェーズ7:
scene-agent× N（重複しないファイル）。フェーズ8: ショットクラスターごとおよび静止フレームレンダリングのqa-agent。フェーズ9: コンタクトシート、高密度フレーム、ラウドネス、ASR証拠を同時に計算。 - 修正ラウンド: 異なる所有者向けのチケットは1メッセージで送信します。レビューは同時に実行できますが、ディレクターはスコアを記録し、
gateを厳密に順序 A → D → E → B → C で実行し（pipeline.pyが強制）、以前のゲートが再開された場合、後のレビュアーの結果は無効になります。
- フェーズ0:
- 実際の依存関係がある場合のみ順次実行: ゲート A → D → E → B → C（レビュアーはアーティファクトの完了を必要とします）、前のレビューに依存する修正ラウンド、および単一の所有者を持つファイル（
kit、timeline、Reel…）。