goldie

goldie：このリポジトリ内のアプリ向け App Store アセット

goldie は argent YAML フローを iOS シミュレーターで再生し、スクリーンショットと録画の生データをキャプチャして、アップロード可能なアセットに仕上げます。スクリーンショットにはデバイスのベゼル、背景、宣伝文を追加します。プレビュー動画は、生の録画をそのままつなぎ合わせたものです。Apple が、フレームや字幕のない単純な画面録画をアプリプレビューとして求めているためです。React のスタジオでは、実際のストアページと同じ見た目で結果を確認できます。あなたが担当するのは、goldie だけではできないすべての作業です。宣伝にふさわしい画面を選び、その画面にたどり着くフローを作成し、宣伝文を書いて、パイプラインを実行します。

最終的には、ベゼル付きのスクリーンショットを4〜5枚、プレビュー動画用の生のクリップをそろえ、動画をバックグラウンドでレンダリングしながら、スタジオ（http://localhost:4321）で確認できる状態にします。

まず、既存の goldie セットアップがあるか確認します

goldie は、ユーザーが再び指示できるよう、成果一式をファイルに保存します。アプリのリポジトリにすでに設定ファイルがある場合は、これはその続きの作業です。まず設定を読み、最初からやり直すのではなく、下記の「既存のセットアップを反復する」に進んでください。

ls goldie/goldie.config.ts .argent/flows/ 2>/dev/null; echo "GOLDIE_CONFIG=$GOLDIE_CONFIG"

goldie/goldie.config.ts と、そこで指定されているフローをすべて読みます。これらが、目に見える選択すべての信頼できる情報源です。どの画面をどの順番で使うか、見出しとサブ見出し、背景色と文字色、ベゼル、ストアの掲載情報、プレビューのストーリーが記されています。内容があなたの頭の中やスタジオにしか存在することはありません。そのため、ユーザーが「もっと暗くして」や「検索のスクリーンショットを設定画面に差し替えて」と言った場合は、これらのファイルを編集するということです。

ステップ0：対象にするストアを決めます

対象となるストアは、リポジトリでビルド可能なものによって決まるため、質問する前に確認します。iOS のターゲット（.xcodeproj／.xcworkspace、アプリのターゲットを含む Swift パッケージ、ios/ ディレクトリ）と、Android のターゲット（アプリケーションモジュールを含む build.gradle[.kts]、android/ ディレクトリ）があるか確認してください。

• 単一プラットフォームのリポジトリ — ネイティブ Android のみ、または iOS／Swift のみの場合です。選択肢は1つしかないため、質問は不要です。対象のストアを選び、最初のメッセージで、どちらを選んだか、そしてその理由を伝えてください。
• クロスプラットフォームのリポジトリ — React Native、Expo、Flutter、Kotlin Multiplatform、または iOS と Android の両方を対象とするその他の構成です。ユーザーがすでにプラットフォームを指定している場合でも、必ず他の作業に入る前に質問してください。「Play ストアのスクリーンショット」という依頼も「App Store も」という意味であることがよくあり、その回答によって、やり直しに大きなコストがかかる作業が決まるためです。Claude Code の AskUserQuestion などの対話型質問ツールが利用できる場合は、複数選択を許可して使い、ユーザーが指定したものをあらかじめ選択するか、最初に提示してください。それ以外の場合はチャットで質問し、どちらか一方または両方を選んでもらいます。

選択肢は次の2つです。

• Apple App Store（iPhone）：iOS シミュレーターでキャプチャする、ベゼル付き iPhone スクリーンショットとアプリプレビュー動画です。
• Google Play ストア（Android）：Android エミュレーターでキャプチャする、Play ストア用スマートフォンのスクリーンショットと縦向きプレビュー動画です。Play のプロモーション動画は YouTube リンクなので、ユーザー自身がそこに動画を投稿します。

両方選択できます。シーンとフローはストア間で共通です。回答によって、設定ファイルに含めるデバイスキー、ステップ1で見つける必要のあるビルド（iOS シミュレータービルド、Android APK、または両方）、および下記の Google Play セクションを適用するかどうかが決まります。既存のセットアップを引き継ぐ場合は、設定ファイルにデバイスがすでに記載されているため、再度質問する必要はありません。

ステップ 0.5：goldie が動作することを確認する

goldie は、CLI、studio、バージョンが固定された argent ドライバーをまとめた npm パッケージです。何もクローンする必要はありません。初回の使用時に npx が取得します。

npx -y goldie@0 help

