What's New クリップ
What's New クリップは、リリースの変更点を、ユーザーがスクロールして通り過ぎるわずかな時間で伝えるためのものです。毎回同じ質問を表示し、バージョン番号を示すオープニングカード、実際のリリースビルドで撮影された変更ごとのシーンとキャプション、そして入手方法を案内するエンディングカードで構成されます。言葉(キャプション)が最優先され、承認者自身の言葉が使われます。シードされた再現可能な状態から撮影し、1つのコマンドでレンダリングし、誰かが見る前に自分のレンダリング結果の静止画を確認します。仕様はリポジトリに残るため、次回のリリースは白紙の編集セッションからではなく、今回のものを基に開始できます。
プロジェクトの情報は、ユーザーのリポジトリ内の docs/agents/whats-new-clip.md に格納されています。リリースノートの場所、リリースビルドのビルド方法とシード方法、この画面のキャプチャ方法、ルック&フィール、フォーマット、クリップの保存場所、承認者などが定義されています。このファイルがない場合は、まず SETUP.md に従ってください。
ツールは scripts/clip.py です。uv run <このスキルのフォルダ>/scripts/clip.py <コマンド> のように実行します。各コマンドの --help でフラグを確認できます。ffmpeg と ffprobe が PATH に含まれている必要があります。uv が Pillow をもたらします。uv がない場合は、リポジトリの外に仮想環境を作成し (python3 -m venv <dir> && <dir>/bin/pip install pillow)、<dir>/bin/python を使用してツールを実行します。仕様のフォーマットと check で適用されるすべてのルールは SPEC.md に記載されています。
1. ユーザーが気づく変更点を見つける
プロジェクトファイルに記載されているリリースノートを読みます。ユーザーが見たり、聞いたり、感じたりするであろう各変更点をリストアップし、それぞれをノートの該当行と結び付けます。誰も気づかない修正や、裏方の作業は除外します。
リストにユーザーが気づくような変更点が何もない場合は、承認者に今回のリリースにクリップが必要かどうかを尋ね、承認者が不要と言った場合は作業を中止します。
完了条件: リストのすべての項目がリリースノートのいずれかの行を指しているか、承認者がこのリリースにはクリップは不要と指示した場合。
2. キャプションを確定する
変更点ごとに1つのキャプションを、表示する順番(最も重要なものを最初)に提案します。シーンごとに1つの変更点です。キャプションは、ユーザーにとってのメリットを平易な言葉で、そのシーンが再生されている間に2回読める程度の短さ(約6語)で記述します。承認者が既に変更点に対して言葉を与えている場合(ノート、メッセージ、アプリ内のWhat's Newなど)、それをそのまま使用します。綴り、文法、大文字小文字も含めてそのままです。
承認者には、リスト全体と各項目に対するあなたの推奨案を一度に提示し、一言で回答できるようにします。キャプションが確定するまでは、いかなる撮影も行いません。キャプションを言い換えると、多くの場合、異なるショットが必要になるからです。
承認者が、製品にも表示されるキャプション(アプリ内のWhat's Newシートやストアのリリースノートなど)を言い換えた場合は、そのテキストも変更するかどうかを尋ね、リリース全体で一貫した表現になるようにします。
完了条件: 承認者がすべてのキャプションに同意し、それぞれが同意された通りのキャプションを保持していること。
3. 仕様書を作成する
セットアップでこのバージョンの仕様が既に作成されている場合は、そのファイルを入力します。そうでない場合は、前回のリリースの仕様を基に開始します。これにより、ルック&フィール、オープニングの文言、エンディングカードが引き継がれます。
clip.py init <version> --out <spec folder> --from <spec folder>/<last version>.json
初めてのクリップの場合は、--from の代わりに --product "<name>" を使用します。各シーンの caption(ステップ2からそのまま)、words_by(言葉を提供した人)、およびキャプションを読むのに十分な長さの計画された in と out を入力します。視覚的に見るものが何もない変更の場合は、キャプションが許す最も短いシーンにします。その後、clip.py check <spec> --words を実行します。
完了条件: check --words が check: ok を出力すること。
4. 各シーンを撮影する
FILMING.md のルールに従い、プロジェクトファイルのビルド、シード、キャプチャコマンドを使用して各シーンを撮影します。このリリースに含まれるものだけを表示します。無効になっているスイッチの背後にあるものや、次回リリースのものは表示しません。
実際の入力をプロダクト自身のUI経由で変更点に到達できない場合は、作業を中止してユーザーに伝えます。それはバグであり、それを回避して撮影されたクリップは、ユーザーが実際にはできないことを約束してしまうことになります。
プロジェクトのキャプチャでまったく撮影できない変更(カメラビューやセカンドデバイスなど)は、保存されたフィルムから表示します。FILMING.md の「キャプチャで撮影できないもの」を参照してください。
フィルムは、このリリースのクリップフォルダ(リポジトリの外)に置きます。各ステップの実行時にログに記録された時間から、各シーンの source、in、out を設定します。マークを信頼する前に、以下のコマンドで確認します。
clip.py peek <film> --from <second> --to <second> --out <a fresh scratch folder> --sheet <scratch folder>/peek.png
これにより、render が読み取る方法で、フィルムの2つの秒間の間を表示します。自分でシークを行って静止画を取得しないでください。スクリーンレコーディングは、画像が変化した場所にのみフレームを保持するため、シークは次の変化点に移動し、それは数秒後になる可能性があります。
その後、clip.py check <spec> --media <films folder> を実行します。
完了条件: --media でフィルムフォルダを指定した状態で check が check: ok を出力すること。
5. レンダリング
clip.py render <spec> --media <films folder> --out <clips folder>/<product, kebab-case>-<version>-9x16.mp4
プロジェクトファイルで指定されている追加フォーマットも、--size を使用してレンダリングします(例:--size 1920x1080)。render が、そのサイズでは画面が小さすぎて読めないと警告した場合(ワイドフレーム内の電話画面など)、そのフォーマットには独自の仕様が必要です。SPEC.md の「別フォーマット」を参照してください。音声はオプションであり、メッセージを伝えるために必須ではありません。ほとんどのユーザーはミュートで視聴するため、キャプションだけでストーリーが伝わる必要があります。
完了条件: render が、プロジェクトファイルで指定されたすべてのフォーマットに対して Wrote ... を出力したこと。
6. レビュアーパス
静止画を新しいフォルダに抽出します。
clip.py stills <clip> --spec <spec> --every 1 --safe --out <scratch folder> --sheet <scratch folder>/sheet.png
これにより、各カードとシーンの中央から1枚、さらに1秒ごとに1枚の静止画、およびそれらをすべてまとめたシートが生成されます。フィードがカバーする端は色付けされます。各フォーマットについて、REVIEW.md に照らしてすべての静止画を確認します。
ハーネスがサブエージェントを起動できる場合は、新しいコンテキストで起動したサブエージェントにこのパスを依頼します。そのエージェントは REVIEW.md、仕様、静止画、シートのみを保持し、画面に表示されているもの(あなたが撮影しようとしたものではなく)を確認します。
各指摘事項を REVIEW.md の表に従って修正し、再レンダリングして静止画を再度抽出します。間違った画像を引き継ぎ時に説明しようとしないでください。
完了条件: すべての静止画が REVIEW.md のすべての項目に合格し、修正待ちが存在しないこと。
7. 引き継ぎ
REVIEW.md の「引き継ぎ」にリストされているものを、プロジェクトファイルで指定された方法で承認者に送り、承認または変更点を求めます。承認者が OK と言うまで、クリップは公開されず、リリースにも添付されません。公開を行うのは、プロジェクトファイルで指定された人物です。
NG の場合は、その変更点をステップ2(言葉)またはステップ4(画像)に戻し、変更が必要なシーンのみを再度撮影します。理由のない NG の場合は、同じショットを再撮影する前に、一度だけ何が気に入らなかったかを尋ねます。
完了条件: 承認者が OK と言ったか、その変更点がステップ2または4に戻されたこと。
8. 次回リリースのために保管する
仕様は、リリースの他の変更と共にリポジトリに残します。フィルムは、承認されたクリップと共にクリップフォルダに保管します。このクリップから学んだ教訓を、プロジェクトファイルの「Lessons」の下に1行ずつ追加します。
完了条件: 仕様がリポジトリにあり、フィルムが承認されたクリップと共に保存され、すべての新しい教訓が docs/agents/whats-new-clip.md に1行として記載されていること。