ChatGPT 앱을 만들며 배운 15가지

Alpic에서는 차세대 제품과 서비스가 AI 중심의 사용자 경험을 바탕으로 만들어질 것이라고 봅니다. 이런 인터페이스에서는 사용자가 미리 정해진 UI 워크플로우를 따라가는 대신 모델과 협력해 원하는 일을 해냅니다.

OpenAI가 Apps SDK를 공개하자마자 저희는 이 SDK로 앱을 만들기 시작했습니다. 3개월 동안 내부에서 쓸 앱부터 여행, 소매, SaaS 분야의 B2B 및 B2C 고객을 위한 앱까지 총 24개의 ChatGPT 앱을 개발했습니다.

초기에 깨달은 점은 ChatGPT 앱 개발이 기존 웹 앱이나 모바일 앱 개발과 근본적으로 다르다는 사실이었습니다. 필요한 순간에 데이터를 가져오거나 UI에서 상태를 관리하거나 사용자가 직접 옵션을 설정하는 등 웹에서 잘 통하던 패턴이 에이전트 환경에서는 제대로 작동하지 않거나 오히려 사용 경험을 해치는 경우가 많았습니다.

이 글에서는 실제로 쓰이는 ChatGPT 앱을 만들며 배운 가장 중요한 교훈 15가지를 추려 소개합니다. 이어서 개발자가 앱을 구상하고 개발하고 테스트해 출시하기까지 걸리는 시간을 크게 줄일 수 있도록, 그 교훈을 커뮤니티용 오픈 소스 프레임워크 Skybridge와 Codex 스킬에 어떻게 담았는지 살펴봅니다.

삼체 문제

기존 웹 앱에서는 구도가 단순했습니다. 사용자와 UI만 고려하면 됐습니다. ChatGPT 앱에는 세 번째 주체인 모델이 등장합니다.

ChatGPT 앱을 만들 때 가장 어려운 일 중 하나는 이 세 주체 사이의 정보 흐름을 관리하는 것입니다. 사용자가 위젯에서 ‘선택’ 버튼을 누르면 화면은 바뀝니다. 하지만 그 컨텍스트를 명시적으로 전달하지 않으면 대화를 이끄는 모델은 무엇이 바뀌었는지 모릅니다. 이어서 사용자가 “이 상품에 대해 좀 더 알려 줘”라고 해도 모델은 사용자가 어떤 상품을 보고 있는지 알 길이 없습니다.

저희는 각 주체가 시스템의 일부만 알고 어느 누구도 전체 상황을 파악하지 못하는 현상을 컨텍스트 비대칭이라고 부릅니다. 좋은 ChatGPT 앱을 만들려면 모든 정보를 동기화하려 하기보다 어떤 정보를 공유할지, 언제 공유할지, 누가 그 정보를 알아야 하는지 결정해야 합니다. 이 문제를 어떻게 풀어내느냐에 따라 앱이 사용하기 번거로워질 수도, 사용자와 에이전트가 자연스럽게 협력할 수도 있습니다.

1. 모든 컨텍스트를 공유할 필요는 없습니다

처음에는 ‘일단 모든 정보를 모든 곳에 공유하자’고 생각했습니다. 초기에 저지른 실수 중 하나였습니다.

실제로는 같은 상태라도 ChatGPT 앱의 각 구성 요소에 의도적으로 서로 다른 정보가 보이도록 해야 할 때가 많습니다. 이유는 두 가지입니다.

• 성능: UI 위젯에는 모델에 필요한 양보다 훨씬 많은 데이터가 필요한 경우가 많습니다. 여행 예약 앱이라면 이미지, 가격 베리언트, 미리 불러온 예약 옵션 등이 여기에 해당합니다. 이를 전부 모델에 보내면 토큰 사용량과 지연 시간이 늘고 모델이 판단에 불필요한 정보까지 처리하게 됩니다.
• 앱 로직: 일부 정보는 설계상 특정 주체만 알아야 합니다. 초기에 만든 Murder in the Valleys 추리 게임에서는 모델이 역할에 맞게 행동하려면 범인이 누구인지 알아야 하지만, UI와 사용자에게는 범인을 숨겨야 합니다. Time’s Up 방식의 게임에서는 반대입니다. UI에는 사용자가 볼 수 있도록 정답 단어를 표시하고 모델에는 숨겨야 합니다.

