動画制作自動化パイプライン（マルチサブエージェント版）

テーマを渡すだけで、リサーチ → 台本 → スライド → 音声 → 動画 → BGM → Vimeo まで 完全自動 で生成する Claude Code パイプライン。

Claude 公式ベストプラクティス（サブエージェント・Skills）に沿って、Stage ごとの専門サブエージェントに分割した構成。

構成（俯瞰）

video-automation-claude-shared/
├── make_video.sh                  # 起動スクリプト
├── .claude/
│   ├── agents/                    # 7エージェント（誰が何をやるか）
│   ├── skills/                    # 5スキル（どうやるか）
│   └── _shared-references/        # 判断基準・トーン・デザイントークン
├── tools/                         # 実行スクリプト群
├── prompts/                       # 起動プロンプト
├── config/loop-limits.yaml        # Bounded Agent Dialogue
├── bgm/                           # BGM 素材（.gitignore 対象）
└── data/                          # ジョブ成果物（.gitignore 対象）

エージェント構成

エージェント	担当 Stage	呼ぶスキル
video-orchestrator	全体統括（Stage順・マーカー・検証ゲート）	—
theme-researcher	0 リサーチ	research-theme
scriptwriter	1 台本	write-script
structure-reviewer	1 構成案審査（critic）	—
slide-designer	2-3 slides.json＋画像	design-slides
narration-producer	4-5 ナレ抽出＋音声	produce-narration
video-assembler	6-8 結合＋BGM＋Vimeo	assemble-video

統括役が各サブエージェントを順に起動し、各 Stage の手順はサブエージェントが自分のスキルを読んで実行する。

パイプライン全体像（9 Stage）

Stage	入力	出力	主なスクリプト
0	テーマ未指定	`theme.md`	`tools/web-search.sh`
1	テーマ	`script.md`	scriptwriter ＋ structure-reviewer 自動審査
2	`script.md`	`slides.json`（SOT）	slide-designer
3	`slides.json`	`slides/slide_NNN.png`	`tools/generate_slides.py`
4	`slides.json`	`audio/slide_texts.json`	`tools/extract-narration.py`
5	`slide_texts.json`	`audio/slide_NNN.mp3`	`tools/audio_generate.py`
6	png + mp3	`output.mp4`	`tools/assemble_video.py`
7	`output.mp4` + BGM	`output_bgm.mp4`	`tools/mix_bgm.py`
8	`output_bgm.mp4`	Vimeo URL（任意）	`tools/vimeo_upload.py`

各 Stage 後に tools/check_consistency.py で slide_id 整合性を検証する。

セットアップ

1. 前提環境

項目	必要
OS	macOS
Python	3.10 以上
Claude CLI	インストール済み + ログイン済み
`ffmpeg`, `ffprobe`	`brew install ffmpeg`
`jq`	`brew install jq`

2. Python 依存

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. `.env.local` を作成

cp .env.example .env.local

キー	取得先	必須
`OPENAI_API_KEY`	https://platform.openai.com/api-keys	✅
`FISH_AUDIO_API_KEY`	https://fish.audio/go-api/	✅
`FISH_AUDIO_VOICE_ID`	Fish Audio のモデルページ	✅
`VIMEO_ACCESS_TOKEN`	https://developer.vimeo.com/apps	任意（Stage 8）
`BRAVE_SEARCH_API_KEY`	https://api.search.brave.com/app/keys	任意（Stage 0）

4. BGM 素材を置く（任意）

bgm/bgm.mp3 に置けば Stage 7 で自動ミックス。無ければスキップ。

5. 実行

# 事前チェック
./make_video.sh --dry-run "AIエージェントで営業リスト作成を自動化する方法"

# 本実行
./make_video.sh "AIエージェントで営業リスト作成を自動化する方法"

完走すると data/<job-id>/output_bgm.mp4（BGM 無しなら output.mp4）が得られる。

設計の核

マルチサブエージェント：Stage の責務境界で分割。各 Stage を独立コンテキストで実行し、長いパイプラインでもコンテキスト汚染を抑える
agent = 役割 / skill = 手順 / references = 判断基準 / tools = 実行コード の4層分離
slide_id を全ファイルの SOT：画像も音声も slide_{slide_id:03d}.X で統一。check_consistency.py が強制検証
完全自動・人間確認ゼロ：構成案は structure-reviewer サブエージェントが自動審査（最大3ループ）
既知バグを tools/ が構造的に回避（-shortest 禁止／amix normalize=0）

設計上の選択：マルチサブエージェント

「薄いエージェント1つ＋全Stage集約の単一スキル」型に対し、本構成は Stage の責務境界でサブエージェントを分割している。

各 Stage を独立コンテキストで実行することで、長いパイプラインでもコンテキスト汚染を抑え、Stage単位の改善・再実行がしやすい。

tools/ と判断基準（_shared-references/）はフォルダ内に内包し、外部参照なしで自己完結する。

ライセンス

BGM・OpenAI / Fish Audio / Vimeo / Brave Search の利用規約はそれぞれユーザー側で確認・遵守すること。

動画制作自動化