본문으로 건너뛰기

개발지시서 한 장으로 토스 미니앱 'MVP' 만들기 — Claude Code × 앱인토스

김코딩

2026.10.15

개발지시서 한 장으로 토스 미니앱 'MVP' 만들기 — Claude Code × 앱인토스 본문 이미지

소개

시도하고자 했던 것과 그 이유를 알려주세요.

매달 빠져나가는 구독료, 다들 정확히 얼마인지 알고 계신가요? 넷플릭스, 유튜브 프리미엄, 쿠팡 와우, ChatGPT…. 하나하나는 몇천~몇만 원이지만 합치면 꽤 큰 돈인데, 막상 "이번 달 구독료 총합"을 물어보면 바로 답하기 어렵더라고요.

그래서 "매달 나가는 구독료, 얼마나 줄일 수 있을까?" 를 한 화면에서 보여주는 토스 미니앱 '구독 다이어트' 를 만들어 보기로 했어요.

  • 이용 중인 구독을 직접 등록하면 월평균 구독료와 연간 예상 지출을 계산해 줘요.

  • 해지할 구독을 고르면 예상 절약 금액을 바로 보여줘요.

  • 회원가입, 서버, 광고 없이 토스 앱 안에서 가볍게 쓰는 것이 목표였어요.

토스 앱인토스(Apps in Toss) 를 고른 이유는 토스 사용자에게 별도 설치 없이 바로 보여줄 수 있기 때문이에요. 다만 앱인토스 SDK와 토스 디자인 시스템(TDS)은 처음이라, 이번에는 AI 코딩 에이전트(Claude Code)에게 "설명"이 아니라 "실제 개발과 테스트"를 맡기면 어디까지 되는지 확인해 보고 싶었어요.


진행 방법

어떤 도구를 사용했고, 어떻게 활용하셨나요?

사용한 도구

도구

용도

Claude Code (Windows, VS Code)

프로젝트 생성부터 코드 작성, 테스트, 문서화까지

앱인토스 WebView SDK 3.x + create-ait-app

공식 프로젝트 생성 도구와 SDK

토스 디자인 시스템(TDS Mobile)

토스스러운 UI 컴포넌트

React 18 + TypeScript + Vite

프런트엔드

Vitest + React Testing Library

자동 테스트

핵심 전략: 먼저 '개발지시서'를 쓰고, 단계별로 승인하기

AI에게 "구독 관리 앱 만들어줘"라고 하면 그럴듯하지만 제가 원하지 않는 기능까지 붙은 결과물이 나오기 쉬워요. 그래서 먼저 개발지시서(개발지시서.md) 를 꼼꼼하게 작성했어요. 담은 내용은 이래요.

  1. 범위를 못 박기: 화면은 정확히 3개(홈 / 등록·수정 / 구독 정리), 만들지 않을 기능 목록(카드 연동, 알림, AI 분석, 광고…)까지 명시

  2. 검증 가능한 숫자 주기: 계산 검증용 데이터와 기대 결과(월평균 51,800원, 연 621,600원 …)

  3. "추측 금지" 규칙: 존재하지 않는 패키지·API를 지어내지 말고, 공식 문서를 확인하고, 확인 못 한 것은 따로 보고할 것

  4. 단계 나누기: STEP 1 환경 구성 → STEP 2 계산·검증 → STEP 3 화면 → STEP 4 저장 → STEP 5 최종 검증

  5. 보고 형식: 각 단계마다 완료한 작업 / 수정한 파일 / 실행한 명령 / 테스트 결과 / 해결 못 한 문제

사용한 프롬프트

실제로 채팅창에 입력한 프롬프트는 놀라울 만큼 짧아요. 핵심은 폴더에 넣어둔 개발지시서였어요.

지금 폴더 보여? 폴더 확인해
앱인토스 프로젝트 초기 세팅해줘

(→ Claude Code가 폴더의 개발지시서.md를 읽고 STEP 1부터 시작)

응

(STEP 2, 3, 4, 5로 넘어갈 때마다 결과 보고를 읽고 "응"으로 승인)

사례글 작성해줘.

개발지시서의 주요 부분은 아래와 같아요. (전문은 첨부한 개발지시서.md 참고)

# Claude Code 개발 지시서
## 프로젝트: 구독 다이어트 — 토스 앱인토스 미니앱

당신은 React, TypeScript, 모바일 UX, 토스 앱인토스 개발에 능숙한 시니어 프런트엔드 개발자입니다.
아래 요구사항에 따라 실제로 실행 가능한 토스 미니앱을 개발해 주세요.
설명이나 예시 코드만 작성하지 말고, 프로젝트 파일을 생성·수정하고 테스트까지 진행하세요.

