new-miniapp

name	new-miniapp
description	Scaffold a new Apps in Toss mini-app by driving the official `create-ait-app` CLI non-interactively (`--inline`, always `@latest`), then verifying the `@apps-in-toss/devtools` wiring (mock SDK + panel) the CLI performs so `npm run dev` runs in a plain browser immediately — falling back to manual wiring only when the CLI did not do it. Supports `--tds` and `--sample iap,iaa` passthrough. Falls back to the bundled react-vite template with `--local` (offline); `--no-devtools` un-wires devtools afterwards. The freshly scaffolded project also gets a design guide seeded into it (tokens, hard rules, icon set, Tossface emoji font wiring) so later sessions build screens against the same standard — `--no-design-guide` and `--no-tossface` opt out of that seeding. Greenfield only (see `inject-devtools` for existing projects). Triggered by `/ait:new <app-name> [--template <name>] [--tds] [--sample <ids>] [--local] [--no-devtools] [--no-design-guide] [--no-tossface]`.
argument-hint	<app-name> [--template <name>] [--tds] [--sample <ids>] [--local] [--no-devtools] [--no-design-guide] [--no-tossface]

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, 별칭 js→vanilla·ts→vanilla-ts, 전체 목록은 --list-templates), --tds(TDS 컴포넌트 홈 + provider, --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 스크립트도 같은 실행이 만든다(실측 2026-08-07, create-ait-app@0.2.3). 순정 create-vite 템플릿에는 SDK mock이 없어 브라우저에서 SDK 호출이 실패하지만(샘플 코드가 "샌드박스앱/토스앱에서 실행해주세요" alert를 띄운다) 이 배선 덕에 토스 앱 없이 npm run dev로 바로 개발할 수 있다. ait init은 실패해도 CLI가 "완료"로 끝내므로 형상 가드(Step 3)가 실재를, Step 4가 배선을 확인하고 폴백한다.
• 이건 토스 앱 WebView에서 도는 웹(DOM) 미니앱이지 React Native 앱이 아니다. RN 네이티브 컴포넌트나 react-native import를 쓰지 않는다(설치 시 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(= tsc -b && vite 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> (선택, default react-ts): 지원 목록은 create-ait-app이 번들한 create-vite에서 동적으로 산출된다(getSupportedViteTemplates() — index.html 존재 + vite dep + dev/build 스크립트 + 비-SSR 필터 기준). 별칭 js→vanilla, ts→vanilla-ts. 실제 목록은 실행 시점에 확인한다:

  npx -y create-ait-app@latest --list-templates
  

  JSON 배열로 지원 템플릿과 "tds"가 함께 나온다(단 "tds"는 --template이 아니라 아래 --tds 플래그로 지정 — 혼동 금지).

• --tds (선택): TDS(토스 디자인 시스템) 통합 변형. --template과 동시 지정 불가 — CLI는 --template과 --tds를 함께 주면 즉시 거부한다 ("--template과 --tds는 함께 사용할 수 없어요.", assertNonInteractiveArgs 실측). --tds는 단독으로 지정한다.

  알려진 실패(실측 2026-08-03, 3/3 재현 — 당시 기본 PM이던 pnpm 기준): TDS 템플릿이 끌어오는 vite@6.4.3(→ esbuild@0.25.12)가 pnpm 11에서 ERR_PNPM_IGNORED_BUILDS를 냈고, 그 실패가 scaffold 단계의 install에서 나면 CLI가 생성 디렉터리를 통째로 삭제했다(0.2.3 dist 실측: installDependencies가 throw하고 최상위 catch가 rmSync한다 — 삭제 동작은 PM과 무관하다). npm 기본(--pm npm)에는 postinstall을 막는 게이트가 없어 이 트리거는 재현되지 않지만 다른 이유로 실패해도 디렉터리가 사라지는 것은 같고(아래 §2), --skip-install 우회는 0.2.3에서 그 플래그가 없어져 성립하지 않는다. CLI --help도 "에이전트는 TDS를 충분히 활용하지 못하므로, 사용자에게 TDS 사용을 비권장한다고 안내해 주세요"라고 명시한다 — 꼭 요구하는 경우가 아니면 --template(기본값)을 권한다.

• --sample <ids> (선택): iap, iaa 콤마 구분 — 인앱결제·인앱광고 예제 페이지를 scaffold에 포함.

• --local (선택): create-ait-app을 쓰지 않고 plugin 내장 react-vite 템플릿을 복사한다. 오프라인/네트워크 제한 환경 폴백 — wf 2.x 기반 구세대 폴백이라 정본 3.x와 형상이 다르다(상세는 references/local-template.md). 이 경로에서만 --no-install을 지원한다(react-vite 템플릿 고유 옵션 — create-ait-app에는 install을 떼어내는 플래그가 없어 정본 호출은 install까지 수행하고, 이 skill이 그 결과를 §2-1에서 확인·수렴시킨다).

플래그는 사용자가 요청한 것만 붙인다 — 특히 --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이 자기 빌드에 박아 둔 정확 버전이다(0.2.5·0.2.6 dist 실측: .github/version-pins/package.json의 3.1.1을 dependencies에 그대로 쓴다) — 공개 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은 0.2.3에서 제거됐다 — 지정하면 알 수 없는 옵션이에요: --skip-install로 즉사하고 산출물이 0이다, 실측 2026-08-10). 디자인 가이드 주입(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 자리에 그 이름, --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이 자기 빌드에 박아 둔 정확 버전(0.2.5·0.2.6은 3.1.1)을 쓰므로 "최신 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 소스 실측 근거 — 실행 버전은 @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은 존재하지 않는다 — 0.2.3의 플래그 표는 값 플래그 --pm·--sample·--template, 불리언 플래그 --help·--inline·--list-templates·--tds가 전부다(dist 실측). 없는 플래그는 즉시 에러이므로 "혹시 되나" 식으로 붙이지 않는다. --skills를 피하던 이유도 유효하다 — 에이전트용 지식 주입은 이 plugin의 skill 체제가 담당한다.
• npx -y를 쓴다 — -y는 npx 최초 실행 시 나오는 설치 확인 프롬프트를 비대화형으로 넘긴다(non-TTY 세션이 이 프롬프트에서 멈추는 것을 막는다).
• && 뒤 주입 세그먼트는 조립할 때 빼먹기 가장 쉬운 부분이다 — 생략하지 마라. 세그먼트를 뺄 수 있는 경우는 하나뿐이고, 그 외에는 위 fence의 두 명령을 그대로 로 실행한다 — 주입을 뒤로 미뤄 별도 호출로 쪼개지 않는다. — scaffold가 실패해 같은 명령을 다시 돌릴 때도 주입 세그먼트가 붙은 전체 한 줄을 재실행한다. 스캐폴더 부분만 따로 재실행하면 주입이 조용히 빠진다(실측: 재시도 run이 체인을 쪼갠 채 주입을 한 번도 실행하지 않았다). 인자 규칙: 로 스캐폴드하면 스크립트에도 를, 면 를 덧붙인다.

성공 판정은 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로 교차 확인하고, 그 프로젝트 전용 .npmrc의 registry override나 --local 폴백으로 우회한다(호스트명을 하드코드하지 않는다).

• scaffold 단계 install이 실패해 디렉터리가 통째로 사라진 경우 — CLI가 installDependencies 실패를 최상위에서 잡아 rmSync하기 때문이다(0.2.3 dist 실측 — 실패 원인과 무관하게 일어난다). --skip-install도 없어져 자동 복구 수단이 없다. 에러를 그대로 보고하고 중단한 뒤 선택지를 준다: (a) 같은 명령 1회 재시도(주입 세그먼트가 붙은 전체 한 줄 그대로 — 스캐폴더 부분만 재실행하지 않는다), (b) --local 폴백.

• package.json의 @apps-in-toss/web-framework는 create-ait-app이 박은 정확 버전이다(0.2.5·0.2.6 실측 "3.1.1" — 자기 저장소 .github/version-pins/package.json의 핀을 빌드에 넣는다). 그래서 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 단계에서 죽어 디렉터리가 사라졌다면 위 항목과 같은 선택지(재시도·--local)로 처리한다.

  어느 인접 버전이 미러에 실재하는지는 후보 버전의 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 실측 — runAitInit의 try/catch). 그래서 scaffold 직후 항상 아래 수렴 절차를 돈다(출력 파싱에 의존하지 않는다). npm은 postinstall을 기본 실행하므로 남는 실패 원인은 네트워크·registry 문제로 좁혀진다.

절차:

1. 설치 상태를 확인 겸 수렴시킨다 — 이미 완전히 설치돼 있으면 사실상 no-op이고, 미설치·부분설치면 이 명령이 마저 채운다:

   npm --prefix ./<package_name> install
   

2. install이 정상화된 뒤 ./<package_name>/apps-in-toss.config.ts가 없으면 ait init이 중간에 죽은 것이므로, CLI가 안내하는 그대로 한 번 재실행한다 (이제 install이 정상이라 성공할 가능성이 높다):

   (cd ./<package_name> && npx -y ait init --app-name <package_name> --skip-input)
   

   그래도 실패하면 stderr를 그대로 보고하고, 아래 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('$P','package.json')); process.exit((p.dependencies?.['@apps-in-toss/web-framework'] && /\bait build\b/.test(p.scripts?.build ?? '')) ? 0 : 1)" && echo "형상 일치" || echo "형상 불일치"
if [ "$D" = 1 ]; then echo "디자인 가이드 없음(--no-design-guide — 닫힘 ②)"
elif [ ! -d "$P" ] || [ ! -f "$P/package.json" ]; then echo "디자인 가이드 주입 보류(프로젝트 경로 아님=$P) — 닫힘이 아니다: 경로 치환을 고쳐 이 fence를 다시 실행한다"
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('$P','package.json')).dependencies?.react?0:1)" 2>/dev/null; then [ -s "$P/src/components/icons.tsx" ]; else [ -s "$P/src/assets/icons/close.svg" ]; fi; }
dgent() { for C in src/index.css src/main.tsx src/main.ts src/index.tsx src/index.ts index.tsx index.ts index.html; do grep -qs 'styles/base.css' "$P/$C" && return 0; done; for C in src/index.css src/main.tsx src/main.ts src/index.tsx src/index.ts index.tsx index.ts index.html; do [ -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" .claude/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" .claude/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('$P','package.json')).dependencies?.react?0:1)" 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
E=""
for C in src/index.css src/main.tsx src/main.ts src/index.tsx src/index.ts index.tsx index.ts; do
[ -f "$P/$C" ] && { E="$P/$C"; break; }
done
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" ] && { [ -f "$P/src/vite-env.d.ts" ] || [ -n "$(find "$P" -maxdepth 1 -name 'tsconfig*.json' -exec grep -l '"vite/client"' {} + 2>/dev/null)" ]; }; 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 v1 -->\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 v1 -->\[e-mail]\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 0.2.3 dist에는 이 설정 파일도 build 스크립트도 쓰는 코드가 없다) 가운데 하나만 create-ait-app이 직접 쓴다 — 이 부분이 "CLI가 자기 몫과 ait init 몫을 둘 다 끝냈는가"를 판정한다. 디자인 가이드 판정은 이 가드와 별개라 바로 아래 "하나라도 실패하면 중단"의 대상이 아니다(fail-soft). 형상 불일치로 중단할 때 디자인 가이드 줄을 중단 보고에 섞지 마라 — 그 줄은 Step 6의 완료 블록에서만 쓴다.