여기서 배운 점은 항상 모든 정보를 동기화하라는 것이 아니라 누가 무엇을 알아야 하는지 명확히 정하라는 것이었습니다. 저희는 도구 출력 필드를 구분해 이 원칙을 구현했습니다.

예를 들어 Time’s Up 게임에서는 _meta 필드로 위젯에만 정답 단어를 전달했습니다. 덕분에 모델은 사용자가 주는 힌트를 바탕으로 단어를 맞힐 수 있었습니다.

2. AI 앱에서는 지연 로딩의 이점이 작습니다

웹 개발에 익숙했던 저희는 자연스럽게 지연 로딩을 택했습니다. 사용자가 클릭할 때 데이터를 가져오고 상세 정보는 요청이 들어올 때 불러와 처음에 전송하는 데이터양을 최소화했습니다.

ChatGPT에서는 상황이 반대입니다. 도구를 호출하면 보안 샌드박스와 모델 추론 때문에 응답을 받기까지 몇 초씩 걸릴 때가 많습니다.

앱을 만들면서 데이터를 최대한 미리 전달하는 방법을 익혔습니다. 첫 도구 응답에 가능한 한 많은 데이터를 담고 window.openai.toolOutput 값을 사용해 위젯의 초기 데이터를 채웠습니다. 거의 모든 경우에 앱이 더 빨라졌고 사용자 조작에도 더 즉각적으로 반응했습니다.

물론 위젯이 공개 API 엔드포인트에서 안전하게 데이터를 가져올 수 있고 그 정보를 모델과 공유할 필요가 없다면, 위젯 안에서 기존 방식대로 XHR을 호출해도 됩니다. 다만 대부분의 경우 대화가 자연스럽게 이어지려면 모델이 스스로 도구를 호출할 수 있어야 합니다.

3. 모델도 사용자가 보는 화면을 알아야 합니다

사용자가 위젯에서 목록에 있는 특정 상품을 선택한 뒤 채팅에서 질문하는 상황을 생각해 보세요. 여기서 눈에 잘 띄지 않지만 중요한 문제가 생깁니다. 사용자가 UI의 어느 부분을 가리키는지 모델이 모르면 정확히 답할 수 없습니다.

이를 해결하기 위해 window.openai.setWidgetState(state)를 사용했습니다. 이 함수로 특정 상태 데이터를 저장하면 다음번에 사용자가 모델과 대화할 때 해당 데이터가 모델의 컨텍스트에 추가됩니다.

앱이 복잡해지면서 모델이 사용자의 화면 이동을 따라갈 수 있도록 여러 곳에 setWidgetState를 추가하게 됐습니다. 그래서 UI 컨텍스트를 선언적으로 기술하는 방식을 도입했습니다. 사용자가 조작할 때마다 명령형 코드로 모델에 변경 사항을 전달하는 대신 컴포넌트에 data-llm 속성을 직접 붙입니다.

1
2
3
4
5
6
7
8
9<div
  data-llm={
    selectedTab === "details"
      ? "User is viewing product details"
      : "User is viewing reviews"
  }
>
  Product details
</div>

이 방식이 내부적으로 작동하도록 해당 속성을 읽어 widgetState를 자동으로 업데이트하는 Vite 플러그인을 만들었습니다. 개발자가 사용자 조작을 일일이 동기화하지 않아도 모델은 필요한 순간에 관련 UI 컨텍스트를 받습니다.

커뮤니티와 개발 경험을 공유하기 위해 만든 오픈 소스 프레임워크에서 이 Vite 플러그인과 이 글에서 소개하는 여러 기법을 확인할 수 있습니다.

4. 상호작용의 종류에 따라 필요한 API가 다릅니다