## 2. 개발 환경 — 프로젝트 생성 규칙
- 빈 폴더라면 공식 앱인토스 프로젝트 생성 도구를 사용합니다.
- 최신 공식 문서를 확인해 지원되는 SDK 및 패키지 버전을 선택합니다.
- 실제 존재하지 않는 패키지나 API를 추측해서 사용하지 않습니다.
- 공식 문서에 접근할 수 없다면 임의로 최신 SDK 사용법을 지어내지 마세요.

## 3. MVP 화면 구성 — 화면은 정확히 3개입니다.
(홈 / 구독 등록·수정 / 구독 정리, 각 화면의 표시 내용·버튼·안내 문구)

## 7. 계산 규칙
- 모든 계산은 React 컴포넌트 외부의 순수 TypeScript 함수로 구현합니다.
- 내부 계산에서는 중간 반올림을 하지 않습니다.
### 계산 검증용 데이터
- 넷플릭스: 월 17,000원 / ACTIVE
- 유튜브 프리미엄: 월 14,900원 / ACTIVE
- 음악 구독: 월 9,900원 / REVIEW
- 클라우드 서비스: 연 120,000원 / ACTIVE
기대 결과: 월평균 51,800원, 연간 621,600원, 월 절약 9,900원, 연 절약 118,800원, 정리 후 41,900원

## 8. 상태 관리
- 저장 실패 상태에서 화면에만 변경 내용이 반영되는 일이 없도록 합니다.
- 빠르게 여러 동작을 수행해도 저장 순서가 꼬이지 않도록 합니다.

## 9. 데이터 저장
- 브라우저 localStorage가 일반 웹에서 작동한다는 이유만으로
  토스 앱에서의 영구 보관을 보장한다고 가정하지 마세요.
- 저장된 데이터가 손상되어도 자동으로 빈 목록을 덮어써서 기존 데이터를 없애지 마세요.

## 13. MVP에서 만들지 않을 기능
카드·은행 연결, 결제 내역 자동 수집, 실제 해지, 알림, AI 분석, 광고, 유료 결제 …

## 15. Claude Code 작업 방식
- 실행하지 않은 코드를 실행했다고 주장하지 않습니다.
- 실제 토스 샌드박스에서 확인하지 못한 항목은 성공했다고 보고하지 마세요.

단계별로 실제 일어난 일

STEP 1. 환경 구성 Claude Code가 공식 개발자센터 문서 전문(llms-full.txt)을 내려받아 찾아보고, 공식 생성 도구 create-ait-app의 실제 옵션을 패키지 README에서 확인했어요. TDS는 React 18이 필요해서 --tds 템플릿을 골랐어요.

npx create-ait-app subscription-diet --inline --pm npm --tds

흥미로웠던 점: 처음엔 현재 폴더(kjy-261007-toss-app)에 바로 만들려고 했는데, "appName에 toss를 포함할 수 없다" 는 오류가 났어요. 그래서 subscription-diet라는 이름으로 만든 뒤 폴더로 옮겼어요.

STEP 2. 계산·검증 (순수 함수 + 단위 테스트 50개) 금액을 "월 환산액"으로 먼저 나누면 소수점 오차가 쌓여요. 그래서 모두 연간 정수로 더한 뒤 마지막에 한 번만 12로 나누는 방식으로 구현했어요.

// src/domain/calculations.ts (일부)
function getYearlyAmount(subscription: Subscription): number {
  return subscription.billingCycle === "MONTHLY"
    ? subscription.amount * 12
    : subscription.amount;
}

/** 현재 월평균 지출 (ACTIVE + REVIEW) */
export function getMonthlyTotal(subscriptions: Subscription[]): number {
  return getYearlyTotal(subscriptions) / 12;
}

/** 연간 예상 지출 (ACTIVE + REVIEW) */
export function getYearlyTotal(subscriptions: Subscription[]): number {
  return sumYearly(subscriptions.filter(isCounted));
}

덕분에 "연 10,000원짜리 구독 3개"의 월평균이 2,499원(각각 반올림)이 아니라 정확히 2,500원으로 나와요. 이 경우도 테스트로 고정해 뒀어요.

STEP 3. 화면 3개 + 하단 탭 + 뒤로가기 처리 TDS 컴포넌트(ListRow, TextField, SegmentedControl, ConfirmDialog, FixedBottomCTA 등)를 썼어요. Claude Code가 TDS 공식 문서와 설치된 패키지의 타입 정의 파일을 직접 읽어 가며 props를 맞췄어요. 안드로이드 백버튼은 앱인토스 공식 이벤트 graniteEvent의 backEvent로 받아서, 입력 중일 때 "변경사항을 저장하지 않고 나갈까요?"를 물어보게 했어요.

