Video Craft Playbook
これは、コーディングエージェント向けのビデオ制作ハンドブックです。高品質な動画を作る前に、手元にある映像表現能力を確認し、それぞれの表現が成立する条件、限界、コスト、過去の事例での組み合わせ方や失敗を把握するために使います。
このハンドブックはツールの選定を規定しません。ツールにデフォルトはなく、固定のレシピもありません。同じ画風・同じ種類の動画でも、制約（予算、素材、尺、物理演算の要否、実写の有無、修正回数）によって最適な組み合わせは異なります。選定は、タスクごとに目的に沿った計画を立てるあなたが行い、このハンドブックは判断材料を提供するだけです。
使い方
1. 作業開始前：未回収の宿題を確認
python3 ~/.agents/skills/video-craft-playbook/scripts/playbook.py status
status は、まだ蒸留されていないケースカード（cases/inbox/）、確認期限を過ぎた能力カード、および待機層（references/lessons-backlog.md）の件数を表示します。集約しきい値に達した場合は consolidate の実行を促します。inbox には、前回は価値があると判断されたものの、蒸留できなかったカードのみが残っています。未回収の宿題がある場合は、先に数分かけてハンドブックに蒸留してから（手順4参照）、新しい動画に取り掛かります。時間が無い場合は、最低限ユーザーに未回収の件数を伝えてください。
2. 設計：まず表現要件を分解し、次に能力をマッチング
「どのツールを使うか」から始めず、「この動画の各要素は何によって成立するか」から始めます。
- 完成動画を要素に分解する：被写体、環境、動き、カメラワーク、テキストと図形、質感、音、リズム。
- 各要素について references/task-lenses.md のいくつかの質問に答える：その「リアルさ」はどこから来るのか、フレーム単位の正確さが必要か、修正は何回入るか、有料のものを使えるか、どれだけ早く仕上げる必要があるか。
- references/capability-atlas.md で各要素に対して少なくとも2つの実行可能な能力を探す：まず上部の概要表で候補を絞り、対応するカードを読む。比較した後、選定理由と採用しなかった代替案を書き留める。候補には「見つけられる実在素材」（atlas の H グループ：ローカル素材インデックス、オープン素材ライブラリ）も含めること。生成やコードだけと比較しない。ソースの段階と「文章 → カット説明 → 検索 → ライセンス確認 → 合成」のチェーンは task-lenses の第11問と craft-lessons L60 を参照。
- 複数の能力を組み合わせる際は、事前にインターフェースを決めておく：時間の基準、フレームレート、座標系とカメラ、アルファチャンネル、色空間、オーディオバス（task-lenses 第3節）。
- 作業開始前に「能力分担表」（テンプレートは task-lenses 第4節）を作成し、最初の返信でユーザーに提示した上で実行する。確認を待つ必要はない。
編集タスク（素材が既に与えられており、主に編集と後処理を行う）については、別途 task-lenses 第6節を参照：手法を汎用部品と「信号 → 手法」ルールに分解する。詳細は references/editing-grammar.md を参照。理解層が出力すべき信号とフィールドは references/edit-signals.md を参照。現在、両方とも推測に基づくものであり、使用時は出発点として扱い、終了時にアップグレードできるかを判断する。
カメラレベルの動きの文法（オープニング、トランジション、テロップ、UI登場、エンディング）は、Remotion を選択した場合、外部のレシピ集インデックス references/shot-vocabulary.md を参照できる：機能スロットとエネルギーでカードを探し、リポジトリでカード全文とデモソースコードを読む。これは製品プロモーションビデオのコンテキストに由来し、ローカルでは未検証。
references/composition-patterns.md には、過去の事例で実際にどのように組み合わせたかが記録されており、アイデアのヒントやコストの見積もりに役立つ。これらはそのタスクの解であり、テンプレートではない：流用する前に、自分のタスクの制約が当時と同じであることを確認すること。
3. 実行：ノウハウと落とし穴
- ツール間で共通するプラクティス（検収優先、時間の単一基準、映像は t の純関数、レビュー用レイヤー分け、有償版3点セット、オーディオ仕様など）は references/craft-lessons.md を参照。
- ツール別の既知の落とし穴は references/pitfalls.md を参照。特定のツールを使う前に、そのグループを一読すること。
- 各ツールの具体的な呼び出し方法は、対応するスキルに従う（atlas の各カードにエントリーポイントが記載）。このハンドブックではコマンドの詳細は繰り返さない。
4. 終了：まず価値があるか判断し、それから回収するか決める
ハンドブックは事例によって成長するが、全ての事例を書き戻す必要はない：既存の項目を繰り返すだけのものや、この動画だけにしか当てはまらない詳細は、ハンドブックを薄めるだけ。動画を納品する（またはタスクを中断する）際は、references/writeback.md の第1節に従って候補をリストアップし、3つの関門（再利用性、非導出性、コスト）を通過したものだけをカウントする。全ての関門を通過し、かつ証拠があるものだけが有効。既存の項目に統合できるものは、新規追加しない。
- 1つ以上該当する場合：writeback 第2節に従って回収する：
new-caseでケースカード作成 → 対応ファイルに蒸留（常駐層が満杯の場合は references/lessons-backlog.md に書き込む）→check→close。蒸留する時間がない場合はカードを inbox に残し、次回のstatusでリマインドされる。 - 1つも該当しない場合：回収をスキップする。ケースカードの作成も台帳への記録も行わない。ユーザーが回収不要と言った場合も同様にスキップする。
最終的な納品説明には、Playbook 回収の行を1行入れ、結論を明記する：変更したファイル、またはケースカードを蒸留待ちとしたこと、または「スキップ：<理由>」。
中立の原則（ハンドブック作成時と使用時の両方で守るべきこと）
- 能力カードには事実のみを書く：得意なこと、不得意なこと、コスト、確実性、検証ソース。「デフォルト」「おすすめ」「推奨」「優先的に使用」などの順位付け用の言葉は書かない。
playbook.py checkはこれらの言葉を検出する。 - カードの順序はメディアの種類で並べられており、ランキングを意味しない。
- 事例で特定のツールがうまく使えた場合、「どのような制約の下で、なぜ成立したか」として記録し、「この種の動画ではこれを使う」と一般化しない。
- ローカルの事例で検証されていない能力も収録する。「インストール済み未検証」または「推測」と明記する。使用経験が無いからといって省いたり、使用経験があるからといって過大評価したりしない。
- ボリュームも偏向の一種である：カードのフィールドは固定長とし、機能リストや実装の詳細はカードに含めない。よく使うツールだからといって、より多くのスペースを占めるようにしない。
- 記録に偏向が見つかった場合（例えば、あるワークスペースの説明に「デフォルトで〇〇を選ぶ」と書いてあるなど）、回収時には条件文に修正する：どのような制約の下でそれが適切かを書く。