Goldie: 코딩 에이전트가 앱을 직접 실행해 앱스토어 스크린샷과 미리보기 영상을 만드는 CLI 도구

9bow · 9월 9, 2026, 12:00오후

Goldie 소개

모바일 앱을 스토어에 올릴 때 마지막까지 남는 일은 등록용 이미지입니다. 시뮬레이터를 띄워 화면을 하나씩 캡쳐하고, 디자인 도구에서 기기 테두리와 배경, 한 줄 문구를 얹고, 언어마다 같은 작업을 반복하고, 스토어가 요구하는 픽셀 크기와 영상 길이에 맞는지 확인해야 합니다. 화면이 조금 바뀌면 이 과정을 처음부터 다시 하게 되고, 그래서 릴리스마다 미루기 쉬운 작업이 됩니다.

Goldie는 이 과정을 명령 하나로 묶은 명령줄 도구입니다. 화면을 확보하는 일은 Software Mansion이 만든 argent가 맡아 iOS 시뮬레이터나 안드로이드 에뮬레이터에서 사용자 흐름을 재생하고, Goldie는 그렇게 캡쳐한 화면에 기기 테두리와 배경, 헤드라인을 입힙니다. 이어서 클립을 이어 붙여 미리보기 영상을 만들고, 완성된 결과물이 스토어의 업로드 규칙에 맞는지 검사합니다. 프레임워크를 가리지 않아 SwiftUI와 UIKit, Jetpack Compose, Flutter, React Native, Kotlin Multiplatform으로 만든 앱에서 같은 방식으로 동작합니다.

Goldie는 코딩 에이전트와 함께 쓰도록 설계되어 있습니다. 앱 저장소에서 "create app store screenshots using goldie" 라고 요청하면 에이전트가 어느 스토어를 목표로 할지 물어본 뒤 앱을 탐색해 흐름과 설정 파일을 직접 작성하고 스튜디오를 열어 줍니다. 이후 "배경을 어둡게 바꿔 줘" 같은 후속 요청은 같은 파일을 수정하는 방식으로 반영됩니다. 저장소 이름과 npm 패키지, 명령어 이름은 프로젝트 이름과 달리 모두 소문자 goldie 이므로, 아래 명령에서는 그 표기를 그대로 씁니다.

Goldie와 기존 방식 비교

같은 결과물을 만드는 다른 방법과 비교하면 Goldie가 어디에 힘을 주었는지가 드러납니다. PyTorchKR에도 이미 소개된 ASO App Store Screenshots는 코드베이스를 분석해 핵심 효용을 뽑고 사람이 찍어 둔 시뮬레이터 스크린샷을 그 효용과 짝지어 이미지 생성 모델로 다듬는 스킬입니다. 두 도구가 자기 저장소에서 밝힌 동작 범위를 축별로 놓으면 다음과 같습니다:

축	손으로 준비하는 방식	ASO App Store Screenshots	Goldie
화면 확보	사람이 시뮬레이터에서 캡쳐	사람이 미리 캡쳐한 이미지를 골라 사용	argent 흐름을 재생해 자동 캡쳐
구성과 문구	디자인 도구에서 직접 배치	코드베이스에서 효용을 도출한 뒤 이미지 생성 모델로 보정	설정 파일과 스튜디오에서 템플릿과 문구를 지정
미리보기 영상	별도 편집 도구	공개된 기능 목록에 없음	클립을 이어 붙여 렌더링
규격 검증	업로드하면서 확인	공개된 기능 목록에 없음	스토어 규격 표와 대조해 검사

정리하면 두 도구는 목표가 겹치지만 접근이 다릅니다. Goldie는 실제로 동작하는 앱을 재생해 화면을 얻고 스토어 규격 검증까지 책임지는 쪽이고, 이미지 자체를 생성 모델로 꾸미지는 않습니다. 반대로 화면을 예쁘게 만드는 일에 이미지 생성 모델의 도움을 받고 싶다면 다른 도구가 더 맞습니다.

Goldie는 누구에게 맞는가

릴리스마다 여러 언어의 스토어 이미지를 다시 만들어야 하고 이미 코딩 에이전트를 쓰고 있는 모바일 앱 팀에게 Goldie는 바로 도입할 값어치가 있습니다. 흐름과 설정이 저장소 안의 파일로 남으므로 다음 릴리스에서는 명령 한 번으로 같은 결과물을 다시 뽑을 수 있고, 결과가 스토어 규격에 맞는지도 도구가 확인합니다.