STEP 4. 저장소 지시서에 "localStorage를 믿지 말라"고 써 두었더니, 공식 문서를 뒤져 앱인토스 SDK의 Storage API(앱을 다시 실행해도 유지)를 찾아 썼어요. 데이터가 손상됐을 때 빈 목록으로 덮어쓰지 않도록 코드 차원에서 막은 부분이 마음에 들었어요.

// src/storage/LocalSubscriptionRepository.ts (일부)
/*
 * 읽은 데이터가 손상됐어도 빈 목록으로 대체하지 않고 오류를 던진다.
 * 호출하는 쪽이 저장을 막아 기존 데이터를 덮어쓰지 않게 하기 위해서다.
 */
async load(): Promise<Subscription[]> {
  let raw: string | null;
  try {
    raw = await this.store.getItem(STORAGE_KEY); // "subscription-diet:v1"
  } catch (error) {
    throw new StorageError("UNAVAILABLE", error);
  }
  if (raw === null) return []; // 첫 실행
  // JSON 파싱 → 버전 확인 → 각 구독 런타임 검증 …
}

STEP 5. 실제 브라우저에서 시나리오 검증 + 문서화 자동 테스트만으로는 불안해서, Claude Code가 Windows의 Edge를 headless로 띄우고 실제 브라우저에서 사용자 시나리오 31단계(등록 → 새로고침 후 유지 → 해지 고려 → 해지 완료 → 미저장 경고)를 자동으로 실행했어요. 이 과정에서 '구독 삭제' 버튼이 화면 밖으로 넘치는 버그를 찾아 고쳤어요. 마지막으로 README.md와 DEVELOPMENT_REPORT.md까지 작성했어요.

결과 화면

아래 이미지는 사례글-이미지/ 폴더에 있어요. (로컬 개발 서버, 모바일 390×844 화면 기준. 오른쪽 아래 AIT 버튼은 개발용 도구이고, 실제 빌드에는 포함되지 않아요.)

빈 홈

홈(합계)

구독 등록

입력 오류

구독 정리

해지 안내

미저장 경고

한국 은행 계좌 스크린샷
한국어 텍스트가 포함된 한국어 앱 스크린샷

결과와 배운 점

결과

항목

결과

화면

홈 / 등록·수정 / 구독 정리 3개 + 하단 탭

자동 테스트

99개 전부 통과 (계산 15, 입력 검증 35, 상태 16, 저장 19, 화면 흐름 14)

검증용 숫자

51,800원 / 621,600원 / 9,900원 / 118,800원 / 41,900원 모두 일치

타입 검사·린트·빌드

모두 통과, 앱 번들 subscription-diet.ait 생성

실제 브라우저 시나리오

31단계 통과

토스 앱 실기기 테스트

아직 (콘솔 등록·업로드 필요)

제가 채팅창에 입력한 건 사실상 "초기 세팅해줘"와 "응" 네 번이 전부였어요. 대신 개발지시서를 쓰는 데 시간을 들였어요.

배운 점과 나만의 꿀팁

  1. "무엇을 만들지 않을지"를 쓰면 결과물이 깔끔해져요. 만들지 않을 기능 목록을 줬더니 AI가 범위를 넘는 기능을 하나도 추가하지 않았어요.

  2. 기대 결과 숫자를 주면 AI가 스스로 검증해요. 계산 검증용 데이터와 정답을 지시서에 넣었더니, 단위 테스트·화면 테스트·실제 브라우저 확인에서 같은 숫자를 반복해서 대조했어요.

  3. "추측 금지 + 확인 못 한 것은 따로 보고"는 꼭 넣으세요. 덕분에 매 단계 보고에 "확인한 것 / 확인하지 못한 것"이 분리돼 왔어요. "토스 앱에서는 아직 테스트하지 않았다"는 사실도 끝까지 성공으로 포장하지 않았어요.

  4. 단계별 승인 방식이 좋았어요. 한 번에 다 만들게 하는 것보다, 단계마다 보고를 읽고 "응"을 누르는 편이 무슨 일이 일어나는지 이해하기 훨씬 쉬웠어요.

  5. 공식 문서의 llms-full.txt를 활용하세요. 앱인토스 개발자센터와 TDS 문서 모두 AI가 읽기 좋은 전문 텍스트를 제공해요. 덕분에 최신 API(Storage, graniteEvent)를 정확히 찾아 썼어요.

