new-miniapp skill
목적
이 문서는 로드된 즉시 현재 턴에서 네가 직접 실행하는 지시문이다 — skill은 백그라운드에서 실행되지 않으며, 기다릴 완료 신호도 없다. 아래 Step을 지금 순서대로 직접 수행한다. ("skill이 실행 중이니 완료를 기다리겠다"는 판단은 오독이다 — 실측에서 약한 모델이 이 오독으로 scaffold를 시작조차 못 했다.)
/ait:new <app-name> 한 번으로 새 앱인토스 미니앱 프로젝트를 빈 상태에서
시작할 수 있게 한다. 사용자가 묻기 전에 답해야 할 것:
- scaffold는
toss/create-ait-app(공식 스캐폴더 CLI)을 비대화형(--inline)으로 호출해 만든다 — 버전은 항상@latest(명시 핀 없음, maintainer 결정 2026-08-10). 템플릿은 번들된 create-vite 프리셋에 위임한다. 스택(프레임워크·언어)은 사용자가 정한다 — 말하지 않았으면 기본react-ts, 말했으면--list-templates출력에서 그 스택의 프리셋을 고른다(아래 "스택 선택").--tds(TDS 컴포넌트 홈 + provider, React 18 전용,--template과 동시 지정 불가 — 아래 참조),--sample iap,iaa(인앱결제·인앱광고 예제)를 그대로 쓸 수 있다. @apps-in-toss/devtools배선과 번들 설정은 CLI가 한다 — create-ait-app이 scaffold 직후ait init을 호출해 devtools를 devDependency로 넣고 번들러 설정에 unplugin을 주입하며,apps-in-toss.config.ts와build/build:vite/deploy스크립트도,.gitignore의*.ait줄도 같은 실행이 만든다(실측 2026-08-07,create-ait-app@0.2.3—*.ait줄은@apps-in-toss/cli3.1.1 dist 실측 2026-09-07, 0.2.8 재현 2026-10-14에서도 동일). 순정 create-vite 템플릿에는 SDK mock이 없어 브라우저에서 SDK 호출이 실패하지만(샘플 코드가 "샌드박스앱/토스앱에서 실행해주세요" alert를 띄운다) 이 배선 덕에 토스 앱 없이npm run dev로 바로 개발할 수 있다.ait init은 실패해도 CLI가 "완료"로 끝내므로 형상 가드(Step 3)가 실재를, Step 4가 배선을 확인하고 폴백한다.- 이건 토스 앱 WebView에서 도는 웹(DOM) 미니앱이지 React Native 앱이 아니다.
RN 네이티브 컴포넌트나
react-nativeimport를 쓰지 않는다(설치 시 SDK가 RN을 peer로 선언해 뜨는unmet peer react-native경고는 무시해도 된다). - 디자인 가이드도 함께 심는다(Step 5-B) — 토큰·기본 CSS·아이콘 6종·
docs/design-guide.md와 캐리어 문서(AGENTS.md·CLAUDE.md), 이모지 서체 Tossface가 들어간다. 나중에 어떤 세션이 화면을 만들어도 같은 기준(글자 크기 하한·터치 44px·하단 CTA safe area)을 따르게 하려는 것이다.--no-design-guide(전체)·--no-tossface(서체만)로 뺀다. - 다음 단계(
npm run dev→ 코드 수정 →/ait:design→npm run build(프로젝트build스크립트 — 끝이ait build)로 번들 생성 → console MCP 도구로 등록·업로드)가 명확히 안내된다.
이 skill은 **scaffold 호출 + 후처리(설치 상태 확인 · 형상 가드 · devtools 배선
확인/폴백 · .gitignore 보강(*.ait·실패 흔적 파일) · 디자인 가이드 주입)**만
담당한다. 콘솔 등록·번들 업로드는 console MCP 도구(miniapp_create/bundle_upload/
bundle_upload_complete)의 책임 — 여기서 자동 호출하지 않는다. 생성되는
README/UI/주석에 과장·홍보성 문구를 넣지 않는다.
입력
<app-name>(필수): 사람이 읽는 이름 후보. 디렉토리/패키지 이름으로 슬러그화된다 (kebab-case, 소문자). 공백·특수문자 포함 가능.--template <name>(선택, defaultreact-ts): 지원 목록은 create-ait-app이 번들한 create-vite에서 동적으로 산출된다(index.html 존재 + vite dep + dev/build 스크립트 + 비-SSR 필터 기준). 별칭js→vanilla,ts→vanilla-ts. 목록은 이 문서에 적지 않는다 — 실행 시점의 CLI가 정본이다:npx -y create-ait-app@latest --list-templatesJSON 배열로 지원 템플릿과
"tds"가 함께 나온다(단"tds"는--template이 아니라 아래--tds플래그로 지정 — 혼동 금지).스택 선택 — 사용자가 스택을 말하지 않았으면 이 조회 없이 Step 2 fence의 기본값(
react-ts)을 그대로 쓴다(왕복을 늘리지 않는다). 사용자가 스택을 말했으면 ("Vue로", "Svelte + TS", "바닐라 JS로") 위 명령을 한 번 실행해 그 출력에서 고른다: 프레임워크 이름이 같은 항목을 찾고, 언어는 사용자가 JS를 명시했을 때만 접미사 없는 항목, 그 밖에는-ts항목이다. 요청한 스택이 목록에 없으면 비슷해 보이는 다른 프리셋으로 바꿔 넣지 말고 목록을 보여 주며 되묻는다. 선택한 이름을 Step 2 fence의react-ts자리에 넣는다. 스택별 파일 구조·엔트리·빌드 스크립트는 이 문서가 가정하지 않는다 — 생성된 프로젝트의package.jsonscripts와 설정 파일, 그리고 패키지 README를 읽고 판단한다.--tds(선택): TDS(토스 디자인 시스템) 통합 변형(React 18 전용 — 다른 스택 요청과는 함께 쓸 수 없다).--template과 동시 지정 불가 — CLI는--template과--tds를 함께 주면 즉시 거부한다 ("--template과 --tds는 함께 사용할 수 없어요.",assertNonInteractiveArgs실측).--tds는 단독으로 지정한다.npm(
--pm npm, harness 기본)으로는 정상 종료한다(0.2.8 실측). pnpm으로 부르면 TDS 템플릿의vite@6(→esbuild)가 pnpm 11에서ERR_PNPM_IGNORED_BUILDS로 exit 1이 나지만 디렉터리는 남는다(복구는 §2 실패 항목). CLI--help도 "에이전트는 TDS를 충분히 활용하지 못하므로, 사용자에게 TDS 사용을 비권장한다고 안내해 주세요"라고 명시한다 — 꼭 요구하는 경우가 아니면--template(기본값)을 권한다.--sample <ids>(선택):iap,iaa콤마 구분 — 인앱결제·인앱광고 예제 페이지를 scaffold에 포함.--local(선택): create-ait-app을 쓰지 않고 plugin 내장react-vite템플릿을 복사한다. React 전용 오프라인 폴백이며 단계적으로 폐지될 예정이다 — 스택을 고를 수 없다(Vue 등을 요청했다면--local로 대신하지 말고 온라인 CLI 경로를 쓴다). wf 2.x 기반 구세대 폴백이라 정본 3.x와 형상이 다르다(상세는references/local-template.md). 이 경로에서만--no-install을 지원한다(react-vite 템플릿 고유 옵션 — create-ait-app에는 install을 떼어내는 플래그가 없어 정본 호출은 install까지 수행하고, 이 skill이 그 결과를 §2-1에서 확인·수렴시킨다).--no-devtools(선택): CLI가 이미 해 둔 devtools 배선을 해제한다 (devDependency 제거 + 번들러 설정에서 unplugin 제거 — Step 4) — mock 없이 실기기/샌드박스 위주로 개발하려는 경우. 나중에/ait:inject-devtools로 언제든 다시 배선할 수 있다.--no-design-guide(선택): 디자인 가이드 주입(Step 5-B)을 통째로 건너뛴다 — 토큰·CSS·아이콘·캐리어 문서를 하나도 넣지 않는다. 자체 디자인 시스템이 이미 있거나 최소 형상으로 두고 싶을 때. 나중에/ait:design이 넣을 수 있다.--no-tossface(선택): 디자인 가이드는 넣되 이모지 서체 Tossface 배선만 뺀다 — 기본 CSS에서 CDN@import한 줄과 폰트 스택의Tossface항목을 제거한다. 오프라인 결정성이 필요하거나 서체를 직접 고르고 싶을 때. 나중에/ait:inject-tossface로 CDN·번들 두 모드 중 골라 배선할 수 있다.
플래그는 사용자가 요청한 것만 붙인다 — 특히 --no-* 계열은 추측해서 붙이지
마라. 이 플래그들은 산출물을 빼는 방향이라, 잘못 붙이면 사용자가 받기로 한 것을
조용히 못 받는다. 요청에 그 플래그의 대상(디자인 가이드 · devtools · Tossface ·
로컬 템플릿)이 이름으로 등장하지 않으면 붙이지 않는다. "간단한 앱으로",
"순수 UI로", "최소한으로", "권한 없이" 같은 말은 만들 앱이 무엇을 하느냐의
범위이지 스캐폴드가 무엇을 깔아 주느냐의 범위가 아니다 — 그런 표현을 산출물
축소 지시로 확대 해석하지 마라(실측: 한 run이 "권한이나 외부 SDK 없이 순수 UI"만
요구한 과제에서 아무도 요청하지 않은 --no-design-guide를 스스로 붙여 디자인
가이드 전체를 뺐다. 완료 보고에 사실대로 적기는 했지만, 사용자는 뺄 생각이 없던
것을 잃었다). 애매하면 붙이지 않는 쪽이 기본값이다 — 빼는 것은 나중에
/ait:design·/ait:inject-*로 되돌릴 수 있지만, 안 넣은 것을 사용자가 알아채지
못하면 되돌릴 기회 자체가 없다.
호출 예 (슬래시 명령과 자연어 요청은 같은 skill로 이어진다 — 슬래시 네임스페이스가 그대로 오지 않는 에이전트에서는 아래 자연어 쪽이 정규 경로다):
/ait:new my-mini-app # 말로: "앱인토스 미니앱 새로 하나 만들어줘. 이름은 my-mini-app 으로."
/ait:new "내 미니앱" --tds # 말로: "토스 디자인 시스템까지 얹어서 미니앱 만들어줘"
/ait:new my-shop --sample iap # 말로: "인앱결제 예제까지 넣은 미니앱 my-shop 만들어줘"
/ait:new my-app --local --no-install # 말로: "오프라인 로컬 템플릿으로 만들고 설치는 건너뛰어줘"
/ait:new my-app --no-devtools # 말로: "devtools 배선 없이 미니앱만 만들어줘"
/ait:new my-app --no-design-guide # 말로: "디자인 가이드는 넣지 말고 미니앱만 만들어줘"
/ait:new my-app --no-tossface # 말로: "이모지 서체는 빼고 미니앱 만들어줘"
의존
- 호스트에 Node 24+(create-ait-app
engines.node >=24+ Vite 요구사항)면 충분하다 — npm은 Node에 동봉된다. npm 고정은 CLI의 한계가 아니라 harness의 규약이다: CLI는 npm/yarn/pnpm 3종을 지원하지만(--pm <name>) 이 skill은 후속npm run dev/npm --prefix흐름과 통일하려고 항상--pm npm으로 부른다 (사용자가 명시적으로 요구하면 그 값에 맞춘다). Step 0이 실행 전 검사한다. - 인터넷 필요 —
npx -y가 create-ait-app을 받아 파일 생성부터 install·ait init까지 한 번에 수행한다.@apps-in-toss/web-framework의 버전은 create-ait-app이 자기 빌드에 박아 둔 정확 버전이다(.github/version-pins/package.json의 핀을dependencies에 그대로 쓴다. 0.2.9 dist 실측3.8.0) — 공개latest가 더 높아도 그 핀을 받고, 핀은 create-ait-app이 새로 발행될 때만 움직인다. 종전 CLI는"latest"리터럴을 써서 install 시점의 registry에 달렸었다(harness#90 항목1 — 공개latest가 3.x 출시 뒤에도 한동안 2.10.8을 가리키는 어긋남이 그때 확인됨). 오프라인이면--local폴백.
이 skill은 콘솔 인증을 요구하지 않는다. 로그인 없이 빈 프로젝트만 만들고 끝낸다. 콘솔 등록은 사용자가 준비됐을 때 별도로.
실행 순서
Step 0 — toolchain 사전 검사
node --version(24+)을 확인한다. npm은 Node에 동봉되므로 npm --version이 정상
응답하는지만 가볍게 본다. 비개발자가 raw 셸 오류를 마주치지 않도록, Node
없음/24 미만이면 여기서 멈추고 nvm(nvm install 24 && nvm use 24) 또는
https://nodejs.org/en/download/ 를 한 블록으로 안내한 뒤 종료한다(Node를 설치하면
npm도 함께 들어온다).
1. 입력 정규화 + 충돌 검사
<app-name>이 비었으면 되묻는다 (예:"앱 이름을 알려주세요 (예: my-mini-app)").package_name = slugify(app_name)— 소문자 → 비-alphanumeric을-로 → 연속-압축 → 양 끝 trim. 빈 문자열/숫자 시작이면 npm 호환 이름을 되묻는다.콘솔 등록 시
appName(=package_name)에는 별도 규칙이 있다고 보고됐다 (harness#90 항목3, 2026-08-07 — 이 skill이 콘솔 공식 문서로 직접 검증한 것은 아니다): 영문 소문자·숫자·하이픈, 63자 이하,toss포함 금지(apps-in-toss도 부분 문자열로 포함하므로/toss/하나면 된다). CLI도 slugify도 이걸 검사하지 않아 위반은 콘솔 등록(miniapp_create) 단계에서야 거부된다 — scaffold 전에 여기서 먼저 막는다. 63자 초과이거나toss를 포함하면 시작하지 않고 되묻는다:package_name이 콘솔 appName 규칙(영문 소문자·숫자·하이픈, 63자 이하, "toss" 포함 불가)을 위반합니다 — 다른 이름을 알려주세요.대상은 현재 cwd 하위
<package_name>/. 이미 존재하고 비어있지 않으면 거부:./<package_name> 디렉토리가 이미 있습니다. 다른 이름을 쓰거나 디렉토리를 먼저 정리해주세요. 자동으로 덮어쓰지 않습니다.(create-ait-app도 같은 상황에서 exit 1 하지만, 우리가 먼저 검사해 명확한 한국어 안내를 준다. CLI에는
--force/overwrite가 없다.)
--local이면 여기서 references/local-template.md를 Read해 그 절차(복사 +
토큰 치환 + 디자인 가이드 확인 + install + 안내)로 진행하고, 아래 2~6은 건너뛴다.
예외는 5-B 하나 — 그 문서의 L-3b가 확인 목적으로 같은 스크립트를 부르고, 템플릿이
자산을 프리베이크로 담고 있어 정상이면 전 항목이 skip으로 끝난다.
2. scaffold — create-ait-app 비대화형 호출
scaffold는 명령 하나다 — CLI가 파일 생성 → npm install →
ait init --app-name <name> --skip-input(devtools·번들 설정 배선)까지 전부
수행한다. install을 떼어낼 방법은 없다(--skip-install은 없다 — 지정하면
알 수 없는 옵션이에요: --skip-install로 즉사하고 산출물이 0이다, 0.2.3 실측
2026-08-10, 0.2.8 플래그 표에도 없다). 디자인 가이드 주입(5-B)도 같은 체인에 잇는다 — 별도 단계로
미루면 일부 run이 건너뛰는 실측 사례가 있어, scaffold가 성공한 모든 run이
반드시 주입까지 실행하도록 명령 레벨에서 결합했다:
npx -y create-ait-app@latest <package_name> --inline --pm npm --template react-ts && bash "<이 skill의 base directory>/../design/scripts/inject-project-guide.sh" "./<package_name>"
위 fence는 기본값 --template react-ts가 이미 채워진 그대로 실행되는 명령이다 —
템플릿 요청이 없으면 한 글자도 바꾸지 않고 실행한다. 바꿔 넣는 자리는 셋뿐이다:
사용자가 다른 스택을 지정했으면 react-ts 자리에 --list-templates에서 고른 이름, --tds면
--template react-ts를 통째로 --tds로 교체(둘을 같이 주면 CLI가 거부한다 —
이때 주입 스크립트 인자에도 --tds를 붙인다), --sample을 요구했으면
--template react-ts 뒤에 --sample iap,iaa를 덧붙인다. "템플릿 얘기가 없었으니
--template은 빼자"가 가장 흔한 낭비였다 — 이전 표기 (--template <template> | --tds)를 모델이 채우지 않고 지워 CLI의 비대화형 실행에 필요한 값이 빠졌어요를
받고서야 다시 넣었다(실측: 25 run 중 19가 첫 호출에서 이 왕복을 했고, 그 재시도가
백그라운드 전환·타임아웃 탈선의 출발점이 된 run이 셋이다). 기본값이 fence에 박혀
있으니 이 왕복은 없어야 한다.
핀을 쓰지 않는 이유와 남는 위험:
create-ait-app은 항상@latest로 부르는 것이 정책이다(maintainer 결정 2026-08-10) — 명시 핀은 upstream 개선(이 skill이 우회하던 결함의 수정 포함)을 받지 못하게 막는 쪽이 더 컸다.@apps-in-toss/web-framework의 버전은 이 skill이 정하지 않는다 — create-ait-app이 자기 빌드에 박아 둔 정확 버전을 쓰므로 "최신 create-ait-app이 고른 wf"를 받는 셈이고, 공개latest보다 뒤일 수 있다. 대신 산출물 형상은 매 run 후처리 0(Step 3)이 검사하므로, 형상이 바뀌면 조용히 깨지는 대신 그 자리에서 멈춘다. 다만 형상 가드가 잡지 못하는 축이 남는다 — CLI의 동작 변화(예:ait init자동 호출이 사라지거나 배선 대상이 바뀌는 것)는 산출물 파일 목록이 같으면 통과할 수 있다. Step 4가 devtools 배선을 실물로 확인하는 이유가 이것이고, 그래도 어긋나면 아래 "호출 규칙" 말미의 원칙(CLI 에러를 그대로 전하고 중단)을 따른다.create-ait-app@latest의 dist-tag 자체가 환경마다 다르게 해석될 수 있다는 위험은 아래 "버전 해석이 실패하는 경우" 항목에서 다룬다.
호출 규칙 (create-ait-app 0.2.3·0.2.8 소스 실측 근거 — 실행 버전은 @latest 해석에
따른다):
<package_name>(positional)·--pm npm·--template react-ts(또는--tds)를 전부 명시 —--inline이면 이 중 하나만 빠져도 CLI가 에러로 즉시 중단한다 (assertNonInteractiveArgs). 프롬프트로 빠지는 게 아니라 실패한다. fence에--template react-ts가 이미 들어 있다 — 그것을 지우는 것이 곧 이 에러다.- 스캐폴더는
create-ait-app하나다 —npm create @apps-in-toss/app같은 변형 명칭을 기억으로 지어내 시도하지 마라(존재하지 않는 패키지라 404가 난다 — 실측). 위 fence의npx -y create-ait-app@latest형태 그대로 쓴다. - 생성 위치는 positional 경로로 지정한다 —
--cwd플래그는 없다(알 수 없는 옵션으로 즉시 에러). 현재 디렉터리에 만들려면 positional에.을 준다 (npx -y create-ait-app@latest . --inline …). positional은 하나만 받는다 — 두 개 이상이면알 수 없는 인수예요로 거부한다. - 현재 작업 디렉터리에서 실행한다 — 명령 앞에
cd를 붙이지 마라. 사용자가 위치를 명시하지 않았다면 세션의 작업 디렉터리가 곧 프로젝트를 둘 자리다. scaffold 앞에cd /tmp·cd ~같은 이동을 붙이면 산출물이 사용자가 찾을 수 없는 곳에 생긴다 — 이후 후처리가 전부 통과해도 사용자 눈에는 결과물이 없는 실패다(실측 사례 있음). 도구 셸의 cwd가 호출 사이에 리셋되는지 유지되는지는 실행 환경마다 다르다 — 어느 쪽도 가정하지 마라(리셋을 가정하고 상대 경로를 다시 쓰다 유지 환경에서 어긋난 사례, 그 반대 사례 둘 다 실측됐다).cd를 안 붙이면 cwd는 어느 환경에서든 작업 디렉터리에 머물러 이 차이가 문제되지 않는다 — Step 3 이후의 모든 후처리 fence도cd없이 적힌 그대로(작업 디렉터리 기준./<package_name>/…상대 경로) 실행한다. 상대 경로가 갑자기 어긋나면("no such file" 등) 경로를 바꿔가며 추측을 거듭하지 말고pwd한 번으로 현재 위치부터 확인한다. "Shell cwd was reset" 알림도 확정 신호가 아니다 — 알림과 실제 cwd가 어긋나는 환경이 있으니, 보이면cd로 되받아치지 말고 프로젝트가./<package_name>에 있는지부터 재확인한다. --skills·--skip-install은 존재하지 않는다 — 플래그 표는 값 플래그--pm·--sample·--template, 불리언 플래그--help·--inline·--list-templates·--tds·--version이 전부다(0.2.8 dist 실측). 없는 플래그는 즉시 에러이므로 "혹시 되나" 식으로 붙이지 않는다.--skills를 피하던 이유도 유효하다 — 에이전트용 지식 주입은 이 plugin의 skill 체제가 담당한다.npx -y를 쓴다 —-y는 npx 최초 실행 시 나오는 설치 확인 프롬프트를 비대화형으로 넘긴다(non-TTY 세션이 이 프롬프트에서 멈추는 것을 막는다).&&뒤 주입 세그먼트는 조립할 때 빼먹기 가장 쉬운 부분이다 — 생략하지 마라. 세그먼트를 뺄 수 있는 경우는--no-design-guide하나뿐이고, 그 외에는 위 fence의 두 명령을 그대로 한 번의 Bash 호출로 실행한다 — 주입을 뒤로 미뤄 별도 호출로 쪼개지 않는다. 재시도에도 그대로 적용된다 — scaffold가 실패해 같은 명령을 다시 돌릴 때도 주입 세그먼트가 붙은 전체 한 줄을 재실행한다. 스캐폴더 부분만 따로 재실행하면 주입이 조용히 빠진다(실측: 재시도 run이 체인을 쪼갠 채 주입을 한 번도 실행하지 않았다). 인자 규칙:--tds로 스캐폴드하면 스크립트에도--tds를,--no-tossface면--no-tossface를 덧붙인다.- 스크립트 경로는 기억으로 지어내지 않는다 — 시스템이 이 skill을 로드할 때
표시한 base directory 문자열 뒤에
/../design/scripts/inject-project-guide.sh를 그대로 붙인다. 그 문자열을 눈으로 다시 확인하고 옮겨라.$PWD·dirname조합으로 새로 만들거나find로 찾아 헤매지 말고,$HOME/.claude/skills/…처럼 "보통 여기 있겠지" 하는 위치를 써 넣지도 마라 — 그렇게 만든 경로는 실측에서 대부분 틀렸다(실측: 한 run은$HOME기반 경로를, 다른 run은 skill 이름 세그먼트가 빠진 경로를 써서 스크립트를 아예 못 찾았다). "No such file"이 나도 거기서 포기하지 마라 — Step 3의 디자인 가이드 fence가 후보 다섯 곳을 스스로 훑어 스크립트를 다시 찾고, 그래도 없으면 자산 폴백으로 넘어가므로, 이 자리에서 경로가 틀렸어도 그 fence가 복구한다. 스크립트 파일을 Read로 열어 보지 마라 — 내용을 알 필요 없이 이 호출 하나면 된다. 출력 해석·보고 규칙은 5-B 절. - 이 규칙과 실제 CLI가 어긋나면 CLI 에러가 최신 규칙이다 —
@latest가 여기 적힌 0.2.9보다 새 버전을 받으면 플래그·인자 규칙이 달라질 수 있다. 그때는 플래그를 빼고 다시 넣어 보는 식으로 우회하지 말고, 에러 문구를 그대로 사용자에게 전하고 중단한다(그 자리에서--help로 현재 규칙을 확인해 함께 보고하는 것까지는 해도 된다).
성공 판정은 exit code로 한다 — 완료 메시지 문구는 버전마다 다르다(0.2.3은
✅ 프로젝트가 생성됐어요.를 낸다). 문구 문자열 매칭으로 판정하면 CLI가 문구를
바꿀 때 조용히 오탐한다. 주입 스크립트는 내부가 fail-soft라 항상 exit 0이므로
&& 체인이 exit code의 의미를 바꾸지 않는다 — 0이 아니면 scaffold/install
실패다. 에러로 끝나면 stderr를 그대로 사용자에게 전하고 중단한다:
완전 오프라인으로 보이면
--local폴백을 안내한다.create-ait-app@latest의 버전 해석이 실패하는 경우 — 일부 사내망 프록시 환경은 특정 버전·dist-tag를 못 내려주거나,latest를 공개 registry와 다르게 준다(최신을 숨겨 구버전을 주기도 하고 공개에 없는 prerelease를 주기도 한다 — 그래서 해석 실패를 "그 버전이 없다"로 단정하면 안 된다). 공개 미러(registry.npmmirror.com)·jsdelivr로 교차 확인한다. 우회가 필요하면--local폴백을 먼저 권하고, 레지스트리를 바꾸는 우회(프로젝트 전용.npmrc의 override,npm_config_registry)는 쓸 호스트와 이유를 사용자에게 보여 주고 동의를 받은 뒤에 한다. 바꾼 registry에서 받은 패키지는 공개 registry와 같은 바이트라는 보장이 없으니, 명령 한 번에만 주고.npmrc에는 남기지 않는다(호스트명을 하드코드하지 않는다).scaffold 단계 install이 실패한 경우 — 0.2.4부터 CLI는 생성 디렉터리를 지우지 않고 남긴 채
cd <dir>이어하기 안내를 낸다(0.2.8 실측). 이 실패는ait init앞에서 난 것이라 안내대로 install만 다시 하면 devtools와apps-in-toss.config.ts가 없는 프로젝트가 된다. 에러를 그대로 보고하고, 원인을 고친 뒤npm --prefix ./<package_name> install로 install을 마치고 §2-1 2번의ait init재실행으로 이어 가거나, 선택지로--local폴백을 안내한다. 주입 세그먼트는 그 뒤에 따로 실행한다(bash "<base>/../design/scripts/inject-project-guide.sh" "./<package_name>"). pnpm(11)에서--tds가ERR_PNPM_IGNORED_BUILDS: esbuild로 실패한 경우는pnpm-workspace.yaml의allowBuilds에esbuild: true를 추가하고pnpm install을 다시 한 뒤 같은ait init재실행을 한다(0.2.8 재현으로 복구 확인).package.json의@apps-in-toss/web-framework는 create-ait-app이 박은 정확 버전이다(자기 저장소.github/version-pins/package.json의 핀을 빌드에 넣는다. 0.2.9 실측"3.8.0"). 그래서 wf 버전은 실행된 create-ait-app 버전에 따라가고,create-ait-app@latest해석이 환경마다 다르면 wf도 따라 달라진다. 종전 CLI는"latest"리터럴을 써서 install 시점마다 달랐다(실측: 공개latest가3.0.1인 시점에3.0.0이 설치됨). 검증·측정 맥락에서는 실제로 설치된 버전을npm --prefix ./<package_name> ls @apps-in-toss/web-framework로 확인해 항상 함께 기록한다. 어느 경로든 build 전에 잡는 게이트는 후처리 0(Step 3)의 major 확인이다 — 아래 그 절차를 반드시 거친다.온라인인데 특정 transitive dep 설치만 실패하는 경우(프록시/미러 registry가 일부 버전을 못 주는 환경 — 실측)는
--local도 같은 vite 툴체인을 설치하다 같은 문제를 밟을 수 있다. 디렉터리가 남아 있다면(=ait init단계에서 죽은 경우)package.json에overrides를 더해 문제 패키지를 미러에 존재하는 인접 버전으로 고정한 뒤npm --prefix ./<package_name> install을 재실행하는 회피를 안내한다. scaffold 단계에서 죽었다면 위 실패 항목으로 처리한다.어느 인접 버전이 미러에 실재하는지는 후보 버전의 tarball URL을
curl -I로 HEAD 요청해 200/404로 확인한다(실측:baseline-browser-mapping@2.11.7이 404, 인접한2.11.1이 200) — 에러 메시지의 registry URL 패턴에서 버전만 바꿔가며 확인하면 된다:curl -sI "<실패한 tarball URL에서 버전만 인접 버전으로 치환>" | head -1
2-1. 설치 상태 수렴
scaffold가 exit 0으로 끝나도 의존성이 다 깔렸다는 뜻은 아니다. CLI는 install을
두 번 한다 — 자기 npm install 한 번, ait init이 devtools를 배선하며 한 번. 이
중 ait init 쪽 실패는 CLI가 삼킨다: ⚠️ ait init 실행에 실패했어요: …
경고만 찍고 ✅와 exit 0을 낸다(0.2.3 dist 실측, 0.2.8 재현에서도 같다).
그래서 scaffold 직후 항상 아래 수렴 절차를 돈다(출력 파싱에 의존하지 않는다).
npm은 postinstall을 기본 실행하므로 남는 실패 원인은 네트워크·registry 문제로
좁혀진다.
절차:
설치 상태를 확인 겸 수렴시킨다 — 이미 완전히 설치돼 있으면 사실상 no-op이고, 미설치·부분설치면 이 명령이 마저 채운다:
npm --prefix ./<package_name> install이 명령이
ETARGET(No matching version found for @apps-in-toss/devtools@…)으로 죽으면 아래 3번으로 간다 — 원인도 복구도 거기 있다.install이 정상화된 뒤
./<package_name>/apps-in-toss.config.ts가 없으면ait init이 중간에 죽은 것이므로, CLI가 안내하는 그대로 한 번 재실행한다 (이제 install이 정상이라 성공할 가능성이 높다):(cd ./<package_name> && A=./node_modules/.bin/ait && if [ -x "$A" ]; then "$A" init --app-name <package_name> --skip-input; else echo "프로젝트에 ait bin이 없어 init을 건너뜁니다: $A" >&2; exit 1; fi)프로젝트 안에 설치된 bin만 쓴다.
npx -y ait는 로컬 bin이 없을 때 npm 레지스트리의 같은 이름 패키지(앱인토스 CLI가 아닌 다른 패키지일 수 있다)를 받아 실행하므로 쓰지 않는다. bin이 없으면 install이 덜 끝난 것이니 위 1번의 install부터 다시 한다.그래도 실패하면 stderr를 그대로 보고하고, 아래 Step 3(형상 가드)에서 중단된다.
devtools가 devDependencies 문자열이 아니라 실물로 설치됐는지 확인한다.
--no-devtools가 지정됐으면 이 확인도 재핀도 하지 않는다 — 배선을 떼어낼 것이므로 Step 4의 4-b(배선 해제)가 받는다.ait init은@apps-in-toss/devtools를 CLI 자기 버전에 맞춘^<version>으로 devDependencies에 먼저 쓰고 나서npm install을 부르는 순서라, 그 버전이 공개 npm에 아직 없으면 install이ETARGET으로 실패해도 문자열은 파일에 그대로 남는다(cli가 "changesets fixed 그룹" 전제로 자기 버전을 그대로 쓰는데, devtools만 별도 changeset 그룹에도 걸려 있어 발행이 지연되면 이 전제가 깨진다 — 문자열 검사만으로는 이 어긋남을 못 잡는다). 그래서 1번의 install이 exit 0이어도 실물 로드까지 확인한다:node -e "require.resolve('@apps-in-toss/devtools/unplugin', { paths: ['./<package_name>'] })"exit 0이면 실물이 있는 것이니 넘어간다.
Cannot find module로 실패하면npm --prefix ./<package_name> ls @apps-in-toss/devtools로 원인을 눈으로 확인만 해 두고, 순서는 건너뛰지 않는다 — Step 3(형상 가드)을 먼저 통과한 뒤 Step 4에 들어가 거기서 "devtools 재핀 폴백"을 맨 먼저 수행한다. 여기서 바로 재핀하지 않는 이유는 Step 4가 devDep 문자열·번들러 배선까지 한 번에 보고 판단하기 때문이고, Step 3을 건너뛰지 않는 이유는 그 형상 가드가 후처리 전체의 전제라 어긋난 형상 위에서는 재핀도 헛돌기 때문이다.
3. 후처리 0 — 형상 가드 + 디자인 가이드 주입
아래 Step 4·5의 전제는 "ait init이 끝까지 돌아 번들 설정과 빌드 스크립트가
배선된 산출물"이다. 핀이 없으므로 이 전제는 매 run 확인한다 — 새 버전이
산출물 형상을 바꾸면 여기서 멈춰야, 어긋난 형상 위에서 후처리가 헛돌지 않는다.
형상 확인과 디자인 가이드 주입은 한 fence가 함께 한다. 나눠 두면 형상 fence는 매번 실행되는데 주입 쪽만 조용히 빠진다(실측: 열 run 중 셋 — 아래 "디자인 가이드 판정 읽기" 참고). 실행 여부를 판단에 맡기면 확률적으로 빠지므로, 빠질 수 있는 fence를 없앴다.
고칠 자리는 1행의 값 넷과 경로 문자열 하나뿐이다: D(--no-design-guide면
1)·T(--tds면 1)·N(--no-tossface면 1)·P=의 <package_name>, 그리고
<이 skill의 base directory>(같은 문자열이 2군데 나오니 둘 다 Step 2와 같은 규칙으로
채운다). 그 밖에는 한 글자도 고치지 마라 — 특히 bash "$G" "$P" "$@" 두 자리에
플래그를 손으로 덧붙이지 마라. 스크립트 인자는 1행의 T/N에서 셸이 파생한다.
{ D=0; T=0; N=0; P="./<package_name>"; MK='ait:design-guide'; R=""; OK=1; G=""; S=""; DG=""; TF=""; TE=""; MV=""; E=""; IF=0
test -f "$P/apps-in-toss.config.ts" && node -e "const p=require(require('node:path').resolve(process.argv[1],'package.json')); process.exit((p.dependencies?.['@apps-in-toss/web-framework'] && /\bait build\b/.test(p.scripts?.build ?? '')) ? 0 : 1)" -- "$P" && echo "형상 일치" || echo "형상 불일치"
if [ "$D" = 1 ]; then echo "디자인 가이드 없음(--no-design-guide — 닫힘 ②)"
elif [ ! -d "$P" ] || [ ! -f "$P/package.json" ]; then echo "디자인 가이드 주입 보류(프로젝트 경로 아님=$P) — 닫힘이 아니다: 경로 치환을 고쳐 이 fence를 다시 실행한다"
elif LK=""; for X in docs src src/styles src/components src/assets src/assets/icons AGENTS.md CLAUDE.md index.html; do [ -L "$P/$X" ] && LK="$LK $X"; done; [ -n "$LK" ]; then echo "디자인 가이드 주입 보류(심볼릭 링크는 따라가 쓰지 않는다:$LK) — 링크를 실제 파일·디렉터리로 바꾸거나 /ait:design으로 나중에 넣을 수 있습니다"
else
touch "$P/.ait-design-guide-failed" 2>/dev/null
if [ "$T" = 1 ] && [ "$N" = 1 ]; then set -- --tds --no-tossface; elif [ "$T" = 1 ]; then set -- --tds; elif [ "$N" = 1 ]; then set -- --no-tossface; else set --; fi
dgico() { if node -e "process.exit(require(require('node:path').resolve(process.argv[1],'package.json')).dependencies?.react?0:1)" -- "$P" 2>/dev/null; then [ -s "$P/src/components/icons.tsx" ]; else [ -s "$P/src/assets/icons/close.svg" ]; fi; }
dgent() { HE="$(grep -o '<script[^>]*>' "$P/index.html" 2>/dev/null | grep 'type="module"' | sed -n 's/.*src="\([^"]*\)".*/\1/p' | head -1 | sed -e 's/[?#].*//' -e 's|^\./||' -e 's|^/||')"; case "$HE" in *..*) HE="";; esac; for C in src/index.css "$HE" src/main.tsx src/main.ts src/index.tsx src/index.ts index.tsx index.ts index.html; do [ -n "$C" ] && grep -qs 'styles/base.css' "$P/$C" && return 0; done; for C in src/index.css "$HE" src/main.tsx src/main.ts src/index.tsx src/index.ts index.tsx index.ts index.html; do [ -n "$C" ] && [ -f "$P/$C" ] && return 1; done; return 0; }
dgok() { grep -qs "<!-- $MK v" "$P/AGENTS.md" && grep -qs "<!-- $MK v" "$P/CLAUDE.md" && [ -s "$P/docs/design-guide.md" ] && { [ "$T" = 1 ] || { [ -s "$P/src/styles/tokens.css" ] && [ -s "$P/src/styles/base.css" ] && dgico && dgent; }; }; }
if dgok; then rm -f "$P/.ait-design-guide-failed"; echo "디자인 가이드 있음(이미 있음)"
else
for C in "<이 skill의 base directory>/../design/scripts/inject-project-guide.sh" "$CLAUDE_PLUGIN_ROOT/shared/skills/design/scripts/inject-project-guide.sh" "$CLAUDE_PLUGIN_ROOT/skills/design/scripts/inject-project-guide.sh" "$HOME/.claude/skills/design/scripts/inject-project-guide.sh"; do
[ -f "$C" ] && { G="$C"; break; }
done
[ -n "$G" ] && { bash "$G" "$P" "$@"; dgok || bash "$G" "$P" "$@"; }
if dgok; then rm -f "$P/.ait-design-guide-failed"; echo "디자인 가이드 있음(스크립트로 보완됨 — 스크립트=$G)"
else
for C in "<이 skill의 base directory>/../design/assets/project" "$CLAUDE_PLUGIN_ROOT/shared/skills/design/assets/project" "$CLAUDE_PLUGIN_ROOT/skills/design/assets/project" "$HOME/.claude/skills/design/assets/project"; do
[ -s "$C/memory-digest.md" ] && [ -s "$C/design-guide.md" ] && { [ "$T" = 1 ] || { [ -s "$C/tokens.css" ] && [ -s "$C/base.css" ] && [ -s "$C/icons.tsx" ] && [ -s "$C/icons/close.svg" ]; }; } && { S="$C"; break; }
done
if [ -z "$S" ]; then
echo "디자인 가이드 주입 실패(스크립트=${G:-못찾음} · 자산=못찾음)"
echo "완료 블록에 그대로 넣을 줄: 디자인 가이드: 주입 실패 — /ait:design으로 나중에 넣을 수 있습니다"
else
DG="$S/memory-digest.md"
if [ "$T" = 1 ]; then
TF="$(mktemp "${TMPDIR:-/tmp}/ait.XXXXXX" 2>/dev/null)"
if [ -n "$TF" ] && awk '/^아이콘: React/{print "이 프로젝트는 TDS 기반이다 — 색·크기·아이콘은 TDS 컴포넌트가 주는 것을 쓴다(위 토큰 목록과 아이콘 파일 경로는 이 프로젝트에 없다)."; next} /^아이콘: vanilla/{print "1층 하드 규칙은 플랫폼 제약이라 그대로 적용된다 — 꺾쇠·닫기·검색은 TDS 아이콘 컴포넌트로 충족하고, 텍스트 글리프로 대체하는 것은 여전히 금지다."; next} {print}' "$S/memory-digest.md" > "$TF" 2>/dev/null && [ -s "$TF" ]; then DG="$TF"; else DG=""; OK=0; R="$R digest=FAIL"; fi
fi
mkdir -p "$P/docs" 2>/dev/null
[ -f "$P/docs/design-guide.md" ] || cp "$S/design-guide.md" "$P/docs/design-guide.md" 2>/dev/null
[ -f "$P/docs/design-guide.md" ] || { OK=0; R="$R guide=FAIL"; }
if [ "$T" = 1 ]; then R="$R css=tds-skip icons=tds-skip entry=tds-skip"; else
mkdir -p "$P/src/styles" 2>/dev/null
[ -f "$P/src/styles/tokens.css" ] || cp "$S/tokens.css" "$P/src/styles/tokens.css" 2>/dev/null
[ -f "$P/src/styles/tokens.css" ] || { OK=0; R="$R tokens=FAIL"; }
[ -f "$P/src/styles/base.css" ] || cp "$S/base.css" "$P/src/styles/base.css" 2>/dev/null
[ -f "$P/src/styles/base.css" ] || { OK=0; R="$R base=FAIL"; }
if [ "$N" = 1 ] && grep -q 'tossface\.css' "$P/src/styles/base.css" 2>/dev/null; then
sed -i.aitbak -e '/tossface\.css/d' -e 's/"Tossface", -apple-system/-apple-system/' "$P/src/styles/base.css" 2>/dev/null; rm -f "$P/src/styles/base.css.aitbak"
grep -q 'tossface\.css' "$P/src/styles/base.css" 2>/dev/null && R="$R tossface=FAIL" || R="$R tossface=off"
fi
if node -e "process.exit(require(require('node:path').resolve(process.argv[1],'package.json')).dependencies?.react?0:1)" -- "$P" 2>/dev/null; then
mkdir -p "$P/src/components" 2>/dev/null
[ -f "$P/src/components/icons.tsx" ] || cp "$S/icons.tsx" "$P/src/components/icons.tsx" 2>/dev/null
[ -f "$P/src/components/icons.tsx" ] || { OK=0; R="$R icons=FAIL"; }
else
mkdir -p "$P/src/assets/icons" 2>/dev/null; IF=0
for I in chevron-down chevron-left chevron-right chevron-up close search; do
[ -f "$P/src/assets/icons/$I.svg" ] || cp "$S/icons/$I.svg" "$P/src/assets/icons/$I.svg" 2>/dev/null
[ -f "$P/src/assets/icons/$I.svg" ] || IF=1
done
[ "$IF" = 0 ] || { OK=0; R="$R icons=FAIL"; }
fi
HE="$(grep -o '<script[^>]*>' "$P/index.html" 2>/dev/null | grep 'type="module"' | sed -n 's/.*src="\([^"]*\)".*/\1/p' | head -1 | sed -e 's/[?#].*//' -e 's|^\./||' -e 's|^/||')"
case "$HE" in *..*) HE="";; esac
E=""
for C in src/index.css "$HE" src/main.tsx src/main.ts src/index.tsx src/index.ts index.tsx index.ts; do
[ -n "$C" ] && [ -f "$P/$C" ] && [ ! -L "$P/$C" ] && { E="$P/$C"; break; }
done
JSOK=0
case "$E" in *.js|*.jsx|*.mjs) JSOK=1;; *.ts|*.tsx|*.mts) if [ -f "$P/src/vite-env.d.ts" ] || [ -n "$(find "$P" -maxdepth 1 -name 'tsconfig*.json' -exec grep -l '"vite/client"' {} + 2>/dev/null)" ]; then JSOK=1; fi;; esac
if [ ! -f "$P/src/styles/base.css" ]; then R="$R entry=skip"
elif [ -n "$E" ] && grep -q 'styles/base.css' "$E" 2>/dev/null; then R="$R entry=skip"
elif [ -n "$E" ] && [ "${E%index.css}" != "$E" ]; then
TE="$(mktemp "${TMPDIR:-/tmp}/ait.XXXXXX")" && printf '%s\n' "@import './styles/base.css';" | cat - "$E" > "$TE" && mv "$TE" "$E" && R="$R entry=index.css" || { OK=0; R="$R entry=FAIL"; }
elif [ -n "$E" ] && [ "$JSOK" = 1 ]; then
TE="$(mktemp "${TMPDIR:-/tmp}/ait.XXXXXX")" && printf '%s\n' "import './styles/base.css';" | cat - "$E" > "$TE" && mv "$TE" "$E" && R="$R entry=js" || { OK=0; R="$R entry=FAIL"; }
elif [ -f "$P/index.html" ] && ! grep -q 'styles/base.css' "$P/index.html" 2>/dev/null; then
TE="$(mktemp "${TMPDIR:-/tmp}/ait.XXXXXX")" && awk '/<\/head>/&&!d{print " <link rel=\"stylesheet\" href=\"/src/styles/base.css\" />";d=1}{print}' "$P/index.html" > "$TE" && mv "$TE" "$P/index.html" && R="$R entry=index.html" || { OK=0; R="$R entry=FAIL"; }
else R="$R entry=skip"; fi
fi
if [ "$OK" = 1 ] && [ -n "$DG" ]; then
MV="$(grep -o "$MK v[0-9]*" "$P/AGENTS.md" 2>/dev/null | head -1)"
if [ -n "$MV" ]; then R="$R agents=skip($MV)"
elif { [ -s "$P/AGENTS.md" ] && printf '\n'; printf '<!-- %s v2 -->\n' "$MK"; cat "$DG"; printf '<!-- /%s -->\n' "$MK"; } >> "$P/AGENTS.md" 2>/dev/null; then R="$R agents=new"
else OK=0; R="$R agents=FAIL"; fi
[ "$OK" = 1 ] && { grep -qs "$MK v" "$P/CLAUDE.md" || { { [ -s "$P/CLAUDE.md" ] && printf '\n'; printf '<!-- %s v2 -->\n@AGENTS.md\n<!-- /%s -->\n' "$MK" "$MK"; } >> "$P/CLAUDE.md" 2>/dev/null || { OK=0; R="$R claude=FAIL"; }; }; }
fi
rm -f "$TF" 2>/dev/null
if [ "$OK" = 1 ] && dgok; then rm -f "$P/.ait-design-guide-failed"; echo "디자인 가이드 있음(자산 폴백으로 보완됨 —$R)"
else
echo "디자인 가이드 주입 실패(스크립트=${G:-못찾음} · 자산 폴백 —$R)"
echo "완료 블록에 그대로 넣을 줄: 디자인 가이드: 주입 실패 — /ait:design으로 나중에 넣을 수 있습니다"
fi
fi
fi
fi
fi; }
이 fence는 통째로 한 번의 Bash 호출로 실행한다. 검사 항목을 추려 자기 식으로 다시
조립하지 마라 — 자체 조립한 run이 끝 세그먼트만 빼먹은 것이 실측됐다(Step 2 fence를
한 줄로 만든 것과 같은 이유다). 앞을 자르든 뒤를 자르든 셸 문법 오류로 죽는다(그게
안전장치다). 실행할지 말지도 판단하지 마라 — 디자인 가이드가 이미 들어가 있으면 fence가
스스로 있음(이미 있음)을 찍고 아무것도 하지 않는다.
fence는 두 줄을 찍는다. 첫 줄이 형상 판정, 둘째 줄이 디자인 가이드 판정이다.
형상은 세 가지를 본다: apps-in-toss.config.ts 존재, dependencies의
@apps-in-toss/web-framework, scripts.build의 ait build. 앞뒤 둘은 ait init이
만들고(create-ait-app dist에는 이 설정 파일도 build 스크립트도 쓰는 코드가
없다) 가운데 하나만 create-ait-app이 직접 쓴다 — 이 부분이 "CLI가 자기 몫과
ait init 몫을 둘 다 끝냈는가"를 판정한다. 디자인 가이드 판정은 이 가드와 별개라
바로 아래 "하나라도 실패하면 중단"의 대상이 아니다(fail-soft). 형상 불일치로
중단할 때 디자인 가이드 줄을 중단 보고에 섞지 마라 — 그 줄은 Step 6의 완료 블록에서만
쓴다.
통과해도 아직 Step 4로 가지 않는다 — 바로 아래 wf major 확인 →
aitbin 확인 두 서브체크까지 이어서 하고, 셋을 다 통과한 뒤에 Step 4로 간다.하나라도 실패하면 Step 4·5를 진행하지 않고 즉시 중단한다. §2-1 2번의
ait init재실행을 아직 안 했다면 그것만 먼저 시도하고, 그러고도 실패하면 사용자에게 한 블록으로 보고하고 멈춘다:scaffold 산출물이 예상한 형상(apps-in-toss.config.ts + package.json의 @apps-in-toss/web-framework 의존성 + ait build를 포함한 build 스크립트)과 다릅니다 — create-ait-app이 새 버전에서 산출물 형상을 바꾼 것으로 보입니다. 이후 후처리를 진행하지 않고 여기서 중단합니다.
설치된 @apps-in-toss/web-framework의 major도 함께 확인한다 — 형상 파일
체크만으로는 부족하다. 현재 create-ait-app은 wf를 정확 버전으로 박지만,
create-ait-app@latest가 구버전으로 해석되는 환경(프록시가 최신을 숨기는 경우)이나
"latest" 리터럴을 쓰던 종전 CLI가 내려온 경우에는 2.x가 조용히 들어올 수 있다(npm의
latest dist-tag가 3.x 출시 이후에도 한동안 2.10.8을 가리킨 어긋남 — harness#90
항목1, 2026-08-07 실측). 아래 ait bin 확인은 이걸 못 잡는다(2.10.8도 ait bin을
준다):
node -p "require('./<package_name>/node_modules/@apps-in-toss/web-framework/package.json').version"
(npm의 flat node_modules를 전제한 경로다 — 모노레포 등 형상이 다르면 이 경로도
깨진다. 아래 devtools sdkVersion auto-detect와 같은 부류의 제약이다.)
major가 3이 아니면(예: 2.10.8) 사용자 응답을 기다리지 않고 지금 바로
아래를 직접 수행한다 — 읽어주고 끝내는 안내문이 아니라 실행하는 복구 절차다.
./<package_name>/package.json을 Edit으로 열어 "@apps-in-toss/web-framework"의
값("latest" 리터럴이든 2.x 정확 버전이든)을 "^3.0.2"로 고치고,
npm --prefix ./<package_name> install을 실행한 뒤, 위 major 확인 커맨드를 다시
돌려 3.으로 시작하는지 본다. 3.x가 재확인되기 전에는 아래 ait bin 확인
이하로 넘어가지 않는다 — 재확인 없이 진행하면 이 가드가 없는 것과 같다.
세 단계를 마친 뒤, 사용자에게는 결과만 한 블록으로 보고한다:
설치된 @apps-in-toss/web-framework가 <원래 출력된 버전>(2.x)이었습니다 — 정본
산출물은 3.x입니다(구버전 create-ait-app이나 registry 응답 어긋남으로 2.x가
들어오는 알려진 사례가 있습니다, harness#90). package.json을 "^3.0.2"로 고치고
재설치해 3.x 설치를 확인했습니다.
재설치 후에도 major가 3이 아니면(예: 재설치가 여전히 2.x를 해석하는 등) 더
이상 자동 재시도하지 않고 중단해, 재확인 결과를 그대로 사용자에게 보고한다.
major 확인이 1차 게이트다. 통과했으면 같은 자리에서 ait bin 존재도 보조로
확인한다 — 단독으로는 2.x/3.x를 구분하지 못하지만(2.10.8도 ait bin을 제공한다
— harness#90 실측, granite bin이 wf 2.x 전용이다) major 확인 이후엔 설치 과정의
다른 이상으로 bin이 안 생겼는지 잡아준다. 이게 없으면 이후 npm run build/ait build가 조용히 실패한 채로 후처리가 계속된다. 위 승격은 "하지 말아야
할 것"의 2.x 강등 금지와 모순되지 않는다 — 잘못 설치된 2.x를 정본 3.x로 올리는
것이다:
ls ./<package_name>/node_modules/.bin/ait
없으면 중단하고 npm --prefix ./<package_name> explain @apps-in-toss/web-framework
출력을 사용자에게 보고한다. @apps-in-toss/web-framework를 2.x로 강등하는
명령은 어떤 형태로도 실행하지 않는다 — 정본 산출물은 3.x이고, 강등은 그걸
되레 깨뜨린다.
디자인 가이드 판정 읽기 — 위 fence의 둘째 줄이 정본이다. 여기서 따로 실행할
블록은 없다. 종전에는 같은 내용의 블록이 이 자리에 따로 있었고, 실측에서 빠진 것이
바로 그것이다 — 열 run 중 셋이 형상 fence·wf major·ait bin을 정상 수행하고 네
번째인 그 블록만 건너뛰었다. 그래서 블록을 형상 fence에 합쳐 Step 3에 남는 셸 호출을
하나로 줄였다.
그 한 줄이 탐지·스크립트 경로 탐색·호출·재시도·자산 폴백·최종 판정의 결과를 전부 담는다. 판정과 보완을 여러 턴에 걸쳐 조율하게 하면 확률적으로 누락된다 — 자산 폴백이 5-B에 있던 시절엔 다섯 run 중 둘이 자산이 멀쩡히 있는데도 폴백을 시도하지 않고 실패로 닫았고, 폴백을 블록 안으로 들인 뒤에는 블록 자체가 열 run 중 셋에서 실행되지 않았다. 고친 이동과 실제로 남아 있던 이동이 달랐던 것이라, 이번에는 이동이 아니라 fence 수를 줄였다.
이 fence는 어떤 경로로도 디자인 가이드로 시작하는 줄을 정확히 하나 찍는다. 그
줄이 안 보이면 fence가 실행되지 않은 것이니 통째로 다시 실행한다. 괄호 안이 원인을
함께 알려준다 — 스크립트=<경로>는 스크립트를 찾아 돌렸다는 뜻이고
스크립트=못찾음은 다섯 후보 어디에도 없었다는 뜻이다.
디자인 가이드 있음(이미 있음 | 스크립트로 보완됨 — … | 자산 폴백으로 보완됨 — …)— 닫힘 ①로 진행한다.디자인 가이드 없음(--no-design-guide — 닫힘 ②)— 닫힘 ②. 완료 블록에서 가이드 줄 자체를 인쇄하지 않는다.디자인 가이드 주입 실패(…)— 닫힘 ③. 둘째 줄이 완료 블록에 그대로 넣을 문장이다 — 그때 새로 짓지 말고 그 줄을 옮긴다. 더 반복하지 말고, 손으로 파일을 만들지 마라.디자인 가이드 주입 보류(프로젝트 경로 아님=…)— 닫힘이 아니다. 아무것도 쓰지 않고 멈춘 것이니 경로 치환을 고쳐 fence를 다시 실행한다.
있음은 캐리어 마커와 산출물이 전부 자리에 있을 때만 찍힌다 — AGENTS.md와
CLAUDE.md의 마커, docs/design-guide.md, 그리고 비-TDS면 tokens.css·base.css·
프로젝트 계열에 맞는 아이콘(react 의존성이 있으면 icons.tsx, 그 밖의 프레임워크는 svg)·entry 배선까지 실재를
본다. 정본 스크립트는 개별 항목이 실패해도 마커를 붙이므로 마커만으로는 성공이
아니고, fence가 그걸 알고 산출물 실재로 다시 판정한다. 파일 몇 개만 들어갔는데 성공으로
보고되는 경로는 없고, 그렇게 걸린 형상은 그 자리에서 폴백이 채워 복구한다 — entry
배선만 빠진 프로젝트에 fence를 다시 돌리면 배선이 붙는다. 실패는 프로젝트 안 .ait-design-guide-failed 흔적
파일로도 남아, 완료 블록 직전 Step 5의 .gitignore fence가 같은 문장을 한 번 더
찍는다.
폴백이 산문 절차가 아니라 이 fence 안에 있는 이유 — 프로젝트로 옮겨지는 내용은
cp/cat이 원본 바이트를 그대로 넘긴 것이다. 원본을 열어 옮겨 적는 절차를 산문으로
맡기면 확률적으로 어긋난다(실측: 스크립트 파일만 지우고 design/assets/project/는
멀쩡히 남겨 둔 조건에서 수동 폴백을 시도한 두 run이 둘 다 원본을 한 번도 Read하지
않고 지어냈다. 한 run은 find … -name "tokens.ts"로 확장자를 잘못 짚어 빈손이 되자
그대로 창작해 파일명·Tossface CDN URL·팔레트가 전부 원본과 달랐는데 완료 보고에는 그
창작 팔레트를 "토스 공식 색상"이라고 적었고, 다른 run은 검색 시도 자체 없이 바로
mkdir+Write로 지어내 --space-1~`--space-6`이 통째로 빠졌다).
어느 실패든 대체물을 지어내지 마라. 토큰 값·하드 규칙·아이콘·다이제스트 본문의
정본은 design skill의 assets/project/ 파일이고, 그 바이트를 옮기지 못했으면 주입은
실패한 것이다 — 그럴듯한 팔레트나 규칙을 창작해 채우지 말고 닫힘 ③으로 정직하게
닫아라(실측: 한 run이 원본을 한 번도 읽지 않은 채 임의 팔레트로 파일 5종을 지어내고
완료 보고에는 디자인 가이드: 포함으로 적었다 — 파일은 있지만 프로젝트가 따를 기준은
없는 상태이므로, 이것은 성공이 아니라 위장이다). 지어낸 대체물을 정규 산출물처럼
보고하는 것은 금지다. 이 fence 밖에서
tokens.css·base.css·icons.tsx·아이콘 svg·docs/design-guide.md·AGENTS.md의
ait:design-guide 블록을 손으로 Write하는 것도 같은 금지에 들어간다 — 이
산출물들은 이 fence의 cp/cat 결과로만 존재해야 한다. fence가 셸 오류로 죽었으면
그대로 한 번 더 실행하고, 그래도 죽으면 손으로 만들지 말고 닫힘 ③으로 간다 — 1행의
흔적 touch는 이미 실행됐으므로 fence가 통째로 죽어도 Step 5가 실패 문장을 완료
블록으로 실어 나른다.
캐리어 마커는 여는 줄 <!-- ait:design-guide v3 -->과 닫는 줄
<!-- /ait:design-guide -->이고, grep 가드가 네 상황을 전부 처리한다 — 파일 없음(새로
생성)·마커 없음(파일 끝에 append, 기존 내용 무손상)·v3(skip)·다른 버전(skip). 요약에
v2가 아닌 버전이 찍히면(agents=skip(ait:design-guide v0)) 덮어쓰지 말고 "가이드
버전이 다릅니다 — /ait:design으로 갱신할 수 있습니다"만 알린다. AGENTS.md에
들어가는 본문은 memory-digest.md 원문 그대로다(한 글자도 고쳐 쓰지 않는다).
CLAUDE.md에는 @AGENTS.md 한 줄만 넣는다 — 같은 본문을 두 파일에 넣으면 세션마다
두 배로 실린다. entry 배선 우선순위는 src/index.css 최상단 @import → JS entry 첫
import → index.html의 <link>이고, 첫 번째로 해당되는 하나만 쓴다. JS entry는
엔트리 파일명을 가정하지 않고 index.html의 <script type="module" src>가 가리키는
파일을 먼저 찾는다(없을 때만 main.ts(x)·index.ts(x) 같은 관례 이름) —
.ts 계열 entry는 vite/client 타입이 있을 때만 import를 더하고, 아니면
index.html의 <link>로 내려간다.
이 판정은 Step 2가 백그라운드로 넘어갔다 끝난 경우에도 건너뛰지 않는다 — 출력
줄(5-B:)을 놓쳤어도 파일 실재가 최종 판정이다. 스크립트는 멱등이라 이미 주입된
프로젝트에 다시 돌아도 전 항목 skip으로 끝나 무해하다.
이 판정이 닫히기 전에는 Step 6의 완료 블록을 인쇄하지 않는다. 닫힘은 세
가지뿐이다: ① 있음 확인, ② --no-design-guide의 의도된 없음, ③ 실패 —
③은 완료 보고에 디자인 가이드: 주입 실패 — /ait:design으로 나중에 넣을 수 있습니다
줄을 반드시 포함해야 닫힌 것이다. 실패 항목을 완료 보고에서 조용히 빼고 성공처럼
보고하는 것도, 성공도 실패도 말하지 않고 항목 자체를 통째로 빼는 것도 금지다(실측:
한 run은 완료 표에서 그 항목만 누락시켰고, 다른 run은 판정을 정확히 찍고도 13턴 뒤
완료 보고에서 "디자인 가이드"를 한 번도 쓰지 않았다). 그래서 이 문장을 기억에 맡기지
않는다 — 위 fence가 실패 시 흔적 파일을 남기고, Step 5의 .gitignore fence가 완료 블록
직전에 그 흔적을 보고 같은 문장을 한 번 더 찍는다.
4. 후처리 B — devtools 배선 확인 (브라우저 dev 활성화)
배선은 CLI(ait init)가 이미 한다 — 이 단계는 그 결과를 확인하고, 안 돼
있을 때만 직접 배선한다. 먼저 세 가지를 본다:
node -e "const p=require('./<package_name>/package.json'); console.log('devDep:', p.devDependencies?.['@apps-in-toss/devtools'] ?? '(없음)')"
ls ./<package_name>/*.config.* 2>/dev/null
node -e "require.resolve('@apps-in-toss/devtools/unplugin', { paths: ['./<package_name>'] })" && echo "실물: 있음" || echo "실물: 없음"
두 번째로 나온 목록에서 번들러 설정 파일(create-ait-app 프리셋은 전부 Vite라
vite.config.*)을 Read해 @apps-in-toss/devtools/unplugin import와 plugins
배열의 aitDevtools.vite(...) 항목이 있는지 확인한다(실측 2026-08-07 React 산출물:
devDependencies에 "@apps-in-toss/devtools": "^3.0.2", vite.config.ts에
import aitDevtools from "@apps-in-toss/devtools/unplugin"; +
plugins: [aitDevtools.vite(), react()] — 뒤쪽은 프레임워크 플러그인이라 스택마다
다르다).
- devDep·unplugin·실물이 셋 다 있으면 이 단계는 끝이다 — 아무것도 바꾸지 않고
Step 5로 넘어간다. CLI가 만든 형태(
aitDevtools.vite()인자 없음 등)를 취향으로 고쳐 쓰지 않는다. - devDep 문자열은 있는데 실물이 없으면 —
ait init이 package.json에@apps-in-toss/devtools를 쓰고 나서npm install을 부르는 순서라 그 install만 실패해도 문자열은 남는다(cli가 자기 버전에 맞춰 쓴^<version>이 공개 npm에 아직 없는 경우가 실제 원인 — 배경은 아래 "devtools 재핀 폴백" 참고). 이땐 vite.config 확인으로 넘어가지 말고 먼저 아래 "devtools 재핀 폴백"부터 수행한다 —--no-devtools면 해당 없이 아래 "배선 해제"로 간다. - devDep·unplugin 중 하나라도 없으면(재핀 이후에도) 아래 4-a 폴백을 순서대로 수행한다.
--no-devtools가 지정됐으면 확인 결과와 무관하게 아래 "배선 해제" 절로 간다.
devtools 재핀 폴백 — devDep 문자열은 있는데 실물이 없을 때
@apps-in-toss/cli(ait init을 수행하는 실체)는 devtools를 자기 자신의
버전에 맞춰 ^<cli 버전>으로 devDependencies에 적는다 — cli·web-framework·
devtools가 changesets fixed 그룹으로 함께 발행된다는 전제다. 이 전제는 devtools가
그 fixed 그룹과 별도의 ignore 설정에도 동시에 걸려 발행이 지연되면 깨진다 — cli는
이미 새 버전을 냈는데 그 버전의 devtools가 공개 npm에 없으면, npm install이
ETARGET(No matching version found for @apps-in-toss/devtools@^<cli 버전>)으로
죽고 나머지 install은 진행되지 않는다. package.json의 devDependencies 문자열은
CLI가 install 실행 전에 이미 써 둔 것이라 이 실패 이후에도 그대로 남는다 — 위 세
확인 중 devDep·unplugin만 보면 "배선됨"으로 오판하는 이유다. 되돌리지
마라: 이 재핀 단계를 지우면 그 오판이 다시 살아난다.
복구는 실패한 정확 버전 고정을 버리고 공개 npm의 최신으로 다시 잡는 것이다 — 아래 4-a가 하는 "devDep이 아예 없을 때"의 신규 설치와 같은 명령이지만, 이미 있는 (깨진) 지정을 덮어쓰는 것이므로 먼저 실행한다:
npm --prefix ./<package_name> install -D @apps-in-toss/devtools@latest
일부 환경은 registry 프록시가 최신 버전을 숨기거나 낡은 dist-tag만 내려줄 수 있다 (루트 CLAUDE.md "dist-tag quirk" 참고) — 위 명령이 같은 이유로 또 실패하면 공개 미러로 정확한 버전을 확인한 뒤 그 버전으로 재시도한다. 레지스트리를 바꾸는 일이므로 미러 호스트와 이유를 사용자에게 보여 주고 동의를 받은 뒤에 한다:
# 1) 미러에서 최신 버전을 읽고, jsdelivr로 같은 값인지 교차 확인한다
npm view --registry=https://registry.npmmirror.com/ @apps-in-toss/devtools version
curl -s "https://data.jsdelivr.com/v1/packages/npm/@apps-in-toss/devtools/resolved?specifier=latest"
# 2) 두 값이 같을 때만, 그 정확 버전을 이 명령 한 번에 한해 미러에서 받는다(.npmrc에는 남기지 않는다)
npm_config_registry=https://registry.npmmirror.com/ npm --prefix ./<package_name> install -D @apps-in-toss/devtools@<위에서 확인한 정확 버전> --ignore-scripts
--ignore-scripts는 미러에서 새로 받는 패키지의 설치 스크립트가 도는 것을 막는다.
@apps-in-toss/devtools에는 설치 스크립트가 없어(미러 packument 확인) 이 옵션이 설치
결과를 바꾸지 않는다. 두 값이 다르면 설치하지 않고 사용자에게
보고한다. 바이트는 이후 lockfile의 integrity가 고정한다.
해석된 정확 버전을 인용해 사용자에게 보고한다 — "latest를 넣었다"고만 말하지 않는다:
npm --prefix ./<package_name> pkg get devDependencies.@apps-in-toss/devtools
npm install -D <pkg>@latest는 이 skill의 다른 자리(web-framework major
복구, 위 Step 3)처럼 caret 범위(^3.2.0 형태)로 기록한다 — 정확 버전 고정으로
바꿔 쓰지 않는다. 위 세 확인(devDep·unplugin·실물)을 다시 수행해 셋 다 통과하면
Step 5로 넘어가고, unplugin 배선만 빠져 있으면 아래 4-a로 간다. 재설치 후에도
실물이 안 잡히면 더 자동 재시도하지 않고 npm --prefix ./<package_name> ls @apps-in-toss/devtools 출력을 그대로 사용자에게 보고한 뒤 중단한다.
4-a. 폴백 — CLI가 배선하지 않았을 때
inject skill의 devtools facet과 같은 패턴을 이 자리에서 수행한다 (idempotent —
이미 된 부분은 건드리지 않는다). 번들러 확인·README 기반 등록 절차가 필요하면 Read <이 skill의 base
directory>/../inject/references/devtools.md.
@apps-in-toss/devtools(공개 npm 발행본, 2026-08-04부터@apps-in-toss/*)는 peer로@apps-in-toss/web-framework >=2.6.0 <3.0.0 || >=3.0.1 <4.0.0을 선언해 정확히3.0.0만 범위에서 빠진다. 설치된 wf가 그 gap이면unmet peer경고가 뜨지만 설치 자체는 막히지 않으니 넘어가면 된다.
devDep이 없을 때만:
npm --prefix ./<package_name> install -D @apps-in-toss/devtools번들러 설정 파일에
@apps-in-toss/devtools/unpluginimport와 plugin 항목을 추가한다. 번들러별 형태·옵션은@apps-in-toss/devtoolsREADME의 해당 번들러 절("번들러 배선",node_modules/@apps-in-toss/devtools/README.md)을 따른다 — 여기서 번들러별 코드를 외워 쓰지 않는다(위에서 가리킨inject참조 문서에도 패턴 요약이 있다). 실제 존재하는 설정 파일만 고친다 —ls ./<package_name>/*.config.*로 확인하고, 없는 확장자로 새 파일을 만들지 않는다(Vite는.js를.ts보다 먼저 탐색하므로 새로 만든 파일이 조용히 무시돼 배선이 침묵 실패한다). 설정 파일이 없으면 중단하고 산출물 목록을 보고한다.
이 배선이 환경 1(브라우저 + mock SDK + panel)을 여는 것이다 — 없으면
--sample로 넣은 IAP/IAA 예제가 브라우저에서 "샌드박스앱/토스앱에서
실행해주세요" alert만 띄운다.
4-b. 배선 해제 — --no-devtools
--no-devtools는 "설치 제외"가 아니라 배선 해제다 — CLI에 배선을 끄는
플래그가 없어 사후에 떼어내는 것 말고 방법이 없다. 위 확인에서 배선이 없었다면
아무것도 하지 않는다.
devDependency 제거:
npm --prefix ./<package_name> uninstall @apps-in-toss/devtools확인된 번들러 설정 파일에서
@apps-in-toss/devtools/unpluginimport 줄과plugins배열의aitDevtools.*(...)항목을Edit으로 제거한다. 배열 자체나 다른 플러그인(프레임워크 플러그인 등)은 그대로 둔다.
해제한 경우 Step 6 완료 안내에서 npm run dev 줄의 설명을 조정하고
/ait:inject-devtools seam을 알린다.
@apps-in-toss/devtools(3.0.2)의 mock은 wf 2.x·3.x 두 표면을 모두 지원한다 —./mock/2x(flat 함수 API)와./mock/3x(네임스페이스 API:Clipboard.*·Device.*·Screen.*·TossPay.*·createAsyncBridge등)가 둘 다 들어 있고, unplugin의sdkVersion(기본'auto'— 소비자 프로젝트의 wf major를 자동 감지)이 하나를 고른다. 이 skill의 scaffold(wf 3.x)에서는 3x facade가 골라져 두 표면 다 브라우저에서 동작한다. 주의: 모노레포·virtual store처럼 auto-detect가 실제 major를 못 읽는 환경에서는aitDevtools.vite({ sdkVersion: '3' })로 명시해야 한다 — 잘못된 표면을 고르면 그 표면에 없는 API가 브라우저에서undefined가 된다.
5. 후처리 C — .gitignore
create-ait-app 템플릿은 .gitignore를 이미 포함한다(create-vite
경로·TDS 경로 모두 — TDS는 _gitignore를 rename해서 만든다). *.ait도 대개
이미 들어 있다 — ait init이 devtools 배선과 같은 실행에서 .gitignore 끝에
*.ait를 조건 없이 append한다(@apps-in-toss/cli 3.1.1 dist 실측 2026-09-07:
appendFile(".gitignore", "\n*.ait\n")). 그래서 이 fence가 실제로 더하는 줄은 보통
Step 3의 실패 흔적 파일 이름 하나이고, *.ait는 ait init이 넣지 않은 산출물(그
줄을 쓰지 않는 다른 버전의 CLI)에만 보충한다. 두 줄은 각각 없을 때만 append한다 —
종전에는 *.ait 부재를 조건으로 두 줄을
…(truncated)