test-on-device skill
목적
/ait:test-on-device는 지금 만들고 있는 미니앱을 실제 토스 앱에서 확인하는
정규 경로를 한 명령으로 밟는다: 번들 빌드 → 콘솔 업로드 → 컴파일 확인 → 토스
앱에서 열기.
"폰에서 보고 싶다"에 대응하는 경로는 셋이고, 목적이 다르다:
| 원하는 것 | 경로 |
|---|---|
| 브라우저에서 mock으로 개발 | 프로젝트의 dev 스크립트(package.json scripts) + /ait:debug 환경 1 (토스 앱 불필요) |
| 실기기에서 동작 확인 | 이 skill — 번들을 콘솔에 올려 토스 앱에서 연다 |
| 실기기에서 CDP로 관측·디버깅 | /ait:setup-debugger 배선 후 /ait:debug 환경 3(QR attach). 이 skill이 디버그 빌드(AIT_DEBUG_BUILD=1)로 올릴 수 있지만 그 배포는 검수에 제출하지 않는다 |
이 경로는 특정 스택 전용이 아니다 — 전제는 .ait 번들 하나뿐이라, web-framework
프로젝트, React Native, Unity·엔진 HTML5 빌드 모두 업로드부터는 같은 절차를 탄다.
스택마다 다른 것은 빌드 방법과 산출물 위치뿐이고, 이는 프로젝트를 읽어 정한다(3).
의존
- cwd가 미니앱 프로젝트 루트여야 한다. 웹·RN 프로젝트는
package.json과 번들 설정 파일이 있다. 정본 scaffold(create-ait-app 0.2.x,new-miniappskill)는apps-in-toss.config.ts를 쓰고, 구세대--local오프라인 폴백 템플릿 (new-miniappL-5)은granite.config.ts를 쓴다. Unity는Packages/manifest.json이나Assets/에 SDK가 있다. 프로젝트 표지가 하나도 없으면 프로젝트 루트로 이동 안내 후 중단. - 콘솔 MCP(
ait-console) 인가가 1회 필요하다 —/mcp에서 승인한다. 인가되지 않았으면 그 안내만 하고 중단한다. - 콘솔에 등록된 앱이 있어야 한다. 없으면
miniapp_create로 1회 등록한다 (아래 2 — 이미 있으면 절대 새로 만들지 않는다). - 아이콘이 비어 있어도
ait build는 실패하지 않는다. 3.x (apps-in-toss.config.ts) 스키마에는brand.icon이 아예 없고(CLI 3.x 마이그레이션이brand에서primaryColor외 속성을 지운다), 2.x (granite.config.ts)도 스캐폴드 기본값이icon: ''이라 빈 값으로 빌드가 통과한다 — CLI2.10.8·3.0.5소스 확인. 다만 2.x 폴백에서 빈 값으로 빌드한 번들이 콘솔 컴파일(CREATED)은 통과하고 앱 실행 시점에 "잠시 문제가 생겼어요"로 실패했다는 보고가 있다(harness#90 — 이 skill이 재현·확인한 것은 아니다). 등록용 자산 자체가 없으면/ait:design을 먼저 안내한다.
입력
/ait:test-on-device는 인자를 받지 않는다. 대상 앱·워크스페이스는 콘솔 MCP
세션이 결정한다(아래 2).
실행 순서
1. 사전 확인 — appName 일치 가드
ls package.json apps-in-toss.config.ts granite.config.ts Packages/manifest.json 2>/dev/null
프로젝트 표지가 하나도 없으면 중단:
미니앱 프로젝트 파일(package.json과 apps-in-toss.config.ts·granite.config.ts, 또는
Unity의 Packages/manifest.json)을 찾을 수 없습니다. 미니앱 프로젝트 루트에서
다시 실행해주세요. 예: cd <project-root> && /ait:test-on-device
웹·RN은 발견된 번들 설정 파일(apps-in-toss.config.ts가 있으면 그것을, 없으면
granite.config.ts를 — 의존 절 참고)을 Read로 읽어 appName을 확인한다.
Unity·엔진 프로젝트는 SDK의 설정 화면이나 패키지 문서에서 앱 이름을 정하는 곳을
찾아 읽고, 어디인지 모르면 사용자에게 묻는다. Deploy Key가 든 설정 파일은
열지 않는다.
이 값이 콘솔에 등록된 앱의 appName과 정확히 같아야 한다. 불일치 번들은
업로드 자체는 성공하지만 컴파일에서 BUILD_FAILED로 끝난다(에러 메시지: "콘솔에
등록된 앱 ID와 granite.config.ts의 appName이 일치하지 않아요" — 콘솔 쪽 메시지
문구는 설정 파일 종류와 무관하게 고정이다). 불일치를 발견하면 업로드 전에
멈추고 어느 쪽을 맞출지 사용자에게 묻는다 — 이름이 다르다는 이유로 콘솔에 앱을
새로 만들지 않는다.
1-b. 결제·서버 사전 경고 (콘솔 상태와 무관하게 먼저 말한다)
프로젝트 소스에서 인앱 결제 호출(웹 SDK는 IAP., 엔진은 해당 SDK의 결제 API)을
찾는다. node_modules·dist·build·.git·Library·Temp 같은 제외 목록을 빼고
프로젝트 전체를 grep한다. 있으면 업로드·콘솔 확인보다 먼저,
콘솔 MCP를 쓸 수 없어 중간에 멈추게 되더라도 사용자에게 이렇게 알린다.
- 토스 앱에서 하는 결제 테스트는 실제로 결제(과금)된다고 가정한다.
- 테스트는 가장 싼 상품 하나로 한다.
- 환불이나 무과금 테스트 방법은 docs MCP로 인앱 결제 문서를 getPage로 읽어 확인한 만큼만 안내한다. 지어내지 않는다.
앱이 서버를 부르면(서버 주소 env, fetch로 부르는 자체 API) 서버 CORS 허용
목록에 테스트 환경 origin이 있는지 확인하라고 알린다. 허용 origin은 docs 서버
API 문서의 CORS 절을 getPage로 읽어 맞춘다. 서버 코드 자체를 고쳐야 하면
/ait:server로 넘긴다.
2. 콘솔 대상 확인
workspace_list로 인가된 계정이 보는 워크스페이스를 확인한다. 콘솔 MCP의 OAuth 세션은 인가한 계정의 워크스페이스 멤버십을 따른다 — 앱이 목록에 없으면 URL 문제가 아니라 계정 문제이므로, 다른 계정으로/mcp재인가가 필요하다고 안내한다.- 대상 앱의 현재 상태를
miniapp_get_status로 확인한다. - 콘솔에 앱이 아직 없을 때만
miniapp_create로 등록한다. 테스트를 이유로 앱을 새로 만들지 않는다 — 등록은 서버가 새 miniAppId를 발급하는 비가역 동작이고, 같은 앱은 계속 재사용한다.
3. 번들 빌드
빌드 방법은 스택마다 다르다. 가정하지 말고 프로젝트를 읽어 정한다. 모호하면 사용자에게 묻는다.
- 웹·RN:
package.jsonscripts를 읽는다.build스크립트가ait build까지 포함하면 그 스크립트 하나로.ait가 생긴다(정본 scaffold가 이 형태다). 포함하지 않으면 번들 단계 스크립트가 따로 있는지 본다. 구세대--local폴백 템플릿은build가tsc -b && vite build뿐이라new-miniappL-5가 추가하는bundle:ait스크립트("ait build")를 이어서 실행해야 한다(shared/templates/react-vite/package.json확인). 그 스크립트가 없으면 L-5 절차가 아직 안 된 것이므로 먼저 그것부터 안내한다. 실행은 프로젝트가 쓰는 패키지 매니저로 한다(락파일로 확인한다). - Unity·엔진 HTML5 빌드: 프로젝트 스크립트가 아니라 엔진 절차를 따른다. Unity는
앱인토스 SDK의 빌드 메뉴(빌드 프로필)로 빌드한다. 메뉴 이름·산출물 확장자와 위치는
docs MCP
getPage로/documentation/unity/build/build-process를 확인하고, 스택별 주의점은../feature/references/stack-pitfalls.md를 본다. 빌드 메뉴는 에이전트가 누르지 못하므로 사용자에게 실행을 안내하고, 끝났다는 답을 받은 뒤 다음으로 간다.
단독 실행 가능 여부는 web-framework 형상마다 다르다 (CLI 2.10.8·3.0.5
소스 확인):
- 3.x —
ait build는 이미 만들어진webBundleDir(기본dist/)를 포장만 한다. 없으면웹 빌드 디렉토리(dist)가 존재하지 않습니다. 웹 빌드를 먼저 실행해주세요.로 종료한다 — 항상 웹 빌드 이후에 돌린다. - 2.x 폴백 —
ait build가web.commands.build를 스스로 실행하므로 단독 실행이 성립한다. 오히려 기존dist/를 먼저 지우고 다시 빌드하므로, 웹 빌드 뒤에bundle:ait를 이어 돌리면 앞의 웹 빌드는 버려지는 중복 작업이다(해가 되지는 않는다).
산출물 .ait는 고정 경로를 가정하지 말고 glob으로 찾는다. 웹 scaffold는 보통
프로젝트 디렉터리 바로 아래에 <appName>.ait를 만든다(package.json 옆. dist/
안도 아니고 프로젝트의 상위 디렉터리도 아니다. 실측: 프로젝트 timer →
timer/timer.ait). 엔진 빌드는 위치가 다를 수 있다. 현재 위치가 프로젝트 밖인지
안인지 먼저 판단하지 말고 한 호출로 찾는다:
find . -maxdepth 4 \( -name node_modules -o -name .git -o -name Library -o -name Temp \) -prune -o -name '*.ait' -type f -exec ls -t {} + 2>/dev/null
여러 개가 나오면 수정 시각이 가장 최근인 것이 방금 빌드한 산출물이다. 오래된
.ait를 올리지 않도록 시각을 확인한다. 도구 셸의 cwd가 호출 사이에 리셋되는지
유지되는지는 실행 환경마다 달라 위치 추측이 자주 빗나간다(실측 — 빗나간 추측이
find·pwd 방황이나 불필요한 재빌드로 번진 사례가 여럿이다). 아무것도 안
나오면 빌드 로그가 찍은 산출 경로를 따른다. 빌드 설정의 출력 디렉터리가 깊으면
-maxdepth를 늘린다. 빌드를 다시 돌리는 것부터 하지 않는다. 빌드 명령이 오래
걸려 백그라운드로 전환됐다면 완료(exit code)를 확인한 뒤에 이 확인을 한다 —
완료 전 조기 탐색으로 ".ait가 없다"고 판단해 재빌드하는 것이 낭비의 전형이다(실측
사례 있음).
빌드 변형은 둘이다. 기본은 릴리즈 빌드다.
- 릴리즈 빌드(기본):
AIT_DEBUG_BUILD없이 빌드한다. 동작 확인과 검수·출시에 올릴 번들은 전부 이 변형이다. 빌드 전에 셸에AIT_DEBUG_BUILD가 남아 있지 않은지 본다 (echo "${AIT_DEBUG_BUILD:-}"가 비어 있어야 한다. 값이 있으면unset한 뒤 빌드한다). - 디버그 빌드: 사용자가 실기기에서 CDP attach로 디버깅하겠다고 한 경우에만, 프로젝트에
/ait:inject-debugger-client배선이 돼 있을 때AIT_DEBUG_BUILD=1을 붙여 빌드한다 (프로젝트 build 스크립트 앞에 환경 변수로 준다). 배선이 없으면/ait:inject-debugger-client을 먼저 안내한다. 사용자가 디버깅을 말하지 않았는데 이 변형으로 빌드하지 않는다. 디버그 도구 버전이../setup-debugger/references/min-versions.json의 최소 버전보다 낮은지도 이 빌드 전에 확인한다(references/debug-builds.md끝 절). 프로젝트에 옛 이름@apps-in-toss/debug-console이나.mcp.json의ait-devtools가 남아 있으면 "배선 없음"이 아니라 업그레이드가 필요한 상태다(../setup-debugger/references/upgrade-check.md0절).
업로드할 번들은 NODE_ENV=production으로 빌드한다. devtools unplugin이 이 값으로 활성화를 판단해,
없으면 일부 번들러(webpack CLI, esbuild, Rollup)가 mock과 패널을 번들에 남긴다. 웹 빌드 출력
디렉터리에서 grep -rlE '__aitDevtoolsStateSingleton__|ait-panel-toggle' <출력 디렉터리>가 0건인지
확인한 뒤 올린다(../feature/references/stack-pitfalls.md의 "번들러" 절).
릴리즈 빌드는 올리기 전에 디버그 마커도 확인한다. 출력 디렉터리(와 .ait)에서
grep -rlE '__ait_status_banner|__ait_debug_status|ait-attach|relayPublicKeys|startDebugConsole|__ait_session_chip|ait_remote_debugger' <출력 디렉터리>가
0건이어야 한다. 걸리면 올리지 말고 원인(__DEBUG_BUILD__ 게이트·define, 남은 환경 변수)을 먼저
잡는다. 디버그 빌드는 이 마커가 있는 것이 정상이다.
빌드 산출물의 deploymentId는 4에서 그대로 쓴다.
4. 업로드 — bundle_upload → bundle_upload_complete
콘솔 MCP 도구를 순서대로 호출한다:
bundle_upload— 응답으로 업로드 대상(presigned URL)을 받는다.- 받은 URL에
.ait번들을 PUT으로 올린다. bundle_upload_complete— 업로드 완료를 콘솔에 알린다. 여기서 컴파일이 걸린다.
인자는 세션에 노출된 도구 스키마를 그대로 따른다. deploymentId는 3의
빌드 산출값을 전달한다 — 임의 UUID를 지어내지 않는다. 어느 단계든 에러가
나면 응답을 가공 없이 사용자에게 전달하고 다음 단계로 넘어가지 않는다.
5. 컴파일 상태 확인 — miniapp_get_status
bundle_upload_complete 호출 뒤 컴파일 진행은 bundle_build_status로 폴링한다.
이 도구는 빌드 중(PREPARE·BUILDING)인 번들만 미니앱 단위로 돌려주는 경량 조회다.
종료 조건: 4에서 올린
deploymentId가builds에서 빠지면 그 번들의 빌드가 끝난 것이다(CREATED또는BUILD_FAILED).builds가 전부 빌 때까지 기다리지 않는다 —bundle_upload만 하고bundle_upload_complete를 하지 않은 번들이 PREPARE로 남아 있으면isBuilding이 계속 true일 수 있다.결과 확인: 빌드가 끝나면
bundle_list에서 그deploymentId항목의 상태를 본다(bundle_list는bundle_upload_complete전의 PREPARE 번들을 보여주지 않는다). 페이지네이션의totalPage는 마지막 페이지 번호(0-base)라 전체가 1페이지면 0이다 — 0이어도 결과 없음으로 해석하지 않는다.miniapp_get_status는 미니앱의 공개 운영 상태(serviceStatus)를 돌려줄 뿐 번들 컴파일 결과가 아니다. 컴파일 판정에 쓰지 않는다.CREATED— 컴파일 성공. 6으로 간다.BUILD_FAILED— 1의 appName 일치부터 다시 본다. 같은 번들을 반복 업로드해서 통과시키려 하지 않는다.
5-B. 디버그 빌드였다면 기록하고 알린다
방금 올린 번들이 디버그 빌드(AIT_DEBUG_BUILD=1)였다면 bundle_upload_complete로 deploymentId가
정해지는 즉시(컴파일 결과를 기다리지 않는다) deploymentId와 번들 버전을 프로젝트 루트의 .ait-debug-deployments.json에 기록한다.
형식, .gitignore 줄 추가, 사용자 안내 문구는 Read
<이 skill의 base directory>/references/debug-builds.md. 사용자에게는 "이 배포는 디버그
빌드라 검수에 제출하면 안 됩니다"를 반드시 전한다. 릴리즈 빌드는 기록하지 않는다.
6. 토스 앱에서 확인
두 갈래를 위에서부터 시도한다.
6-A. bundle_test_push의 privateLink를 그대로 전달한다.
bundle_test_push(workspaceId, miniAppId, 선택 deploymentId — 생략하면 빌드
완료된 최신 번들)는 업로드한 번들을 요청자 본인의 토스 앱으로 테스트 푸시로
보내고, 응답에 진입 링크를 담는다.
privateLink— 이 번들만 실행되는 테스트 전용 딥링크 (intoss-private://<appName>?_deploymentId=<uuid>형태,debug/SKILL.md§5-B 참고, 형식 검증은packages/debugger/src/mcp/deeplink.ts). 푸시를 못 받았거나 다른 기기에서 열 때 쓴다. 가공 없이 사용자에게 전달하고 폰에서 열도록 안내한다. 라이브 번들이 열리는 서비스 링크(intoss://<appName>)와 다르고, 본인 외 사람이 열어도 번들이 뜨지 않는다.consoleTestUrl— 이 번들의 테스트 QR을 띄우는 콘솔 웹 주소. 딥링크가 열리지 않는 환경이면 PC에서 열어 QR을 찍도록 안내한다.- 본인 외 멤버에게는 발송되지 않는다. 호출하면 해당 deployment에
isTested=true(테스트 환경 준비 완료)가 기록되는데, 실제 테스트 완료를 뜻하지 않는다. 링크를 안내한 뒤 멈추고, 사용자가 현재 대화에서 테스트 완료와 검토 요청을 명시하기 전에는bundle_submit_review를 호출하지 않는다(그 호출은 이 skill 범위 밖이고/ait:launch의 몫이다). - 대상은 지금 작업 중인 앱의 방금 올린 번들뿐이다. 다른 앱·다른 번들로 푸시하지 않는다.
링크를 손으로 조립하지 않는다 — 문서 예제의 링크 형태에 deploymentId 같은
값을 끼워 넣어 만든 링크는 열리지 않는다(2026-08-07 도그푸딩에서 실제로 그렇게
만든 링크가 실패했다). privateLink가 응답에 없으면 "링크가 응답에 없다"고 그대로 말하고
6-B로 간다.
링크를 폰으로 옮기는 방법: 메신저로 자신에게 전송하거나, 로컬 QR 생성
도구로 변환해 카메라로 스캔한다(debug skill 환경 3의 start_attach QR
발급과 같은 패턴이지만, 이 skill은 console MCP만 쓰므로 QR을 직접 발급하는
도구는 호출하지 않는다 — 링크 문자열을 옮기는 구체 수단은 사용자 환경에 맡긴다).
6-B. 링크를 받지 못했거나 열리지 않으면 콘솔 웹으로 간다.
bundle_test_push가 에러를 돌려주거나 privateLink가 비어 있거나 딥링크가 열리지
않는 환경이면, consoleTestUrl이 있으면 그것을 안내하고 없으면 콘솔 웹에서 해당
앱의 번들 목록을 열어 테스트 발송을 사용자가 직접 하도록 안내한 뒤 멈춘다. 에러
응답은 가공 없이 전달한다. 도구 이름이나 링크를 지어내지 않는다.
확인이 끝나면 한 블록으로 마무리한다:
<appName> 번들이 콘솔에 올라갔습니다.
버전 <versionName>
상태 CREATED (컴파일 완료)
토스 앱에서 확인:
1. 위 링크(`bundle_test_push`의 privateLink)를 폰에서 엽니다 (직접 조립하지 마세요)
2. 열리지 않으면 consoleTestUrl을 PC에서 열어 QR을 찍거나, 콘솔 웹에서 테스트 발송을 진행합니다
폰에서만 재현되는 문제를 코드 레벨로 파고들려면
(명령을 몰라도 됩니다 — 따옴표 안 문장을 그대로 말해도 같은 단계로 갑니다):
/ait:setup-debugger # 디버그 MCP 배선 (1회)
# 말로: "나중에 폰 디버깅할 수 있게 디버거 연결을 미리 세팅해줘"
/ait:debug # 실기기 CDP attach로 관측
# 말로: "미니앱이 폰에서 이상하게 동작하는데 라이브 상태를 디버깅하고 싶어"
(디버그 빌드를 올렸다면 이 블록에 아래 한 줄을 더한다)
주의 이 배포는 디버그 빌드입니다. 검수에 제출하지 마세요. .ait-debug-deployments.json에 기록했습니다.
폰에서 확인을 마치고 검수에 넣을 차례라면 (검수용은 AIT_DEBUG_BUILD 없이 빌드한 릴리즈 빌드를 올립니다):
/ait:launch # 출시 전 점검, 검수 요청
# 말로: "검수 넣기 전에 한번 봐줘"
문서가 필요하면 docs MCP(searchDocumentation/getPage)로 조회하세요.
Out of scope (이 skill이 하지 않는 것)
- ❌ 검수 제출 —
review_*계열,bundle_submit_review. 비가역 상태 전환이라 이 skill은 어떤 경우에도 호출하지 않는다. 검수 요청은/ait:launch가 사용자 승인을 받은 뒤에 한다. - ❌ 릴리즈·롤백·프로모션 — 라이브 버전 전환 계열 도구 전반. 실기기 확인은 업로드·컴파일까지가 경계다.
- ❌ 마케팅 푸시 캠페인 발송, 푸시 전달률·지연 QA. 이 skill은 자기 번들을 자기 폰에서 여는 경로만 다룬다.
- ❌ 실기기 CDP attach·테스트 러너 —
/ait:setup-debugger배선 후/ait:debug환경 3. - ❌ 등록용 이미지 자산 생성 —
/ait:design. - ❌ Deploy Key/API 키 기반 직접 배포(
ait deploy --api-key)를 Bash로 호출. 인가는 항상 콘솔 MCP의 OAuth 세션만 쓴다. - ❌ 코드 수정 — 실패 원인을 진단해 알려주고, 수정은 에이전트의 일반 편집 흐름으로.
하지 말아야 할 것
- ❌ 진입 링크를 손으로 조립. 문서 예제 +
deploymentId조합으로 만든 링크는 열리지 않는다 — 링크는 항상bundle_test_push가 돌려준privateLink그대로만 쓴다(6-A). - ❌ 확인되지 않은 도구 이름을 추측해 호출. 세션에 실제로 노출된 이름·스키마만 근거로 삼고, 없으면 콘솔 웹 안내로 내려간다(6-B).
- ❌ appName 불일치를 콘솔 쪽 새 앱 생성으로 해결. 기존 앱을 재사용하고, 어느 쪽을 맞출지는 사용자가 정한다(1).
- ❌
BUILD_FAILED를 같은 번들 재업로드로 우회 시도. 원인(대개 appName 불일치)을 먼저 잡는다(5). - ❌
builds가 전부 빌 때까지bundle_build_status를 기다림. 내가 올린deploymentId가 빠졌는지로 판정한다(5). - ❌
bundle_test_push성공(isTested=true)을 테스트 완료로 간주해 검수 제출로 이어감(6-A). - ❌ 사용자가 디버깅을 말하지 않았는데
AIT_DEBUG_BUILD=1로 빌드해 올림. 동작 확인과 검수용은 릴리즈 빌드다. - ❌ 디버그 빌드 배포를 기록하지 않고 넘어감, 또는 그 배포를 검수 제출 후보로 안내함.
- ❌ 브라우저에서 재현되는 문제를 실기기 업로드로 확인. 그건 프로젝트 dev 스크립트 +
/ait:debug환경 1이 훨씬 빠르다. - ❌ 시크릿·인증 코드·업로드 presigned URL의 서명 파라미터를 stdout·로그·메시지에 출력.
- ❌ 메시지에 과장·홍보성 문구. 안내는 상태와 다음 행동을 설명하는 최소한으로.
참고
- 짝 skill:
new-miniapp(scaffold),design(화면·등록용 이미지 자산),setup-debugger·debug(실기기 CDP attach — 이 skill 다음 단계),inject의 debugger-client facet(디버그 빌드에 attach 표면 설치). references/debug-builds.md: 디버그 빌드 배포 기록 파일 형식과 절차.- 콘솔 MCP(
ait-console) 인가는/mcp1회. 세션이 보는 워크스페이스는 인가한 계정의 멤버십을 따른다(2). - 번들 규격·콘솔 등록 절차·진입 스킴 등 주제별 문서는 docs
MCP(
searchDocumentation/getPage)로 조회한다.