반대로 애플 생태계 장비가 없는 팀에게는 Goldie로 App Store 이미지를 만들 수 없습니다. App Store 스크린샷은 iOS 시뮬레이터가 필요해 Xcode가 설치된 macOS를 전제하고, 리눅스와 윈도우에서는 안드로이드 에뮬레이터 기반의 Google Play 산출물만 만들 수 있습니다. 그런 환경에서는 설정의 devices 에 pixel-10-pro 만 남겨야 하며, 실행할 수 없는 iOS 기기가 설정에 들어 있으면 goldie doctor 가 그 사실을 알려 줍니다.

Goldie가 만드는 스토어별 산출물

Goldie는 같은 장면 정의에서 스토어마다 다른 규격의 결과물을 냅니다. 저장소의 src/specs.ts가 이 규격의 근거이며, 주석에 2026년 8월 24일 기준으로 App Store Connect와 Play Console 문서를 확인했다고 적혀 있습니다:

iphone-6.9 기기 키는 iPhone 17 Pro Max 시뮬레이터를 골라 1320 x 2868 스크린샷과 886 x 1920 H.264 미리보기 영상을 만듭니다. 미리보기 영상은 애플이 업로드 시점에 강제하는 조건에 맞춰 30fps, 15초에서 30초 사이, 영상 비트레이트 11Mbps로 인코딩되고 파일 크기 상한은 500MB입니다. 스크린샷에는 알파 채널이 들어갈 수 없어 rgb24 픽셀 형식으로 저장됩니다.

pixel-10-pro 기기 키는 같은 장면에서 1080 x 1920 Google Play 스크린샷을 만듭니다. 캡쳐는 안드로이드 에뮬레이터에서 오고, 에뮬레이터의 AVD는 Pixel 10 Pro나 Pixel 9 Pro 하드웨어 프로필이어야 합니다. 두 프로필이 1280 x 2856 화면을 공유하기 때문에 어느 쪽으로 만들어도 같은 결과가 나옵니다. Goldie는 조건에 맞는 실행 중인 에뮬레이터를 재사용하거나 없으면 AVD를 직접 부팅합니다. 안드로이드 타일에는 기본으로 포함된 Pixel 10 Pro 테두리 이미지가 쓰이고, 설정의 frame 변형은 아이폰용 그림이라 적용되지 않습니다.

영상 쪽에서 두 스토어의 차이가 가장 큽니다. Play 스토어는 영상 업로드를 받지 않고 홍보 영상을 유튜브 링크로 받으므로, Goldie는 에뮬레이터에서 미리보기 장면을 녹화해 1080 x 2400 세로 영상으로 렌더링해 주고 유튜브 게시는 사용자가 직접 합니다. 애플의 15초에서 30초 제한도 이 영상에는 적용되지 않습니다.

Goldie의 명령과 스튜디오

README는 doctor 와 all, studio 세 명령을 소개하지만, src/cli.ts의 사용법 문자열에는 파이프라인의 각 단계를 따로 실행하는 명령까지 함께 정의되어 있습니다:

명령	하는 일
`goldie doctor`	도구와 시뮬레이터, 플래그, 흐름을 점검
`goldie capture`	모든 장면 흐름을 재생하고 원본 캡쳐를 저장
`goldie frame`	원본 스크린샷에 테두리와 문구를 합성
`goldie preview`	원본 클립을 이어 미리보기 영상으로 렌더링
`goldie verify`	완성된 산출물을 스토어 규격 표와 대조
`goldie manifest`	스튜디오 앱이 읽는 `out/store.json` 을 작성
`goldie studio`	스튜디오를 `http://localhost:4321` 에 제공
`goldie all`	capture에서 verify까지 전체 파이프라인 실행

산출물은 out/screenshots/<device>/<locale>/ 과 out/previews/<device>/<locale>/ 에 기기와 언어별로 나뉘어 떨어집니다. 한 번만 다르게 돌려 보고 싶을 때는 설정을 고치지 않고 --device 와 --locale, --background, --frame, --font, --template, --layout, --screen-only 옵션으로 그 실행에만 적용할 수 있습니다.

