토스 미니앱 심사 통과를 위한 Claude Code 가이드

토스 미니앱은 코드가 돌아가도 심사에서 떨어지면 끝 입니다. 그런데 AI 코딩 도구는 코드가 돌아가면 "완료"라고 말합니다. 이 간극을 메우는 가장 쉬운 방법이 Superpowers였습니다. Superpowers가 하는 일은 하나입니다. AI가 "완료"라고 말하기 전에 증거를 내놓게 하는 것. 그 증거 자리에 토스 심사 규칙을 넣으면, 반려 방지가 사람의 기억이 아니라 작업 순서 안에 들어갑니다.

우리 컴퓨터에서 실제로 이 방식으로 만든 미니앱 1개(수면 관리 앱 "꿀잠 도우미", 지금 이름은 "모닝스타")의 기록으로 설명하겠습니다.

바쁘시면 이것만:

• Superpowers는 AI에게 "설계서 → 작업 계획서 → 실행 → 검사" 순서를 강제하는 Claude Code 플러그인입니다. 건설 현장의 "설계도 없이 공사 금지"와 같습니다.
• 토스 미니앱에서는 이 순서의 처음과 끝에 심사 규칙을 넣습니다. 설계서에 심사 규칙 5줄 → 작업 계획서의 첫 작업이 "반려 방지 세팅", 마지막 작업이 "심사 규칙 자동 검사".
• 그 결과 완료 보고가 이렇게 바뀝니다. "다 됐어요" → 11개 기능 harness-validate 통과
• 7개월 뒤 오늘 다시 검사해 보니 테스트 7개 전부 통과, 심사 규칙 5개 중 4개 통과. 1개는 계획서가 낡아서 생긴 착시였습니다.

이런 분께 도움이 되는 가이드

• Claude Code로 앱인토스 미니앱을 만드는데, 기능은 되는데 심사에서 반려된 적이 있는 분
• AI가 질문도 없이 코드부터 쏟아내는 게 불안한 분
• 미니앱을 여러 개 만들면서 매번 같은 반려 규칙을 AI에게 다시 설명하는 분

반려 규칙의 문제점

앱인토스 심사에는 일반 웹에 없는 규칙이 있습니다. 대표적인 다섯 가지입니다.

1. 화면을 손가락으로 확대(핀치줌)할 수 없게 할 것
2. 앱을 켜자마자 토스 로그인을 띄우지 말 것 (소개 화면 먼저)
3. 앱 안에 자체 뒤로가기 버튼·헤더를 만들지 말 것 (토스가 제공하는 것만 사용)
4. 토스 기능(SDK)은 "토스 앱 안에서 실행 중인지" 확인하고 부를 것
5. 앱 이름을 모든 위치에서 똑같이 쓸 것

이 다섯 가지의 공통점은 어겨도 빌드 에러가 나지 않는다 는 겁니다. 코드는 멀쩡히 돌아가고, AI는 "완료"라고 말하고, 반려는 며칠 뒤 사람이 받습니다.

사용 도구 소개

• Superpowers — Claude Code 플러그인. 설치는 /plugin install superpowers@claude-plugins-official 한 줄.
• harness 스킬 2개 — 앱인토스용으로 우리가 만든 것. harness-init은 반려 방지 설정 파일을 만들고, harness-validate는 심사 규칙을 자동으로 검사합니다.
• 대상 앱 — 꿀잠 도우미(모닝스타). 수면 점수 + 기상 미션 + 포인트 리워드.

Superpowers의 4단계와 토스에서의 차이점

Superpowers는 명령어 3개(/brainstorm, /write-plan, /execute-plan)와 자동으로 켜지는 규칙 14개로 되어 있습니다. 복잡해 보이지만 결국 4단계입니다. 각 단계에서 토스 미니앱이라서 달라지는 점 만 짚겠습니다.

1단계: 설계서 작성

/brainstorm을 치면 AI는 코드를 쓰는 대신 질문을 합니다. "이 앱을 쓰는 순간이 언제인가요?" 같은 질문을 하나씩 던지고, 합의되면 설계서를 씁니다.

토스에서 달라지는 점: 설계서에 "심사 준수 사항" 섹션을 따로 둡니다. 꿀잠 도우미 설계서는 223줄인데, 그중 §8이 이것입니다. 코드는 한 줄도 없고 5줄뿐입니다.

123456## 8. 앱인토스 심사 준수 사항
- 핀치줌 금지 viewport 메타태그 필수
- 앱 시작 시 appLogin() 즉시 호출 금지 → 인트로 화면 먼저
- 자체 헤더/백버튼 구현 금지 → 네비게이션바만 사용
- 앱명 "토스 꿀잠 도우미" — 모든 위치 동일 적용
- 브랜드 컬러 결정 필요

이 5줄이 중요한 이유는 다음 단계에서 그대로 작업과 검사 항목이 되기 때문 입니다.

2단계: 작업 계획서 작성

/write-plan은 설계서를 "작업 계획서"로 바꿉니다. Superpowers의 원칙은 이 계획서를 "판단력 없는 신입도 그대로 따라 할 수 있게" 쓰라는 것입니다. 어떤 파일을, 어떤 내용으로, 어떻게 확인하는지까지 전부 적습니다.

꿀잠 도우미 계획서는 2,461줄, 작업(Task) 12개입니다. 구조를 보면 토스 미니앱용 계획서의 모양이 보입니다.