ChatGPT 앱에서 위젯, 서버, 모델은 여러 경로로 상호작용합니다. 각 경로는 서로 다른 종류의 상호작용을 지원하므로 다른 경로로 대체할 수 없습니다.

ChatGPT 앱을 만들며 배운 중요한 교훈 중 하나는 이러한 통신 경로를 명확하게 구분하고 사용자 경험의 각 부분을 어떤 경로로 처리할지 결정해야 한다는 점입니다.

통신 경로를 그림으로 나타내면 다음과 같습니다.

지금까지 살펴본 내용은 ChatGPT 앱 설계의 기초입니다. 컨텍스트를 어떻게 공유하는지, 모델이 사용자의 화면 상태를 어떻게 파악하는지, 서로 다른 상호작용이 시스템 안에서 어떻게 전달되는지 살펴봤습니다. 다음으로 이런 특성이 UI 설계에 어떤 영향을 미치는지 알아보겠습니다.

AI에 맞게 UI 다시 설계하기

ChatGPT 앱은 완전히 새로운 환경입니다. 저희는 UI에 대한 고정관념을 내려놓아야 이 환경의 새로운 기능을 충분히 활용할 수 있다는 사실을 금세 깨달았습니다. 효과적인 앱을 만들기 위해 인터페이스 설계에서 어떤 점을 새로 익혀야 했고 어떤 기존 가정을 버려야 했는지 살펴보겠습니다.

5. UI는 여러 표시 모드와 각 모드의 제약에 맞춰야 합니다

ChatGPT 앱의 레이아웃은 하나로 고정되지 않습니다. 같은 위젯도 언제 어떻게 호출하느냐에 따라 세 가지 모드로 표시될 수 있습니다.

앱은 대화 안에 인라인으로 표시하거나 대화 위에 화면 속 화면(PiP)으로 띄울 수 있습니다. 더 넓은 공간이 필요하면 전체 화면으로 표시할 수도 있습니다. PiP와 전체 화면에서는 더 풍부한 인터페이스를 구성할 수 있지만, 위젯이 제어할 수 없는 UI 요소가 위에 겹쳐 표시되기도 합니다. 콘텐츠가 잘리지 않고 사용자가 편하게 조작할 수 있도록 기기별 안전 영역을 고려해야 합니다. 예를 들어 모바일에서는 항상 표시되는 닫기 버튼의 자리를 비워 둬야 합니다.

여러 앱을 만들면서 각 표시 모드가 어떤 상황에 적합한지 알게 됐습니다.

6. 다른 인터페이스 안에 들어가는 UI는 일관성이 중요합니다

초기에 고민했던 문제 중 하나는 ChatGPT 앱의 시각적 디자인을 어디까지 자유롭게 바꿔도 되는지였습니다. 사용자에게 새로운 인터페이스인 만큼 저희가 만든 앱끼리도 일관성이 있어야 하고, 주변의 ChatGPT 인터페이스와도 잘 어우러져 익숙하게 느껴져야 했습니다. 독립형 제품과 달리 위젯은 기존 인터페이스 안에 표시되므로 시각적으로 어긋나는 부분이 바로 눈에 띕니다.

다행히 OpenAI Apps SDK UI Kit가 명확한 기준이 되어 주었습니다.

이 키트는 Tailwind CSS를 기반으로 하며 ChatGPT 디자인 시스템에 맞는 컴포넌트, 아이콘, 디자인 토큰을 바로 쓸 수 있도록 제공합니다. 덕분에 Mapbox 연동처럼 맞춤형 컴포넌트가 필요한 경우에도 빠르게 개발할 수 있었습니다. 이렇게 만든 위젯은 주변 UI와 시각적으로 어우러져 ChatGPT의 일부처럼 자연스럽게 보였습니다.

7. 자연어로 조건 지정하기