과정 중에 겪은 시행착오

  • appName 규칙 위반: 폴더 이름에 toss가 있어서 공식 생성 도구가 거부했어요. 이름을 바꿔 생성한 뒤 옮겨서 해결했어요.

  • 문서와 실제 도구의 차이: 문서 예시는 granite.config.ts인데, 최신 생성 도구(SDK 3.x)는 apps-in-toss.config.ts를 만들어요. "문서보다 실제 설치된 버전을 우선한다"는 원칙대로 생성된 쪽을 유지했어요.

  • 샌드박스 앱이 없음: 지시서에는 "샌드박스 테스트"라고 썼는데, 공식 문서를 확인해 보니 SDK 3.x는 샌드박스 앱을 제공하지 않고, 로컬 브라우저(AIT DevTools)에서 개발한 뒤 콘솔에 업로드해서 토스 앱으로 테스트하는 방식이었어요.

  • 테스트 환경(jsdom)과 TDS의 충돌: 다이얼로그가 닫힌 뒤에도 화면이 잠기는 문제, 라우터의 AbortSignal 오류 등이 있었어요. Claude Code가 원인을 하나씩 추적해서 테스트 설정에서만 보정했고, 앱 코드는 건드리지 않았어요.

  • 접근성 문제 발견: TDS 입력칸이 스크린리더에 라벨 대신 placeholder를 읽히고 있었어요. 테스트가 실패한 덕분에 발견했고, aria-label을 지정해 고쳤어요.

  • 화면 확인 문제: 처음에는 headless 브라우저가 아무것도 출력하지 않아 화면을 못 봤어요. 브라우저를 원격 제어하는 방식으로 바꾸자 실제 화면 캡처와 시나리오 검증이 가능해졌어요.

도움이 필요한 부분

  • 앱인토스 콘솔에서 미니앱을 등록하고 토스 앱 실기기에서 테스트하는 과정은 아직 해보지 않았어요. 특히 아래 내용을 경험해 보신 분의 조언을 듣고 싶어요.

    • SDK Storage가 실제로 앱 재실행 후에도 잘 유지되는지

    • iOS Safe Area나 키보드 때문에 하단 버튼이 가려지지 않는지

  • 번들 크기가 약 1.39MB(대부분 TDS)인데, 토스 앱에서 첫 로딩 속도가 괜찮을지 궁금해요.

앞으로의 계획

  1. 앱인토스 콘솔에 등록하고 QR 코드로 토스 앱에서 실기기 테스트하기

  2. 출시 체크리스트 점검 후 검수 요청하기

  3. 저장 데이터가 손상됐을 때를 위한 "데이터 초기화" 기능 추가 여부 결정하기

  4. 실제 사용 반응을 보고 다음 버전 기능(예: 결제일 알림)을 검토하기

3

함께 이야기해요 3

로그인하고 댓글을 남겨 주세요

백경_BK 프로필 이미지
백경_BK2026.10.15

김코딩님, 개발지시서 한 장으로 MVP를 만드는 전략이 깔끔해요.

테스트가 실패한 덕분에 입력칸이 placeholder만 읽히는 접근성 문제를 찾아낸 대목이 특히 인상 깊었어요. 회원가입, 서버, 광고 없이 가볍게 가려는 방향도 '구독 다이어트'와 잘 맞는 것 같아요! ㅎㅎ!!

근데 엄청 깔끔하게 정리해주셔서 저도 공부가 많이 되네요!! 공유해주셔서 감사합니다!

은
은쌤T2026.10.15

만들지 않을 기능을 적어 줬더니 AI가 범위를 넘는 기능을 하나도 안 붙였다는 내용이 인상적입니다.

도움 요청하신 iOS 화면 쪽은, 저는 아이폰 실기기에서 제목이 내비게이션 바에 가려진 적이 있었는데 viewport-fit=cover를 빼고 해결했어요. 실기기 테스트하실 때 한번 같이 봐 주세요.

폴더 이름에 toss가 들어가면 생성 도구가 거부한다는 건 몰랐네요. 출시하시면, 저도 유용하게 잘 쓰겠습니다. 구독료 다이어트.. ㅎㅎ

뽀짝이 프로필 이미지
뽀짝이2026.10.15

김코딩님, 안녕하세요. 채팅창에 입력한 건 "초기 세팅해줘"와 "응" 네 번인데, 그 뒤에 개발지시서가 있었다는 점이 이 글의 핵심이라고 느꼈어요.

"만들지 않을 기능 목록"을 먼저 못 박았더니 AI가 범위를 넘는 기능을 하나도 안 붙였다는 점, 그리고 51,800원 / 621,600원 같은 기대 숫자를 줬더니 단위 테스트부터 실제 브라우저 31단계까지 같은 숫자를 계속 대조했다는 점이 특히 설득력 있었어요. 토스 앱 실기기 테스트는 아직 안 했다는 사실을 끝까지 성공으로 포장하지 않은 것도 믿음이 갔어요.

시행착오 중에는 샌드박스 앱이 SDK 3.x에는 없다는 걸 공식 문서로 확인해 고친 부분과, 테스트가 실패한 덕에 placeholder만 읽히던 접근성 문제를 aria-label로 잡은 부분이 재밌었어요 👀 실기기에서 Storage 유지와 Safe Area 결과가 나오면 후속 글도 기대할게요.

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기