스튜디오는 결과를 브라우저에서 확인하며 손보는 화면입니다. 기기와 배경, 템플릿, 테두리, 글꼴, 타일별 문구를 바꿀 수 있고, 고른 값은 goldie.design.json 에 저장되어 이후 명령줄 실행이 같은 결과를 내도록 합니다. 스튜디오를 다른 포트에서 열거나 브라우저를 자동으로 띄우지 않으려면 --port 와 --no-open 을 씁니다.

Goldie의 디자인 옵션

설정 파일에서 고를 수 있는 값은 세 묶음입니다. 테두리는 17-pro-blue 와 17-pro-silver, 17-pro-orange 중에서 고르거나 직접 만든 이미지를 쓸 수 있고, theme.screenOnly 를 켜면 테두리 없이 화면만 렌더링합니다. 레이아웃은 editorial 과 showcase, magazine, storyboard, dynamic 같은 템플릿을 고르거나 classic 부터 panorama-duo, minimal 까지 열한 가지 낱개 레이아웃을 직접 순서대로 지정하는 방식입니다. 글꼴은 CSS 글꼴 스택을 그대로 받으며 Merriweather와 DM Mono, Lato, DM Sans, Montserrat, 그리고 중국어 간체용 Noto Sans SC가 기본으로 들어 있습니다. 기기 뒤에 배지나 이미지를 겹치는 decorations 도 설정으로 지정합니다.

실무에서 걸리기 쉬운 두 가지는 저장소가 따로 적어 두었습니다. 하나는 반드시 릴리스 빌드를 쓰라는 것으로, 디버그 빌드는 캡쳐 화면에 LogBox 배너를 그려 넣습니다. 다른 하나는 앱이 바뀌면 흐름이 깨진다는 점이고, 이때는 코딩 에이전트에게 수리를 맡기거나 argent로 다시 녹화하면 됩니다.

Goldie 설치와 사용

Node 20.12 이상과 실행 경로에 있는 ffmpeg가 필요합니다. 명령줄 도구는 npm으로 전역 설치합니다:

npm i -g goldie

코딩 에이전트에 스킬로 추가하는 방법은 두 가지입니다. 첫 줄은 Cursor와 Codex를 비롯해 스킬 형식을 지원하는 모든 에이전트에서 동작하고, 아래 두 줄은 Claude Code용 플러그인 설치 경로입니다:

npx skills add kacperkapusciak/goldie            # Cursor, Codex 등

/plugin marketplace add kacperkapusciak/goldie   # Claude Code
/plugin install goldie@goldie

에이전트 없이 직접 쓸 때는 goldie.config.example.ts 를 goldie.config.ts 로 복사하고, 설정의 장면이 .argent/flows 에 있는 argent 흐름을 가리키게 한 뒤 실행합니다:

goldie doctor     # 도구와 시뮬레이터, 흐름 점검
goldie all        # 캡쳐, 합성, 미리보기 렌더링, 검증
goldie studio     # 브라우저에서 결과 확인과 수정

Google Play 산출물까지 만들려면 설정에 기기 키와 안드로이드 빌드 정보를 함께 적습니다. argent 흐름은 두 플랫폼에서 모두 재생되므로 장면 흐름 자체는 공유하고, 선택자가 양쪽에서 맞으면 같은 흐름이 그대로 동작합니다:

devices: ["iphone-6.9", "pixel-10-pro"],
android: {
  appPath: "/path/to/app-release.apk",
  applicationId: "com.example.app",
},

Goldie의 라이선스

Goldie는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

한 가지 관계는 밝혀 둘 필요가 있습니다. Goldie는 Argent를 만든 소프트웨어 개발 회사 Software Mansion의 후원을 받고 있고, 저장소도 그 사실과 함께 회사에 프로젝트를 의뢰할 수 있다는 안내를 담고 있습니다. 다만 Goldie와 argent 자체는 무료로 공개된 오픈소스이고 기능이 유료 구간에 갇혀 있지 않습니다.

Goldie 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임은 이런 글들을 한국어로 정리해 나누고 있습니다. 회원으로 가입하시면 주요 글들을 이메일로 보내드리고, 텔레그램(Telegram)과 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 다음 글을 정리하는 데 힘이 됩니다~