> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/ai-vibe-coding/intro.md).
# 미니앱 만들기
"이런 앱이 있었으면 좋겠다"는 아이디어만 있어도 충분해요. 코드를 몰라도 AI에게 원하는 내용을 말로 설명하면, AI가 대신 코드를 작성해 줘요.
이 문서는 Claude Code, Codex 같은 AI 도구와 대화하면서 아이디어를 실제로 동작하는 앱인토스 미니앱으로 만드는 전체 과정을, 처음부터 끝까지 순서대로 안내해요.
{% hint style="info" %}
**이런 분께 도움이 돼요**
* 코딩을 전혀 해본 적 없는 분
* 앱 아이디어는 있지만 어떻게 시작해야 할지 모르는 분
* AI의 도움을 받아 빠르게 미니앱을 만들어 보고 싶은 분
{% endhint %}
이미 웹 프로젝트가 있다면 기존 [Web 프로젝트 개발 가이드](/ai-vibe-coding/tutorials/webview.md)를, React Native로 개발하고 싶다면 [React Native 개발 가이드](/ai-vibe-coding/tutorials/react-native.md)를 참고해 주세요.
***
### 1. AI 도구 설치하기
앱을 대신 만들어 줄 AI 도구를 먼저 설치하고, 개발에 필요한 기본 환경을 준비해요.
사용할 MCP 클라이언트에 맞는 단계를 따라 진행해 주세요.
이미 사용 중인 AI 도구가 있다면 이 단계는 건너뛰어도 괜찮아요.
{% tabs %}
{% tab title="Claude Code" icon="claude" %}
Claude Code는 터미널에서 사용하는 AI 개발 도구예요. \
먼저 내 컴퓨터에서 `claude` 명령어를 사용할 수 있는지 확인해 주세요.
**macOS**
1. 키보드에서 `Command(⌘) + Space`를 눌러 Spotlight 검색을 열어요.
2. `터미널`을 입력하고 Enter를 눌러요.
3. 터미널 창이 열리면 아래 명령어를 입력하고 Enter를 눌러요.
```bash
claude
```
**Windows**
1. 시작 메뉴에서 `PowerShell`을 검색해 열어요.
2. PowerShell 창이 열리면 아래 명령어를 입력하고 Enter를 눌러요.
```powershell
claude
```
Claude Code가 실행되면 로그인까지 완료해 주세요.
`claude`를 찾을 수 없다는 메시지가 나오면 [Claude Code 설치 가이드](https://code.claude.com/docs/en/quickstart)를 열고 사용 중인 운영체제에 맞게 Claude Code CLI를 설치해 주세요. \
설치가 끝나면 터미널이나 PowerShell을 새로 열고 다시 `claude`를 실행해 주세요.
{% endtab %}
{% tab title="Codex" icon="openai" %}
Codex는 ChatGPT 데스크톱 앱에서 사용할 수 있어요.
[ChatGPT 앱 다운로드 페이지](https://chatgpt.com/download/)에서 사용 중인 운영체제(macOS·Windows)에 맞는 설치 파일을 내려받아 설치해 주세요.
설치가 끝나면 ChatGPT 앱을 실행하고 로그인해 주세요. \
왼쪽 위의 `ChatGPT` 버튼을 눌러 `Codex`를 선택해 주세요.
{% embed url="" %}
{% endtab %}
{% endtabs %}
***
### 2. 앱인토스 개발을 위한 플러그인 연결하기
AI가 앱인토스 문서를 찾아보고, 미니앱을 만들고, 콘솔에 등록할 수 있도록 `apps-in-toss` 플러그인을 설치해요.
#### 2-1. Git 설치하기
플러그인을 설치하기 전에 Git이 필요해요. 먼저 사용 중인 운영체제에 맞게 Git을 설치해 주세요.
{% tabs %}
{% tab title="macOS" %}
[Git macOS 다운로드 페이지](https://git-scm.com/downloads/mac)를 열고 안내에 따라 설치해 주세요.
macOS에서는 Git이 포함된 Xcode Command Line Tools만 설치하면 돼요.
1. 키보드에서 `Command(⌘) + Space`를 눌러 Spotlight 검색을 열어요.
2. `터미널`을 입력하고 Enter를 눌러요.
3. 터미널 창이 열리면 아래 명령어를 붙여넣고 Enter를 눌러요.
```bash
xcode-select --install
```
4. 설치 창이 뜨면 안내에 따라 설치를 완료해 주세요.
5. 설치가 끝나면 사용 중인 AI 도구를 껐다가 다시 켜 주세요.
{% endtab %}
{% tab title="Windows" %}
[Git for Windows 다운로드 페이지](https://git-scm.com/downloads/win)를 열고 설치 파일을 내려받아 실행해 주세요.
대부분의 Windows PC에서는 아래 항목을 선택하면 돼요.
`Git for Windows/x64 Setup`
ARM 기반 Windows 기기를 쓰는 경우에만 아래 항목을 선택해요.
`Git for Windows/ARM64 Setup`
설치가 끝나면 사용 중인 AI 도구를 껐다가 다시 켜 주세요.
{% endtab %}
{% endtabs %}
설치가 잘 되었는지 확인하고 싶거나 중간에 막힌다면, Claude Code나 Codex에 아래처럼 요청해 보세요.
```
Git이 설치되어 있는지 확인해줘.
설치가 안 되어 있다면 내가 따라 할 수 있게 도와줘.
```
#### 2-2. apps-in-toss 플러그인 설치하기
사용 중인 MCP 클라이언트에 맞는 단계를 따라 `apps-in-toss` 플러그인을 설치해 주세요.
{% tabs %}
{% tab title="Codex" icon="openai" %}
Codex에서는 ChatGPT 데스크톱 앱의 Plugins 화면에서 `apps-in-toss` 플러그인을 설치해요.
{% embed url="" %}
1. ChatGPT 데스크톱 앱을 열어요.
2. 왼쪽 위의 `ChatGPT` 버튼을 눌러 `Codex`로 전환해요.
3. Codex 화면에서 Plugins 설정을 열어요.
4. Marketplace 추가 버튼을 클릭해요.
5. 화면의 `출처`에 `toss/apps-in-toss-harness` 를 입력해 추가해요.
6. Personal(개인) 탭에 새로 추가된 `apps-in-toss` 플러그인을 설치해요.
7. `apps-in-toss-console` 로그인을 완료해요.
8. `/ait:welcome` 을 입력해요.
{% endtab %}
{% tab title="Claude Code" icon="claude" %}
Claude Code에서는 Claude CLI로 플러그인을 설치해요.
먼저 macOS에서는 터미널, Windows에서는 PowerShell을 열고 `claude`를 입력해 Claude Code가 실행되는지 확인해 주세요.
```bash
claude
```
`claude` 명령어가 인식되지 않으면 [Claude Code 설치 가이드](https://code.claude.com/docs/en/quickstart)에서 Claude Code CLI를 설치한 뒤 다시 진행해 주세요.
Claude Code가 준비되었다면 아래 명령어를 순서대로 실행해 주세요.
{% embed url="" %}
```bash
claude plugin marketplace add toss/apps-in-toss-harness
claude plugin install ait@apps-in-toss -y
claude
```
Claude 대화 안에서 `/mcp`를 입력해 `apps-in-toss-console` 에 로그인 해주세요.
`/ait:welcome` 을 입력하여 플러그인 설치가 잘 되었는지 확인해요.
{% endtab %}
{% endtabs %}
***
### 3. 개발하기
이제부터는 복잡한 명령어를 외우지 않아도 돼요. 만들고 싶은 앱, 넣고 싶은 기능, 테스트하고 싶은 상황을 AI에게 말로 요청하면 돼요.
{% hint style="info" %}
**이런 순서로 진행해요**
1. 만들고 싶은 앱을 설명해요.
2. AI가 앱 구조와 필요한 기능을 정리해요.
3. 미니앱을 만들고 코드를 준비해요.
4. 필요한 기능을 하나씩 추가해요.
5. 내 휴대폰의 토스 앱에서 테스트해요.
6. 문제가 있으면 캡처와 함께 다시 고쳐 달라고 해요.
7. 준비가 끝나면 검수를 요청해요.
{% endhint %}
#### 3-1. 기획하기
만들고 싶은 미니앱 아이디어를 AI에게 설명해 보세요. 아래처럼 요청하면 AI가 앱인토스 정책에 맞는지 확인해 주고, 필요한 화면과 기능을 정리해서 제안해 줘요.\
제안이 마음에 들면 그대로 진행하고, 원하는 방향과 다르면 다시 요청해서 다듬어도 돼요.
```
[만들고 싶은 앱 설명]을 만들고 싶어.
1. 앱인토스 오픈 정책에 맞는 아이디어인지 확인해줘.
2. 어떤 화면과 기능이 필요할지 정리해줘.
3. 개발하면서 앱인토스 가이드에 어긋나는 부분이 있으면 미리 알려줘.
```
#### 3-2. 미니앱 만들기
앱인토스에 미니앱을 등록하고, 코드가 담길 공간까지 함께 만들어져요. 아래처럼 요청해 보세요.\
`{미니앱이름}` 자리에는 원하는 이름을 자유롭게 지어서 넣어 주세요.
```
{미니앱이름} 이름으로 앱인토스 미니앱을 만들어줘.
```
#### 3-3. 원하는 기능 요청하기
이제 AI에게 원하는 기능을 하나씩 요청할 차례예요.\
어떤 기능이 필요한지 말만 하면 AI가 앱인토스 문서를 확인하면서 만들어 줘요.\
앱인토스에서 제공하는 [기능 문서](https://developers-apps-in-toss.toss.im/documentation/)를 참고해도 좋아요.
```
토스 로그인을 이용해서 사용자를 구분하고 싶어.
사용자별로 닉네임과 점수를 저장해줘.
메인 화면 하단에 배너 광고를 넣어줘.
결제가 필요한 아이템을 살 수 있게 해줘.
현재 위치를 기준으로 가까운 매장을 보여줘.
즐겨찾기한 항목을 저장해줘.
```
{% hint style="info" %}
**AI에게 잘 요청하는 방법**
* 최대한 구체적으로 말해요
* "버튼 만들어줘" 보다 "화면 중앙에 시작하기 버튼을 만들고, 누르면 보상형 광고가 나오게 해줘"처럼 말하면 더 정확해요.
* 한 번에 완벽하지 않아도 괜찮아요
* 마음에 안 드는 부분이 있으면 "이 부분은 이렇게 바꿔줘"처럼 편하게 다시 요청하면 돼요.
{% endhint %}
미니앱을 만드는 모습을 영상으로 확인해요
{% embed url="" %}
#### 3-4. 외부 저장소 서비스 연동하기
미니앱에서는 [Storage API](broken://spaces/pKzGxtCGPMEzZAbz7TSP/pages/bP6r4B11x05DL7f8lkSv)를 사용해 데이터를 저장할 수 있어요. 다만 이 데이터는 사용자의 기기 환경에 저장되기 때문에, 기기를 변경하거나 앱 데이터가 초기화되면 사라질 수 있어요.
사용자가 남긴 게시글, 찜한 상품 목록, 저장한 닉네임처럼 다른 기기에서도 다시 확인해야 하거나 장기간 보관해야 하는 데이터가 있다면 외부 저장소 서비스를 연결해 주세요.\
기기 변경 후에도 유지해야 하는 데이터가 없다면 이 단계는 건너뛰어도 괜찮아요.
외부 저장소로는 Supabase, Firebase, Cloudflare 같은 서비스를 사용할 수 있어요.\
무료로 시작할 수 있는 구간이 있지만, 사용량이 늘어나거나 유료 기능을 사용하면 비용이 발생할 수 있어요.\
실제 적용 전에는 각 서비스의 최신 요금제, 제한 사항, 미니앱 연동 가능 여부를 확인해 주세요.
* [Supabase](https://supabase.com/): PostgreSQL 기반의 데이터베이스를 제공하는 백엔드 서비스예요. 게시글, 사용자 설정, 찜 목록처럼 구조화된 데이터를 저장할 때 사용할 수 있어요.
* [Firebase](https://firebase.google.com/?hl=ko): Google이 제공하는 백엔드 서비스예요. Firestore나 Realtime Database를 사용해 앱에서 필요한 데이터를 외부에 저장할 수 있어요.
* [Cloudflare](https://www.cloudflare.com/ko-kr/): 응답 속도가 빠른 인프라 서비스를 제공해요. Workers KV, D1, R2 등을 사용해 비교적 가벼운 데이터나 파일을 저장하는 용도로 사용할 수 있어요
{% hint style="warning" %}
**보안 설정을 확인해 주세요**
외부 저장소는 기본적으로 아무나 데이터에 접근할 수 있는 상태인 경우가 많아요.
AI에게 "보안 설정도 확인해줘"라고 요청하면 안전하게 설정하는 방법을 안내해 줘요.
서비스 대시보드에서 직접 실행해야 하는 부분도 있으니, AI가 안내하는 대로 따라가 주세요.
{% endhint %}
***
### 4. 테스트하고 출시하기
미니앱은 다 만든 뒤에만 테스트할 수 있는 게 아니에요. 개발하는 중간중간 화면이 궁금할 때마다 언제든 틈틈이 테스트해 봐도 괜찮아요.
#### 4-1. 토스앱으로 테스트하기
미니앱을 내 휴대폰의 토스 앱에서 테스트할 수 있어요. 아래처럼 요청해 보세요. AI가 테스트할 수 있는 상태로 준비해 주고, 휴대폰에서 열 수 있는 방법을 안내해 줘요.
```
만든 미니앱을 내 휴대폰의 토스 앱에서 확인해보고 싶어.
테스트할 수 있게 푸시 메시지를 보내줘.
```
테스트할 때 필요한 조건
* 토스 앱에 로그인되어 있어야 해요.
* 워크스페이스 멤버여야 해요.
* 만 19세 이상이어야 해요.
에러나 이상한 화면이 보이면 캡처해서 AI에게 보여주세요. AI는 실제 기기 화면을 볼 수 없어서, 캡처와 함께 설명하면 더 정확하게 고쳐줘요.
```
이 화면에서 결제 버튼을 눌렀는데 아무 반응이 없어.
캡처를 보고 원인을 찾아서 고쳐줘.
```
원하는 대로 안 되면 "이 부분은 이렇게 바꿔줘"처럼 편하게 다시 요청하세요. 수정한 뒤 다시 테스트하면 돼요. (예: "메인 화면 배너 광고를 조금 더 아래로 내려줘")
에러를 미리 예방하고 싶다면 Sentry 연동하기를 요청해 보세요.\
에러가 났을 때 AI가 로그를 직접 확인할 수 있어서, 원인을 더 빠르고 정확하게 찾아줘요.
토스앱에서 테스트하는 모습을 영상으로 확인해요
{% embed url="" %}
#### 4-2. 출시하기
미니앱을 출시하려면 먼저 앱인토스팀의 검수를 통과해야 해요.\
검수는 미니앱이 정책과 가이드를 잘 지켰는지 확인하는 절차예요. 테스트가 끝나면 검수를 요청해 보세요.
```
미니앱을 출시하고 싶어. 검수를 요청해줘.
```
검수 결과는 콘솔과 이메일로 안내해드려요.\
검수가 승인되면 콘솔의 '출시하기' 버튼을 눌러야 미니앱이 사용자에게 공개돼요.\
출시하면 1시간 후에 토스 미니앱 리스트에 바로 반영돼요.
앱을 만든 뒤에는 사용자에게 다가가기 위해 [마케팅 가이드](https://appsintoss.gitbook.io/appsintoss-docs/guide/marketing)도 함께 참고해 보세요.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://developers-apps-in-toss.toss.im/ai-vibe-coding/intro.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