以下の各コマンドは npx -y goldie@0 <cmd> で、これを goldie と呼びます。Node 20 以降と、PATH 上の ffmpeg が必要です（macOS では brew install ffmpeg、Windows では winget install ffmpeg、Linux では apt install ffmpeg）。iOS デバイスには macOS ホストが必要です。Linux と Windows では Android デバイス（pixel-10-pro）のみ実行できるため、そこでの devices には iOS のキーを含めないでください。$GOLDIE_ROOT が設定されている場合、ユーザーはソースチェックアウトから作業しています。その場合は、代わりに bun $GOLDIE_ROOT/src/cli.ts <cmd> を実行してください。アプリ固有のファイルはすべてアプリのリポジトリにあります。

goldie は 3 台のデバイスに対応しています。iphone-6.9（iPhone 17 Pro Max、App Store が必須とするサイズ）、ipad-13（iPad Pro 13-inch、iPad にも対応するアプリ向け）、pixel-10-pro（Google Play 用のスマートフォン）です。すべて同じフローを再生し、コピー、テーマ、テンプレートを共有します。それぞれに固有のベゼル、生キャプチャ、出力フォルダー、studio ビューがあります。

ステップ 1：アプリの情報を集める

確認する内容は、ステップ 0 で選択したストアによって異なります。

• アプリ名と識別子。 iOS：Xcode プロジェクト、app.json／app.config.*（Expo）、または Info.plist。Android：app/build.gradle[.kts] の applicationId、または Expo 設定の android.package。
• iOS の Release シミュレータービルド（App Store のみ）。最新の ~/Library/Developer/Xcode/DerivedData/<App>-*/Build/Products/Release-iphonesimulator/<App>.app を探します。Debug しかない場合は Release をビルドしてください。Debug ビルドには Metro が必要で、キャプチャに LogBox バナーが描画されるため、マーケティング素材として使えなくなります。
• Android APK（Google Play のみ）。release APK が最適です。リポジトリ独自のスクリプト、または ./gradlew :app:assembleRelease でビルドしてください。署名されていない release APK はインストールできないことに注意してください。ネイティブ Android アプリなら debug APK でもかまいません。デバッグ用のオーバーレイは描画されないためです。React Native の場合、debug APK には Metro が必要で、開発用オーバーレイも表示されるため、release をビルドしてください。

リポジトリにビルドスクリプトがある場合は、必ずそれを使用してください。

ステップ 2：アプリを確認してシーンを選ぶ

何かを決める前に、argent MCP ツールを使ってアプリを確認してください。対象ストアに合わせてデバイスを起動します。App Store なら iPhone 16 Pro Max クラスのシミュレーター、Google Play なら Pixel 10 Pro（または Pixel 9 Pro）の AVD を使います。ビルドをインストールして起動し、describe と screenshot を使ってメイン画面を確認します。また、アプリのリポジトリで .argent/flows/ に既存の記録済みフローがないか確認してください。動作するセレクターや座標を知るための最良の情報源です。アプリが iPad にも対応している場合（Expo 設定の supportsTablet、または iPad ターゲット）、devices に "ipad-13" を追加する計画を立て、「iPad Pro 13-inch (M4)」シミュレーターで同じ画面を確認します。複数のデバイスを対象にする場合、フローではどのレイアウトでも有効なセレクターを使う必要があります。そのため、座標よりも text: と id: を優先してください。

次のものを選びます。

• スクリーンショット用のシーンを 4 つまたは 5 つ。 それぞれ、機能をアピールする 1 画面にします。メインのリスト、詳細画面、検索、特徴的な機能画面などです。実際のコンテンツのように見える画面を優先してください。
• 3 または 4 セグメントのプレビューストーリー。 短いユーザージャーニーを順番に伝えます。たとえば、メイン画面を見る、主要な操作を開始する、完了する、結果を見る、という流れです。各セグメントが 1 つのクリップになります。クリップはキャプションやフレームなしで連結されるため、各ステップが単独でも分かる必要があります。App Store では、動画の合計時間を 15～30 秒にする必要があります。Google Play ではアップロードではなく YouTube のリンクを使うため、Android 動画はユーザーが自分で投稿できるようにレンダリングされ、長さの制限はありません。両方のストアを対象にする場合は、Apple の時間枠に合わせてください。

確認中に、セレクターとして必要になる画面上の正確なテキストラベルとアクセシビリティ ID を記録してください。また、ラベルのない要素（通常はアイコンのみのタブバー）については、正規化座標を記録してください。

ステップ 3：設定とフローを作成する