기존 대시보드에서는 사이드바에 체크박스와 범위 슬라이더를 채워 넣습니다. 에이전트 UI에서는 이런 방식이 오히려 사용성을 떨어뜨릴 때가 많습니다. 사용자가 “200달러 미만으로 갈 수 있는 유럽 여행지 중 날씨가 맑은 곳을 찾아 줘”처럼 원하는 조건을 자연어로 바로 말할 수 있는데 여러 UI 컨트롤을 일일이 조작하게 하면 번거롭습니다. 원하는 것을 말하는 것만으로 충분해야 합니다.

그래서 저희는 대부분의 앱에서 ‘필터 없는 UI’를 택했습니다. 필터와 정렬 옵션이 있는 사이드바 대신 도구 매개변수에 사용할 수 있는 값 목록(LOV)을 모델에 제공합니다.

그러면 모델은 사용 가능한 옵션을 추측할 필요 없이 사용자 메시지를 그대로 입력으로 받을 수 있습니다. 즉, 자연어 표현을 백엔드 API가 요구하는 값에 직접 대응시킬 수 있습니다. 사용자가 “맑은 날씨”라고 하면 모델은 weather=“sunny”로 도구를 호출해야 한다는 것을 압니다.

8. 파일을 활용하면 상호작용의 폭이 넓어집니다

더 복잡한 앱을 만들면서 파일을 보조 입력으로만 취급해서는 안 된다는 점을 배웠습니다. ChatGPT 앱에서는 파일 덕분에 새로운 상호작용이 가능해집니다. 양식을 작성하거나 필터를 선택하는 대신 사용자가 이미 가진 자료에서 시작할 수 있습니다.

예를 들어 전자상거래 앱에서는 사용자가 채팅에 상품 사진을 올리면 모델이 상품을 식별하고, 사용자는 위젯에서 바로 일치하는 상품을 찾거나 다른 상품을 둘러볼 수 있습니다.

이런 경험이 가능한 이유는 모델과 UI 양쪽에서 파일을 처리할 수 있기 때문입니다. 모델 쪽에서는 도구가 openai/fileParams로 채팅에 업로드된 파일을 직접 입력받을 수 있어 모델이 이미지나 사용자가 제공한 다른 자료를 바탕으로 추론할 수 있습니다. UI 쪽에서도 위젯이 window.openai.uploadFile과 window.openai.getFileDownloadUrl을 사용해 파일을 직접 다룰 수 있습니다. 따라서 UI 플로우 안에서 파일 업로드를 요청하거나 사용자가 다운로드해 재사용할 파일을 생성할 수 있습니다.

프로덕션으로 전환하기

앱이 로컬 개발 단계를 벗어나면 보안, 설정, 개발 도구 측면에서 새로 고려해야 할 문제가 생깁니다. 세 번째로 살펴볼 교훈은 이 단계에서 배운 것들입니다.

9. CORS만큼 신경 써야 하는 CSP

OpenAI는 보안을 위해 두 겹으로 중첩된 iframe 안에서 앱을 렌더링합니다. 콘텐츠 보안 정책(CSP)은 iframe 격리에 쓰이는 기본 메커니즘입니다. 이 환경에서는 CSP를 엄격하게 적용하기 때문에 흔히 말하는 ‘로컬에서는 되는데 프로덕션에서는 안 되는’ 문제가 자주 발생합니다.

기존 웹 개발에서는 정책을 느슨하게 설정해도 작동하는 경우가 있지만, Apps SDK에서는 허용 범위를 정밀하게 지정해야 합니다.

앱 매니페스트에서는 상호작용 유형별로 어떤 도메인을 허용할지 꼼꼼하게 선언해야 합니다.

처음부터 CSP 설정을 주요 개발 과제로 다룬 덕분에 나중에 프로덕션에서 디버깅하는 시간을 크게 줄였습니다.

10. 작은 위젯 플래그가 앱 동작을 크게 바꿉니다

CSP 외에도 몇 가지 위젯 설정이 위젯, 모델, 호스트 환경이 각각 무엇을 제어하는지 결정합니다. 놓치기 쉬운 플래그지만 화면 이동, 도구 접근, 앱 게시에 중요한 기준이 됩니다.

호스트와 화면 이동 범위

