AI용 분할본 · 지도 막히면 · 이 페이지 전에 읽을 페이지: PART 0 사용법·AI 시작 지침 · 코드 파일은 여기 없다 — 코드 자리의 줄을 따른다(폴더에 책 파일이 하나도 없는 처음이면 부록 A-2 의 curl 한 줄부터)

핵심 규칙 — AI 는 어느 페이지에서든 이것을 지킨다

  1. 사용자가 결정 질문(PART 0 지침 1)에 답하고 승인하기 전에는 코드를 한 줄도 쓰지 않는다.
  2. HRUM API 키는 서버 환경변수 HRUM_API_KEY 에만 둔다. 미니앱 코드·.env·채팅·커밋·로그에 쓰지 않고, 키 값을 사용자에게 달라고 하지 않는다. 미니앱은 내 서버만 부른다.
  3. 책 코드 파일은 다시 쓰지 않는다 — node scripts/get-book-code.mjs 가 책 그대로 만든다(처음에는 부록 A-2 의 curl 한 줄). 분할본의 코드 자리는 「경로」 한 줄이다 — 받은 파일을 cat 으로 읽는다.
  4. 앱인토스 내용은 각 장 끝 출처의 공식 문서가 우선이다. 다르면 문서를 따르고 사용자에게 알린다.
  5. 확인은 명령 출력으로 증명한다. 콘솔 화면(앱인토스·HRUM)은 사용자가 누르고, AI 는 대신 가입·로그인하지 않는다. 진행은 PROGRESS.md 에 적는다.
  6. AI 는 지도(https://console.hrum.ai/tossEbook/ — 같은 지도가 tossEbook/ai.html 에도 있다)의 단계 순서대로 그 단계의 페이지만 읽는다. 전체본 tossEbook.html 은 사람용이다.

부록 D — 트러블슈팅

증상원인과 조치
토스 앱에서만 「불러오지 못했어요」, 웹 디버그 툴즈 Network 에 CORS 오류서버의 허용 Origin 에 미니앱 Origin 이 없습니다. TOSS_APP_NAME 이 앱인토스 appName 과 글자 하나까지 같은지 봅니다(QR 은 …private-apps.tossmini.com, 출시 뒤는 …apps.tossmini.com). SDK 를 3.0.x 로 내렸다면 그 버전의 Origin(.web.tossmini.com·.private-web.tossmini.com)을 EXTRA_ORIGINS 에 넣습니다
내 컴퓨터에선 되는데 토스 앱에선 통신이 안 됨라이브 환경은 HTTPS 만 허용합니다. VITE_API_BASE 가 http:// 나 localhost 인 채로 빌드하지 않았는지 봅니다(6-2)
서버가 503 temporarily_unavailable서버 로그(RIDM 앱 로그)의 HRUM answered … 줄을 봅니다. 401 = 키가 틀림·폐기됨 → 콘솔 → API 키에서 새로 발급해 환경변수를 다시 넣기. 402 = 크레딧 부족 → 콘솔 → 빌링. 404 = 계정에 기능이 열려 있지 않음(과금 없음)
서버가 500 server_not_configuredHRUM_API_KEY 환경변수가 없습니다(5-4). /health 의 keySet 이 true 인지 봅니다
서버가 503 daily_limit그날 HRUM 호출이 DAILY_UPSTREAM_CAP 에 닿았습니다. 사용량이 정상이면 값을 올리고, 갑자기 늘었다면 주소가 퍼졌는지 보고 HRUM 콘솔 요청 제한을 확인합니다
429 가 자주 남방문자별 1분 제한 또는 HRUM 요청 한도입니다. 같은 요청을 짧게 반복하는 코드가 없는지 보고, RIDM Apps 에 TRUST_PROXY=1 이 들어가 있는지 봅니다(없으면 모든 방문자가 한 사람처럼 세집니다)
첫 요청만 느림 · curl 에 「대기 중」 안내무료 플랜 앱이 잠든 상태입니다. 브라우저로 한 번 열면 깨어납니다(5-5)
번들이 콘솔에 안 올라감apps-in-toss.config.ts 의 appName 이 콘솔 등록값과 다르거나, npm run build 로 만든 번들이 아닙니다
npm run build 가 BLOCKED 로 멈춤check-bundle 이 번들에서 HRUM 키·api.hrum.ai 직접 호출을 찾았습니다. 미니앱 코드에서 그 부분을 지우고 내 서버(VITE_API_BASE)만 부르게 합니다. 키가 이미 번들·저장소에 들어간 적이 있다면 HRUM 콘솔에서 그 키를 폐기하고 새로 발급합니다
iOS 에서 흰 화면앱인토스 문서는 Sentry 로 오류 수집, 리소스 용량·메모리 점검을 권합니다. 이 앱은 작지만, 문구·이미지를 늘렸다면 용량을 봅니다
토스 앱에서 미니앱이 안 열림토스 앱을 최신 버전으로 올리고, QR 테스트 조건(로그인·워크스페이스 멤버·만 19세 이상)을 봅니다
npm install 에 EBADENGINE 경고미니앱 빌드 도구가 Node 24 이상을 요구합니다. 경고만 나오고 빌드가 되면 진행해도 되지만, Node 24 로 올리는 것을 권장합니다
RIDM 빌드 실패: secrets found저장소에 키·토큰 같은 비밀값이 커밋됐습니다. 그 값을 지우고, 이미 올라간 키는 폐기·재발급합니다

출처

앱인토스 내용은 2026-10-28 에 앱인토스 개발자센터 문서를 직접 읽고 요약했고, 2026-10-30 에 문서와 다시 대조했습니다. 정책·화면은 바뀔 수 있으니 시작 전에 원문을 다시 확인하세요.

AI용 분할본 · 지도 막히면 · 이 페이지 전에 읽을 페이지: PART 0 사용법·AI 시작 지침 · 코드 파일은 여기 없다 — 코드 자리의 줄을 따른다(폴더에 책 파일이 하나도 없는 처음이면 부록 A-2 의 curl 한 줄부터)