フローは argent フローで、アプリ独自のフローストアに、すでに記録されているフローがあればその隣に配置します。設定は goldie/ ディレクトリに置きます。

<app-repo>/
├── .argent/flows/
│   ├── store-01-<scene>.yaml ...        one per screenshot scene
│   └── store-preview-01-<segment>.yaml  one per preview segment
└── goldie/goldie.config.ts

シーンのフロー名は argent flow run <name> と同じ形式で指定します。flow: "store-01-home" は .argent/flows/store-01-home.yaml を実行します。マーケティング用のフローにはプレフィックスを付け、アプリのテスト用フローと区別できるようにします。また、すでに画面に到達できるフローがある場合は、その名前で既存のフローを再利用します。設定の flowsDir は場所を上書きします。既定では appRoot の下の .argent/flows です。

設定スキーマ、注釈付きの例、コピーライティングのガイダンスについては references/config.md を参照してください。フロー YAML の語彙と、フローを再実行可能に保つための規約については references/flows.md を参照してください。見出しと小見出しはアプリのトーンに合わせて自分で作成してください。これらはマーケティング層なので、短く、メリットを前面に出したものにします。

すべて設定ファイルを基準とする相対パスで出力されます。出力先は <app-repo>/goldie/out/ です。アプリの .gitignore に goldie/out/ を追加し、goldie.config.ts とフローをコミットしてください。

通常の argent フローなので、それぞれアプリのリポジトリから argent flow run store-01-home で単独実行できます。フルキャプチャの前にフローを確認する最速の方法です。

ステップ 4：doctor を実行してからキャプチャする

すべての goldie コマンドは、GOLDIE_CONFIG 環境変数から設定パスを読み込みます。 Bash の呼び出し間でシェルの状態は保持されないため、goldie コマンドのすべてにこの変数を付けてください。

GOLDIE_CONFIG=<app-repo>/goldie/goldie.config.ts npx -y goldie@0 doctor

キャプチャの前に、doctor が指摘した内容をすべて修正してください。よくある指摘とその修正方法は、goldie の README の Gotchas セクションに記載されています。よくあるものは、argent の動画ウォーターマークフラグ、スクリーンショットのスケール上書き、Debug ビルドです。

次にキャプチャして静止画をレンダリングします（動画は数分かかるため、今はスキップしてください）。

GOLDIE_CONFIG=... npx -y goldie@0 capture
GOLDIE_CONFIG=... npx -y goldie@0 frame
GOLDIE_CONFIG=... npx -y goldie@0 manifest

capture はプレビュー区間を含むすべてのフローを再実行するため、後で動画を遅延レンダリングする際に使える生のクリップが作成されます。

フローが失敗した場合

フローは LLM なしで再実行されるため、セレクターが間違っていると明確に失敗します。goldie は失敗したステップと argent の理由を表示します。argent MCP 経由で修正してください。ライブ画面を describe して実際のラベルまたは ID を見つけ、YAML を修正してからキャプチャを再実行します。text: と id: のセレクターを優先してください。座標しか使えない場合は、その座標が何を指すのかを説明する echo: ステップを上に追加し、次回の修正時に何を再確認すべきか分かるようにします。

ステップ 5：スタジオを開き、動画を遅延レンダリングする

スタジオをバックグラウンドで起動します。これにも GOLDIE_CONFIG が必要です。そうすると、アプリのリポジトリの out/ が提供されます。

GOLDIE_CONFIG=... npx -y goldie@0 studio --no-open   # background task; serves http://localhost:4321

http://localhost:4321 で起動していることをユーザーに伝えてください。次に、完了後の再読み込み時にプレビュー動画が表示されるよう、こちらもバックグラウンドでレンダリングします。

GOLDIE_CONFIG=... npx -y goldie@0 preview && GOLDIE_CONFIG=... npx -y goldie@0 manifest

合計が 15〜30 秒の範囲外であるために preview が拒否された場合は、セグメントのペース配分（wait: ステップと holdSeconds）を調整し、変更した箇所だけ再キャプチャしてください。

最後に GOLDIE_CONFIG=... npx -y goldie@0 verify を実行し、結果を報告してください。存在するアセット、その場所、Apple のルールに準拠しているかどうかを伝えます。スタジオのサイドバーにも同じチェック結果が表示されます。赤い行はルール違反を示します。Design パネルを使うと、ユーザーは背景、レイアウト、ベゼル、フォントを自分で再スタイルできます。Export では、アップロード用の zip をダウンロードできます。

Google Play