• widgetDomain 설정은 앱 제출 시 필수입니다. 전체 화면 모드에서 ‘<App>에서 열기’ 버튼이 기본적으로 연결되는 위치를 정합니다. 위젯은 <widgetDomain>.web-sandbox.oaiusercontent.com 아래에서 렌더링되므로 허용할 출처를 정할 때도 이 값을 사용합니다. 저희는 setOpenInAppUrl을 사용해 컨텍스트에 맞는 경로로 사용자를 안내했습니다.

모델의 도구 접근 범위

• 도구 어노테이션은 게시 가이드라인을 따라야 합니다. readOnly, destructiveHint, openWorldHint 등의 플래그는 필수이며 제출 과정에서 검증됩니다.
• 도구 공개 범위도 중요합니다. 모델이 호출해서는 안 되는 도구는 명시적으로 비공개로 표시해야 합니다.

위젯 실행 범위

• widgetAccessible 설정은 위젯이 callTool을 사용해 직접 도구를 호출할 수 있는지 결정합니다.

각각은 작은 설정이지만 게시한 앱이 의도대로 작동하려면 이 설정들이 함께 맞아야 합니다.

빠른 반복 개발을 위한 최적화

Apps SDK는 빠르게 발전하고 있으며, 저희도 그 변화에 발맞춰 앱을 만드는 과정이 즐거웠습니다. 개발 워크플로우를 원활하고 효율적으로 운영하기 위해 자체 오픈 소스 프레임워크를 만들어 커뮤니티와 공유하기로 했습니다. 초기에 겪은 개발상의 어려움을 피하는 데 도움이 될 만한 교훈을 소개합니다.

11. 빠르게 반복 개발하려면 핫 리로드가 필요합니다

가장 먼저 해결하려 한 문제 중 하나는 반복 개발 속도였습니다. 리소스 캐시의 TTL이 길고 리소스를 JSON-RPC로 전달하기 때문에 Vite나 Next.js에서 쓰는 표준 핫 모듈 리로드는 기본 상태로는 ChatGPT 앱과 호환되지 않습니다.

Vite의 내부 구조를 파악하는 데 상당한 시간을 들인 끝에 ChatGPT 안에서 위젯을 실시간으로 다시 불러오는 Vite 플러그인을 만들었습니다. 이 플러그인은 MCP 서버로 향하는 리소스 요청을 가로채고 ChatGPT iframe에 변경 사항을 실시간으로 반영합니다. IDE에서 코드를 수정하자마자 ChatGPT에서 결과를 확인할 수 있어 피드백을 받기까지 걸리는 시간이 크게 줄었습니다.

12. 모든 테스트를 ChatGPT에서 실행할 필요는 없습니다

가장 확실한 방법은 ChatGPT에서 직접 테스트하는 것이지만, 초기에는 로컬 에뮬레이터를 쓰면 개발 속도를 높일 수 있습니다. 특히 도구 정의를 수정할 때마다 ChatGPT에서 맞춤형 MCP 서버 연결을 새로고침해야 하는 경우에 효과적입니다.

초기 반복 개발을 빠르게 진행하기 위해 ChatGPT 호스트 환경을 모방하고 디버깅 도구와 앱 전용 로그를 제공하는 경량 로컬 에뮬레이터를 만들었습니다. 덕분에 React 상태와 레이아웃 변경 결과는 밀리초 단위로 확인하고, 모델과의 상호작용이나 예외 상황은 실제 ChatGPT에서 검증할 수 있었습니다.

13. 모바일 테스트에는 별도 지원이 필요합니다

모바일 테스트에는 또 다른 문제가 있었습니다. ChatGPT에서 테스트하려면 로컬 서버에 터널을 연결해야 하는데, Vite는 기본적으로 로컬호스트를 사용하기 때문에 다른 기기에서는 같은 URL에 접속할 수 없습니다.

이를 해결하기 위해 터널이 연결된 포트에서 도메인 포워딩을 지원하도록 Vite 플러그인을 확장했습니다. 덕분에 iOS와 Android 기기 모두에서 테스트할 수 있게 되었고 모바일 검증도 일상적인 개발 워크플로우에 포함할 수 있었습니다.