• Task 1: 반려 방지 세팅 — 설정 파일, 핀치줌 금지 태그, 기능 목록 파일. 기능보다 먼저 만듭니다.
• Task 2~11: 실제 기능 (로그인, 기상 미션, 기록, 리워드, 내 정보)
• Task 12: 심사 규칙 자동 검사 + 마무리

Task 12는 사람이 눈으로 보는 체크리스트가 아닙니다. 검사 명령과 기대 결과가 적혀 있습니다. 예를 들어 "앱 시작 직후 로그인 금지" 규칙은 이렇게 검사합니다.

검사: 코드 전체에서 appLogin이 어디서 불리는지 찾는다
기대: 로그인 버튼을 눌렀을 때 실행되는 함수 안에서만 나와야 한다
     앱 시작 파일에서 직접 불리면 → 반려 대상

"반려 대상"이라는 말이 계획서에 적혀 있다는 게 핵심입니다. 이 작업을 맡은 AI는 토스 심사 가이드를 읽은 적이 없지만, 이 한 줄로 왜 검사하는지 압니다.

3단계: 실행

/execute-plan은 작업 하나마다 새 AI(서브에이전트)를 띄워 맡깁니다. 작업이 끝나면 검토를 두 번 합니다. 먼저 "설계서대로 했나", 그다음 "코드 품질은 괜찮나".

토스에서 달라지는 점: 첫 번째 검토의 기준이 곧 설계서 §8 입니다. 품질 검토와 섞으면 검토자가 코드 구조를 지적하느라 "소개 화면 전에 로그인이 뜨는가"를 놓칩니다. 그래서 둘을 분리합니다.

실행 중에는 "테스트 먼저" 규칙도 적용됩니다. 다만 토스 기능은 토스 앱 안에서만 돌아가서 컴퓨터에서 테스트할 수 없습니다. 그래서 실제 기록에서는 토스와 상관없이 틀릴 수 있는 계산 (수면 점수 계산식, 기상 미션 수학 퍼즐)에만 테스트를 먼저 썼고, 토스 기능 호출부는 Task 12의 자동 검사로 감쌌습니다. 테스트 파일 3개, 테스트 7개가 지금도 남아 있습니다.

4단계: 완료 선언

Superpowers의 가장 강한 규칙입니다. "방금 실행한 검사 결과 없이 완료라고 말하지 마라." 꿀잠 도우미 계획서는 마지막 단계에서 커밋 메시지(저장 기록에 남기는 한 줄 설명)까지 지정했고, 실제 기록에 그대로 남았습니다.

2026-03-11  feat: 토스 꿀잠 도우미 전체 구현 완료 — 11개 기능 harness-validate 통과

"완료"가 아니라 "11개 기능 / 심사 검사 / 통과"입니다. 숫자와 검사 이름이 들어 있어서 나중에 누구든 다시 확인할 수 있습니다.

실제 사례 세 가지

1) 빠른 개발과 심사 통과

3월 10일 밤 11시에 브레인스토밍을 시작해 같은 날 설계서와 계획서가 나왔고, 다음 날 11일에 기능 커밋 7건과 완료 커밋이 찍혔습니다. 기능 목록 파일에는 11개 기능이 전부 "통과"로 기록되어 있습니다. 빨랐던 이유는 AI가 똑똑해서가 아니라, 계획서가 AI에게 판단할 거리를 남기지 않았기 때문입니다.

2) 계획서의 유효성 재검토

이 글을 쓰면서 저에게도 같은 규칙을 적용했습니다. 2026년 10월 20일, 계획서 Task 12의 검사를 지금 코드에 다시 돌렸습니다.

• 테스트 7개: 전부 통과
• 핀치줌 금지: 있음
• 앱 시작 직후 로그인 금지: 지킴. 소개 화면 파일 맨 위에 "앱 시작 직후 로그인 호출 금지"라는 주석까지 남아 있음
• 브라우저 기본 팝업(alert) 사용: 없음
• 토스 기능 직접 불러오기: 없음
• 앱 이름 일치: 계획서의 기대값 "토스 꿀잠 도우미"와 다름

마지막 항목이 처음엔 규칙 위반처럼 보였습니다. 그런데 기록을 보니 9월 9일에 토스 SDK 3.x로 업그레이드하면서 설정 파일 이름이 바뀌었고, 앱 이름도 "모닝스타"로 바뀌어 있었습니다. 설정 파일과 화면 제목은 서로 일치 합니다. 즉 "모든 위치에서 같은 이름" 규칙은 지켜지고 있고, 계획서에 적힌 기대값만 3월 시점 것이었습니다.

여기서 배운 것 두 가지입니다.

• 계획서는 그날의 결정 기록 이지 현재 상태 문서가 아닙니다. Superpowers도 계획서 파일명에 날짜를 넣어 보관하라고 합니다.
• 검사의 기대값은 "앱 이름 = 토스 꿀잠 도우미"처럼 고정 문자열이 아니라 "설정 파일 이름 = 화면 제목"처럼 관계로 적어야 업그레이드를 견딥니다.

3) 사람 확인이 필요한 검사

토스포인트 교환 기능은 실제 토스 서버 인증서가 필요합니다. 작업 기록을 보면 AI는 인증서 파일이 제대로 읽히는지까지만 검사하고, 실제 프로모션 코드 입력과 교환 테스트는 "다음 단계(사용자)" 로 넘겼습니다. 할 수 없는 검사를 "했다"고 적지 않는 것도 같은 규칙의 일부입니다.

2

출처

• 원문: https://www.gpters.org/nocode/post/toss-mini-app-development-f1jvFjF78CZxNgW (2026-10-19 · 벤쿠버쪼)