pixel-10-pro デバイスキーでは、同じシーンから Play 用のスマートフォンのスクリーンショット（1080 x 1920）をレンダリングします。シーンとフローはデバイス間で共有され、セレクターが一致すれば、argent のフローを Android で再生できます。設定に android: { appPath: "<apk>", applicationId: "<id>" } ブロックを追加し、Pixel 10 Pro または Pixel 9 Pro のハードウェアプロファイルを使用する AVD が存在することを確認してから、同じキャプチャ／フレームコマンドを実行してください（goldie は実行中のエミュレーターを再利用するか、AVD を自ら起動します）。Android のタイルには、設定の frame バリアント（iPhone のアート）の代わりに、同梱の Pixel 10 Pro ベゼルが適用されます。android.frame を使うと、独自のアートに置き換えられます。Play では動画をアップロードできない（プロモーション動画は YouTube のリンクです）ため、preview はユーザーが自分で YouTube に投稿するための 1080x2400 の縦向き動画をレンダリングします。動画の長さに制限はありません。

既存のセットアップを反復して調整する

追加のプロンプトは、設定またはフローの小さな変更に対応させ、その変更を反映する最もコストの低い段階を実行します。アプリを再調査したり、ユーザーが言及していないシーンを書き直したりしないでください。次のプロンプトでその変更を引き継げるよう、変更したファイルとフィールドを報告してください。

ユーザーの要望	編集する項目	その後に実行
見出し、サブ見出し、またはストア用コピーを変更する	scenes[].headline / subhead、store.*	frame、manifest
見た目を変更する：背景、テキストの色、フォント、サイズ	theme.*、またはタイルを1つだけ変更する場合は scenes[].background	frame、manifest
ベゼルを変更する、またはベゼルをなくす	frame.variant（1つのバリアント、またはデバイスキーごとに1つ）、theme.screenOnly	frame、manifest
iPad のスクリーンショットも追加する	devices: ["iphone-6.9", "ipad-13"]、frame.variant["ipad-13"]	capture --device ipad-13、frame、preview、manifest
変化のあるストリップにする：パノラマの導入、ヒーロー、傾けたタイル、ひと息つける余白	theme.template：組み込みキー、またはレイアウトキーの並び（references/config.md を参照）	frame、manifest
タイルごとに異なるレイアウトにする、または1つだけ変更する	theme.layout、またはタイルを1つだけ変更する場合は scenes[].layout	frame、manifest
1つのタイルに2つの画面を表示する、または2タイルのパノラマにする	scenes[].layout: "duo" / "panorama-duo" と secondScene、または "panorama"	frame、manifest
タイルにバッジ、ステッカー、またはロゴを付ける	theme.decorations（すべてのタイル）、または scenes[].decorations（1つのタイル）	frame、manifest
ダークモードでキャプチャする	appearance: "dark"（テキストの色も合わせる）	capture、frame、manifest
スクリーンショットの順序を変更する、削除する、または追加する	scenes[]。新しいシーンには .argent/flows に新しいフローが必要です	capture（新しいフロー）、frame、manifest
1つの画面に別の状態を表示する	シーンのフロー YAML	capture、frame、manifest
プレビューのストーリーやテンポを変更する	プレビューの segments[]、holdSeconds、フローの wait: ステップ	capture、preview、manifest
別のロケールを追加する	locales と、すべてのコピー記録の <locale> キー	capture、frame、preview、manifest
コピーだけでなく、各ロケールの言語でアプリ自体を表示する	localizedCaptures: true（iOS デバイス）	capture、frame、preview、manifest

capture はすべてのフローを再生します。変更した部分だけを再キャプチャするには、他のシーンはそのままにして余分に1分かかるのを受け入れるか、実行前に out/raw/ 内の古いファイルだけを削除してください。frame と manifest は数秒で完了するため、必要に応じて実行できます。http://localhost:4321 のスタジオは、再読み込みすると変更を反映します。起動していない場合は、GOLDIE_CONFIG を指定して再起動してください。

スタジオの Design パネルは設定ファイルの隣にある goldie.design.json に書き込み、CLI の --background / --frame / --font / --template / --layout / --screen-only フラグは実行時のみのオーバーライドです。どちらも設定ファイルは変更しません。ユーザーがそこで何かを試し、その内容を保持したい場合は、その値を theme.background、frame.variant、theme.fontFamily、 theme.template、theme.layout、または scenes[].layout にコピーして、次のプロンプトでの再指示がユーザーに見えている内容を起点にできるようにしてください。現在ディスクに保存されている値は goldie/out/web/store.json の design にもあり、スタジオに現在表示されている内容を確認する最も手早い方法です。