14. React 훅처럼 익숙한 추상화를 쓰면 프론트엔드 개발이 빨라집니다

Apps SDK는 강력한 기능을 제공하지만 대부분 저수준 JavaScript API를 통해 노출합니다. React를 오래 사용해 온 저희는 이미 익숙한 개념으로 이 기능들을 다루고 싶었습니다.

그래서 React에 잘 맞는 추상화를 도입했습니다. useCallTool, useWidgetState, useLocale 같은 훅을 만들고, 복잡한 데이터 플로우에는 Zustand 기반의 createStore 같은 고급 상태 관리 기능을 마련했습니다. 익숙한 프론트엔드 패턴을 다시 활용하면서 반복해서 작성하는 코드가 줄고 위젯 개발 방식도 현대적인 웹 개발 워크플로우에 가까워졌습니다.

배운 내용을 Codex 스킬에 담기

15. 배운 내용을 재사용 가능한 도구로 만드세요

여러 앱에서 같은 패턴이 나타나면서 매번 같은 해결책을 다시 찾아내느라 개발이 느려진다는 점이 분명해졌습니다. 저희 팀과 커뮤니티 모두가 ChatGPT 앱을 더 빠르게 개발하고 개발 과정을 더 잘 예측할 수 있도록 그동안 배운 내용을 개발 도구에 직접 반영하기로 했습니다.

그 결과 서로 보완하는 두 가지 도구가 탄생했습니다.

1. Skybridge 프레임워크: 이 오픈 소스 React 프레임워크에는 이 글에서 소개한 여러 패턴이 재사용 가능한 구성 요소로 담겨 있습니다. 저희가 만든 훅(useCallTool, useToolInfo), 개발 도구(HMR과 로컬 에뮬레이터), data-llm 속성 등이 포함됩니다.
2. chatgpt-apps-builder Codex 스킬: 이 프레임워크를 바탕으로 앱의 전체 수명 주기를 지원하는 전용 Codex 스킬을 만들었습니다.
   • 아이디어 구상: 기존 웹 앱을 단순히 옮기는 데 그치지 않고 에이전트가 주도적으로 동작하는 앱을 만들 방법을 함께 구상합니다.
   • 코드 생성: 적절한 UX와 UI 패턴을 미리 적용한 React 프론트엔드와 MCP 서버 백엔드를 동시에 작성합니다.
   • 로컬 테스트: 개발 서버를 시작하고 로컬 앱을 ChatGPT에 연결해 핫 리로드로 변경 사항을 실시간으로 확인하며 개발합니다.
   • QA 및 게시: OpenAI의 제출 가이드라인에 따라 CSP 검증, 안전 영역 확인, 프로덕션 테스트 등을 체계적으로 수행합니다.
   • 앱 배포: 앱을 출시하고 이후에도 계속 개선하는 데 필요한 마지막 단계를 지원합니다.

스킬을 설치해 사용하려면 다음 명령어를 실행하세요.

npx skills add alpic-ai/skybridge

마치며

ChatGPT 앱을 만들려면 컨텍스트가 전달되는 방식, 인터페이스가 동작하는 방식, 사용자와 모델이 협력하는 방식을 다시 생각해야 합니다. 이 글에서 소개한 교훈 중 상당수는 익숙한 웹 개발 패턴을 에이전트 시스템에 적용하면서 차이를 발견한 데서 나왔습니다.

저희가 배운 내용을 공유하고 오픈 소스 프레임워크와 Codex 스킬에 담은 것이 다른 팀에도 도움이 되기를 바랍니다. 같은 문제를 다시 파악하는 데 드는 시간을 줄이면 이 새로운 상호작용 방식으로 무엇을 할 수 있을지 더 깊이 탐색할 수 있습니다. 가장 매력적인 ChatGPT 앱은 기존 제품을 그대로 옮기는 데서 나오지 않을 것입니다. 처음부터 AI 중심의 새로운 사용자 경험을 염두에 두고 설계할 때 그런 앱을 만들 수 있습니다.