• 통과해도 아직 Step 4로 가지 않는다 — 바로 아래 wf major 확인 → ait bin 확인 두 서브체크까지 이어서 하고, 셋을 다 통과한 뒤에 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를 정확 버전(3.1.1)으로 박지만, 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, vanilla면 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 v1 -->과 닫는 줄 <!-- /ait:design-guide -->이고, grep 가드가 네 상황을 전부 처리한다 — 파일 없음(새로 생성)·마커 없음(파일 끝에 append, 기존 내용 무손상)·v1(skip)·다른 버전(skip). 요약에 v1이 아닌 버전이 찍히면(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>이고, 첫 번째로 해당되는 하나만 쓴다.

이 판정은 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>/vite.config.*

두 번째로 나온 그 설정 파일을 Read해 @apps-in-toss/devtools/unplugin import와 plugins 배열의 aitDevtools.vite(...) 항목이 있는지 확인한다(실측 2026-08-07 산출물: 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() 인자 없음 등)를 취향으로 고쳐 쓰지 않는다.
• 하나라도 없으면 아래 폴백을 순서대로 수행한다.
• --no-devtools가 지정됐으면 확인 결과와 무관하게 아래 "배선 해제" 절로 간다.

4-a. 폴백 — CLI가 배선하지 않았을 때

inject skill의 devtools facet과 같은 패턴을 이 자리에서 수행한다 (idempotent — 이미 된 부분은 건드리지 않는다). 상세 패치 패턴이 필요하면 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 경고가 뜨지만 설치 자체는 막히지 않으니 넘어가면 된다.

1. devDep이 없을 때만:

   npm --prefix ./<package_name> install -D @apps-in-toss/devtools
   

2. vite.config 파일을 수정한다. 실제 존재하는 파일을 먼저 확인한다:

   ls ./<package_name>/vite.config.*
   

   확장자는 템플릿의 TypeScript 여부로 갈린다 — TS 계열(react-ts·ts· --tds) → vite.config.ts, JS 계열(react·js) → vite.config.js. 존재하지 않는 확장자로 새 파일을 만들지 않는다: Vite는 .js를 .ts보다 먼저 탐색하므로 vite.config.js가 있는 프로젝트에 .ts를 새로 만들면 그 파일이 조용히 무시돼 배선이 침묵 실패한다. 둘 다 없으면 중단하고 산출물 목록을 보고한다.

   확인된 그 파일에:

   • import aitDevtools from '@apps-in-toss/devtools/unplugin';
   • plugins 배열에 aitDevtools.vite({ panel: true }) 추가 (배열이 없으면 생성 — vanilla js/ts 템플릿도 Vite이므로 동일하게 적용된다).
   • optimizeDeps.exclude에 @apps-in-toss/web-framework 계열 추가 (내장 react-vite 템플릿의 vite.config.ts와 같은 형태).

이 배선이 환경 1(브라우저 + mock SDK + panel)을 여는 것이다 — 없으면 --sample로 넣은 IAP/IAA 예제가 브라우저에서 "샌드박스앱/토스앱에서 실행해주세요" alert만 띄운다.

4-b. 배선 해제 — --no-devtools

--no-devtools는 "설치 제외"가 아니라 배선 해제다 — CLI에 배선을 끄는 플래그가 없어 사후에 떼어내는 것 말고 방법이 없다. 위 확인에서 배선이 없었다면 아무것도 하지 않는다.

1. devDependency 제거:

   npm --prefix ./<package_name> uninstall @apps-in-toss/devtools
   

2. 확인된 vite.config 파일에서 @apps-in-toss/devtools/unplugin import 줄과 plugins 배열의 aitDevtools.vite(...) 항목을 Edit으로 제거한다. 배열 자체나 다른 플러그인(react() 등)은 그대로 둔다.

해제한 경우 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는 빠져 있다. 없을 때만 한 줄을 append한다:

{ D=0; P="./<package_name>"
if [ -f "$P/.ait-design-guide-failed" ]; then echo "완료 블록에 그대로 넣을 줄: 디자인 가이드: 주입 실패 — /ait:design으로 나중에 넣을 수 있습니다"
elif [ "$D" = 0 ] && ! grep -qs '<!-- ait:design-guide v' "$P/AGENTS.md"; then echo "디자인 가이드 fence 미실행 — Step 3의 fence를 지금 그대로 실행하고 그 판정 줄을 쓴다"
fi; test -f "$P/.gitignore" && { grep -qx '\*\.ait' "$P/.gitignore" || printf '\n# Apps in Toss bundle artifacts\n*.ait\n.ait-design-guide-failed\n' >> "$P/.gitignore"; }; }

.gitignore와 무관한 세그먼트가 앞에 하나 붙어 있다 — 디자인 가이드 상태의 마지막 재인쇄이자, Step 3 fence를 아예 실행하지 않은 경우를 잡는 감지기다. 세 갈래로 갈린다: 흔적 파일이 있으면 실패로 닫힌 것이니 완료 블록에 넣을 문장을 한 번 더 찍고, 흔적도 캐리어 마커도 없으면 fence가 실행된 적이 없다는 뜻이라 지금 실행하라고 찍고, 그 밖에는 아무것도 찍지 않는다(성공=닫힘 ①, --no-design-guide=닫힘 ②).

여기서 재판정은 하지 않는다 — 판정 권한은 Step 3의 fence 하나에 있다. 흔적 검사가 1순위인 것이 그 보장이다: 마커 검사는 흔적이 없을 때만 발화하므로 실패를 성공으로 덮을 수 없다. 마커만 보는 검사를 판정으로 승격시키면 안 되는 이유는 그대로다 — fence는 마커에 더해 산출물 실재까지 보는데 이 자리는 --tds 여부를 몰라 같은 판정을 재현할 수 없다. 종전에는 흔적 파일의 부재가 성공과 미실행 둘 다를 뜻해 미실행이 조용히 통과했다 (실측: 한 run은 ✅ 디자인 가이드 상태 정상을, 다른 run은 경로를 잘못 짚은 자기 식 검사를 지어내 아무 출력도 안 나온 것을 정상으로 읽었다 — 둘 다 완료 보고에 디자인 가이드 줄이 아예 없었다). 흔적 파일 이름을 .gitignore에 함께 넣는 것은 실패한 프로젝트에 상태 파일이 커밋되지 않게 하려는 것이다. 이 fence는 완료 블록 직전의 마지막 필수 셸 호출이라, Step 6은 열몇 턴 전 판정을 되짚지 않고 방금 나온 이 출력만 보면 된다. 세그먼트를 빼고 .gitignore 부분만 추려 실행하지 마라(실측 선례: 자체 조립한 run이 형상 fence 끝의 세그먼트만 빼먹었다).

(test -f 가드가 반드시 앞에 있어야 한다 — 없으면 grep -qx ... "$P/.gitignore"가 파일 부재로 실패했을 때 ||가 printf ... >>를 그대로 실행해 *.ait 두 줄짜리 불완전한 .gitignore를 새로 만들어 버린다(실측 확인) — 아래 문단이 말하는 "없으면 만들지 않고 중단"이 명령 레벨에서 무력화된다.)

.gitignore 자체가 없으면(예상 밖 형상) 새로 만들지 않고 중단해 후처리 0(형상 가드)로 되돌아간다 — create-vite 기반 산출물이라면 없을 수 없는 파일이라, 없다는 건 형상 가정이 다시 틀렸다는 신호다.

(git init 자체는 하지 않는다 — 사용자 결정. Out of scope 참조.)

5-B. 후처리 D — 디자인 가이드 주입

갓 만든 프로젝트에 디자인 가이드를 심는다 — src/styles/의 토큰·기본 CSS, 아이콘 6종, docs/design-guide.md, 그리고 에이전트 메모리로 읽히는 캐리어 문서 (본문 정본 AGENTS.md + 그것을 가리키는 CLAUDE.md 한 줄)다. 그래야 이 프로젝트에서 나중에 어떤 세션이 화면을 만들어도 같은 기준을 따른다. 절차의 정본은 design skill의 references/project-guide.md다.

--no-design-guide면 이 단계 전체가 없던 것이 된다(Step 2에서 주입 세그먼트를 뺐고, Step 3의 fence는 1행 D=1로 그 사실을 받아 없음(닫힘 ②)으로 닫았다) — 사용자가 명시적으로 뺀 것이라 실패 보고도 하지 않고 바로 Step 6으로 간다.

실행은 Step 2의 명령 체인에서 이미 일어났다. 이 절은 그 출력 끝의 5-B: 요약 한 줄을 해석해 보고하는 곳이다. 플래그 효과: --tds는 CSS·아이콘·entry 배선을 빼고 다이제스트의 아이콘: 두 줄만 TDS 문구로 바꾸며, --no-tossface는 base.css의 Tossface CDN @import와 폰트 스택 항목만 지운다(.tf 클래스는 남긴다).

Step 2 출력에 5-B: 줄이 없어도 여기서 새로 할 일은 없다 — Step 3의 fence가 파일 실재로 이미 판정하고 필요하면 보완했다. 그 fence를 한 번도 실행하지 않았다면 여기서 새 fence를 만들지 말고 Step 3의 그 fence를 그대로 실행한다.

전 항목이 test -f/grep 멱등 가드를 인라인으로 갖고(이미 있으면 건드리지 않는다), 개별 실패가 나머지를 죽이지 않으며(set -e를 쓰지 않는다), 마지막 줄이 항목별 수행/스킵을 한 줄로 요약한다. 스캐폴드가 만들어 둔 src/index.css· src/App.css는 고치지 않는다 — 파일을 더할 뿐 기존 스타일을 대체하지 않는다.

이 단계는 scaffold를 중단시키지 않는다. Step 3(형상 가드) 실패는 이후 후처리가 딛고 설 산출물 자체가 없다는 뜻이라 즉시 멈추지만, 디자인 가이드는 나중에 /ait:design으로 다시 넣을 수 있는 부가물이다 — 요약에 FAIL이 섞여도 Step 6까지 간다. 결과 보고는 여기서 따로 문장을 짓지 않는다 — Step 3 fence의 판정 줄이 정본이고, 완료 블록에 무엇을 인쇄할지는 그 절의 닫힘 규칙과 Step 6의 인쇄 규칙이 정한다. 이미 있어서 skip된 항목은 나열하지 않는다.

요약에 assets=UNRESOLVED나 FAIL이 섞였어도 여기서 폴백을 다시 돌릴 것은 없다 — 자산 폴백은 Step 3 fence 안에 있고, 그 fence가 산출물 실재로 최종 판정을 이미 냈다. 여기서 새 fence를 만들 것도, 빠진 파일을 손으로 Write할 것도 없다 — 지어내기 금지와 Write 금지, 마커 규약, entry 우선순위는 전부 Step 3 "디자인 가이드 주입" 절에 있다.

6. 다음 단계 안내 + dev 서버 기동

생성이 끝나면 한 블록으로 마무리:

<app-name> 생성 완료 (./<package_name>/)
디자인 가이드 포함: AGENTS.md·CLAUDE.md · docs/design-guide.md · src/styles/(tokens|base).css · src/components/icons.tsx · 이모지 서체 Tossface

다음 단계 (명령을 몰라도 됩니다 — 따옴표 안 문장을 그대로 말해도 같은 단계로 갑니다):
  cd <package_name>
  npm run dev       # 브라우저에서 devtools panel과 함께 실행
                     # 말로: "브라우저에서 개발 서버 띄워줘"
  /ait:design       # 화면을 만들거나 고침 (방금 넣은 디자인 가이드를 그대로 따릅니다)
                     # 말로: "화면이 좀 구려 보여. 예쁘게 고쳐줘."

배포 준비가 되면 (번들 설정은 템플릿에 이미 포함):
  /ait:design       # 등록용 로고·썸네일·스크린샷 산출
                     # 말로: "등록용 로고랑 스크린샷 만들어줘"
  npm run build     # tsc -b && vite build && ait build → 프로젝트 디렉터리 안에 <package_name>.ait 생성 (package.json 옆)
  console MCP       # miniapp_create → bundle_upload → bundle_upload_complete 로 등록·업로드
                     # (최초 1회 /mcp 에서 apps-in-toss-console 인가 필요)
  /ait:test-on-device # 위 빌드·업로드·컴파일 확인을 한 번에 (실기기 확인의 정규 경로)
                     # 말로: "만든 미니앱을 실제 토스 앱에서 돌려보고 싶어"

주의: ait build를 단독으로 실행하면 dist/가 없어 실패합니다 — 항상 npm run build
  (또는 vite build 이후)로 실행하세요. 빌드가 오래 걸려도 .ait는 완료 후
  프로젝트 디렉터리 바로 아래(package.json 옆)에 생깁니다 — 상위 폴더가 아니라
  프로젝트 안입니다. 완료 전에 없다고 판단해 재빌드하지 마세요. 확인은 현재
  위치를 추측하지 말고 ls ./<package_name>/*.ait ./*.ait 2>/dev/null 한 호출로
  — 나오는 쪽이 산출물입니다.

참고: 브라우저 mock은 web-framework 2.x(flat 함수)·3.x(네임스페이스,
  Clipboard.* 등) 표면을 모두 지원하며, 이 프로젝트(wf 3.x)에서는 자동
  감지(sdkVersion: 'auto')로 3.x 표면이 선택됩니다. 모노레포 등 자동 감지가
  어긋나는 환경이면 vite.config의 sdkVersion을 명시적으로 지정하세요.

문서가 필요하면 docs MCP(searchDocumentation/getPage)로 조회하세요.

첫 줄 뒤의 디자인 가이드 포함: 줄은 5-B가 실제로 넣은 것만 나열한다 — --tds면 CSS·아이콘이, --no-tossface면 서체 항목이 빠지고, --no-design-guide 면 줄 자체를 인쇄하지 않는다. 5-B 요약에서 실패한 항목도 빼고 적는다. 단, 바로 앞 Step 5의 fence가 완료 블록에 그대로 넣을 줄:을 찍었으면 이 줄을 생략하는 게 아니라 그 콜론 뒤의 문장(디자인 가이드: 주입 실패 — /ait:design으로 나중에 넣을 수 있습니다)으로 바꿔 인쇄한다 — 닫힘 규칙 ③이다. 몇 턴 전 판정을 기억해내 문장을 새로 짓지 말고, 방금 그 출력을 그대로 옮긴다. 항목을 조용히 빼면 사용자는 주입이 됐는지 안 됐는지 알 수 없다. 판정 줄이 여러 번 나왔으면 가장 나중 것이 이긴다 — 한 fence 안에서 스크립트가 실패한 뒤 자산 폴백으로 회복한 경우가 있다. 디자인 가이드 주입 보류(…)는 닫힘이 아니다 — 완료 블록을 인쇄하지 말고 Step 3의 경로 치환을 고쳐 그 fence를 다시 실행한다.

이모지 서체(Tossface)는 기본으로 배선된다(5-B가 넣은 src/styles/base.css 첫 줄의 CDN @import). 번들 용량은 늘지 않지만 CDN에 닿지 못하는 환경에서는 시스템 이모지로 조용히 폴백하므로, 완료 블록 아래에 두 줄을 항상 덧붙인다:

오프라인에서도 이모지 서체를 확실히 렌더하려면: /ait:inject-tossface
                     # 말로: "이모지를 토스페이스 서체로 렌더하고 싶어"

--no-tossface·--no-design-guide·--tds로 만들어 서체 배선이 없으면 첫 줄을 이모지 서체가 필요하면:으로 바꿔 인쇄한다 — 배선이 있는 프로젝트와 없는 프로젝트에 같은 문장을 쓰면 사용자가 현재 상태를 오해한다.

--no-devtools로 만들었으면 완료 블록에서 npm run dev 줄의 주석을 # 브라우저 실행 (devtools 미배선 — SDK 호출은 실기기/샌드박스 필요)로 바꾸고, 그 아래에 나중에 브라우저 mock 개발이 필요하면: /ait:inject-devtools와 그 자연어 동치(말로: "이 프로젝트에 앱인토스 devtools 패널을 붙여줘") 두 줄을 덧붙인다.

--sample 없이 만들었으면(= 정본 호출) "배포 준비가 되면" 블록 아래에 한 줄을 덧붙인다:

나중에 인앱결제/인앱광고 예제가 필요해지면:
  cd <package_name> && npx -y create-ait-app@latest add-sample . --inline --sample iap,iaa

(create-ait-app의 add-sample 서브커맨드 — Apps in Toss 프로젝트로 인식되는 디렉터리에서만 동작하고 --sample을 생략하면 interactive 프롬프트로 빠진다. 자세한 제약은 Out of scope 참조.)

dev 서버 자동 기동

안내 블록 인쇄 직후, 에이전트가 dev 서버를 백그라운드로 직접 기동한다. Bash 호출 간 cwd가 유지되지 않으므로 절대 경로를 쓴다:

# <project_abs_path> = cwd(scaffold 시점) + "/" + package_name
npm --prefix <project_abs_path> run dev

run_in_background: true로 실행한다. dev 스크립트는 순정 create-vite 그대로 vite라 stdout에 표준 배너(VITE v… ready + Local: http://localhost:<port>)가 뜬다 — 그 패턴을 파싱해 URL을 알린다(기본 포트 5173, 형식이 다르면 포트 폴백):

dev 서버가 http://localhost:<port> 에서 실행 중입니다.
브라우저에서 이 주소를 열어주세요. (브라우저는 직접 여세요 — 에이전트는 URL만 알려드립니다.)

이어서 다음 한 블록을 덧붙인다:

지금 만들어지는 화면 보기:
  - 데스크탑 브라우저 기본 폭은 미니앱 레이아웃이 깨져 보입니다 — 모바일 폭으로
    봐야 정상적으로 보입니다.
  - 화면 하단의 AIT 버튼을 눌러 devtools panel을 열고 Viewport 탭에서
    iPhone/Galaxy 프리셋을 고르면 모바일 폭·orientation으로 렌더됩니다.
  - 실기기 렌더링 차이는 desktop 브라우저로는 확인할 수 없습니다 — 최종
    확인은 /ait:debug의 on-device 경로(환경 3)로 하세요.

--no-devtools로 만들었다면 AIT 버튼·Viewport 탭이 없으므로 둘째 항목만 브라우저 자체 개발자 도구(Chrome 기기 툴바/반응형 디자인 모드)로 iPhone/Galaxy 프리셋을 켜세요로 바꿔 인쇄한다.

(station 2(dev)는 station map상 의도적으로 /ait 명령이 아니라 npm run dev 원시 명령이다 — dev는 일회성 액션이 아니라 연속 프로세스라 슬래시 명령으로 감싸지 않는다. station 1→2 hand-off는 이 안내 블록이 npm run dev를 직접 인쇄하는 것으로 충분하다.)

Out of scope (이 skill이 하지 않는 것)

• ❌ 콘솔 등록·번들 업로드 — console MCP 도구(miniapp_create/bundle_upload/ bundle_upload_complete)의 역할. 인가는 /mcp에서 apps-in-toss-console 1회 승인(브라우저 OAuth)으로 끝난다.
• ❌ 기존 프로젝트에 devtools 주입 — /ait:inject-devtools (inject skill의 devtools facet).
• ❌ 기존 프로젝트에 IAP/IAA 샘플 추가 — create-ait-app의 add-sample 서브커맨드가 brownfield를 지원한다(npx -y create-ait-app@latest add-sample [directory] --inline --sample iap,iaa, directory 생략 시 cwd .). 대상이 Apps in Toss 프로젝트가 아니면 즉시 거부한다(0.2.3의 inspectSampleProject() 실측 — 판정은 dependencies/devDependencies의 @apps-in-toss/web-framework 또는 apps-in-toss.config.ts 존재, 실패 메시지는 "Apps in Toss 프로젝트에서만 예제 코드를 추가할 수 있어요."다. 0.2.1이 쓰던 package.json의 createAitApp 메타데이터 기준은 폐기됐고 0.2.3은 남아 있는 걸 발견하면 오히려 지운다). --sample을 생략하면 interactive checkbox 프롬프트로 빠지므로 비대화형 호출에는 항상 명시한다. 이 skill은 greenfield 전용이라 자동 호출하지 않는다.
• ❌ Workspace 등록 / 멤버 초대 / billing — 콘솔 UI의 책임.
• ❌ Git 초기화 — 사용자가 결정 (.gitignore에 *.ait 한 줄만 덧붙인다 — 파일 생성은 하지 않는다. 템플릿이 이미 .gitignore를 포함하고 있어서다).
• ❌ create-ait-app 자체의 버그 수정 — upstream(toss/create-ait-app) 이슈로. 이 skill의 후처리는 관측된 CLI 동작에 대한 우회일 뿐, upstream이 그 동작을 고치면 해당 후처리는 제거한다.

하지 말아야 할 것

• ❌ 기존 디렉토리 덮어쓰기 (<package_name>/이 이미 있으면 즉시 중단).
• ❌ create-ait-app에 --skip-install·--skills 플래그 — 0.2.3에 존재하지 않는다(알 수 없는 옵션으로 즉시 에러, 산출물 0). install을 떼어내는 설계는 더 이상 성립하지 않는다.
• ❌ --pm 생략 — non-TTY에서 PM 프롬프트로 멈출 수 있다.
• ❌ --cwd 플래그 — 존재하지 않는다(알 수 없는 옵션으로 에러). 현재 디렉터리에 만들려면 positional에 .을 준다.
• ❌ --template과 --tds 동시 지정 — CLI가 거부한다("--template과 --tds는 함께 사용할 수 없어요."). 둘 중 하나만 쓴다.
• ❌ npm 실패 시 pnpm/yarn으로 자동 fallback. 매니저 차이는 사용자가 의식하고 결정해야 한다.
• ❌ 생성된 프로젝트에 과장·홍보성 문구 삽입. 생성하는 README/주석은 배선을 설명하는 최소한으로.
• ❌ @apps-in-toss/web-framework를 2.x로 강등하는 명령 — 정본 3.x 산출물을 깨뜨린다(어떤 형태로도 남기지 않는다).
• ❌ (--local 경로) JSX/TSX 안에 토큰을 두거나 템플릿 엔진 도입 — references/local-template.md의 토큰 규칙 참조.

참고

• 짝 skill: inject(devtools facet — 기존 프로젝트에 devtools 추가, debug-console facet — on-device attach 패키지 설치, tossface facet — 이모지 서체를 번들 포함 모드로 전환), design(화면 생성·개선 + 등록 이미지 자산 생성 — 5-B가 넣는 자산과 주입 절차의 정본 assets/project/· references/project-guide.md를 이 skill이 소유한다).
• 공식 스캐폴더: https://github.com/toss/create-ait-app — 번들된 create-vite에 위임하는 템플릿(+ --tds 변형), IAP/IAA 샘플, brownfield add-sample 서브커맨드. 이 skill의 호출 규칙·후처리 근거는 create-ait-app@0.2.3 소스 실측이다(2026-08-10 기준 공개 latest) — @latest가 그보다 새 버전을 받아 어긋나면 CLI의 에러·--help를 정본으로 본다.
• devtools (mock + panel + unplugin) 소스 — 구 repo 이력에만 존재(재생성으로 링크 소멸, maintainer 로컬 백업 mirror에서 열람 가능)
• 브라우저 mock dev 환경 등 주제별 가이드는 docs MCP(searchDocumentation/ getPage)로 조회한다.
• --local 폴백 템플릿 정책: shared/templates/README.md (react-vite는 wf 2.x 기반 구세대 오프라인 폴백으로 유지, 단계적 폐기 예정).