안녕하세요. 토스 Commerce Personalization Team에서 토스 쇼핑의 추천 시스템을 만들고 있는 ML Engineer 구국원입니다.

추천 시스템은 흔히 더 좋은 모델을 만드는 문제로 보입니다. 하지만 실제 서비스를 운영하다 보면 모델 바깥에도 성능을 좌우하는 중요한 결정이 많아요. 각 추천 모델에서 상품을 몇 개씩 가져올 것인지 정하는 TopK도 그중 하나입니다.

저희는 여러 리트리벌(Retrieval) 모델의 TopK를 경험적으로 정해 왔습니다. 새로운 리트리벌 모델이 생길 때마다 후보 수는 조금씩 늘었고, 어느새 랭커(Ranker)가 평가해야 할 상품과 광고 유효성 검사량도 함께 커졌어요. 그렇다고 모든 리트리벌 모델의 후보를 같은 비율로 줄이면 가치 있는 상품까지 잃을 수 있었습니다.

이 글에서는 이 문제를 조합 최적화 문제로 바꿔 풀고, 온라인 실험으로 검증한 과정을 소개할게요. 결론부터 말하면 전체 후보 수를 약 절반으로 줄이면서 User CVR(User Conversion Rate)은 7.55%, 사용자당 주문 수는 10.13% 높일 수 있었습니다.

TopK가 커질수록 추천이 좋아질까요?

토스 쇼핑의 추천 시스템은 크게 Retrieval, Ranking 단계로 이루어져 있어요.

TopK의 K는 각 리트리벌 모델이 다음 단계로 넘기는 상품 수예요. 예를 들어 구매 이력을 보는 모델에서 500개, 최근 클릭을 보는 모델에서 200개를 가져오면 두 모델의 TopK 합은 700개가 됩니다.

후보가 많으면 좋은 상품을 놓칠 가능성은 줄어듭니다. 하지만 공짜는 아니에요. Ranking 단계가 평가할 상품이 많아지고, 광고 상품의 유효성을 확인하는 비용도 늘어납니다. 따라서 피드를 만드는 데 총 소요 시간이 증가하여 응답 시간이 길어질 수 있고, 점수가 낮은 후보가 뒤 단계까지 살아남을 가능성도 커져요.

당시 TopK는 주로 각 모델을 담당하는 ML Engineer의 경험에 따라 정했습니다. 개별 모델만 보면 합리적인 값이어도 여러 리트리벌 모델의 후보를 합치면 전체 후보 수가 계속 커지는 구조였어요. 더 어려운 점은 모든 리트리벌 모델이 같은 가치를 만들지 않는다는 것이었습니다. 어떤 모델은 상위 수백 개까지 구매 가능성이 높지만, 다른 모델은 상위 몇십 개 이후 가치가 빠르게 낮아졌어요.

그래서 질문을 바꿨습니다.

모든 리트리벌 모델의 TopK를 똑같이 줄이지 않고, 전체 후보 수라는 예산 안에서 가치가 높은 모델에 더 많은 TopK를 배정할 수 없을까?

TopK 배정을 배낭 문제로 바꿔보기

이 문제는 배낭 문제(Knapsack Problem)와 닮았습니다. 무게 제한이 있는 배낭에 물건을 담되, 물건 가치의 합을 가장 크게 만드는 조합을 찾는 문제예요.

추천 시스템에 대입하면 이렇게 볼 수 있습니다.

가치가 높은 물건부터 차례로 넣는 탐욕적 방법만으로는 전체 최적 조합을 놓칠 수 있어요. 10kg 배낭에 9kg짜리 100점 물건 하나를 넣는 것보다 5kg짜리 60점 물건 두 개를 넣는 편이 더 좋은 것과 같습니다.

저희는 이 조합을 찾기 위해 정수계획법(Integer Programming)을 사용했습니다. 정수계획법은 선택 여부처럼 정수로 표현되는 결정을, 반드시 지켜야 할 조건 안에서 최적화하는 방법이에요. 세 가지 요소만 기억하면 됩니다.

수식으로는 다음처럼 표현할 수 있습니다.

여기서 x_{i,k}는 리트리벌 모델 i의 k번째 상품을 선택하면 1, 아니면 0인 값입니다. w_{i,k}는 그 상품의 예상 가치예요. 실제 실험군을 만들 때는 노출 이후 구매 가능성을 나타내는 pICVR(=pCTR * pCVR)을 선택했습니다.

제약 조건도 함께 넣었습니다.

세 번째 조건이 필요한 이유는 TopK가 ‘몇 위까지 가져올 것인가’를 뜻하기 때문이에요. 100번째 상품만 고르고 그보다 높은 순위의 상품을 버릴 수는 없습니다.

실제 로그로 모델별 가치 곡선 만들기

최적화에 넣을 가치는 추측으로 정하지 않았습니다. 실제 추천 로그를 바탕으로 다음 과정을 거쳤어요.

pICVR(Predicted ICVR)은 노출 후 구매까지 이어질 확률을 뜻합니다. 즉, 각 모델별 후보 상품이 창출할 것으로 기대되는 비즈니스 가치를 추정한 값이에요.

시뮬레이션 결과는 모델마다 달랐습니다. 기존 TopK를 그대로 유지하는 편이 좋은 리트리벌 모델도 있었고, 25%나 10% 수준까지 줄여도 전체 목적 함수에 미치는 영향이 작은 모델도 있었어요. 모든 리트리벌 모델의 TopK를 50%씩 줄이는 방식보다, 모델별 가치 곡선에 따라 다르게 배분해야 한다는 뜻이었습니다.

온라인에서 네 가지 방법 비교하기

오프라인 시뮬레이션이 좋아도 실제 사용자의 행동이 같으리라는 보장은 없습니다. 그래서 홈 피드에서 여러 실험군을 동시에 비교했어요.

실험은 7일 동안 진행했고 위너를 고르는 규칙도 결과를 보기 전에 정했습니다.

가장 높은 숫자보다 균형 잡힌 결과를 선택했어요

정수계획법 실험군은 비교군보다 전체 후보를 약 절반만 사용하면서 다음과 같은 변화를 보였습니다. 아래 수치는 모두 비교군 대비 상대 변화율입니다.

User CVR, Order PU의 p-value는 0.0001보다 작았습니다. p-value는 ‘실제로 차이가 없다고 가정했을 때, 우연히 이 정도 이상의 차이를 관측할 가능성’을 가늠하는 값이에요. 값이 작을수록 단순한 우연만으로 설명하기 어렵다는 뜻입니다.

흥미로운 점은 목표 지표가 가장 높았던 실험군이 따로 있었다는 것입니다. TopK를 1/4로 줄인 실험군은 User CVR이 8.89%, Order PU가 10.52% 증가했습니다. 하지만 RPU는 3.98%, AOV(Average Order Value)는 5.73% 감소했어요. 주문 수는 늘었지만 낮은 가격대의 상품에 구매가 치우쳤을 가능성이 있었습니다.

Maximum Coverage 실험군은 RPU가 2.05% 증가해 수익성 방어에는 더 유리했습니다. 반면 User CVR과 Order PU의 개선 폭은 정수계획법 실험군보다 작았습니다.

저희는 목표 지표, 수익성, 전환 효율을 함께 비교해 정수계획법 실험군을 최종 위너로 선택했습니다. 한 지표의 최고점을 고르는 대신, 제품이 만들고 싶은 전체 효용을 기준으로 결정한 셈이에요.

후보를 줄이는 데에도 비용이 있었습니다

좋은 결과만 있었던 것은 아닙니다. 정수계획법 실험군의 CTR은 3.71% 감소했고, 사용자당 고유 노출 상품 수도 22.07% 줄었습니다.

CTR이 낮아진 동시에 CVR이 높아졌다는 것은 어떻게 봐야 할까요? 후보를 줄이면서 클릭 기회 자체는 감소했지만, 남은 클릭이 구매로 이어지는 효율은 높아졌다고 해석할 수 있습니다. ‘많이 보여주기’보다 ‘구매 가능성이 높은 후보를 남기기’에 가까운 변화예요. 다만 이 결과만으로 인과관계를 단정할 수는 없습니다.

고유 노출 상품 수의 감소는 더 분명한 과제였습니다. 목적 함수가 예측 구매 가치에 집중하면 자주 좋은 점수를 받는 상품이 반복해서 선택될 수 있어요. 전환 효율을 높이는 것과 새로운 상품을 발견하게 하는 것은 서로 충돌할 수 있습니다.

그래서 후속 실험에서는 TopK를 유지한 채 Gumbel Weighted Sampling을 적용했습니다. 목표 지표를 유의하게 떨어뜨리지 않으면서 피드 중복도를 평균 11.25% 낮추고, 노출 상품 다양성을 4.61% 높였습니다. RPU도 2.30% 증가했습니다. 첫 실험에서 드러난 비용을 다음 실험의 목표로 바꾼 결과였어요.

Next Step: 사용자마다 다른 TopK

이번 프로젝트로 경험에 의존하던 TopK를 데이터 기반의 최적화 문제로 바꿀 수 있었습니다. 하지만 현재 방식은 여전히 모든 사용자에게 같은 모델별 TopK를 적용하는 Global K입니다.

사용자마다 필요한 후보의 구성은 다를 수 있어요. 구매와 클릭 이력이 충분한 사용자는 개인화 모델의 후보를 더 많이 활용할 수 있습니다. 반대로 이력이 거의 없는 사용자는 인기 상품 모델이나 탐색형 리트리벌 모델이 더 중요할 수 있어요. 최근 행동의 유무나 관심사의 선명도에 따라서도 적절한 배분은 달라질 겁니다.

앞으로는 다음 두 방향을 검토하고 있습니다.

• 동적으로 갱신되는 Global K: 최근 로그와 모델 성능을 반영해 모델별 TopK를 주기적으로 다시 계산합니다.
• 개인화된 TopK: 사용자의 이력량, 최근성, 상태에 따라 같은 전체 예산 안에서도 모델별 TopK를 다르게 배정합니다.

개인화된 TopK는 후보를 더 많이 가져오는 방식이 아닙니다. 사용자에게 필요한 리트리벌 모델에 후보 예산을 더 정확하게 쓰는 방식에 가까워요. 다만 예측 오차가 배정 결과로 이어질 수 있고, 신규 리트리벌 모델은 로그가 부족하다는 문제가 있습니다. 신규 리트리벌 모델을 실제 노출 없이 평가할 수 있는 Shadow Logging과, 다양성·중복도 지표를 함께 관리하는 체계가 필요한 이유입니다.

마치며

추천 시스템의 성능은 모델의 정확도만으로 결정되지 않습니다. 어떤 후보를 몇 개 가져오고, 어떤 지표를 최적화하며, 무엇을 안전장치로 둘지 같은 운영 결정도 사용자 경험과 비즈니스 성과를 크게 바꿉니다.

이번 프로젝트에서 얻은 가장 큰 교훈은 세 가지였습니다.

후보를 절반으로 줄이는 일은 단순한 비용 절감이 아니었습니다. 어떤 후보가 정말 가치 있는지 다시 정의하고, 추천 시스템이 쓰는 한정된 예산을 더 잘 배분하는 일이었어요. 이제는 이 배분을 사용자마다 다르게 만드는 다음 문제를 풀어보려 합니다.

안녕하세요, 토스뱅크 Visual Designer 고명은입니다. 오늘은 키워봐요 적금의 9가지 다람쥐 캐릭터와, 다람쥐가 돋보이는 화면을 만든 과정을 이야기해 보려고 해요.

매일 찾아와야 자라는 적금

키워봐요 적금은 캐릭터를 직접 키우면서 저금하는 적금이에요. 키우고 싶은 캐릭터를 정할 수 있고, 저금할 때마다 자라서 만기 때는 최종 형태로 진화하죠.

초기 버전은 가입만 하면 그 뒤로는 사용자가 앱에 오지 않아도 자동이체를 통해 캐릭터가 알아서 자랐어요. 시간이 지날수록 리텐션이 떨어졌죠. 매일 들여다볼 이유가 없으니, 가입한 뒤 점점 잊히는 적금이 된 거예요.

그래서 새로운 버전에서는 정반대로 설계하고자 했어요. 자동이체 없이 사용자가 직접 저금해야만 캐릭터와 이자가 자라도록요. 이 구조가 효과적이려면 두 가지가 필요했어요. 첫 번째, 캐릭터 자체가 매력적이어서 키우고 싶어야 할 것. 두 번째, 내가 직접 키우고 있다는 감각이 전달될 것. 저는 최종 진화 단계의 다람쥐 9마리와 이 다람쥐들을 키우는 화면을 만드는 일을 담당하게 됐어요.

101명의 연습생에서 9명의 데뷔조까지

짧은 시간 안에 최대한 많은 시안을 만들어보고 좋은 캐릭터를 찾아야 했기 때문에 AI를 적극적으로 활용했어요.

9마리가 저마다 다른 매력을 갖게 하고 싶었어요. 성공한 9인조 아이돌처럼, 누구에게 물어봐도 최애가 갈릴 만큼 멤버의 개성이 뚜렷하면서도 한데 모아놓으면 한 팀처럼 보이길 바랐죠.

그런데 이 다람쥐들은 단순히 9가지 캐릭터를 만드는 게 아니었어요. 31일 동안 쌓인 매력·지혜·힘 스탯에 따라 최종 모습이 결정되는 구조였거든요. 그래서 캐릭터를 먼저 그리기보다, 각 스탯이 쌓였을 때 어떤 성격과 매력을 가진 다람쥐가 나와야 할지부터 정했어요. 귀여운 애, 초현실적인 애, 강인한 애처럼 각자 어떤 개성을 가질지 정하고, 그에 맞춰 캐릭터의 콘셉트를 만들어갔어요.

예를 들어 지혜와 힘이 함께 쌓이면 똑똑하면서도 강인한 우주비행사로, 매력만 쌓이면 무대 위의 아이돌로 표현하는 식이었어요. 캐릭터마다 어떤 모습과 이야기를 가질지 정하고 나니, 프롬프트에 담아야 할 요소도 자연스럽게 정해졌어요. 표정과 의상, 소품부터 조명까지 모두 캐릭터의 설정에서 가져왔죠.

처음부터 잘 짜인 프롬프트가 있었던 건 아니에요. 노드 기반 AI 이미지 툴에서 여러 번 테스트하면서, 모든 캐릭터에 공통으로 들어가는 고정 문장과 캐릭터마다 바꿔 넣는 빈칸으로 나눈 뼈대를 만들었어요.

뼈대가 잡히자 속도가 확 빨라졌어요. 서핑 다람쥐를 아이돌 다람쥐로 바꾸고 싶으면 새 프롬프트를 쓸 필요 없이 빈칸만 갈아 끼우면 됐거든요. 처음에는 백 장을 뽑아야 쓸 만한 하나가 나왔다면, 나중에는 서른 장, 더 나중에는 두세 장만으로도 그럴싸한 다람쥐 연습생을 캐스팅할 수 있었어요.

AI가 만들어준 캐릭터는 바로 데뷔시킬 정도로 완성도가 높지는 않았어요.

캐릭터를 조금이라도 만져본 분이라면 아실 거예요. 표정의 작은 픽셀 하나, 캐릭터가 입은 옷과 손에 든 아이템 하나가 캐릭터의 인상을 크게 좌우해요.

게다가 이 다람쥐들은 손바닥만 한 앱 화면 한가운데에 작게 들어가요. 작게 들어가는 리소스일수록 디테일이 뭉개지기 쉽고, 뭉개진 디테일은 곧 뭉개진 인상이 돼요. 결국 이 작업은 처음부터 끝까지 디테일 싸움이었어요.

처음에는 좋은 부분들을 하나씩 얹으며 작업했어요. 질감과 장식, 소품을 겹겹이 쌓을수록 캐릭터는 화려해졌죠. 그런데 실제 앱 화면에 들어가는 크기로 줄여보면 오히려 인상이 흐려지는 경우가 많았어요. 요소들이 서로를 가려서, 뭉개지는 정도가 아니라 하나로 뭉쳐 보였거든요.

그래서 어느 순간부터 ‘무엇을 더 넣을지’보다 ‘무엇을 남길지’를 먼저 생각했어요.

작은 화면에서도 가장 먼저 보여야 하는 표정과 실루엣은 남기고, 캐릭터의 인상을 흐리는 장식이나 디테일은 덜어냈어요. 많이 넣는 것보다 작은 화면에서도 캐릭터의 매력이 선명하게 보이는 것이 더 중요했으니까요.

AI로 수많은 캐릭터를 빠르게 만들어볼 수 있었지만, 그중에서 무엇을 남기고 어떻게 다듬을지는 결국 디자이너가 판단해야 했어요.

다람쥐는 31일 동안 여러 단계를 거쳐 자라고, 마지막에야 아홉 가지 모습 중 하나로 진화해요. 최종 진화형은 혼자 존재하는 그림이 아니라, 이전 단계의 다람쥐에서 이어지는 마지막 장면이었던 거예요.

여기서 어려웠던 건 ‘내가 키우던 다람쥐’라는 느낌과 ‘드디어 진화했다’는 느낌을 동시에 만드는 것이었어요. 이전 단계와 너무 비슷하면 진화한 느낌이 없고, 너무 다르면 전혀 다른 캐릭터처럼 보이니까요.

그래서 몸의 비율과 귀, 꼬리, 일부 이목구비의 모양은 그대로 가져갔어요. 대신 피부색과 옷, 아이템처럼 캐릭터의 성격을 보여주는 요소는 크게 바꿨어요. 익숙한 형태는 이어가면서도, 31일 동안 키운 결과는 확실히 느껴지도록 한 거죠.

그렇게 디테일까지 다듬은 아홉 마리를 나란히 놓아봤어요. 한 팀으로 보이면서도 각자의 개성은 분명했어요. 팀에 공유했을 때도 다들 서로 다른 다람쥐를 최애로 꼽았고요.

그렇게 9명의 데뷔조가 확정됐어요.

캐릭터가 주인공인 무대 만들기

다람쥐가 완성됐다고 끝이 아니었어요. 일반적인 적금 화면에 다람쥐를 올려보니 캐릭터만 스티커처럼 붕 떠 보였어요. 반대로 게임처럼 배경의 밀도를 높이면 캐릭터에 집중하기 어렵고 화면이 오히려 올드해 보였고요.

기존의 UI 문법 위에 캐릭터만 얹어서는, 다람쥐가 주인공인 화면을 만들 수 없었어요. 다람쥐는 다람쥐대로, UI는 UI대로 따로 놀았죠.

그래서 이 적금만을 위한 작은 디자인 시스템과 UI 프로토타입을 새로 만들었어요. 진행 바와 선택 영역부터 레벨과 스탯을 보여주는 캐릭터 상태창까지, 캐릭터를 중심으로 화면의 구조와 디테일을 다시 잡았어요.

• 모은 돈은 가장 위에, 가장 크게

  게임처럼 보여도 이건 적금이에요. 그래서 계좌에 모인 금액은 화면 맨 위에 가장 큰 숫자로 뒀어요. 캐릭터를 키우다가도 눈을 들면 내가 모은 돈이 얼마나 되는지 바로 알 수 있게 했어요.

• 그림자로 공간감을 줬어요

  캐릭터가 허공에 떠 보이지 않도록 발밑에 그림자를 깔았어요. 말풍선에도 은은한 그림자를 넣어 영역을 구분하고, 화면에 깊이감을 더했어요.

• 상태창 하나에 필요한 정보를 담았어요

  레벨과 이름, 세 가지 스탯, 다음 진화까지 남은 날을 하나의 상태창에 묶었어요. 진행 바에는 발자국 아이콘을 넣어 다람쥐가 지금까지 걸어온 길처럼 읽히게 했고요.

• 선택지와 스탯을 같은 언어로 연결했어요

  설명을 읽지 않아도 ‘이걸 고르면 이 스탯이 오른다’는 걸 알 수 있도록, 선택지 옆의 매력·지혜·힘 아이콘과 상태창의 스탯 아이콘을 같은 모양으로 만들었어요.

캐릭터와 말풍선 사이의 간격, 스탯과 진행 바의 정렬도 픽셀 단위로 맞췄어요. 하나만 보면 티가 나지 않지만, 이런 요소가 조금씩 어긋나면 화면 전체가 조립한 것처럼 보이거든요.

캐릭터를 UI에 올려놓는 것이 아니라, UI 전체가 캐릭터를 하나의 주인공으로 만들어주는 것. 그게 이 화면을 만들면서 가장 중요하게 생각한 부분이었어요.

매일 찾아오게 만드는 인터랙션

무대 세팅까지 끝! 다음 단계는 다람쥐와 사용자 사이의 인터랙션을 설계하는 것이었어요.

다람쥐와 무대가 아무리 매력적이어도, 오늘 저금한 일이 별다른 경험으로 남지 않으면 금방 지루해질 수 있어요. 키우고 싶은 마음은 31일 뒤의 최종 모습이 아니라, 오늘 한 번의 저금에서도 생겨야 했어요. 그래서 선택지를 고르는 그 한 번의 탭에 화면 전체가 대답하도록 만들었어요.

단순히 캐릭터를 잘 만드는 데서 끝내지 않고, 이 캐릭터를 어떻게 보고, 키우고, 다시 만나게 할지까지 고민한 거예요.

탭하는 순간 저금액과 스탯 숫자가 함께 올라가요. 오늘 넣은 돈이 그대로 다람쥐의 성장으로 이어지는 걸 한눈에 볼 수 있게 했어요.

숫자만 변하는 것도 아니에요. 성장 단계마다 여러 가지 캐릭터 모션을 만들어, 저금할 때마다 다람쥐가 다르게 반응하도록 했어요. 내가 한 행동에 캐릭터가 바로 반응하니, 다람쥐와 함께 무언가를 쌓아가는 느낌이 들도록 한 거죠.

오늘의 보람만으로 매일 다시 들어올 이유를 만들기는 어려웠어요. 다음 진화까지 얼마나 남았는지도 보여줘야 했어요.

그래서 오늘의 대화를 마치면 다람쥐가 걸어가듯 발자국 아이콘이 진행 바를 채워요. 남은 날짜를 단순히 숫자로 보여주는 대신, 다람쥐가 다음 모습에 한 걸음씩 가까워지는 장면으로 표현했어요.

오늘 쌓인 저금액과 스탯은 오늘의 보람이 되고, 다음 진화에 가까워진 모습은 내일 다시 들어올 이유가 돼요.

매일의 저금이 통장에서 ‘빠져나간 돈’으로만 남는 게 아니라, 다람쥐와 함께 ‘쌓인 뿌듯함’으로 느껴졌으면 했어요.

적용해보기

키워봐요 적금을 만들면서 제가 계속 붙들었던 질문들이에요. 캐릭터를 중심으로 서비스를 만들고 있거나, 캐릭터의 매력을 화면과 인터랙션으로 어떻게 보여줄지 고민하고 있다면 이런 질문을 던져보세요.

• 캐릭터의 매력을 화면 전체에서 보여주고 있나요?

  캐릭터만 바꾸는 게 아니라, 주변의 UI도 캐릭터에 맞게 달라져야 화면 전체가 하나의 경험으로 읽혀요.

• 작은 화면에서 정말 남아야 할 것은 무엇인가요?

  좋은 요소를 계속 더하기보다, 작은 화면에서도 캐릭터의 인상을 가장 잘 보여주는 요소를 남기는 게 중요해요.

• 캐릭터와 사용자의 행동이 연결되어 있나요?

  사용자의 행동에 캐릭터가 바로 반응해야, 캐릭터를 보는 경험이 실제 행동과 자연스럽게 이어져요.

안녕하세요. 토스뱅크에서 주택담보대출을 디자인하고 있는 Product Designer 김혜미입니다. 이번 글에서는 전세대출 팀에서 AI 상담 서비스를 디자인했던 과정을 얘기해 보려고 해요.

정보는 충분했지만 확신은 없었다

전세대출 팀에서 하는 고민은 대체로 이런 거예요. 플로우를 어떻게 더 쉽게 설계할까, 어떻게 전환율을 높일까. 그런데 그것만으로는 해결하기 어려운 문제가 있었어요. 사용자가 화면을 다 이해하고도 여전히 불안해서 고객센터를 찾는 것이죠.

상담팀에서 사용자들이 서류를 제대로 제출하지 못해 심사가 자꾸 막힌다는 이야기를 전해주셨어요. 그때 처음으로 상담팀에 들어오는 문의 데이터를 직접 찾아봤어요. 데이터를 열어보니 서류 제출 방법뿐만 아니라 단순한 정보를 묻는 문의량이 유독 높았어요. 이런 문의가 상담 인력을 계속 붙잡다 보니, 정작 심사가 늦어지는 일까지 생기고 있었고요.

사실 이런 정보는 화면에 이미 쉽게 설명되어 있었어요. 그런데도 사용자는 화면에서 답을 찾지 못하고 결국 고객센터를 찾았던 거예요. 그 정보가 내 상황에도 맞는지 확신할 수 없었던 거죠.

그래서 상담으로 들어오는 단순 문의를 제품 안에서 해결할 방법을 찾아보기로 했어요.

설명은 멈추고 질문받기

화면에 있는 정보를 더 잘 보이게 만드는 것만으로는 문제를 해결하기 어렵다고 봤어요.

사용자는 답을 못 찾는 게 아니었어요. 화면에서 정보를 찾고, 내게 필요한 내용을 골라내고, 그 답이 정말 내 상황에 맞는지 판단하는 것까지 모두 사용자의 몫이었어요.

전세대출에서는 이런 과정이 특히 부담스러워요. 집을 구하는 데 필요한 큰돈이 걸려 있기 때문이에요. 조금이라도 확실하지 않으면 ‘아마 맞겠지’ 하고 넘어가기 어렵죠. 결국 사람에게 직접 확인하고 싶어져요.

그래서 방향을 바꿨어요. 화면이 먼저 설명하는 방식이 아니라, 사용자가 자기 말로 묻고 제품이 답하는 방식으로요.

상담원에게 묻는 것처럼, 사용자가 어떤 말로 질문하더라도 그 뜻을 이해하고 각자의 상황에 맞는 답을 해주는 게 목표였어요.

사용자들은 궁금한 건 비슷해도 제각각 말해요. 누군가는 “태아도 자녀로 쳐요?”라고 하고, 누군가는 “임신 중인데 부양가족에 들어가나요?”라고 물어요. 여기에 보증금 규모나 계약 형태, 신청 시점 같은 조건까지 달라지면 답도 달라지고요.

결국 사용자의 말을 이해하고, 상황에 맞는 답을 만들어내려면 AI가 필요했어요. 그래서 머신러닝 팀과 대출 운영팀에 프로젝트를 제안했고, 세 팀이 모여 AI 상담 서비스를 만들기 시작했어요.

디자이너인 저는 AI가 할 수 있는 것과 없는 것을 화면에 어떻게 풀어낼지 고민했어요. 대출 운영팀은 실제 상담에서 어떤 답을 해야 하는지 알려주었고, 머신러닝 팀은 그 답을 AI가 할 수 있도록 만들었어요.

사용자가 묻고 싶게 만들기

그렇게 AI를 출시하고, 상품 인트로 화면에 진입점을 놓았어요. "대출 신청하기 전, 궁금한 점 AI에게 물어보기"라는 배너였고, 누르면 빈 입력창이 열리는 구조였죠.

그런데 거의 아무도 누르지 않았어요. 상담 전화가 줄어드는 경향은 보였지만, 쓰는 사람 자체가 너무 적어서 효과를 확인할 수조차 없었어요.

저는 무엇을 물어야 할지 몰라서라고 봤어요. 빈 입력창만 덩그러니 있으면 무엇이든 물어볼 수 있지만, 반대로 어떤 질문부터 해야 할지는 사용자가 직접 정해야 하니까요. 이 AI가 어디까지 답해줄 수 있는지도 알기 어려웠을 거고요.

그래서 상담 문의 데이터를 다시 살펴봤어요. 사용자들이 실제로 무엇을 궁금해했는지 알 수 있었으니까요. 그리고 그 데이터를 바탕으로, 각 단계에서 사용자들이 가장 많이 물었던 질문을 진입점에 보여줬어요.

상품 인트로에서는 금리와 한도가 얼마인지, 법인 임대인도 대출이 되는지를 보여줬어요. 심사 대기 중에는 심사가 언제 끝나는지, 결과는 언제 나오는지를 보여줬고요.

그 결과 인트로 화면의 AI 사용률은 약 5배, 심사 대기 화면은 약 2배 올랐어요.

이 결과를 보면서, 사용자가 자기 말로 질문하게 하려면 먼저 어떤 질문을 할 수 있는지 보여줘야 한다는 걸 알게 됐어요. 다른 사람들이 실제로 물어본 질문을 보는 순간 “아, 이런 것도 물어봐도 되는구나” 하고 알게 되는 거죠. 그러고 나니 사용자들도 자기 상황을 덧붙여 자유롭게 질문하기 시작했어요.

미리 준비해 둔 문답만으로는 답하기 어려운 질문들이었어요. 사람마다 표현도, 상황도 달랐으니까요. 이렇게 예상하기 어려운 질문까지 받아낼 수 있다는 게 AI 상담의 장점이었어요.

정보보다 중요한 것

AI에 질문하고 적합한 답변을 받은 사용자는 그렇지 않은 경우보다 상담 전화로 이어지는 비율이 약 10%p 낮았어요. 상담 전화는 월 550건 줄었고, 통화 시간으로 환산하면 연 300시간이에요. 다른 대출 상품까지 적용하면 절감 규모가 지금의 열 배 이상으로 커질 것으로 보고 있고요.

이번 프로젝트를 하면서, 답을 보여주는 것과 확신을 주는 건 다른 일이라는 걸 알게 됐어요.

전세대출 화면에는 필요한 정보가 이미 있었어요. 그런데도 사용자는 전화를 걸었죠. 자기 상황에도 이 정보가 적용되는지 확신할 수 없었기 때문이에요.

그래서 화면을 설계할 때는 ‘무엇을 알려줘야 하지?’에서 끝나면 안 된다는 걸 배웠어요. 이 정보를 보고 있는 사용자가 지금 무엇을 걱정하고 있는지, 무엇을 확신하지 못하고 있는지까지 봐야 했어요. 그래야 어떤 정보와 기능이 정말 필요한지도 보이더라고요.

적용해보기

안녕하세요. 토스뱅크 Visual Designer 김현지입니다. 오늘은 자산관리 리포트 기능의 클릭률을 3배로 올리기까지의 과정, 그리고 그 안에서 얻은 러닝을 이야기해 보려고 해요.

유용한 추천인데 왜 누르지 않을까

자산관리 리포트는 사용자의 자산 상태를 분석해 알맞은 상품이나 서비스를 추천하는 기능이에요. 토스뱅크 홈의 입출금 영역 아래에 배너로 노출하고 있었는데, 클릭률이 2%에 그쳤어요.

내 상황을 보고 해주는 추천인데, 왜 눌러보지 않을까요? 여러 가설을 세워본 끝에, 토스뱅크 홈에는 정보가 많다 보니 주변 정보와 충분히 구분되지 않아 그냥 지나칠 수 있겠다고 생각했어요.

그래서 리포트가 눈에 잘 띄면서도, 내 상황에 맞는 개인화된 추천이라는 점이 한눈에 느껴지도록 디자인하는 것을 목표로 잡았어요.

표현을 바꿔도 화면은 여전히 복잡한 이유

먼저 표현 방식을 바꿔봤어요. 말을 건네듯 제안하는 말풍선 형태, 사용자의 자산 상태를 먼저 보여준 뒤, 그에 맞는 상품을 차례로 제안하는 방식도 만들어봤죠. 직접 말해주는 것처럼 표현하면 추천이 더 와닿을 것 같았어요.

그런데 화면은 여전히 복잡했어요. 저마다의 목적으로 찾아온 화면 사이에 읽을거리를 하나 더 얹는 구조는 달라지지 않았거든요.

문제는 계좌 정보와 추천이 같은 자리에서 시선을 나누고 있다는 것이었어요. 계좌는 사용자의 정보이고, 리포트는 저희가 새롭게 건네는 제안이에요. 역할이 다른 둘이 한데 섞여 있다 보니, 리포트도 계좌 정보를 훑어보는 과정에서 함께 지나치기 쉬웠어요.

그렇다고 리포트만 무작정 강조할 수도 없었어요. 계좌를 확인하려는 사람에게 리포트가 먼저 보이면, 정작 필요한 정보가 잘 보이지 않을 수 있었어요.

리포트를 발견하게 하면서도, 하려던 일을 방해하지 않는 방법을 찾아야 했어요. 그래서 리포트의 위치 자체를 다시 생각했어요. 계좌 정보와 한자리에서 경쟁하게 하는 대신, 아예 다른 자리에서 보여주면 어떨까 하고요.

툴팁에서 찾은 새로운 영역

떠올린 건 웹사이트에서 마우스를 올렸을 때 나타나는 툴팁이에요. 툴팁은 기존 화면을 가리지 않으면서, 필요한 정보를 그 위에 덧붙여 보여주잖아요.

이 구조를 모바일에도 가져왔어요. 계좌 정보가 있는 기본 화면은 그대로 두고, 자산 상태에 대한 제안은 그 위에 떠 있는 플로팅 카드로 분리했어요. 같은 화면 안에서도 계좌 정보와 추천이 서로 다른 층에 놓이도록 한 거예요.

하지만 화면에 없던 영역을 새로 띄우는 건 또 다른 문제를 만들 수 있었어요. 사용자가 원하지 않았는데 갑자기 나타나면, 정보가 아니라 방해물처럼 느껴질 수 있으니까요. 광고처럼 보이거나, 내용을 읽기도 전에 닫기 버튼부터 찾게 될 수도 있고요.

그래서 플로팅 카드가 사용자에게 자연스럽게 받아들여지려면 어떻게 해야 할지 하나씩 정해갔어요.

1 ) 내용이 먼저 보이는 첫인상 만들기

화면 위에 떠 있는 카드는 팝업 광고와 형태가 비슷했어요. 내용을 읽기도 전에 광고처럼 보일 수 있겠다는 걱정이 들었어요.

그래서 광고와 기능이 사용자에게 어떻게 다르게 보이는지 토스 안의 배너를 비교해 봤어요. 광고는 큼직한 그래픽과 눈에 띄는 컬러로 시선을 끌고 있었고, 기능은 텍스트와 버튼을 중심으로 정보의 위계로 내용을 전하고 있었어요.

리포트도 기능처럼 느껴지게 하려면 비주얼적 요소보다 내용이 먼저 보여야 한다고 생각했어요. 그래서 그래픽과 컬러를 덜어내고, 내용에 시선이 먼저 닿도록 했어요.

대신 디테일로 채웠어요. 모서리에는 코너 스무딩을 넣고, 반투명한 재질감을 더해 화면에 자연스럽게 어우러지도록 했어요. 버튼에는 미세한 그래디언트를 더해 밀도를 높였고요. 작은 디테일을 하나씩 쌓아 기능으로서의 완성도를 높여갔어요.

2 ) 스크롤 하면 작아지게

리포트를 발견한 뒤에도 계속 시선을 요구하면 부담스러울 수 있었어요. 사용자는 추천을 읽고 싶을 수도 있지만, 당장은 다른 정보를 먼저 보고 싶을 때도 있으니까요.

그래서 스크롤을 시작하면 리포트가 작아지도록 했어요. 사용자가 화면을 둘러보기 시작하면 자리를 내어주고, 다른 콘텐츠를 편하게 볼 수 있게 한 거죠. 작아진 카드는 궁금할 때 다시 열어볼 수 있는 진입점으로 남아요.

리포트가 얼마나 눈에 띌지를 한 가지 상태로 고정하지 않고, 사용자의 행동에 따라 달라지게 했어요.

3 ) 말을 건네듯 펼쳐지게

홈에 들어오면 리포트는 닫힌 상태에서 시작해 펼쳐져요. 화면이 먼저 보인 뒤 카드가 열리면, 지금 내 자산 상태를 보고 건네는 제안처럼 느껴질 것이라고 생각했어요. 열리고 닫히는 과정을 자연스럽게 보여주면서, 언제든 다시 닫을 수 있다는 것도 전하고 싶었고요.

그 느낌을 만들기 위해 움직임의 결도 여러 번 바꿔봤어요.

• 빠르게 나타나는 움직임: 카드가 툭 튀어나오는 느낌이라 부담스러웠어요.
• 느리고, 약한 반동이 있는 움직임: 부드럽지만 화면이 느리게 반응하는 것처럼 보였어요.
• 반동이 큰 움직임: 경쾌하지만 자산 정보를 보여주기에는 다소 산만했어요.

최종적으로는 빠르게 시작해 부드럽게 감속하고, 끝에 살짝 반동을 더한 이징을 골랐어요. 부드럽게 마무리해 부담을 덜고, 작은 반동으로 생기를 더했어요.

여기에 translate와 scale 모션의 시작점을 어긋나게 뒀어요. 두 모션이 동시에 시작되면 단순히 크기가 변하며 이동하는 것처럼 보이지만, 시작 시점을 조금 다르게 주면 곡선을 그리듯 움직이는 디테일을 만들 수 있어요.

문제를 푼 건 표현이 아닌 구조

기존 안, 인터랙티브 안, 플로팅 안으로 A/B 테스트를 진행했어요.

표현을 바꾼 인터랙티브 안은 CTR이 1.1배 오르는 데 그친 반면, 구조를 바꾼 플로팅 안은 CTR과 CVR이 모두 3배 올랐어요.

특히 눈여겨본 건 CVR이었어요. 클릭만 늘었다면 리포트가 눈에 잘 띄어서 눌린 것일 수 있어요. 하지만 클릭 이후의 행동까지 함께 늘었다는 건, 리포트를 발견하는 것뿐 아니라 실제 추천까지 이어지는 경험도 달라졌다는 뜻이니까요.

처음 세웠던 목표는 ‘나를 위한 제안’이라는 느낌을 주는 것이었어요. 결과적으로 단순히 표현을 바꾸는 것보다, 계좌 정보와 리포트의 역할을 분리한 구조가 이 목표에 더 가까운 결과를 만들었어요.

적용해보기

저는 이번 작업에서 처음엔 형태와 색, 표현을 바꾸는 데 집중했어요. 그런데 아무리 다듬어도 문제가 풀리지 않았죠. 익숙한 디자인 문법 안에서만 답을 찾고 있었던 거예요.

표현을 바꾸는 것만으로 해결되지 않는다면, 문제가 생기는 구조 자체를 다시 볼 필요가 있어요. 비슷한 고민을 하고 있다면, 이런 질문부터 던져보세요.

• 표현을 바꾸는 것만으로 정말 문제가 해결될까?
• 구조를 바꿔야 하는 문제는 아닐까?
• 사용자의 시선을 끄는 데서 그치지 않고, 이후의 경험까지 챙겼을까?

토스 앱은 매주 새 버전을 내보냅니다. 그 과정에서 플랫폼별로 5~7개의 RC(Release Candidate, 배포 후보) 빌드가 쌓이고, 빌드가 나올 때마다 누군가는 회원가입부터 로그인, 자산, 송금까지 같은 화면을 손으로 눌러 봅니다. 핵심 기능이 망가지진 않았는지 빠르게 훑는 스모크 테스트죠. 빠지면 안 되는 일이지만, 매번 사람이 반복하기엔 품이 너무 많이 들어요.

안녕하세요, 토스 QA Platform 팀입니다. 저희는 이 스모크 테스트를 자동화한 토스닥터를 만들어 운영하고 있습니다.

토스의 기술 컨퍼런스 SLASH를 기억하시나요? '약은 약사에게, 테스트는 토스닥터에게'라는 세션으로 소개했던 그 도구가 바로 토스닥터 V1입니다. V1은 제 역할을 했습니다. 하지만 매주 돌리다 보니 불편이 쌓였어요. 테스트를 새로 짜는 데 손이 많이 갔고, 화면이 조금만 바뀌어도 테스트가 우수수 깨졌고, 깨진 뒤엔 "이게 왜 실패했지"를 사람이 하나하나 들여다봐야 했죠.

그래서 토스닥터 V2에서는 네 가지를 뜯어고쳤습니다. 코드를 만드는 법, 화면 속 요소를 찾는 법, 실패를 판단하는 법, 그리고 고치는 법. 그리고 이 네 가지가 실제 디바이스에서 끊김 없이 이어지도록 실행 환경도 다시 만들었습니다. 오늘은 그 이야기입니다. 그리고 이 V2가 지금 저희가 쓰고 있는 '토스체커'의 근간이 됐는데요, 그건 맨 뒤에서 짧게 이야기하겠습니다.

코드를 사람이 짜지 않게 됐습니다

예전엔 테스트 하나를 만들려면, 화면을 열어 요소를 찾고 클릭·입력·검증을 절차적으로 코드에 옮겨 적어야 했습니다. 이 테스트가 무엇을 검증하는지는 코드 속에 묻혀 있었고, 새 기능이 나올 때마다 같은 작업을 처음부터 반복했어요.

토스닥터 V2에서는 테스트를 두 단계로 나눴습니다. 먼저 사람은 '무엇을 검증할지'만 적습니다. 절차적인 스텝 대신, Gherkin 문법의 시나리오로요.

Given-When-Then은 사람이 읽어도 바로 이해되고, AI가 코드로 옮기기에도 좋은 형식입니다. 그다음 /codegen 명령이 이 .feature 파일을 실제 실행 코드로 변환합니다. LLM에 Appium MCP를 붙여, 실제 디바이스를 보며 요소를 찾아 스텝을 구현합니다. .feature에 남긴 주석은 그대로 구현 가이드가 돼요.

여기서 한 번 부딪힌 게 있는데요. 요소를 찾을 때 화면과 UI 트리를 통째로 AI에 넘겼더니 토큰이 감당이 안 됐습니다. 그래서 요소 탐색을 3단계로 나눠, 필요한 만큼만 찾게 바꿨습니다. 먼저 스크린샷과 화면에 드러난 요소 목록만으로 찾고(전체 UI 트리는 넘기지 않습니다), 안 되면 화면 구조 전체(XML)를 깊게 뒤지고, 그래도 안 되면 사람에게 물어요. 값싼 방법부터, 비싼 방법은 꼭 필요할 때만 찾습니다.

시나리오는 사람이 쓰고, 코드는 도구가 씁니다.

가입부터 송금·인증서·자산까지 앱의 핵심 흐름을 폭넓게 덮었습니다.

화면이 바뀌어도, 요소를 스스로 찾습니다

코드를 아무리 잘 짜도, 실행 중에 예상 못한 화면이 끼어듭니다. 어제 없던 이벤트 팝업이 뜨고, 버튼 이름이 확인에서 확인하기로 살짝 바뀌고, 심지어 앱 위로 외부 광고 웹페이지가 통째로 덮이기도 합니다. 이럴 때마다 테스트가 깨지면, 자동화는 오히려 사람 손이 계속 가는 짐이 돼요.

그래서 스마트파인더를 만들었습니다. 테스트가 요소를 못 찾고 실패하려는 바로 그 순간, 서버가 이 스킬을 호출합니다. 말하자면, 쓰러진 그 자리에서 곧바로 하는 심폐소생이에요. 스킬은 실패한 그 화면을 직접 들여다본 뒤 두 가지를 시도합니다.

실제로 이런 장면이 잡힙니다.

타행 계좌로 송금하는 스텝에서, 계좌번호 입력칸 위로 외부 앱 공유 툴팁이 떠서 화면을 가리고 있었습니다. 스마트파인더는 이걸 블로커로 판단해 툴팁을 닫고, 가림이 사라진 걸 확인한 뒤 원래 계좌번호 입력 스텝을 이어갔습니다.

그리고 한 번 살려낸 걸로 끝나지 않습니다. 성공한 기록은 JSONL로 쌓이고, 다음에 같은 화면·같은 스텝에서 막히면 과거 성공 사례를 먼저 참고합니다. 자주 나오는 팝업일수록 더 빨리, 더 정확히 넘겨요.

한 가지는 특히 조심했는데요. 검증(then) 스텝에서는 similar-match를 금지했습니다. '비슷한 요소를 눌러서 통과시키는' 건 여기선 거짓 성공을 만들고, 그게 다음 스텝으로 연쇄되기 때문이에요(실제로 5스텝이 줄줄이 거짓 성공한 적이 있었습니다). 그래서 검증 스텝에선 가리던 걸 치우는 것까지만 허용하고, 결과 자체는 눈속임하지 않습니다.

실패하면, 왜 실패했는지부터 판단합니다

테스트가 깨지는 건 자연스러운 일입니다. 중요한 건 그다음이에요.

토스닥터는 실패를 감지하면 그 순간의 정보를 모읍니다. 실패한 시나리오, 스텝 코드, 에러 메시지, 스크린샷까지요. 이걸 토션에 실시간으로 기록하고, 곧바로 분석(/diagnosis)을 돌립니다.

분석은 세 가지를 내놓는데요. 추정 원인, 필요한 조치, 그리고 recoverable 판정. 이 마지막 하나가 핵심이에요.

말로만 하면 와닿지 않으니 실제 사례를 살펴볼게요. 아래 두 에러는 같은 '송금 실패'인데, 한 번의 실행에서 서로 다른 recoverable 판정을 받았습니다.

하나는 코드로 고치면 되고, 하나는 코드 밖의 일이죠. 이 선을 긋는 게 분석의 일입니다.

스크린샷은 실패한 화면 하나만 보지 않습니다. _ERROR.png와 직전 스텝들의 화면을 시간 순서대로 함께 봅니다. 실패 화면만 보면 중간에 스쳐 간 툴팁·팝업·화면 전환 실패를 놓치기 때문이에요.

고칠 수 있는 건 스스로 고칩니다

recoverable이 true면, 토션의 분석 결과를 바탕으로 곧바로 복구 실행(/recovery)을 시작할 수 있어요. 평소의 전체 실행과는 목적이 다릅니다.

중요한 점은 멈추고 → 붙여서 → 확인한다는 것입니다. 전체 실행은 에러가 나도 전체 결과를 모으기 위해 계속 진행하지만, 복구 실행은 첫 에러에서 즉시 멈춰요. 멈춘 화면에 Appium MCP를 붙이면, 분석이 '추정'했던 걸 실제 요소를 보며 '확인'할 수 있습니다.

복구는 E-1부터 E-5까지 순서대로 흐릅니다. 앞의 타행 계좌 송금 예시를 이어가 볼게요.

E-1부터 E-5까지, 사람이 손댄 곳은 없어요. 고칠 수 있다고 판단한 실패는 이렇게 스스로 고쳐 두고, 사람에게는 정말 사람이 봐야 할 실패만 남깁니다.

무대 뒤에는 서버가 있습니다

지금까지의 이야기에는 숨은 조력자가 하나 있는데요. 코드젠도, 스마트파인더도, 에러 분석과 복구도 스스로 깨어나지 않습니다. 누군가 제때 불러줘야 움직여요. 그 ‘누군가’가 토스닥터 서버입니다.

시작은 토션에서 빌드를 선택하고 실행하는 것부터예요. RC 빌드가 나오면 사람이 빌드를 고르고 실행을 요청합니다. 그다음부터는 서버의 일입니다. 빌드를 받아 디바이스에 설치하고, 테스트를 실행하고, 진행 상황을 실시간으로 전달해요.

여기서 중요한 건 테스트가 끝난 뒤 결과를 모아서 처리하는 방식이 아니라는 것입니다. 서버와 테스트 프로세스는 양방향으로 통신하면서, 스텝 하나가 끝날 때마다 결과를 주고받아요.

그래서 테스트가 요소를 찾지 못하면 그대로 실패 처리하지 않습니다. 멈춘 화면에서 서버에 도움을 요청하고, 서버는 그 순간 LLM과 Appium MCP를 연결해 화면을 확인해요. 스마트파인더가 복구할 수 있다고 판단하면 그 결과를 다시 테스트에 전달하고, 테스트는 원래 흐름을 이어갑니다.

실행이 끝나면 서버는 실패한 시나리오를 모아 분석을 돌리고, 결과를 처음 실행을 요청했던 곳에 다시 전달합니다. 시작한 곳에서 끝을 보는 거죠.

빌드 실행부터 테스트, 실패 대응, 결과 전달까지. 토스닥터 서버는 이 전체 흐름을 연결하는 실행의 중심입니다.

토스닥터에서, 토스체커로

토스닥터 V2에서 만든 네 가지 방식은 스모크 테스트 안에서만 머물지 않았어요. 한국어 BDD 시나리오, 실패에 스스로 대응하는 self-healing, 실기기 기반 실행. 이 아이디어들을 더 키우고 다듬어, 더 넓은 시나리오까지 검증하는 프레임워크로 발전시켰습니다. 저희는 이걸 토스체커라고 부릅니다.

스모크가 '숨이 붙어 있나'를 본다면, 리그레션은 '어디 아픈 데는 없나'를 봅니다. 더 넓고 깊은 검증을 사람 손으로 매번 하기는 어려워요. 토스닥터 V2에서 만든 네 가지 방식은 이 영역에서도 그대로 활용할 수 있었습니다.

실제로 토스체커는, 세 명의 테스터가 꼬박 이틀을 매달려 손으로 돌리던 배포 전 리그레션 테스트를 대신하기 시작했어요. 1,375개의 테스트 케이스를 기존 업무와 병행하며 3주 만에 자동화했죠. 토스닥터가 '한 앱의 스모크를 자동화한 도구'였다면, 토스체커는 '그 방식을 더 넓은 검증 영역으로 확장한 QA 자동화 플랫폼'입니다. 어떻게 해냈는지, 또 어디까지 넓혀갈지는 다음 아티클에서 자세히 다루겠습니다.

다시 처음으로 돌아가 볼까요. 매주 수십 개의 빌드를 사람이 손으로 확인하던 일에서 시작했습니다. 이제 코드를 만들고, 화면 속 요소를 찾고, 실패의 원인을 판단하고, 고칠 수 있는 문제를 고치는 일까지 도구가 맡습니다. 사람은 모든 테스트를 직접 돌보는 대신, 무엇을 검증할지와 어디까지 자동화할지를 설계하는 일에 집중할 수 있게 됐습니다. 토스닥터 V2가 다시 만든 건 단순히 테스트 자동화 도구 하나가 아니었어요. 다음 단계로 나아갈 수 있는 구조였습니다.

안녕하세요. 해외송금을 디자인한 토스뱅크 Product Designer 서자영입니다. 은행 지식도 외화 지식도 없던 디자이너가 규제와 운영 논리가 가득한 도메인에서 어떻게 팀의 기준을 바꿨는지에 대해 이야기해 보려고 해요.

해외송금에서 가장 중요한 건 정말 수수료일까?

팀에 합류하고 6개월 후에 해외송금 기능을 런칭해야 했는데, 제가 제대로 아는 건 없었어요. 해외로 돈을 보내면 하루 넘게 걸린다는 것도 팀에 들어오면서 처음 알았죠. 파트너사 선정, 전문(電文) 설계, 규제 검토 등 정할 건 산더미였어요. 그중에서도 당시 팀에서 가장 많이 고민했던 건 후발주자로서 어떤 강점을 가져야 할까였어요. 사실 이 질문에 대한 팀의 답은 어느 정도 정해져 있었어요. 수수료가 싸야 한다는 것.

저는 해외송금에 대한 이해도는 낮았지만, 어딘가 찝찝했어요. 정말 사용자가 가장 원하는 게 수수료가 싼 송금일까? 그런데 자신 있게 말할 수는 없었어요. 팀에서 제가 남들보다 잘 아는 건 하나도 없었거든요.

그렇다고 아무것도 할 수 없는 건 아니었어요. 도메인에 대한 지식은 부족해도, 사용자에게 직접 물어보는 건 할 수 있었죠. 돌이켜보니 팀원 중 누구도 실제로 해외에 돈을 보내본 사람에게 어떤 점이 불편했는지 물어본 적이 없었더라고요.

수수료보다 크게 느껴지는 불안

해외송금은 자주 하는 일이 아니다 보니 인터뷰 대상을 모으는 것부터 쉽지 않았어요. 여러 번의 스크리닝 끝에 실제로 해외로 돈을 보내본 분들을 만났어요.

수수료가 아깝다는 이야기는 나왔어요. 하지만 수수료가 조금 싸다고 해서 다른 은행으로 옮길 생각까지 하지는 않았어요. 수수료는 은행마다 크게 다르지 않고, 이미 송금 정보가 저장된 은행을 떠나는 것도 번거롭다는 거예요. 오히려 더 크게 반복되는 감정이 있었어요.

불안함이었어요.

유학생, 현지 체류자, 해외 비즈니스 담당자 등 송금하는 상황은 모두 달랐지만, 외국 은행 계좌번호를 입력하는 순간부터 돈이 도착하는 이틀 동안은 비슷한 걱정을 하고 있었어요.

• 내가 제대로 입력한 게 맞나?
• 지금 내 돈은 어디에 있지?
• 문제없이 가고 있는 걸까?

해외송금은 돈을 보내고 나면 당장 결과를 확인하기 어려워요. 그동안 무슨 일이 일어나고 있는지도 잘 보이지 않고요. 인터뷰를 통해 사용자가 원한 건 단순히 싼 송금이 아니라, 불안하지 않은 송금이라는 생각이 들었어요.

답을 찾았다고 생각해 인터뷰 결과를 팀에 공유했죠. 돌아온 첫 반응은 이거였어요.

“그래도 결국 제일 싼 곳이 이기는 것 아닌가요?”

사용자의 목소리만으로는 팀의 확신을 바꾸기 어려웠어요. 그래서 방법을 바꿔보기로 했어요.

팀이 직접 경험해보다

설득하는 대신, 직접 겪게 하기로 했어요. 한 PM 분이 직접 영국으로 돈을 보내봤어요. 송금을 신청하자마자 화면에 초록색 체크와 함께 ‘정상 송금’이라는 문구가 떴어요. 다음 날에도 ‘정상 송금’, 그다음 날에도 ‘정상 송금’. 3일 내내 같은 화면이었죠. 돈이 도착했다는 건지, 아직 도착하지 않았지만 문제없이 진행되고 있다는 건지 알 수가 없었어요. 고객센터에 물어봤더니 문제가 없다고 했어요. ‘정상 송금’이면 며칠 내에 안전하게 도착할 테니 걱정하지 않아도 된다고요. 이 경험을 팀에 공유하면서 PM 분이 이런 말을 했어요.

“걱정하지 말라고 했는데, 걱정은 그대로였어요.”

그때부터 이건 남의 이야기가 아니라 팀원이 직접 겪은 일이 됐어요. “결국 싼 곳이 이기지 않냐”라고 했던 사람들이 각자 다른 은행으로 직접 송금을 해보기 시작했죠. 그리고 팀의 기준이 바뀌었어요. ‘얼마나 싼가’에서 ‘얼마나 불안하지 않은가’로. 이제부터는 이 기준으로 하나씩 제품을 디자인하기로 했어요.

송금 과정의 불안을 줄이다

인터뷰를 통해 발견한 불안은 크게 두 가지였어요. 송금하는 순간의 불안, 그리고 돈을 보내고 기다리는 동안의 불안. 먼저 송금 과정부터 살펴봤어요.

국내 송금은 금액과 계좌번호만 입력하면 끝나지만, 해외송금은 입력해야 하는 정보가 훨씬 많아요. 은행 코드, 계좌번호, 현지 주소 등 낯선 정보가 계속 등장하죠. 특히 CHASUS33XXX 같은 은행 코드는 암호처럼 생겼어요. 이걸 제대로 입력했는지 확인할 방법도 마땅치 않았고요. 사용자는 ‘내가 잘못 입력해서 돈이 엉뚱한 곳으로 가면 어떡하지?’라는 불안함을 느끼죠.

그래서 은행 코드를 입력하면 바로 ‘JP Morgan Chase’처럼 은행 이름이 보이도록 했어요. 단순히 이름 하나를 보여주는 인터랙션이지만, 실제로는 은행 코드와 은행 이름을 연결하는 별도의 작업이 필요했어요. 송금 자체만 놓고 보면 없어도 되는 기능이에요. 은행 코드를 정확하게 입력하기만 하면 송금은 되니까요. 이전의 기준이었다면 “굳이 필요한가?”라는 질문으로 끝났을지도 몰라요. 하지만 불안하지 않은 송금이 목표라면, 사용자가 입력한 정보가 맞다는 확신을 주는 일도 꼭 필요하다고 생각했어요.

또 하나는 현지 주소였어요. 나라마다 주소 체계가 무척 다르잖아요. 어떤 곳은 거리명과 숫자로 되어있는데, 어떤 곳은 건물 번호도 필요하고 아예 유닛이라는 새로운 체계로 이루어진 곳도 있어요. 실제로 살아보지 않으면 너무 생소하죠. 어떻게 주소 입력창을 만들어야 할지 고민하고 있는데, 개발자분이 주소를 입력할 때 지도 앱처럼 몇 글자만 입력해도 검색해서 정확한 주소를 고르게 하면 어떻겠냐고 제안해 주셨어요. 지도 API를 연동해야 하고 호출 비용도 드는 일이었어요. 다른 은행에서는 자유 입력으로 받는 정보이기도 했고요. 하지만 이 방식을 쓰면 더 정확한 정보를 받을 수 있다는 이점도 있어요. 결과적으로 오타로 인한 반송도 줄게 되죠. 사용자의 편의와 운영 효율성 측면에서도 꼭 필요한 일이라고 설득해서 지도 API를 사용하게 되었어요.

송금 후의 불안을 줄이다

송금 후의 불안은 더 컸어요. 인터뷰에서 많은 사용자가 공통으로 이야기한 건, 돈을 보낸 순간부터 도착할 때까지 하루이틀을 아무것도 모른 채 그냥 기다려야 한다는 것이었어요.

실제로 해외송금은 그사이에 고객 확인, 외국환거래 규정 확인, AML·제재 스크리닝, 수취 은행 검사, 입금, 사후 모니터링 등 여러 단계를 거쳐요. 그렇다고 이 과정을 사용자에게 모두 보여주는 게 답은 아니라고 생각했어요. 내부에서 어떤 일이 일어나는지 전부 보여주면 오히려 더 불안해질 수도 있으니까요. 그래서 서버 개발자와 송금 상태를 하나씩 짚어봤어요.

‘이건 사용자가 알아야 하는 정보인가, 아니면 우리만 알고 있으면 되는 정보인가?’

돈이 제대로 송금되지 않는 경우에도 여러 가지 원인과 내부 로직이 있었지만, 그걸 하나하나 설명하기보다는 사용자가 실제로 알아야 하는 결과에 집중했어요. 여러 논의를 거쳐 아홉 개였던 송금 상태를 세 개로 줄였어요.

송금 처리 중 → 해외 은행 도착 → 완료

모든 과정을 보여주는 대신, 지금 내 돈이 어디까지 갔는지 알 수 있는 정보만 남긴 거예요. 보여주고 싶었던 건 복잡한 송금의 과정이 아니라, 내 돈이 지금 어떻게 되고 있는지였어요. 그래서 해외송금의 캐치프레이즈도 자연스럽게 정해졌어요.

‘보내면 보이는 해외송금.’

수수료를 낮추는 것도 물론 중요하지만, 팀이 만들고 싶었던 건 단순히 싼 송금이 아니었어요. 돈을 보내고 나서도 무슨 일이 일어나고 있는지 알 수 있고, 기다리는 동안 막연하게 불안해하지 않아도 되는 경험이었어요.

적용해보기

제가 한 일은 외화 지식을 빠르게 공부해 전문가가 되는 게 아니었어요. 오히려 잘 몰랐기 때문에 당연하게 여겨지는 것들을 한 번 더 사용자에게 물어볼 수 있었어요. 그리고 그 답을 팀이 직접 확인할 수 있도록 만들었고요.

처음에는 ‘얼마나 싼가’를 고민하던 팀이 ‘사용자가 무엇을 불편해하는가’를 기준으로 제품을 바라보기 시작한 것. 저에게 이 프로젝트에서 가장 의미 있었던 변화였어요.

이번 프로젝트에서 디자이너는 도메인 지식을 가장 잘 아는 사람이 아니라, 좋은 질문을 던지고 사용자의 경험을 기준으로 답을 찾는 사람이란 것을 배웠어요. 그리고 팀 전체가 사용자 관점으로 생각하기 시작하면 더 좋은 해결책이 나올 수 있다는 것도요.

도메인 지식이 없거나, 팀의 관점을 바꿔야 하는 디자이너라면 이런 질문을 던져보면 좋겠어요.

• 도메인 지식을 더 쌓아야 한다는 이유로, 사용자에게 직접 물어보는 일을 미루고 있진 않나요?
• 사용자의 목소리를 팀에 전달하는 데서 끝내고 있진 않나요? 팀이 직접 겪어볼 방법은 없을까요?
• 어떻게 하면 디자이너 혼자가 아니라 팀 전체에서 더 좋은 해결책을 고민할 수 있을까요?

안녕하세요. 토스뱅크에서 7세부터 17세까지, 미성년자를 위한 제품을 만들고 있는 Product Designer 오주연이에요. 저는 10대가 스스로 정한 목표를 달성할 수 있도록 돈을 빼내기 어렵게 하는 저금통 잠그기 기능을 만들었어요.

이 글에서는 ‘사용자를 돕기 위해 일부러 어렵게 만드는 경험은 어디까지 괜찮을까?’를 고민했던 이야기를 나눠보려고 해요.

"목표금액까지 못 채우면 못 꺼내게 해주세요"

10대를 위한 제품을 만들며 여러 리서치를 했는데, 아이들의 용돈 생활에 공통적으로 나타난 패턴이 있었어요. 돈을 모으고 싶어 하지만 쓰고 늘 후회하는 경험을 반복하는 거였죠.

저축을 결심해도 눈앞의 사고 싶은 것을 참기 어려웠고, 결국 열심히 모으던 돈을 써버리는 것이었어요. 이런 실패가 쌓이면서 ‘나는 돈을 잘 관리할 수 있다’는 감각도 낮아지고 있었고요.

발달심리학에서는 이를 이중 시스템 모델로 설명하기도 해요. 무언가를 갖고 싶게 만드는 보상·감정 시스템은 사춘기 무렵 빠르게 발달하지만, 충동을 조절하는 전두엽은 20대 초중반까지 발달이 이어져요. 10대는 저축하고 싶은 마음은 충분히 크지만, 당장의 유혹을 참는 힘은 아직 자라는 중인 셈이죠. 그러니 저축에 실패한 건 단순히 의지가 약해서가 아니었어요.

어느 날은 이런 피드백들이 올라왔어요.

“목표금액까지 못 채우면 돈 못 꺼내는 저금통 만들어주세요ㅜㅜ 저를 못 믿겠어요.”

아이들은 이미 자신에게 어떤 도움이 필요한지 알고 있었어요. 저축하고 싶은 마음은 있지만, 마음이 흔들리는 순간 한 번 더 자신을 말려줄 무언가가 필요했던 거죠.

이 목소리에서 잠금 저금통이 출발했어요.

잠금을 어떻게 풀 것인가

그런데 목표금액을 채우지 않아도 결국에는 자신의 돈이기 때문에 원하면 돈을 꺼낼 수 있어야 해요. 그렇다면 얼마나 쉽게, 혹은 얼마나 어렵게 풀리게 해야 할까요? 이 난이도가 잠금 저금통의 가장 중요한 부분이라고 생각했어요. 그래서 팀원들과 삼삼오오 모여 아이디어를 모았고, 어느새 스레드에는 70개가 넘는 의견이 쌓였어요. 주사위를 굴려서 6이 나와야 열리는 것, 계좌번호를 외워서 입력해야 하는 것, 친구에게 허락을 받아야 열리는 것… 재미있는 아이디어가 정말 많았어요.

그중 유독 반응이 좋았던 아이디어가 ‘돼지저금통 부수기’였어요. 화면 속 저금통을 두드리면 쨍그랑 깨지면서 모은 돈이 쏟아지는 거예요. 설명하지 않아도 바로 이해할 수 있고, 어릴 때 게임에서 무언가를 신나게 부숴본 기억도 있잖아요. 팀 반응도 좋았고, 저도 처음에는 ‘이거다’ 싶었어요.

그런데 막상 디자인을 시작하니 마음 한구석이 계속 걸렸어요. 어릴 때 용돈을 모으던 돼지저금통을 깼던 날이 떠올랐거든요. 돈이 필요해서 어쩔 수 없이 깼는데, 동전을 하나씩 세는 내내 기분이 이상했어요.

사고 싶은 걸 사는 건데, 왜 혼나는 기분이 들지?

돌이켜보니 인터뷰에서 아이들이 저축에 실패했을 때 이야기했던 감정도 이와 크게 다르지 않았어요. 돈을 쓴 것 자체보다 ‘또 참지 못했다’는 아쉬움과 스스로에 대한 실망이 남는다는 이야기가 반복됐어요.

30대인 제 눈에는 돼지저금통을 부수는 게 재미있는 인터랙션이지만, 그걸 경험하는 10대에게는 ‘저축에 실패했다’는 낙인이 될 수도 있겠다는 생각이 들었어요. 돈을 꺼내는 건 잘못이 아닌데, ‘부순다’는 연출은 마치 잘못을 저지른 것 같은 기분을 남길 수 있으니까요. 만드는 사람에게 재미있는 경험이, 쓰는 사람에게는 상처가 될 수도 있었어요.

재미보다 기준을 먼저 세우다

결국 저금통을 부수는 방식은 사용하지 않기로 했어요. 대신 ‘잠금을 푸는 경험은 어떤 모습이어야 하는가’부터 다시 정의했어요.

하나. 누구에게나 공평하게 작동할 것

인지능력, 문해력, 손재주, 반응 속도에 따라 난이도가 달라지면 안 돼요. 계좌번호를 외워 입력하는 방식은 17살에게는 재미있는 미션일 수 있지만, 어린 사용자에게는 훨씬 어려운 일이 될 수 있어요. 잠금은 저축을 돕기 위한 장치인데, 사용자의 능력에 따라 돈을 꺼낼 수 있는 정도가 달라져서는 안 된다고 생각했어요.

둘. 죄책감을 느끼게 하지 않을 것.

미래의 목표를 다시 생각하게 만드는 건 괜찮지만, 지금의 기분을 나쁘게 만드는 방식은 피하기로 했어요. 저축을 지키게 만들겠다고 죄책감을 도구로 쓰는 순간, 그건 응원이 아니라 벌이 될 수 있으니까요. 그래서 돈을 꺼내는 순간을 실패처럼 보여주는 연출은 제외했어요. 돈을 꺼내면 저금통이 눈물을 흘린다던가, “목표를 지키지 못했어요” 말을 따라 쓰게 한다던가 하는 것들이요.

셋. 아이의 돈은 아이의 것일 것.

어떤 경우에도 스스로 자기 돈에 도달할 수 있는 경로가 있어야 했어요. 친구의 허락을 받아야 열리는 방식은 재미있는 소셜 요소처럼 보이지만, 내 돈을 꺼내는 데 다른 사람의 허락이 필요하다면 돈에 대한 주도권을 아이가 갖기 어려워져요.

잠금이 응원이 되도록

가장 신경 쓴 건 ‘온도’였어요. 잠금은 자칫 ‘막힌 문’처럼 느껴질 수 있어요. 돈을 꺼내지 못하게 하는 장치니까요. 하지만 이 잠금은 아이가 스스로 원해서 건 것이잖아요. 그렇다면 아이를 가두는 장치가 아니라, 아이가 세운 결심을 지켜주는 장치여야 했어요.

그래서 해제 방식으로는 버튼을 몇 초간 지그시 누르고 있어야 잠금이 풀리는 방식을 택했어요. 돈을 꺼내기 전까지 잠깐의 ‘틈’을 만들어주니까요. 충동적으로 손이 가더라도, 버튼을 누르고 있는 그 몇 초가 ‘정말 지금 꺼낼까?’를 한 번 더 생각하게 해요. 이 과정을 통해 10대들이 충동을 인내하는 힘을 기를 수 있을 거라고 생각했어요.

그리고 잠금이 강제나 부담으로 느껴지지 않도록 UI와 인터랙션의 무게감을 조절했어요. 예를 들어 잠글 때 ‘철컹’ 하고 강하게 잠기는 느낌은 피하고 싶었어요. 비주얼 디자이너와 함께 부드러운 톤과 그라데이션을 사용해, 잠그는 순간조차 무겁게 느껴지지 않도록 했죠. 잠글 때도, 풀 때도 아이가 혼나는 기분보다 응원받는 기분을 느낄 수 있도록요.

가장 오래 고민한 건 기술이나 화면보다는 ‘어떻게 하면 아이가 실패감 대신 성장의 경험을 갖게 할까?’를 가장 많이 고민했죠.

그래서 출시 후 들어온 이런 목소리가 유독 반가웠어요.

은행은 보통 계좌, 이자, 잔액처럼 돈을 관리하는 곳이라고 생각해요. 하지만 잠금 저금통을 만들면서, 은행이 사용자의 금융 경험을 함께 만들어가는 곳이 될 수도 있겠다는 생각을 하게 됐어요. 이제 막 돈을 배우기 시작한 아이들에게는 특히 더 그렇고요.

적용해보기

이 경험은 꼭 10대들의 저금통에만 해당하는 이야기는 아니라고 생각해요. 집중 모드, 앱 잠금, 사용 시간 제한처럼 사용자를 위해 일부러 무언가를 어렵게 만드는 제품은 많아요. 그럴 때 한 번쯤 이런 질문을 던져볼 수 있어요.

• 나이와 이해도, 상황이 다른 사용자에게도 공평한 난이도일까?
• 이 설계가 사용자에게 죄책감이나 실패감을 남기지는 않을까?
• 만드는 나에게 재미있는 것과, 쓰는 사람에게 좋은 것을 혼동하고 있지는 않을까?
• 사용자를 돕기 위해 만든 장치가 오히려 사용자의 선택권을 빼앗고 있지는 않을까?

새 모델이 나올 때마다 우리는 먼저 리더보드를 봅니다. 모델의 지능이 얼마나 높은지, 수학을 잘 푸는지, 코드를 잘 짜는지. 점수가 높으면 자연스럽게, 이 모델이면 우리 서비스도 더 좋아지겠다는 기대를 하게 되죠.

하지만 실제 서비스에 붙여 보면 꼭 그렇지만은 않습니다. 영어를 잘 이해하는 모델이 한국어 정책을 잘 읽는다는 보장은 없고, 추론(Reasoning) 모드에서 높은 점수를 얻은 모델이 빠른 응답이 필요한 운영 환경에서도 같은 성능을 낸다는 보장도 없습니다. 무엇보다 범용 시험을 잘 푸는 것과 토스 도메인 업무를 처리하는 것은 다른 능력입니다.

LLM Modeling 팀은 토스의 다양한 업무에 맞는 모델을 평가하기 위해 Toss Benchmark를 만들었습니다. 한정된 GPU 자원에서 서빙할 모델을 선별하고, Toss Foundation 모델이 갖춰야 할 능력을 정하기 위한 기준입니다. 먼저 토스에서 LLM에 어떤 일을 맡기고 있는지 살펴보겠습니다.

토스는 LLM으로 어떤 문제를 풀고 있을까

토스에서는 상품 카탈로그를 만들고, 카드 약관을 분석하고, 광고를 검수하는 데 LLM을 활용합니다. 토스쇼핑 입점 판매자와 상품 운영에 필요한 안내와 협의를 진행하는 음성 에이전트, 도구로 고객 정보를 조회하는 상담 에이전트처럼 대화와 행동을 이어가는 사례도 있습니다. 금융 서비스뿐 아니라 커머스, 광고, 사내 개발·운영까지 적용 범위가 넓습니다.

아래는 각 영역에서 LLM을 활용하는 사례의 일부입니다.

Toss Benchmark는 이처럼 다양한 업무에 사용할 모델을 비교하기 위해 실제 데이터와 프롬프트를 모아 성능을 측정하고, 평가 대상을 계속 추가하고 있습니다.

이 글에서는 토스 업무에 맞는 평가 기준을 만들고, 실제 업무 성능과의 관계를 확인한 과정을 소개합니다. 이를 통해 어떤 모델을 서빙하고, Toss Foundation 모델에서 어떤 능력을 강화할지 판단하는 기준을 살펴봅니다.

Toss Benchmark는 무엇을 평가할까

Toss Benchmark는 한국어 범용 성능과 토스 도메인 성능을 함께 봅니다. 한국어 범용 평가는 모델의 기본 능력을 넓게 확인하고, 도메인 평가는 실제 업무 처리와 그 업무에 공통으로 필요한 능력을 확인합니다.

한국어 범용 성능은 왜 따로 측정할까

공개 리더보드는 후보 모델을 비교할 때 유용합니다. 하지만 평가에 사용한 언어나 추론 설정이 실제 서비스와 다르면, 같은 모델도 성능과 순위가 달라질 수 있습니다.

프롬프트 언어가 바뀌면 성능과 순위도 바뀐다

한국어 서비스에 사용할 모델이라면, 영어 평가에서의 강점이 한국어 요청에서도 유지되는지 확인해야 합니다. 이를 보기 위해 수학과 코딩은 같은 문제의 영어 원문과 한국어 번역본으로 평가했습니다.

아래 표는 순위 역전이 나타난 구간을 발췌한 것입니다. 영어 점수 순으로 정렬했으며, 순위는 각 표에 포함된 모델 안에서 다시 매겼습니다. 전체 리더보드 순위를 뜻하지는 않습니다.

수학: 같은 문제의 한국어 번역본

코딩: 같은 문제의 한국어 번역본

수학에서는 영어 점수가 81.74점인 gemma-4-26B-A4B-it보다 79.74점인 Qwen3.6-27B가 한국어에서 앞섰습니다. 코딩에서도 영어에서는 Qwen3.5-122B-A10B가 Qwen3.6-27B보다 높았지만, 한국어에서는 순서가 바뀌었습니다.

여기서 볼 것은 점수 하락 자체뿐 아니라 모델 간 우위가 유지되는지입니다. 같은 요구사항을 담은 문제라도 한국어로 제시했을 때 후보 모델의 순서가 달라질 수 있었습니다.

지식: 한국어권의 지식과 문화적 맥락도 확인하기

지식은 수학·코딩과 평가 방식이 다릅니다. 같은 문제를 번역한 것이 아니라 영어와 한국어에서 각각 다른 벤치마크를 사용했습니다. 한국어 평가는 한국어권의 지식과 문화적 맥락을 다루는 벤치마크로 구성했습니다.

영어 평가에서는 Qwen3.5-122B-A10B와 Qwen3.5-35B-A3B가 이 다섯 모델 중 앞섰지만, 한국어 평가에서는 gemma-4-26B-A4B-it가 가장 높았습니다. 수학·코딩 비교가 같은 문제를 한국어로 제시했을 때의 변화를 확인한다면, 지식 평가는 한국어 서비스에서 필요한 지식 범위에서도 모델이 잘하는지를 확인합니다. 두 비교는 서로 다른 질문에 답하지만, 공개 영어 평가만으로 모델을 선택하기 전에 한국어 환경에서 다시 측정해야 한다는 점으로 이어집니다.

추론 설정에 따라 성능은 어떻게 달라질까

언어를 맞추는 것만으로 평가 조건이 같아지지는 않습니다. 모델이 답변을 내기 전에 추론 과정을 생성하는 Reasoning 모드는 문제 해결에 도움이 될 수 있지만, 서비스에서는 비용과 응답 시간 때문에 이를 끄거나 최소화하기도 합니다. 충분한 추론을 허용했을 때의 점수와 실제 운영 설정에서의 점수를 구분해야 하는 이유입니다.

그렇다면 Reasoning을 끄면 모든 모델의 성능이 비슷하게 내려갈까요? 같은 모델을 두 실행 방식으로 평가한 코딩 결과를 비교했습니다. 아래 표는 점수 하락 폭이 큰 순서로 정렬했습니다.

코딩 — 모델마다 다른 Reasoning 설정의 영향

GLM-5.1은 Reasoning을 껐을 때 30.6점, Kimi-K2.6은 26.4점 낮아졌습니다. 반면 gemma-4-26B-A4B-it의 차이는 6.0점이었습니다. 같은 코딩 평가에서도 설정 변경에 따른 하락 폭이 모델마다 크게 달랐습니다.

순서도 달라졌습니다. Reasoning을 켰을 때 GLM-5.1은 78.7점으로 DeepSeek-v4-pro의 76.9점보다 높았지만, 껐을 때는 각각 48.1점과 57.8점으로 역전됐습니다. 추론을 허용한 평가에서 더 높은 모델을 골라도, 실제 서비스에서 추론을 끄면 다른 모델이 더 나을 수 있다는 뜻입니다.

공개 벤치마크 점수는 해당 평가에 사용한 언어와 모델 설정에서 얻은 결과입니다. 앞서 살펴본 것처럼 한국어로 요청하거나 Reasoning 설정을 바꾸면 모델 간 순위도 달라질 수 있습니다. 공개 점수를 참고하되, 우리 서비스에서 사용할 언어와 추론 설정에 맞춰 평가하면 모델의 적합성을 더 정확하게 판단할 수 있습니다.

Toss Benchmark는 이런 차이를 반영해 토스의 서비스 환경에 맞는 평가 결과를 제공합니다. 공개 리더보드의 순위에 더해, 우리 업무에서 필요한 품질을 내는지 살펴보기 위한 기준입니다.

범용 성능만으로는 왜 부족할까

한국어와 모델 설정을 맞춰 평가하더라도 실제 업무에서 요구하는 능력은 별도로 확인해야 합니다.

예를 들어 상품명을 표준 속성으로 바꿔 카탈로그에 넣는 업무를 생각해 보겠습니다. 실제 서비스 프롬프트는 아래처럼 정보의 역할과 출력 원칙을 정의합니다.

아래는 입력 상품명 및 추출 속성 예시입니다. (브랜드·머신·제품명은 가상의 명칭)

여기서 모비오는 캡슐의 맛이나 상품명이 아니라 사용할 수 있는 머신을, 더블은 두 개 묶음이 아니라 커피의 종류를 뜻합니다. 또 캐치프레소 모비오 캡슐은 한 슬리브에 10개가 들어간다는 정보를 알아야 3슬리브를 30EA로 바꿀 수 있습니다. 이런 해석은 범용적인 문자열 처리만으로는 안정적으로 하기 어렵고, 카테고리별 상품 지식과 서비스 정책을 함께 알아야 합니다

이 업무에서 도메인 지식은 상품명 속 정보의 의미를 해석하는 데 필요하고, 정책 준수는 그 정보를 정해진 속성과 형식으로 바꾸는 데 필요합니다. Toss IFBench와 Toss Knowledge는 이 두 능력을 각각 평가하기 위해 만들었습니다.

토스 도메인 성능을 평가하는 방법

토스 도메인 성능은 다음 세 종류의 평가로 나눴습니다.

이미 정답 데이터가 있는 업무는 운영 태스크로 직접 평가할 수 있습니다. IFBench와 Knowledge는 개별 업무의 평가 데이터가 없어도 도메인 성능을 파악할 수 있는 공통 기준입니다.

Toss IFBench: 정책을 이해하고 지키는 능력

토스의 LLM 업무에는 정책이 긴 프롬프트로 들어가는 경우가 많습니다. 상품 속성을 추출할 때의 출력 형식, 고객 문의를 분류할 때의 기준, 두 상품이 같은지 판단하는 규칙이 그 예입니다.

Toss IFBench는 상품 속성 추출과 상품 동일성 판단, 두 업무의 실제 서비스 프롬프트에서 규칙 기반으로 채점할 수 있는 지시와 판단 기준을 추렸습니다. 그리고 개별 업무의 표현에 묶이지 않도록 일반화해, 토스 도메인에서 필요한 정책 이해와 준수 능력을 평가합니다.

형식만 맞추는 것과 규칙을 따르는 것은 다릅니다

상품 속성 추출에는 보통 여러 조건이 한꺼번에 들어갑니다. 예를 들어 ‘JSON으로 답할 것’, ‘키는 정해진 순서로 쓸 것’, ‘수량은 EA 단위를 붙일 것’처럼요. 조건을 하나라도 놓치면 서비스가 결과를 그대로 쓰기 어려워집니다.

형식 지시 평가는 이 조건들을 지시 단위로 나누어 각각 확인합니다. 덕분에 단순히 그럴듯한 JSON을 내는지를 넘어, 프롬프트에 적힌 세부 규칙을 빠뜨리지 않고 읽는지 볼 수 있습니다.

판단 지시는 한 단계 더 나아갑니다. 같은 상품 쌍을 두고, 판단 규칙만 바꿔 두 번 묻습니다.

예를 들어 면도기 1개와 10개 묶음은 기본 규칙에서는 다른 상품이지만, ‘수량 차이는 무시한다’는 규칙에서는 같은 상품입니다. 모델이 상품 자체만 보고 “당연히 다르다”고 답한다면 한 문제는 맞혀도 다른 한 문제에서 틀립니다. 이 방식은 원래 판단을 고집하는 모델과 프롬프트 규칙에 맞춰 판단을 바꾸는 모델을 구분합니다.

두 지시 유형에서 모델의 성능은 실제로 다르게 나타났습니다. 아래 차트는 IFBench 종합 점수 상위 5개 모델을 대상으로, 형식 지시와 판단 지시 점수를 나란히 보여줍니다.

\* reasoning을 완전히 끌 수 없어 reasoning_effort=low 조건으로 측정했습니다.

gemini-3.8-flash와 gemma-4-31b-it는 판단 지시에서 모두 83.2점으로 공동 1위입니다. 하지만 형식 지시에서는 gemini-3.8-flash가 78.0점, gemma-4-31b-it가 56.2점으로 21.8점 차이가 납니다. 규칙에 따라 판단을 바꾸는 능력과, 여러 출력 조건을 빠뜨리지 않고 지키는 능력은 같지 않습니다. 정책 준수 능력을 보려면 두 축을 함께 봐야 합니다.

Toss Knowledge: 토스 도메인 지식을 평가하는 방법

Toss Knowledge는 토스 업무에 필요한 도메인 지식을 평가합니다. 첫 대상으로 커머스를 택한 것은 상품 검수·카탈로그 생성·상품 매칭 등 다양한 업무가 브랜드·규격·옵션에 대한 공통 지식을 요구하기 때문입니다.

이 지식을 평가하기 위해 아래 다섯 영역의 4지선다 문항을 구성했습니다.

이런 질문을 합니다

아래는 평가 문항의 예시입니다. (브랜드 이해·상품 이해 예시의 브랜드와 제품명은 가상의 명칭으로 바꾸고, 일부 설명을 재구성)

브랜드 이해

다음 중 브랜드 ‘로에빈’에 대한 설명으로 옳은 것은?

① 테니스 라켓과 운동복을 주력으로 판매하는 스포츠 브랜드 ② 냄비와 프라이팬을 주력으로 판매하는 주방용품 브랜드 ③ 의류와 가방을 주력으로 판매하는 패션 브랜드 ④ 유리컵과 접시를 주력으로 판매하는 식기 브랜드

예시에서 설정한 정답: ③

이커머스 용어

제조사가 제품의 기획·설계·개발까지 직접 하고, 판매 기업은 자사 브랜드만 붙여 파는 생산 방식은?

① 3PL　② OEM　③ ODM　④ OBM

정답: ③

상품 이해

다음 중 상품 ‘그립온 토르빗’에 대한 설명으로 옳은 것은?

① 전선 피복을 자동으로 벗기는 스트리퍼 ② 단자를 압착할 때 사용하는 래칫형 압착기 ③ 버튼으로 턱 간격을 조절하는 워터펌프 플라이어 ④ 손잡이를 잠가 물체를 고정하는 바이스 플라이어

정답: ③

최신 정보 접근 여부의 영향을 줄이기 위해, 출시 후 충분한 시간이 지났고 현재도 활발히 거래되는 브랜드·상품을 중심으로 문항을 구성했습니다. 지나치게 쉬운 문항을 제외하고 새 문항을 보충했으며, 정답 보기의 길이가 단서로 작용하지 않도록 조정했습니다.

채점은 정답을 각 보기 위치에 한 번씩 배치해 네 차례 평가한 정답률의 평균(avg@4)을 사용했습니다. 특정 보기 위치에 대한 선호가 점수에 미치는 영향을 줄이기 위한 방식입니다.

주요 5개 모델을 축별로 보면, 같은 상위권 모델이라도 강점은 다릅니다. gemma-4-31b-it는 다섯 축 모두 89~97점으로 고른 성능을 보입니다. 반면 GPT-5.4-mini는 이커머스 용어에서 76점으로 크게 낮고, GLM-5.3-flash는 상품 스펙 97점에 비해 상품 이해 81점으로 차이가 큽니다. gemma-4-26b-a4b-it도 이커머스 은어는 97점이지만 상품 이해는 81점입니다. 즉, 종합 순위가 비슷해도 서비스에서 주로 묻는 지식 축에 따라 더 적합한 모델은 달라질 수 있습니다.

실제 운영 성능과도 연결될까

공통 평가 기준을 만든 뒤에는 기존 운영 업무의 성능과 연결되는지 확인했습니다. 공개 범용 지표인 AAII(Artificial Analysis Intelligence Index), Toss IFBench 형식 지시, Toss Knowledge를 각각 운영 태스크 평균 점수와 비교했습니다.

평가의 공정성을 위해, 벤치마크 데이터 구성 시 참고했던 운영 태스크는 상관관계 분석 대상에서 제외했습니다. 벤치마크를 만드는 데 참고한 업무와 평가 대상을 분리해, 다른 운영 업무의 성능과도 연결되는지 확인했습니다.

상관계수는 두 가지를 함께 봤습니다. Spearman ρ는 모델들의 순위가 함께 움직이는 정도이고, Pearson r은 점수 차이의 크기까지 비례하는 정도입니다. 둘 다 +1에 가까우면 관계가 강하고, 0에 가까우면 뚜렷한 상관이 관찰되지 않았다는 뜻입니다.

세 그래프는 같은 11개 모델을 비교합니다. 점 하나는 모델 하나이며, 가로축은 각 지표의 점수, 세로축은 동일한 운영 태스크의 평균 점수입니다. 점선은 점수 사이의 선형 추세, 음영은 그 추세의 95% 신뢰구간으로, Pearson r이 나타내는 관계입니다.

Toss IFBench 형식 지시 점수가 높은 모델은 운영 태스크 평균도 높은 경향을 보였습니다. 서비스 프롬프트에서 뽑은 정책 준수 평가가 기존 업무 성능을 판단할 때 참고할 만한 정보를 담고 있다는 결과입니다.

Knowledge도 운영 태스크 평균과 양의 상관을 보였습니다. 하지만 여러 업무를 합친 평균만으로는 커머스 지식이 어떤 업무의 성능과 연결되는지 알기 어렵습니다. 그렇다면 실제 커머스 운영 태스크를 따로 살펴보면 어떨까요? 같은 모델 집합에서 각 커머스 태스크의 점수와 Knowledge 점수를 비교했습니다. 아래는 높은 상관이 관찰된 상품 분류·그룹화·검수 결과입니다.

상품 분류·그룹화·검수에서는 커머스 지식 점수가 높은 모델이 업무 점수도 높은 경향을 보였습니다. 이를 통해 Toss Knowledge가 측정하는 커머스 지식이 실제 운영 성능과도 연결된다는 점을 확인할 수 있었습니다.

모델 비교와 추천으로 연결하기

평가 결과는 사내 GenAI Portal의 모델 카탈로그에서 확인할 수 있습니다. 사용 가능한 모델의 평가 결과와 서빙 지표를 한 화면에서 비교하고, 새 모델이 등록되면 같은 기준으로 평가해 추가합니다.

업무 목적을 입력하면 에이전트가 평가 결과를 바탕으로 후보 모델을 제안합니다. 예를 들어 상품 카테고리 분류를 요청하면, 분류 규칙 준수와 상품 이해에 관련된 점수를 비교해 우선 후보와 비교 후보를 제안하고 추천 근거를 설명합니다.

Foundation 모델의 개발 기준으로 활용하기

Toss Benchmark는 현재 개발 중인 Toss Foundation 모델의 개발 목표를 정하는 데도 활용하려고 합니다. 한국어 이해, 정책 준수, 도메인 지식 중 어떤 능력을 강화해야 하는지 파악하고, 학습 전후의 평가 결과를 비교해 개선 여부를 확인하는 기준입니다.

마치며

현재 Toss Benchmark를 다음 세 방향으로 확장하려고 합니다.

앞으로도 실제 업무에서 얻은 사례를 평가에 반영하고, 그 과정에서 확인한 모델의 특성과 평가 경험을 공유하려고 합니다. 이 글이 각자의 서비스에 맞는 모델 평가 기준을 고민하는 데 도움이 되었으면 합니다. 감사합니다.

안녕하세요. 토스증권 Data Infra 팀 Data Engineer 장재영입니다.

지난 상반기 동안 ML Platform 팀의 김진웅 님과 함께 Kubernetes 기반 GPU 클러스터를 구축했는데요. 오늘은 그 과정에서 겪은 문제와 해결 방법을 공유하려고 합니다.

토스증권의 서비스와 데이터 플랫폼은 쿠버네티스를 기반으로 운영됩니다. 수백 명의 개발자가 이 환경에서 다양한 대고객 서비스를 개발하고 운영합니다. AI 서비스도 같은 기반을 활용할 수 있도록, GPU 워크로드를 기존 쿠버네티스 클러스터 안에서 실행할 수 있게 해야 했습니다.

그래서 저희의 첫 과제는 쿠버네티스가 GPU를 자원으로 인식하고 할당하며, 컨테이너에서 사용할 수 있도록 연결하는 것이었습니다. 이 글에서는 GPU를 인식하고 워크로드에 할당할 수 있는 상태를 GPU-aware라고 부르겠습니다.

하지만 GPU를 사용할 수 있게 된 뒤에도 운영에서 풀어야 할 문제는 남았습니다. 노드가 Ready여도 개별 GPU에는 오류가 있을 수 있었습니다. 점검이나 설정 변경을 마친 노드를 언제 다시 서비스에 투입해도 되는지 판단할 기준도 필요했습니다. 서비스마다 필요한 자원의 크기가 다른데 GPU를 한 장씩 제공하는 방식은 비효율적이었고요.

여러 팀이 GPU를 함께 쓰려면 플랫폼에서 이 문제들을 다뤄야 했습니다. GPU의 정상 여부를 판단하고, 검증된 노드만 워크로드를 받게 하며, 서비스에 필요한 단위로 자원을 나누고 배치할 수 있어야 했습니다. 저희는 이러한 운영 조건까지 갖춘 상태를 GPU-native라고 부르고 있습니다. 토스증권은 멀티테넌트 GPU 클러스터를 운영하며 이 조건들을 하나씩 갖춰 왔고, 필요한 경우 업스트림에도 기여했습니다.[1]

흥미로운 점은 쿠버네티스 자체에서도 관련 변화가 이어지고 있다는 것입니다. DRA(Dynamic Resource Allocation)[2]는 단순히 ‘GPU 한 개’를 요청하는 데서 나아가, 필요한 조건을 가진 장치를 요청하고 할당받을 수 있도록 합니다. 저희가 지난 2년 동안 별도 구성 요소와 운영 로직으로 보완해 온 문제 중 일부가 쿠버네티스 자체에서도 다뤄지고 있는 셈입니다.

이 글에서는 먼저 GPU-aware한 쿠버네티스를 구성하는 기본 요소를 살펴보겠습니다. 이어 실제 운영에서 마주한 여러 문제와, 이를 해결하며 GPU-native한 클러스터로 발전시켜 온 과정을 공유하겠습니다.

1단계. GPU-aware한 클러스터 구축하기

그럼 GPU-aware한 쿠버네티스를 구축하기 위해서는 무엇이 필요할까요? GPU 한 장이 파드에서 쓰이기까지는 총 네 스텝을 거쳐야 합니다.

Step 1. 하드웨어 / 드라이버

서버에 GPU 디바이스가 탑재되어 있고, 운영체제가 이를 사용할 수 있도록 NVIDIA 커널 드라이버가 준비되어야 합니다. NVIDIA 커널 드라이버가 없으면 운영체제부터 GPU를 장치로 인식하지 못하게 됩니다.

Step 2. NVIDIA Container Toolkit

NVIDIA Container Toolkit은 컨테이너 런타임과 NVIDIA 드라이버 사이를 연결합니다. 이를 통해 할당된 GPU를 컨테이너가 실제로 사용할 수 있게 되는데요. 노드가 GPU를 인식하더라도 이 연결이 없으면 컨테이너에서는 GPU를 사용할 수 없습니다.

Step 3. NVIDIA Device Plugin

여기까지 와도 쿠버네티스 API는 아직 GPU를 자원으로 인식하지 못하는데요. NVIDIA Device Plugin은 노드의 GPU를 kubelet에 등록합니다. kubelet은 이를 노드의 Capacity와 Allocatable에 nvidia.com/gpu라는 자원으로 반영하고, 스케줄러는 이 값을 기준으로 GPU를 요청한 파드에 배치합니다.

Step 4. 파드 계층

마지막은 사용자 영역입니다. 파드 스펙에서 nvidia.com/gpu를 요청하면, 앞에서 준비된 경로를 통해 컨테이너에 GPU가 연결됩니다.

각 스텝의 역할은 다르지만, 어느 한 곳에 문제가 생겼을 때 나타나는 결과는 비슷합니다. 노드에는 GPU가 있는데 쿠버네티스 자원으로 나타나지 않거나, 파드는 배치됐지만 컨테이너에서 GPU를 사용하지 못하게 됩니다.

실제 운영에서 드라이버와 Container Toolkit, Device Plugin을 각각 설치하고 호환되는 버전과 설정을 유지하는 것은 분명 운영 부담인데요. GPU 노드가 늘어날수록 모든 노드에서 동일한 구성을 유지하기 어려워지고, 구성 차이가 장애로 이어질 가능성도 커집니다.

앞선 네 스텝을 거치면 GPU는 쿠버네티스의 스케줄링 대상이 되고, 컨테이너에서도 사용할 수 있게 됩니다. 이 글에서 말하는 GPU-aware한 상태입니다.

2단계. GPU-aware만으로 충분할까?

GPU 메모리는 어떻게 관리될까요?

GPU-aware한 상태가 되었다면 GPU 운영의 모든 문제가 해결된 걸까요? GPU가 보이고 사용할 수 있다는 것과, 그 내부 자원까지 쿠버네티스가 제어한다는 것은 다른 이야기입니다.

이 차이를 이해하려면 CPU와 메모리, GPU가 서로 다른 제어 경로를 거친다는 점부터 살펴볼 필요가 있습니다.

CPU와 시스템 메모리는 리눅스 커널의 cgroup을 통해 컨테이너 단위로 제어가 가능합니다. 컨테이너가 사용할 수 있는 CPU 시간과 메모리 한도를 정하면, 한도를 넘었을 때 커널이 개입합니다. 쿠버네티스의 CPU와 메모리 자원 관리도 이 기능을 바탕으로 동작해요.

반면 GPU 메모리는 쿠버네티스가 사용하는 cgroup 기반의 자원 제어 경로에 포함되지 않아요. 앞서 설명했던 것과 같이 컨테이너가 GPU를 사용하기 위해서는 NVIDIA Container Toolkit의 도움이 필요합니다.

NVIDIA Container Toolkit은 컨테이너 런타임과 연동해, 할당된 GPU 디바이스와 필요한 드라이버 라이브러리를 컨테이너에 연결하는데요. 이를 통해 CUDA 애플리케이션은 /dev/nvidia* 디바이스와 libcuda.so를 사용해 호스트의 GPU에 접근할 수 있습니다.

이 구조에서 Device Plugin과 kubelet은 어떤 GPU를 컨테이너에 할당할지 결정하고, Container Toolkit은 선택된 디바이스를 컨테이너가 사용할 수 있도록 연결합니다. 하지만 쿠버네티스가 제어할 수 있는 경계는 여기까지입니다.

nvidia.com/gpu: 1은 GPU 장치 하나를 할당한다는 의미이지, 그 안에서 사용할 VRAM 크기나 연산 비율까지 지정한다는 뜻은 아닙니다. 즉, 쿠버네티스는 CPU와 메모리를 cgroup으로 제어하듯 GPU 내부 자원을 직접 제어하지는 못합니다.

이 한계는 VRAM을 사용할 때 분명히 드러납니다. 쿠버네티스에는 memory: 4Gi처럼 컨테이너 메모리를 요청하고 제한하는 방법이 있지만, vram: 40Gi처럼 GPU 메모리를 요청하는 표준 자원은 없어요.

그래서 VRAM이 부족해졌을 때도 쿠버네티스가 이를 제어할 수 없습니다. 애플리케이션은 CUDA OOM 같은 오류를 만나고, 실제 운영에서 그 원인을 쿠버네티스 이벤트만으로 진단하기는 어려워요. 파드가 종료된 뒤 GPU 상태가 정상으로 돌아왔는지는 쿠버네티스의 기본 이벤트와 자원 상태만으로 충분히 확인할 수 없습니다.

이처럼 GPU-aware한 상태는 GPU 운영의 출발점이었지만, VRAM은 쿠버네티스가 GPU를 인식하는 것과 운영 가능한 상태로 이해하는 것이 다르다는 점을 보여 주는 대표적인 예였습니다. GPU를 할당할 수 있다는 것이 그 안의 메모리 사용량까지 같은 방식으로 제한할 수 있다는 뜻은 아니었습니다.

GPU를 사용할 수 있게 된 뒤, 실제 서비스를 운영하기 위해서는 다음 세 가지 질문에도 답해야 했습니다.

질문 1. Node Ready는 GPU Ready인가?

쿠버네티스의 Node Ready는 노드와 kubelet의 기본적인 동작 상태를 보여 주지만, 개별 GPU와 GPU 스택의 정상 상태까지 의미하지는 않습니다. 노드가 Ready이고 파드가 Running이어도 특정 GPU에서는 이미 ERR! 상태나 Xid 오류가 발생했을 수 있습니다.

따라서 쿠버네티스가 보여 주는 상태와 별개로, 드라이버와 CUDA 실행 경로가 정상인지, 운영 중인 GPU 내부에서 어떤 오류가 발생하고 있는지 판단할 수 있어야 했습니다.

질문 2. 언제 GPU 노드를 서비스에 투입할 수 있는가?

GPU의 상태를 확인할 수 있게 된 것과, 그 노드를 실제 서비스에 투입해도 된다고 판단하는 것은 또 다른 문제였습니다. 새로운 GPU 노드가 클러스터에 연결되고 자원으로 등록됐다는 사실만으로는 토스증권의 서비스 워크로드를 받을 준비가 끝났다고 볼 수 없었습니다.

OS·커널·드라이버와 CUDA 버전이 토스증권 GPU 클러스터의 표준 구성에 맞는지, GPU가 부하를 견디는지, 쿠버네티스에 정상적으로 편입됐는지, 실제 CUDA 연산과 모델 서빙이 동작하는지 확인해야 했습니다. 신규 장비뿐 아니라 장애 점검을 마치고 돌아온 장비에도 동일하게 적용할 수 있는 명확한 투입 기준이 필요했습니다.

질문 3. GPU 한 장은 서비스에 적절한 제공 단위인가?

서빙 워크로드를 효율적으로 배치하려면 단순히 GPU를 “쓸 수 있다”에서 한 걸음 더 나아가야 합니다. 서비스마다 필요한 연산량과 VRAM, 격리 수준이 다르기 때문에, 플랫폼은 물리 GPU 한 장보다 더 세밀한 제공 단위를 가져야 하는데요. 그러나 0.5코어처럼 쪼개서 요청 가능한 CPU와는 달리, nvidia.com/gpu 같은 확장 리소스는 정수 단위로만 요청할 수 있습니다.[4]

GPU를 더 작은 단위로 나눈 뒤에도 해결할 문제가 남아 있었습니다. 분할한 자원을 여러 물리 GPU에 분산할지, 한 GPU부터 채울지에 따라 Full GPU 확보와 구성 변경의 유연성이 달라지기 때문입니다. 서비스에 맞는 제공 단위뿐 아니라, 그 단위를 어떻게 배치할지도 함께 결정해야 했습니다.

이 세 질문에 답하기 위해서는 GPU를 단순히 인식하고 할당하는 데서 나아가, GPU의 상태를 판단하고, 서비스 투입 기준을 세우며, 자원을 나누고 배치하는 방식을 보완해야 했습니다. 다음 단계에서는 이 세 질문에 답하기 위해 무엇을 바꿨는지 살펴보겠습니다.

3단계. 클러스터를 GPU-native하게 만들기

1. Node Ready와 GPU Ready 구분하기

쿠버네티스의 노드 상태 조건인 Node Ready=True는 kubelet이 정상적으로 상태를 보고하고, 노드가 파드를 실행할 기본 조건을 갖췄다는 뜻입니다. Pod Running 역시 파드의 실행 단계를 나타낼 뿐, 그 안에서 GPU 워크로드가 정상적으로 동작한다는 것을 보장하지는 않습니다.

그래서 저희는 GPU Ready를 별도의 운영 기준으로 정의했습니다. GPU 실행 경로가 모두 동작하는지, 기대한 GPU 자원이 노출되는지, 개별 장치의 상태 조회가 정상인지, 복구가 필요한 오류가 없는지를 함께 확인하는 기준입니다.

GPU Ready를 판단하려면 실행 전 스택 검증, 실행 중 상태 관측, 장애 신호와 대응의 연결이라는 세 가지 관점이 필요했습니다.

nvidia-validator — GPU 스택 상태 검증

먼저 GPU 워크로드에 필요한 스택이 정상인지 확인해야 했습니다. GPU 파드가 실행되려면 드라이버, Container Toolkit, Device Plugin, CUDA가 각각 정상적으로 동작해야 합니다. nvidia-validator는 이 요소들이 기본 검증을 통과했는지 확인합니다.

문제는 nvidia-validator가 통과했다고 해서 항상 “모든 GPU가 정상”이라고 말할 수는 없었다는 점이었어요. 실제로 운영 중인 H100 노드 하나에서 dcgm-exporter가 nvml error: unknown error로 CrashLoopBackOff에 빠진 적이 있었습니다.

노드에서 nvidia-smi를 확인해 보니 H100 GPU 네 장 중 한 장이 ERR! 상태였는데요.

당시 nvidia-validator는 이 노드를 정상으로 보고 있었습니다. nvidia-validator의 드라이버 검증이 nvidia-smi 명령의 종료 코드에 의존하고 있었기 때문인데요. 개별 GPU가 ERR!로 표시돼도 명령 자체는 exit 0이었던 거죠. 기본 검증의 성공과 저희가 판단하는 개별 GPU의 정상 상태가 같지 않았던 것입니다.

그래서 NVIDIA의 기본 검증 체계는 유지하면서, 저희 운영 기준으로 GPU readiness를 판단하는 별도 DaemonSet을 구성했습니다. readiness를 결정하는 DaemonSet에서는 nvidia-smi 출력의 ERR!, 치명적인 Xid, NVIDIA Device Plugin이 보여 주는 GPU 수와 실제 PCI 디바이스 수의 차이를 함께 보도록 했어요.

이렇게 보완한 판정 결과는 전부 노드별 메트릭으로 노출됩니다. 아래는 저희가 실제 대시보드에서 보는 지표들입니다.

이 중 드라이버, Container Toolkit, Device Plugin, CUDA 네 개의 readiness 신호가 모두 1이어야 GPU 실행 경로가 정상이라고 판단했습니다. 물리 GPU와 노출된 자원의 수, 마지막 검증 성공 시각은 장치 누락이나 검증 중단을 발견하기 위한 보조 기준으로 사용했습니다.

이렇게 실행 전 GPU 스택의 상태를 확인할 수 있게 되었습니다. 그러나 검증 시점에 GPU 스택이 정상이라는 것과, 워크로드가 실행되는 동안 GPU가 어떤 상태인지를 아는 것은 다른 문제였습니다.

DCGM Exporter — GPU 상태 메트릭 상시 관측

워크로드가 실행되기 시작하면 GPU 상태는 계속해서 변하는데요.

DCGM Exporter는 GPU 사용률과 VRAM, 온도, 전력, ECC·Xid 오류, PCIe·NVLink 상태를 Prometheus 메트릭으로 노출합니다. 쿠버네티스 이벤트나 Node Ready만으로는 보이지 않는 GPU 내부 상태를 관측 체계 안으로 끌어오는 역할을 수행해요.

저희는 메트릭의 개수를 늘리는 것보다, 운영자가 답해야 하는 질문에 맞춰 필요한 지표를 묶는 데 집중했습니다.

각 메트릭이 답하는 질문은 서로 다릅니다. 예를 들어 DCGM_FI_DEV_GPU_UTIL은 GPU에서 작업이 실행되고 있는지를 보여 주지만, 서빙 워크로드가 연산 유닛을 얼마나 활용하는지 판단하려면 DCGM_FI_PROF_SM_ACTIVE 같은 프로파일링 지표를 함께 봐야 했습니다.

이처럼 DCGM Exporter를 통해 운영 중인 GPU의 내부 상태를 파악할 수 있게 되었습니다.

하지만 GPU 상태를 볼 수 있다는 것과, 장애를 제때 알아차려 대응하는 것은 다른 문제였습니다. 마지막으로 GPU의 장애 신호를 실제 대응으로 연결해야 했습니다.

Xid Error — 장애 신호를 알럿으로

Xid는 NVIDIA 드라이버가 GPU 관련 오류를 감지해 운영체제의 커널 로그에 남기는 오류 보고입니다. 문제는 이 신호가 쿠버네티스 이벤트에서는 관측되지 않는다는 것인데요. Node Ready여도, Pod Running이어도, 특정 GPU에서는 이미 오류가 발생했을 수 있다는 겁니다.

이는 실제 운영에서 중요한 차이점이었습니다. 서빙 워크로드가 GPU에 배치된 뒤 CUDA 오류나 NVML 오류로 실패하면, 쿠버네티스 이벤트만 봐서는 원인이 파드 문제인지, 노드 문제인지, 특정 GPU 디바이스 문제인지 알 수 없는 거죠.

그렇다고 Xid가 보이면 곧바로 노드를 장애로 판단할 수 있는 것도 아닙니다. 예를 들어 Xid 31은 GPU 메모리 페이지 폴트를 나타냅니다. 주로 애플리케이션의 잘못된 메모리 접근으로 발생하지만, 드라이버나 하드웨어 문제일 가능성도 있습니다.

그래서 Xid가 발생했는지뿐 아니라, 어떤 워크로드에서 발생했는지, 같은 GPU에서 반복되는지, readiness 신호와 함께 봤을 때 워크로드를 계속 받아도 되는 상태인지를 함께 봐야 했습니다.

저희는 이러한 판단을 실제 대응으로 연결하기 위해 Xid를 단순 로그가 아니라 노드·GPU·워크로드 정보를 함께 전달하는 알럿으로 구성했습니다.

실제로 운영 중인 H100 GPU 한 장에서 HBM의 복구 불가능한 메모리 오류인 DBE(Double Bit Error)가 발생한 적이 있었습니다. 해당 GPU를 사용하던 vLLM 엔진이 두 차례 종료됐고, Xid 알럿과 GPU readiness 신호도 같은 시간대에 변했습니다. 워크로드는 다른 노드로 재스케줄돼 서비스는 계속됐지만, 파드가 종료됐다는 사실만으로는 애플리케이션 문제인지 GPU 하드웨어 문제인지 구분하기 어려웠습니다.

저희는 이미 Xid 기반으로 가시성을 구성해 놓았기 때문에, 이때 발생한 신호를 하나의 장애 흐름으로 읽을 수 있었습니다. HBM에서 복구 불가능한 DBE가 발생했고(Xid 48·171), 오류가 GPU 전체에 확산되지 않고 해당 vLLM 워크로드에 격리됐습니다(Xid 94). 이후 row remapping이 기록됐고(Xid 63), 드라이버는 GPU를 비우고 리셋해야 한다는 복구 동작을 요구했습니다(Xid 154).

Xid를 단순 오류 카운트가 아니라 격리와 복구, 재투입 여부를 결정하는 운영 신호로 사용한 사례였습니다.

요약하자면

쿠버네티스의 Node Ready와 GPU Ready는 다릅니다. GPU를 쿠버네티스 자원으로 등록한 뒤에도 운영자는 아래 세 가지를 확인할 수 있어야 합니다.

이 세 가지를 확인할 수 있게 되면서 Node Ready와 GPU Ready를 구분해 운영할 수 있게 되었습니다.

여기까지가 GPU 상태를 관측하고, 장애 신호를 운영 판단으로 연결하는 과정이었습니다. 그러나 GPU의 상태를 판단할 수 있게 된 것과, 신규 또는 복구된 GPU 노드를 실제 서비스에 투입해도 된다고 판단하는 것은 또 다른 문제였습니다.

2. 검증된 GPU만 서비스에 투입하기

토스증권은 Blackwell 시리즈를 도입하면서 앞에서 정리한 GPU 상태 판단 기준을 신규 장비의 투입 과정에도 적용해야 했습니다.

새로운 GPU 아키텍처가 들어오면 하드웨어만 바뀌는 것이 아닌데요. 드라이버, CUDA, NVIDIA Device Plugin, GPU Operator, DCGM, MIG 구성, 실제 서빙 워크로드까지 모두 다시 맞춰 봐야 합니다. 그래서 저희는 운영 중 정립한 판단 기준을 신규 GPU 노드의 투입 전 검증 절차로 묶고, 이를 GPU 시범운행(preflight)이라는 절차로 구현했습니다.

GPU 시범운행은 GPU 자체의 동작 여부만 확인하는 데 그치지 않습니다. 표준 스펙, GPU 스택, 하드웨어, 쿠버네티스 편입 상태, 실제 CUDA와 모델 서빙을 차례로 검증해, 이 장비가 토스증권의 서비스 워크로드를 받을 수 있는 상태인지 판단하는 최종 투입 기준입니다.

검증은 다음과 같은 순서로 진행됩니다.

"투자의 힘을 모두에게"라는 토스증권 미션을 담은 프롬프트에 새 GPU가 다음 토큰을 이어서 출력하면 최종 검증이 통과됩니다. 드라이버가 로드되는 것만으로 실제 서비스 워크로드가 동작한다고 볼 수 없기 때문에, CUDA 커널과 작은 LLM 서빙까지 통과 조건으로 삼았습니다.

각 관문의 결과는 메트릭으로 수집되며, 모든 검증을 통과한 노드에만 preflight=passed 라벨이 붙습니다.

저희는 이 라벨을 서비스 스케줄링 게이트로 사용합니다. 검증을 통과한 노드는 cordon을 해제해 워크로드를 받을 수 있게 하고, 하나라도 실패한 노드는 cordon 상태로 유지합니다.

신규 GPU 노드와 하드웨어 점검 후 복귀한 노드는 모든 관문을 통과해야만 스케줄 대상이 됩니다.

이렇게 노드 투입 기준을 세운 뒤, 마지막으로 남은 문제는 한정된 GPU를 서비스가 필요로 하는 크기에 맞춰 어떻게 효율적으로 제공할 것인가였습니다.

3. GPU를 서비스에 맞는 단위로 제공하기

토스증권은 GPU를 서비스에 필요한 단위로 제공하기 위해 MIG(Multi-Instance GPU)를 선택했습니다. 이 이야기는 이전에 GPU를 밀도 있게 쓰는 방법 — 토스증권의 GPU 가상화(MIG) 도입기[5]에서 자세히 다뤘습니다. MIG는 GPU를 하드웨어 수준에서 여러 개의 독립 인스턴스로 쪼개, 조각 하나하나가 연산 유닛과 메모리를 물리적으로 격리한 채 별도의 GPU처럼 동작할 수 있게 합니다.

하드웨어 기반의 가상화인 MIG에는 여러 장점이 있지만, 문제도 있는데요. MIG 인스턴스를 수동으로 관리하기 위해 노드마다 접속해 필요한 크기의 인스턴스를 직접 만들고, 구성이 바뀔 때마다 다시 설정해야 한다는 운영 비용입니다. 노드가 늘어날수록 이 비용은 같이 증가하고요.

이러한 문제를 피하기 위해 MIG Manager를 사용했습니다. 원하는 MIG 구성을 ConfigMap에 정의하고, 노드 라벨로 적용할 구성을 선택하면, 각 노드의 GPU가 선언한 구성에 맞게 자동으로 설정됩니다. 노드마다 접속해 MIG 인스턴스를 수동으로 구성하던 부담을 줄일 수 있었습니다.

하지만 GPU를 원하는 크기로 쪼개는 것과, 만들어진 조각을 효율적으로 배치하는 것은 또 다른 문제였는데요. MIG Manager는 MIG 구성을 만들고, 워크로드에 어떤 인스턴스를 할당할지는 NVIDIA Device Plugin이 결정합니다.

실제 Device Plugin의 getPreferredAllocation 함수에서도 사용 가능한 디바이스와 요청 수량을 받아, 설정된 정책에 따라 할당할 디바이스를 선택하는 흐름을 확인할 수 있습니다.

서비스의 자원 요구 사항에 따라 Full GPU와 여러 MIG 프로파일 사이를 유연하게 전환하려면, 사용 중인 MIG 인스턴스가 어느 물리 GPU에 배치되는지도 중요했습니다. 하지만 Device Plugin의 기본 정책인 Distributed Allocation은 MIG 조각을 여러 물리 GPU에 골고루 배치합니다.

그 결과, 사용하는 MIG 조각이 몇 개뿐이어도 여러 GPU가 부분적으로 점유됐습니다. Full GPU를 확보하거나 MIG 프로파일을 변경하려면 여러 GPU를 함께 비워야 했고, 원하는 구성으로 유연하게 전환하기 어려웠습니다.

그래서 MIG 인스턴스를 한 물리 GPU부터 채워, 완전히 비어 있는 GPU를 남기는 Packed Allocation이 필요했습니다.

이를 위해 사용자가 GPU 디바이스의 배치 정책을 선택할 수 있도록 allocationPolicy 개념과 Packed Allocation을 구현해 NVIDIA k8s-device-plugin에 제안했습니다.[1] 이 변경은 업스트림에 머지됐으며, v0.20.0부터 sharedDevicesAllocationPolicy 설정(packed/distributed)으로 제공됩니다.

마치며 — GPU를 쿠버네티스 운영 체계 안으로

GPU를 인식하고 할당할 수 있는 GPU-aware한 클러스터를 만드는 일은 시작이었습니다. 안정적이고 효율적으로 운영하려면 GPU가 정상인지 판단하고, 검증된 노드만 서비스에 투입하며, 워크로드에 맞게 자원을 나누고 배치할 수 있어야 했습니다.

저희는 GPU 스택 검증과 DCGM·Xid 관측으로 Node Ready와 GPU Ready를 구분했고, GPU 시범운행이라는 절차로 서비스 투입 기준을 세웠습니다. MIG로 서비스에 필요한 단위의 GPU를 제공하고, Packed Allocation을 구현해 업스트림에 기여하며 배치 방식도 운영 요구에 맞게 보완했습니다. 이렇게 GPU-aware한 클러스터에 운영 조건을 하나씩 갖춰 가는 과정이 저희가 말하는 GPU-native로의 전환이었습니다.

이 과정에서는 쿠버네티스 운영 경험과 GPU·모델 서빙에 대한 이해가 함께 필요했습니다. Data Infra 팀과 ML Platform 팀이 각자의 경험을 바탕으로 문제를 함께 풀어 갈 수 있었던 이유이기도 합니다. 이 글이 쿠버네티스에서 GPU를 운영하는 분들께, 현재 클러스터에 어떤 운영 기준이 더 필요한지 점검하는 데 도움이 되었으면 합니다.

참고자료

안녕하세요, 토스뱅크 프론트엔드 개발자 이다용입니다.

토스뱅크 프론트엔드에서는 Next.js Pages Router를 주로 사용해요. 그런데 Pages Router는 유지보수 모드예요. 보안 패치와 버그 수정은 이어지지만 새 기능은 들어오지 않죠. 언젠가 다음에 쓸 것을 정해야 했고, 가장 먼저 살펴본 선택지가 App Router와 React Server Components(RSC)였어요. 필요한 데이터를 컴포넌트마다 가져오고, 준비된 영역부터 보여준다는 점이 매력적이었거든요.

2025년 가을, 프레임워크에 관심 있는 동료들이 모여 기술그룹을 만들었어요. 현구님, 지우님, 현웅님과 실제 서비스를 옮겨보고 매주 막히는 지점을 공유했어요.

결론은 도입하지 않는 것이었어요. 저희 화면에서 얻을 수 있는 이득에 비해, 서비스의 안정성을 지키며 전환하고 유지하는 비용이 컸거든요.

어떻게 그 결론에 닿았는지, 검토 과정에서 마주한 질문들을 따라 이야기해볼게요.

준비된 것부터 보여주면 더 좋을까요?

기존에는 서버에서 화면을 그릴 때 필요한 데이터를 getServerSideProps 한 곳에서 모아 가져왔어요. 페이지 단위로만 쓸 수 있다 보니, 저희 구현에서는 API 하나가 실패하면 정상적으로 받은 데이터까지 다시 요청하는 경우가 있었어요.

App Router에서는 데이터를 가져오는 컴포넌트를 나누고 각각을 Suspense로 감싸, 준비된 영역부터 보여줄 수 있어요.

토스뱅크의 화면은 대부분 토스 앱 안의 웹뷰로 이뤄져 있고, 요소가 주로 세로 한 줄로 쌓여요. 이 구조에서도 영역을 따로 보여주는 것이 자연스러운지 직접 재봤어요.

세 영역에 각각 1초, 3초, 5초 지연을 주고, 브라우저가 화면을 언제 그리는지 녹화했어요. 웹뷰는 대부분 안드로이드에서 Chromium, iOS에서 WebKit으로 돌아가기 때문에 두 엔진을 함께 봤고요.

첫 콘텐츠가 그려지는 시점(FCP)이 Chromium에서는 64밀리초, WebKit에서는 5,065밀리초였어요. WebKit은 마지막 섹션이 준비될 때까지 첫 표시를 미뤘어요. 화면을 그리기 전에 콘텐츠가 충분한지 판단하는 기준이 있어서인데, 이 때문에 표시가 늦어지는 현상은 공개 이슈에서도 논의되고 있어요.

우회는 가능했어요. 화면 위에 눈에 보이지 않는 SVG를 넣자 WebKit의 FCP가 103밀리초로 줄었어요. 두 엔진 모두 준비된 영역부터 그리기 시작한 거예요.

그런데 먼저 그리기 시작하니 다음 문제가 보였어요. 스켈레톤이 실제 콘텐츠로 바뀔 때 높이가 달라지거든요. 세로로 쌓인 화면에서는 위쪽 영역의 높이가 늘어나면, 이미 보고 있던 아래쪽 내용까지 그만큼 아래로 밀렸어요.

스켈레톤 높이를 콘텐츠가 들어갈 높이와 최대한 비슷하게 맞추자 움직임은 줄었어요. 레이아웃 이동값도 0.138에서 0.036으로 내려갔고요. 다만 섹션을 추가할 때마다 로딩 화면을 만들고, 콘텐츠가 바뀔 때마다 다시 맞춰야 했어요. 영역을 잘게 나눠 먼저 보여주는 이득보다, 화면이 흔들리지 않도록 관리하는 부담이 더 컸어요.

RSC를 우리 코드에서 얼마나 활용할 수 있을까요?

스트리밍을 넓게 쓰기는 어렵겠다고 봤지만, 그것만으로 App Router를 접을 수는 없었어요. 스트리밍을 쓰지 않더라도 RSC에는 따로 기대할 것이 있었거든요.

가장 큰 건 번들 크기예요. Server Component의 구현과 거기서만 쓰는 의존성은 클라이언트 번들에서 아예 빠지거든요.

부차적으로는 데이터를 가져오는 코드를 정리할 수 있었어요. 기존에는 인증 정보를 getServerSideProps에서 꺼내 서버용 API 함수에 넘겨야 했는데, App Router의 서버 코드에서는 headers()로 직접 읽을 수 있어요. 인증을 챙기는 일이 데이터를 가져오는 함수 안으로 들어가는 거예요. 브라우저에서 쿠키가 알아서 실려 나가듯, 서버에서도 부르는 쪽은 인증을 신경 쓰지 않아도 되고요.

다만 headers()를 Client Component에서 직접 사용할 수는 없어요. 서버에서 렌더링되는 동안에도 마찬가지예요. next/headers를 가져오는 순간 그 파일 자체가 브라우저로 나갈 수 없게 되기 때문에, 한 파일 안에서 조건문으로 갈라 쓰는 방법은 통하지 않았어요.

그래서 쓴 방법이 패키지의 환경별 분기예요. package.json의 조건부 export로 RSC용 구현과 클라이언트용 구현을 나누면, 호출하는 쪽에서는 같은 경로로 가져다 쓸 수 있어요. 구조를 단순화하면 다음과 같아요.

RSC용 구현만 headers()로 인증 정보를 읽어 붙여요. 브라우저용 구현은 기존 방식 그대로예요. 쿠키가 알아서 실려 나가니 따로 할 일이 없거든요.

이제 부르는 쪽은 어느 환경인지 몰라도 돼요. 쿼리 정의 하나로 서버에서 미리 가져올 때와 브라우저에서 조회할 때를 모두 처리해요.

쿼리마다 서버용 코드를 따로 만들던 일이 사라지는 거예요. 처음에는 부차적인 이득이라고 봤는데, 만들어서 써보니 개발 흐름이 눈에 띄게 단순해졌어요. 번들 크기만큼이나 큰 이점이라고 생각을 바꿨어요.

다만 서버에서만 렌더링되는 트리(RSC)가 생긴 게 장점만 있는 건 아니었어요. 어디까지가 그 트리이고 어디부터 브라우저에서 도는 코드인지를 계속 구분해야 하거든요. 저희가 마주한 비용은 대부분 여기에서 나왔어요.

먼저 경계를 그을 수 있는 자리가 생각보다 적었어요. 검토한 화면에는 버튼, 입력, 웹뷰에서 앱으로 요청을 보내는 앱 브릿지 호출처럼 브라우저에서 처리할 동작이 많았거든요. Client Component로 남는 영역이 많았고, RSC를 쓸 수 있다고 본 자리는 주로 화면을 그리기 전에 데이터를 가져오는 부분이었어요. 거기서 데이터를 모두 기다린 뒤 화면을 보여준다면, 사용자가 겪는 로딩 흐름은 기존 방식과 크게 다르지 않았고요.

경계를 잘못 그었을 때 바로 드러나지 않는 것도 문제였어요. 앱 브릿지가 그랬어요. 앱 밖에서도 문제없이 돌아가도록 만들어져 있다 보니, Server Component에서 호출해도 에러 없이 그냥 넘어가거든요. 앱까지 요청은 가지 않는데도요. 이런 건 컴포넌트만 옮겨서는 드러나지 않아요. 함께 쓰는 공통 패키지도 새 실행 환경에 맞는지 하나씩 살펴봐야 했어요.

서버에서 캐시를 쓸 때도 새로 익혀야 할 규칙이 있었어요. 요청 간에 데이터를 재사용하는 캐시에 사용자별 응답을 저장할 때는, 캐시 키에도 사용자 구분이 들어가야 해요. 이를 빠뜨리면 다른 사용자의 응답이 재사용될 수 있거든요. 어떤 캐시가 어디까지 공유되는지 이해하고 써야 했어요.

요청 코드는 간결해졌지만, 이 경계를 익히고 안정적으로 다루는 비용은 늘었어요.

운영하면서 조금씩 옮길 수 있을까요?

Next.js는 Pages Router와 App Router를 함께 두고 화면을 하나씩 옮기는 점진적 마이그레이션을 지원해요. 저희도 일부 화면부터 적용하면서 이득과 비용을 확인하려고 했어요.

그런데 특정 경로 구조에서 기존 화면의 이동이 깨졌어요. basePath를 설정한 상태에서 Pages Router 화면끼리 이동하면, 경로 앞에 basePath가 두 번 붙었어요.

같은 이동을 두고 App Router 쪽의 구성을 바꿔보니 조건이 좁혀졌어요.

클라이언트 라우터는 이동할 주소가 App Router 쪽 화면인지 판단할 때 블룸 필터를 써요. 블룸 필터는 크기를 줄이는 대신 아닌 것을 맞다고 답하는 경우를 허용하고, 그래서 잘못 답해도 되돌릴 수 있는 자리에 쓰죠. 여기서도 맞다고 판단하면 페이지를 통째로 다시 불러와요. 서버는 실제 경로를 아니까, 판단이 틀렸더라도 화면은 제대로 나와야 하고요.

문제는 다시 불러오는 그 주소가 틀렸다는 점이었어요. basePath가 두 번 붙어 없는 주소로 가고, 사용자는 404를 봐요. 잘못 판단했을 때 되돌려주는 장치가 오히려 화면을 깨뜨린 거예요.

코드를 따라가 보니 App Router의 /a/[id]가 필터에 /a로 등록돼 있었어요. 이동할 주소의 앞부분을 하나씩 넣어보기 때문에, Pages Router의 /a/a도 /a에서 걸렸고요. 확률이 아니라 등록 방식 때문에 매번 걸린 거예요.

주소가 두 번 붙는 이유도 같이 나왔어요. Pages Router는 화면을 옮길 때 주소 앞에 basePath를 먼저 붙여요. 이미 붙어 있는 주소인데, 다시 불러올 주소를 만들 때는 확인 없이 한 번 더 붙인 거예요. 같은 유형의 이슈는 지금도 열려 있어요.

두 라우터를 함께 두는 건 위험을 줄이려고 고른 방법이었어요. 그런데 이 문제는 함께 두는 동안에만 생겨요. 안전하게 옮기려던 방법이 오히려 위험을 만든 셈이에요.

많은 개발자가 쓰면 해결도 빠를까요?

앞의 문제를 겪으면서도 크게 걱정하지는 않았어요. 많이 쓰는 프레임워크니까 필요한 기능이나 수정도 곧 나올 거라고 생각했거든요.

그런데 저희에게 필요했던 것들은 그렇지 않았어요. 로깅이 그랬어요. Pages Router의 router.pathname은 /blog/[slug] 같은 경로 패턴을 돌려줬어요. 화면별로 묶어서 집계하려면 이 패턴이 있어야 하거든요. 그런데 App Router의 usePathname()은 /blog/hello-world 같은 실제 주소만 돌려줘요. 이 정보를 제공하려는 PR은 2025년 10월 29일에 열렸고, 글을 쓰는 지금도 초안 상태예요.

사라진 router.events도 마찬가지였어요. URL 변화를 관찰하는 다른 방법은 있었지만, 기존에 쓰던 동작을 그대로 옮기려면 별도 패키지를 만들어 메워야 했어요.

많이 쓰인다고 우리 문제가 먼저 풀리는 건 아니었어요. 기다리는 시간과 그동안 직접 메우는 작업도 도입 비용이었고요.

그래서 Pages Router를 유지하기로 했어요

물론 이득도 있었어요. 데이터를 가져오는 코드가 정리되는 건 분명했고요. 다만 저희가 얻을 수 있는 이득에 비해, 전환하고 운영하는 비용이 컸어요.

그래서 이번에는 App Router를 도입하지 않고 Pages Router를 유지하기로 했어요. 앞으로도 새로운 기술을 검토할 때는 그 장점이 우리 서비스에서도 유효한지, 전환하고 운영하는 비용은 감당할 수 있는지 직접 확인하려고 해요.

앞으로도 검토할 기술과 내려야 할 결정은 많아요. 어떤 기술이 우리 서비스에 더 나은 선택일지 함께 고민해보고 싶은 분들의 토스뱅크 합류를 기다릴게요.

안녕하세요, 토스뱅크 ML Engineer 김경윤입니다.

지난 글 DS와 MLE가 함께 일하는 법에서, 마지막에 이런 문장을 한 줄 남겼어요.

AI로 코드를 작성하게 되면서, 역할 나누기를 넘어 코드 스타일까지 맞추는 게 새로운 협업 과제가 됐습니다.

오늘은 위 내용에 이어서 얘기해보려고 합니다. Coding Agent로 코드를 작성하면서 겪은 문제와, 그걸 어떻게 풀었는지에 대한 이야기예요. 결론부터 말하면, 저희가 찾은 답은 Agent Loop 안에 Feedback Loop를 하나 더 심는 것이었습니다.

Coding Agent로 작성하면서 시작된 문제

예전엔 이게 문제가 아니었습니다. 사람이 직접 코드를 작성했으니까요.

사람이 코드를 작성할 때는 다른 사람이 작성한 코드를 보면서 맥락을 파악해요. 리뷰를 주고받으면서 "아 이 팀은 이렇게 쓰는구나"를 자연스럽게 인지하게 되고요. 굳이 문서로 안 적어도 시간이 알아서 맞춰줬습니다.

그런데 에이전트는 전반적인 코드 맥락을 보지 않습니다. 수정이 필요한 일부 맥락만 파악하고, 그 안에서만 코드를 작성하다 보니, 큰 틀의 규칙을 잘 지키지 못하는 문제가 발생합니다.

처음엔 그냥 말로 알려줬습니다. "여기는 Enum을 쓰는 게 좋을 것 같아요", "if-else 보다 match을 쓰는 게 좋을 것 같아요" 같은 피드백을 리뷰마다 남기는 식이었죠.

그런데 이 방식은 결국 팀 약속을 각자의 기억에 맡기는 셈이 됩니다. 아는 사람이 있으면 고쳐지고, 아무도 못 보면 그냥 넘어가요.

그래서 다음으로 간 게 AGENTS.md 같은 Global Instruction이었어요. 프로젝트 루트에 두는 안내 문서인데, 세션이 시작될 때 에이전트가 이 문서를 먼저 읽고, 그대로 따르려고 합니다.

그런데 여기에 적어두는 것만으로는 해결되지 않았습니다.

Lost in the Middle

Global Instruction을 적용하고, 며칠 써보니 이상한 패턴이 보였습니다. 세션 초반엔 잘 지키지만, 길어지면 잘 안 지키는 패턴이었어요.

이 문제는 흔히 Lost in the Middle(긴 입력을 줬을 때 가운데 있는 내용을 모델이 잘 못 쓰는 현상)이라고 부르는 상황입니다. Context 오염이라고도 하고요.

세션 시작에 규칙을 읽긴 읽습니다. 그런데 그 뒤로 파일 읽기, 코드 작성, 테스트 결과가 계속 쌓입니다.

30번째 바퀴쯤 되면 에이전트는 세션 시작에 읽은 규칙보다 방금 읽은 코드와 맥락을 더 믿습니다. 맨 앞에 넣어둔 Context는 조용히 무시하게 되고요.

모델이 강하게 반응하는 자리는 맨 앞과 맨 뒤입니다. 문제는 대화가 길어질수록 맨 앞이 더 이상 ‘맨 앞’처럼 느껴지지 않는다는 거예요. 규칙은 어느새 한가운데, 가장 안 보는 자리에 가 있어요.

여기에 문제가 하나 더 있는데요. 세세한 규칙은 Global Instruction에 적기가 부담스럽다는 점입니다.

‘외부 라이브러리 타입은 반드시 내부 DTO로 한 번 매핑해야 한다’ 같은 것은 한 줄로 적을 수 있어요. 그런데 저희가 리뷰에서 실제로 주고받는 지적은 훨씬 자세합니다.

이런 걸 다 적으면 어떤 프로젝트에서 작업하든 Context를 크게 차지합니다. 규칙이 늘어날수록 그중 하나하나를 지키기는 오히려 더 어려워지고요. 앞에서 본 문제가 그대로 심해지는 거죠.

즉 문제는 ‘무엇을 알려주느냐’가 아니었습니다. ‘언제, 몇 개를 알려주느냐’였어요. 그래서 저희는 이 세세한 규칙들을 언제 어떻게 꺼낼지 고민하기 시작했어요.

Coding Agent는 어떻게 동작할까

먼저 Coding Agent가 어떻게 동작하는지부터 다시 봤습니다. 크게, 다섯 단계로 볼 수 있어요.

그리고 마지막 세 단계는 목표를 이룰 때까지 반복됩니다.

여기서 중요한 지점이 있는데요. 사용자가 요청을 한 번 하면, 에이전트는 그 안에서 Tool Calling을 수십 번 반복합니다. 파일 하나 고칠 때마다 한 번, 테스트 돌릴 때마다 한 번씩이요.

그런데 지금까지 팀 약속이 들어가던 자리는 맨 앞 한 곳뿐이었습니다. 반복 구간에는 아무것도 안 들어가고 있었던 거죠.

Linter Feedback Loop에서 가져온 아이디어

여기서 오래된 기억이 하나 떠올랐습니다.

LLM 성능이 지금 같지 않던 시절엔, 코드를 한 번에 제대로 못 짰어요. 그래서 흔히 쓰던 방법이 Linter(코드에 문법 오류나 나쁜 습관이 있는지 자동으로 검사해주는 도구)를 함께 쓰는 것이었습니다.

LLM이 코드를 쓰면 → Linter를 돌려서 → 에러 메시지를 다시 LLM에게 넣어주고 → 고치게 하고 → 통과할 때까지 반복하는 방법이었죠. 사람이 중간에서 맥락을 계속 날라줬습니다.

이 방식엔 장점이 하나 있었습니다. 방금 작성한 코드에 바로 코멘트를 남길 수 있다는 것이에요. "아까 세션 시작에 말했잖아"가 아니라, "방금 네가 쓴 이 줄이 문제야"라고 말할 수 있는 거죠.

그래서 Linter 자리에 팀 컨벤션을 넣으면 되겠다는 아이디어를 떠올렸어요. Linter는 "이건 문법이 틀렸어"를 말하는데, 저희가 넣고 싶은 건 "이건 우리 팀 방식이 아니야"거든요. 검사하는 내용만 다르고 흐름은 똑같습니다.

코드를 작성한 직후에 피드백하기

여기서 쓰는 장치가 Hook입니다. 에이전트가 특정 순간에 다다르면 자동으로 실행되는 작은 스크립트인데요. 세션이 시작될 때, 파일을 작성한 직후처럼 정해진 시점에 끼어들 수 있습니다.

저희가 고른 자리는 파일을 작성한 직후예요. 에이전트가 파일을 하나 작성하면, 그 직후에 방금 쓴 코드 본문을 훑어서 관련 규칙을 골라 넣습니다.

이렇게 팀 규칙을 모아두고 각 Hook에 꽂아주는 플러그인을 만들었어요. 이름은 pfmls-stylepack이에요. 아래에서는 줄여서 ‘Stylepack’이라고 부를게요.

규칙 파일 하나가 곧 규칙 하나입니다. 언제 띄울지를 정하는 발동 조건과, 실제로 에이전트에게 들어갈 문장이 한 파일에 같이 있어요.

여기서 중요한 건 속도예요. Hook은 파일을 작성할 때마다 도니까 즉시 끝나야 해요. 그래서 AI를 부르지 않고 정규식과 파일명 패턴 같은 간단한 방법으로 규칙을 골라요.

사실 처음엔 "정규식은 부정확하니 AI가 관련성을 판정하게 하자"고 생각해서 붙여봤어요. 그런데 재보니 요청 하나당 10초가 더 걸렸어요. Hook이 매번 AI를 부르니까요.

관련 있는지 없는지의 최종 판단은 어차피 규칙을 받아 든 에이전트가 하면 되거든요. 저희는 후보를 좁혀주기만 하면 돼요.

실제 동작 예시

팀원이 Verdict에 PASS를 하나 더 넣고, “새 판정값 추가했는데 알림 쪽도 좀 봐줘”라고만 입력했어요. 팀 약속 얘기는 한 마디도 안 했고요.

작업 중인 코드는 아래와 같았습니다.

문제가 눈에 잘 안 보입니다. 방금 추가한 PASS를 처리하는 분기가 없는데도, 아무데서도 에러가 안 나요. 알림만 조용히 안 나갈 뿐입니다. 반환값이 없는 함수라 타입 검사기가 걸릴 자리가 없거든요.

에이전트가 이 파일을 고쳐 쓰는 순간, Hook이 코드 본문에서 case Verdict.REJECT: 같은 모양을 보고 enum 분기 규칙을 걸어요.

그러면 이런 내용이 에이전트에게 바로 들어갑니다.

그러면 에이전트가 이 피드백을 읽고, 고칠 게 있는지 스스로 판단해서 이렇게 바꿔요.

빠져 있던 PASS 분기가 채워졌습니다. 앞으로 값이 하나 더 늘어도 assert_never에 걸리기 때문에, 실행해 보기 전 타입 검사 단계에서 바로 알 수 있고요.

다만 같은 얘기를 계속 반복하면 그것대로 Context를 잡아먹어요. 그래서 한 번에 최대 2개, 같은 규칙은 세션당 한 번만 넣도록 제한했습니다.

남은 문제, 전체적인 그림

이 Feedback Loop로 대부분의 문제가 풀렸습니다.

그런데 이걸로도 안 풀리는 종류가 하나 남았어요. 파일 하나만 봐서는 알 수 없는 문제인데요. 이번엔 저장소 계층을 새로 만드는 작업이었어요. 에이전트가 파일 두 개를 작성했어요.

파일 하나씩 보면 둘 다 멀쩡합니다. repository.py는 인터페이스와 구현을 제대로 나눴고, service.py는 생성자로 주입을 받고 있어요. 두 파일을 나란히 놓고 봐야 ‘서비스가 인터페이스가 아니라 구현체에 묶여 있다’가 보여요.

코드를 작성한 직후에 도는 Hook은 방금 쓴 그 파일 하나만 보기 때문에 이걸 잡지 못합니다.

• repository.py를 쓸 때: 2계층 저장소 규칙이 떴어요. 그런데 이 파일은 규칙을 잘 지켰으니 에이전트는 그냥 넘어가요.
• service.py를 쓸 때: 이 파일엔 class ...Repository 선언이 없어서 규칙이 아예 안 떠요.

그래서 Agent Loop가 마무리되는 자리에 한 번 더 넣기로 했어요.

에이전트가 "다 했어요" 하고 끝내려는 순간, 이번 작업의 변경 전체(git diff)를 다시 봅니다. 이제 두 파일이 한 덩어리로 들어오니까, 같은 규칙이 실제 위반을 짚을 수 있어요.

그러면 에이전트가 service.py의 타입을 인터페이스로 되돌립니다.

타입 이름 하나 바뀐 것뿐이지만, 이제 테스트에서 DB를 띄우지 않고 가짜 구현을 넣을 수 있습니다. 두 자리는 같은 규칙 저장소를 쓰지만, 성격이 달라요.

• 코드 작성 직후: 방금 쓴 파일 본문 하나, 빠르게, 최대 2개. 지금 쓰는 코드를 그 자리에서 고치게 하는 게 목적이에요
• 끝내기 직전: 이번 변경 전체, 조금 느리게, 최대 4개. 마지막 안전망이에요

여기까지를 한 장으로 정리하면 이런 그림입니다.

팀 공통 Context 주입과 실시간 전파

Stylepack이 Feedback Loop만 하는 건 아닙니다. 세션이 시작할 때 하는 일이 하나 더 있어요.

바로 레포의 언어 환경에 맞는 팀 공통 Context를 넣어주는 일이에요. 레포에 pyproject.toml이 있으면 Python 안내를, build.gradle이 있으면 Spring 안내를 붙입니다. Python 레포에 Kotlin 규칙이 뜨면 방해만 되니까요.

그런데 이걸 만들면서 풀어야 했던 문제가 하나 더 있었어요. 전파예요.

보통 새 Python 서비스를 만들 때는 Template 레포를 복사해서 시작합니다. 그 안에는 AGENT.md도 들어 있고, 팀 약속을 적어두기에 딱 좋은 자리로 보였어요.

문제는 복사하고 나면 끝이라는 것이었습니다. 원본을 아무리 좋게 고쳐도, 이미 복사돼 나간 서비스 레포로는 그 변화가 흘러가지 않아요. 템플릿은 복사되는 순간부터 늙기 시작합니다.

그래서 방향을 뒤집었어요. 각 레포에 규칙을 복사해 두는 게 아니라, 중앙 저장소 하나에 두고 플러그인이 주기적으로 당겨오게 했습니다. 세션이 시작될 때마다 백그라운드로 최신 규칙을 받아와요. 팀원은 아무것도 안 해도 늘 최신 규칙을 쓰게 되죠.

Stylepack 자체의 Feedback Loop

여기까지 만들고 나니 겉으로는 잘 돌아가는 것 같았습니다. 그런데 "정말 모든 규칙이 제대로 먹히고 있나?"라고 스스로 물어보니, 답을 하기가 어려웠어요. 에이전트에게 Feedback Loop를 만들어줬으면, 저희 규칙에도 Feedback Loop가 있어야 하는데요. 그래서 규칙이 뜨는 모든 순간을 파일에 한 줄씩 남기기 시작했습니다.

• 어떤 규칙이 어느 시점에 적용되었는지
• 어떤 조건 때문에 적용되었는지

조건이 너무 간단해서, 불필요한 Feedback을 하는 경우

enum 멤버를 키로 쓴 dict를 잡는 규칙이에요. 데이터를 enum 밖에 흩어놓지 말라는 규칙이죠.

이 조건은 이름 · . · 이름 · : 이 순서로 이어지는 자리를 찾아요. 그런데 이 순서를 만족하는 코드가 하나 더 있었습니다.

item.score:도 이름 · . · 이름 · : 이거든요. 그래서 dict가 아닌데도 그대로 걸렸습니다. 21개 세션에서 떴는데 코드가 바뀐 건 0이었어요. 둘을 갈라내는 건 콜론 바로 뒤 한 칸이었습니다. 발동 조건 끝에 공백 하나를 더 요구하는 것으로 해결됐어요.

이런 Feedback이 쌓이면 에이전트는 규칙 자체를 흘려듣게 됩니다. 틀린 지적은 안 하느니만 못하죠.

조건이 너무 까다로워서, 필요한 케이스에 Feedback을 하지 않는 경우

반복문 안에서 저장소를 조회하지 말라는 규칙이에요. 흔히 N+1이라고 부르는 문제죠.

for와 .forEach, 딱 두 형태만 보고 있어요. 그래서 이런 코드는 잡아요.

그런데 팀 PR 리뷰에서 사람이 실제로 잡은 N+1은 이 형태였어요.

for도 .forEach도 아니라서 규칙이 아예 안 떴어요.

.map, .flatMap을 조건에 추가할 수도 있습니다. 그런데 이렇게 넓히는 건 금방 한계가 와요. 반복을 표현하는 방법은 계속 늘어나기 때문입니다.

다시 보니 이건 코드 모양의 문제가 아니었어요.

이렇게 코드 모양이 아니라 실행돼 봐야 드러나는 문제는, 발동 조건으로 좁히기보다 상시 Context로 깔아두는 게 낫습니다. 그래서 팀 Context에 이렇게 한 줄 추가했어요.

기준은 이렇게 갈라요.

• 코드 모양으로 판정되는 건 규칙으로 — 보면 바로 알 수 있는 형태
• 실행돼 봐야 아는 건 상시 Context로 — N+1처럼 런타임에만 드러나는 문제

새 규칙은 PR 리뷰에서 가져와요

규칙은 사람이 직접 추가하기도 합니다. 리팩토링을 하다가 "이건 팀 규칙으로 두자" 싶으면 그 자리에서 만들어요.

그런데 그것만으로는 부족했습니다. 여러 PR에서 같은 피드백이 반복되는데, 아무도 그걸 규칙으로 옮기지 않는 경우가 많았거든요. 그래서 리뷰 코멘트를 모아 반복되는 지적을 찾아내는 입구를 따로 만들었어요.

실제로 이렇게 만들어진 규칙이 있어요. 한 서비스 레포의 PR 두 건에서 리뷰 코멘트를 묶었더니, 같은 지적이 반복되고 있었습니다.

@dataclass는 ‘값을 담는 상자’라는 뜻입니다. 그런데 이 클래스는 캐시를 들고 있고 조회도 해요. 읽는 사람에게 값처럼 보이는데 실제로는 서비스인 거죠. 값인 줄 알고 복사해 쓰다가 상태가 어긋나기 좋습니다.

그래서 이렇게 바꾸자는 코멘트가 여러 PR에서 반복됐어요.

이걸 규칙 하나로 옮겼어요.

여기서는 발동 조건에 이름 접미사라는 문턱을 하나 둔 게 중요합니다. @dataclass만 보면 멀쩡한 값 홀더에 전부 뜨거든요. Checker, Service, Manager처럼 ‘동작하는 물건’임을 드러내는 이름이 같이 있을 때만 뜨게 했습니다.

Stylepack Flywheel

마지막으로 Stylepack이 스스로 좋아지는 흐름을 한 장으로 보면 아래와 같아요.

마무리

팀 컨벤션은 정하는 것도 중요하지만, 잘 지켜지게 만드는 게 더 중요합니다. Coding Agent에게는 코드를 고친 바로 그 순간에 피드백을 줘야 잘 작동한다는 것을 알게 됐죠. 이런 고민을 같이 하고 싶으시다면, 토스뱅크에 합류해 주세요.

감사합니다.

*This is the English version of a previously published article.

What It Means for a Technical Writer to Be a Product Owner

Earlier, I broke down the work of Technical Writers (TWs) at Toss into four areas. The first was building products. But what does it actually mean for a TW to build a product? Let me start with my own experience.

I currently lead a product team called the Knowledge System Team. I work alongside developers, designers, and TWs to set the direction of our products and decide on our roadmap and priorities. I interview users directly and bring those insights back to the team. I plan features and sometimes build them myself using AI tools. In other words, I’m not simply someone who communicates documentation-related requirements. I work as a Maker who makes product decisions and helps build the product itself.

So why are TWs building products?

It comes down to what our product is fundamentally about: documentation and knowledge. TWs have spent years thinking deeply about questions like why some documents are difficult to read, what makes a good document, and how information should be structured so that AI can use it effectively. Over time, we’ve developed our own standards around these questions. That puts us in a unique position to bring some of the most important insights into a product built around documentation and knowledge.

Our end goal is to turn TW expertise into a product that connects documentation with workflows, allowing knowledge to build naturally as people work and making it easy for anyone to find and use. And here’s the product we’re building toward that vision.

todoc: A Product Built by Technical Writers

How do we build a documentation system that remains effective over time and scales across an organization?

Our search for an answer eventually led us to todoc, our internal documentation platform, last October.

As soon as we announced the beta, we were surprised by how many positive responses we received: “I want to try this right now,” and “This is exactly the documentation platform I’ve been waiting for.”

We realized that the need was there across the board. Teams that were already documenting their work wanted an easier way to connect their knowledge to AI, while teams whose documentation was still fragmented needed an easier way to start building up team knowledge in the first place.

Six months later, todoc has accumulated more than 500 documents and 40,000 valid pages, with over 1,000 people using it every month.

But why build a new product when we already had GitHub and other documentation tools? First of all, there were several problems with our existing internal documentation.

First, documentation built with static site generators (SSGs) was difficult for non-developers to use. Making a small edit meant cloning a repository, writing in Markdown, opening a pull request, and going through review. That workflow may feel natural to developers, but for designers or PMs, it could be enough friction to make them give up before they even start writing.

Second, our existing documentation tools had accumulated too many notes and too much “junk knowledge.” There were pages with no clear author, date or purpose; outdated documents that had long since changed; half-finished notes left behind and forgotten. You’ve probably seen this happen. Over time, all of this turns into documentation debt: a growing body of information that’s difficult to navigate, maintain, or trust.

Finally, knowledge was fragmented across whatever tools people happened to choose. Some lived in SSG-based documentation, some in other documentation tools, some in code, some in conversations on our internal messenger, and some only in people’s heads. Unless we could bring these fragmented sources together, we wouldn’t be able to build a reliable, usable body of organizational knowledge.

So we built todoc around four core principles.

1. Anyone should be able to write documents easily.

We removed as many barriers to documentation as possible. With todoc, anyone can create and edit documents directly. No matter where the information starts, whether it’s GitHub, another documentation tool, or our internal messenger, it can be connected to todoc.

2. Knowledge in todoc should be easy to use with AI.

Ultimately, one of the biggest reasons to collect and maintain high-quality knowledge is so that AI can use it. With todoc, putting that knowledge to work with AI is easy. Teams can connect it to their own bots and freely access it through APIs, CLI tools, or MCP. Different teams are already using it in different ways, from powering request-handling bots to organizing product specifications.

3. All internal knowledge should come together in one place, creating a Single Source of Truth.

todoc connects fragmented sources and turns them into complete, usable documents, so people no longer have to wonder, “Where am I supposed to find this?” Because there is one place to determine which information is current and still valid, todoc can serve as the organization’s Single Source of Truth (SSoT).

4. The system should be built to scale.

When a team wants to start documenting its work, it shouldn’t have to choose a new tool or build its own infrastructure. It should be able to start on top of todoc, which is already up and running. Each team is given its own documentation space within one platform.

Previously, every team or chapter had to choose its own tools, set up infrastructure, and spend time maintaining it. With todoc, team members can focus solely on the documentation itself. And we’re now expanding this structure to Toss affiliates as well.

What We Still Need to Solve

We’ve lowered the barrier to documentation, but the easier it becomes to create documentation, the harder it becomes to maintain its quality.

This is something TWs have thought about for a long time.

In the past, we addressed it manually. TWs reviewed documents themselves and checked whether documentation had become outdated. In todoc, we’ve started automating that work by translating the standards TWs have developed for “good documentation” into the product itself. For example, we provide AI-powered editing as well as bots that can automatically generate first drafts.

But people still had to make time to sit down and write things down. After seeing how people actually use todoc, I realized that wasn’t enough.

Deciding “I’m going to document this” and then turning it into a finished document takes significant time and effort. So instead, we’re designing todoc so that documents take shape naturally as the work happens.

todoc can turn decisions, discussions, and code from our internal workflows into documentation automatically. We’re also building systems that monitor code changes and discussions that happen after decisions are made, so documents can stay up to date without depending on someone remembering to maintain them.

And documentation isn’t just about collecting information or generating text. The real challenge is determining what knowledge is still valid.

Does a written policy match what has actually been implemented in code? Is this piece of knowledge still being used? How recently was it updated? These are the kinds of problems we’re now solving with todoc.

How TW Expertise Is Expanding and Shifting

In the past, one of the most important skills for a TW was the ability to write a good document. Now, the more important skill is the ability to design systems that consistently produce good documentation.

The expertise TWs have built up isn’t disappearing. It’s being embedded into systems in new ways.

• Our experience asking, “Why are some documents so hard to read?” has become a standard for documentation that anyone can write and AI can easily understand.
• Our judgment of what makes a good document has now become the foundation for AI-powered editing and automated reviews.
• Our ability to identify outdated documents and determine what information is still valid has become a system for identifying knowledge that can still be trusted today.

Within this shift, what we need to do is clear:

Once todoc has solved all of these problems, this is what I imagine my day looking like as both a product team lead and a TW.

I no longer have to post reminders asking people to review documents that haven't been updated in over a month. todoc is detecting outdated documents, notifying the right owners, and suggesting improvements. Documentation stays trustworthy without anyone having to constantly look after it. I no longer have to manually update the project management tools. Everything the teams produced along the way had already been captured and organized. I can spend my time thinking only about what we should do next. Release announcements and answers to recurring questions are all captured and preserved. New team members, and teams integrating with us for the first time, no longer have to repeat the same questions over and over again. Every time someone does a piece of work, it leaves behind knowledge that helps everyone else move faster. I would open my laptop, and quietly close it again, because there was nothing left for me to do, as todoc is running perfectly on its own.

This is where Toss’s Technical Writing Chapter is headed: turning TW expertise, and the standards behind that expertise, into systems.

Beyond that, we want to put systems in place that enable every organization to document its work well without relying on TWs to manage it.

And once that system is in place, we’ll move on to the next problem.

*This is the English version of a previously published article.

Hi, I’m Juyeon Han, Technical Writing Chapter Lead at Toss. In this series, I’ll share how Technical Writers (TWs) at Toss have expanded our role from simply writing documentation to designing the systems that manage knowledge across the organization.

“Why is this built this way?”

It’s the kind of question you hear, and ask, all the time at work. Maybe you track down the person who wrote the code and try to piece together what they remember. Maybe you dig through a year-old thread for context. And sometimes, there’s simply no one left to ask.

As we rely more on AI, this problem becomes even harder to ignore. AI may know a lot about the world, but it doesn’t know the context and history unique to your organization. So every time you ask it to do something, you have to fill in the gaps.

People often say that code is the Single Source of Truth (SSoT). But code only preserves the outcome. It can tell you what something does, but not necessarily why it was built that way or what decisions led to it. Most of us have probably stared at uncommented code at some point, trying to figure out how we got there.

That’s why I believe documentation matters as much as ever. A true SSoT is only complete when you have both the code and the context surrounding it.

Ultimately, we’re the ones who have to explain why the code is the way it is. If we want AI to work with what we know, we first have to capture that knowledge somewhere. And that’s the gap the Technical Writing Chapter has been working to fill.

But our job isn’t simply to write documents that fill in the missing context. Looking at what TWs do today, the role has changed significantly since I first joined Toss five years ago.

Our goals have changed, too. This year, we’re working toward a system where knowledge builds up on its own. And the ultimate goal of the Technical Writing Chapter is to make ourselves unnecessary.

When I first thought about how AI might change our work, I assumed Technical Writers would be among the first to be replaced. But I couldn’t have been more wrong. If anything, our work has expanded. So how did we get from writing technical docs to designing knowledge systems, with the ultimate goal of making ourselves unnecessary?

From Writing Documents to Bringing Knowledge to People

When I first started working on internal documentation at Toss, one of my first projects was creating onboarding documents for our Frontend Chapter. But as I worked on internal docs, something kept bothering me. To me, the goal of Technical Writing isn’t to produce great writing. It’s to help readers solve problems and accomplish what they need to do. And no matter how good a document is, people rarely read it from beginning to end. They look for the one thing they need. I do the same. So I started thinking: instead of writing a document and sending people a link, how could we make sure the knowledge inside it actually gets used?

That question led to Mr. Park (박씨), a chatbot we built. (*Refer to TMC25) It lets people ask questions conversationally from the messaging tools and IDEs they already use, then answers based on our existing documentation, with sources included.

Instead of asking people to go find the documentation, we brought the documentation to them.

What happened next was interesting.

People who had never been particularly interested in writing (or reading) documentation started coming to us.

“We want something like this for our chapter.” “Could we build this for our organization too?”

As Toss grew, people were getting tired of getting the same questions over and over. They wanted a way to retrieve institutional and tacit knowledge from a system.

At the same time, rapid advances in AI were making documentation more important than ever. If we wanted AI to understand our work and actually be useful, we first had to give it the knowledge and context to work with.

Documentation had long been treated as a chore. Suddenly, everyone wanted it.

It was fascinating to watch. And amid that shift, I started building a knowledge system that everyone at Toss could use. I’ll cover that product in more detail in the next article.

From Documentation to Knowledge Systems

That was when we began to push beyond the traditional boundaries of Technical Writing. We realized our role could no longer stop at documentation. We needed to become people who design knowledge systems tailored to the needs of different organizations. And as AI takes on more and more work, capturing the knowledge and tacit context scattered across the organization has become more important than ever.

A well-designed knowledge system makes the entire organization more productive while helping every team member get up to speed quickly. As organizations grow, questions multiply and communication becomes increasingly costly. A strong knowledge system is critical for maintaining both the speed and quality of how we work.

Today, the work of the Technical Writing Chapter at Toss falls into four main areas.

First, we build products. We lead the team that builds and operates todoc, our internal knowledge management platform.

Second, we embed ourselves in different organizations and lead their documentation efforts. We bring together scattered knowledge in ways tailored to each organization and make that knowledge as useful as possible. There’s no one-size-fits-all knowledge system, so we adapt our approach to each organization.

Third, we eliminate the manual Technical Writing work. Through AI workflows and automation, we’re building ways for anyone to create and review documentation at a consistently high level.

Finally, we build a culture of documentation across Toss. We run community-wide sessions on topics such as how to write documentation that AI can understand effectively. We also run documentation guilds and knowledge committees within individual organizations, changing how knowledge is captured and managed throughout Toss.

What We’ll Cover in This Series

Here’s what we’ll explore in the rest of the series:

Our job title is still “Technical Writer.” But the work we actually do today is much closer to designing an organization’s knowledge infrastructure. We didn’t set out to redefine the role. We simply followed the problems that needed solving, and ended up redrawing the boundaries of the job along the way. Before we knew it, we had created a role that didn’t quite exist anywhere else in the industry.

And this shift isn’t unique to Technical Writing. AI is redefining the work of every profession. In such an environment, anyone can expand the boundaries of their role. Our chapter started with one person. Now there are three of us, and we’re looking for more people to join us. Over the course of this series, we’ll share how we got here, one story at a time.

*This is the English version of a previously published article.

Every developer has been here. You're deep in building a new feature, thirty tabs open, and suddenly you need to look up how an internal tool works… except you can't even remember where the documentation is. So you ping a teammate and wait. Just like that, your flow is gone. Ever had the same experience?

It was a problem our Frontend Chapter knew all too well. So we tried a different approach: instead of making documentation better to find, we made it come to developers.

Breaking Path Dependence in Documentation

Documentation path dependency is the constraint that forces users to follow a predetermined route just to reach the information they need. Traditional technical docs are structured from the writer's perspective, which means finding exactly what you're looking for often takes multiple searches. To break that pattern, we began observing developers in their natural work environment and interviewing them about how they actually get things done.

The dominant way developers got knowledge was simply by “asking.” A tap on the shoulder, a quick Slack message to a teammate who might know the answer. It's natural, and honestly, makes a lot of sense. Searching through pages of documentation takes time and effort that a thirty-second conversation doesn't. So rather than fight that instinct, we leaned into it.

We asked ourselves what it would take to give documentation that same immediacy, to make it respond like a knowledgeable colleague rather than a reference manual. Documentation that answers back, fetching the right context for the exact question being asked, is documentation worth using.

And that’s how Mr. Park was created.

Mr. Park: Talk to your Docs

• How it works: Ask a question and get an answer straight from the docs
• Where to find it: IDE (VSCode, Cursor) and on the company’s messenger
• What it does: Find information through “conversation” not “navigation”
• Fun fact: Mr. Park was named after the persona of Sojin Park, the Head of the Frontend Chapter

Mr. Park is a RAG(Retrieval-Augmented Generation) based chatbot built to make LLM responses more accurate and trustworthy. It draws from existing documents to deliver reliable answers, always with sources attached. Developers can ask questions naturally and get what they need without ever opening a doc or running a search. The answers are more precise than what you'd get from a teammate, and consistent no matter who's asking.

For Mr. Park to give quality answers, it needs a solid knowledge base to draw from. So we've put serious effort into improving both the quantity and quality of our documentation. But technical writers and a handful of developers alone couldn't produce enough coverage. For this system to scale, we needed an easy way to document an individual’s knowledge. That's what led us to build Sillokbot, a documentation automation tool.

Sillokbot: Auto-document your conversations

• What it does: Automatically documents key information from company messenger conversations
• How it works: React to a thread with the Sillokbot emoji, or call the bot directly. It analyzes the conversation, summarizes it using AI, and opens a PR.
• How it helps: Knowledge gets captured automatically as problems get solved, with no one having to sit down and write a separate document

Sillokbot automatically summarizes the important conversations happening within the team. The thing is, developers have already been exchanging knowledge on the company messenger all along, answering questions and talking through problems. The trouble is those conversations disappear fast, and the same questions keep coming back up. Sillokbot steps in to capture those threads, summarizes them, and opens a PR to the documentation repository, so useful discussions get preserved with almost no extra effort.

Say a developer realizes that a bug-fixing thread was particularly useful. They call Sillokbot on it, and just like that, the whole discussion becomes a document that Mr. Park learns from. The next person with the same question gets an answer without having to open the same discussion. Documentation stops being a separate chore and starts happening naturally, at the exact moment knowledge gets shared.

Knowledge that Flows

Thanks to Mr. Park and Sillokbot, knowledge at the Toss Frontend Chapter no longer pools around a single person, and the same questions have stopped making the rounds on the team. The right information reaches people at the right moment, and knowledge moves the way it should. That's had a direct impact on the team's productivity and efficiency. The bet paid off. By observing how developers actually work and treating technical documentation as a system for learning and problem-solving rather than a static collection of information, we got real results.

Technical writing has evolved alongside all of this. The old focus was on structuring information and explaining features well from the writer's perspective. Now the focus is on building a system that actually puts documentation to work for developers. Because at the end of the day, technical writing has always been about making documentation genuinely useful for developers.

The Toss Frontend Platform Team is looking for people to join us in building a learning infrastructure where knowledge is easy to share and access. There's a lot ahead, like pushing the AI-powered documentation system further, building documentation automation that connects naturally with code, and creating a documentation ecosystem that works seamlessly across the company messenger and other platforms.

Join us if building an environment where developers do their best work sounds like your kind of challenge.

어드민 하나를 만들려면 무엇을 해야 할까요?

프로젝트를 스캐폴딩하고, 필요한 의존성을 추가하고, 빌드 도구를 고르고, 인증을 붙이고, 배포를 설정해요. 그다음 프론트엔드 코드를 작성하고 API를 연결한 후 빌드해서 배포해요. 어드민이라면 여기에 개인정보 마스킹, 정보 조회 사유 수취, 다운로드 파일 암호화 같은 보안 요건을 추가로 고려해야 해요. 간단한 어드민 하나를 만들려고 해도 해야 할 일이 많죠.

토스에서는 여러 팀이 빠르게 비즈니스를 시도하면서 다양한 어드민을 만들고 수정할 일이 꾸준히 생겨요. 기존에는 어드민마다 개발/보안/배포 과정을 반복해야 해서, 수요가 커질수록 비용도 같이 커졌어요. 공통으로 필요한 정책과 실행 환경을 표준화하면서도, 각 팀에 필요한 어드민을 빠르게 만들 수 있는 방식이 필요했어요.

TOI는 이 문제를 풀기 위해 만든 사내 어드민 제작 플랫폼이에요. 사용자는 어드민에서 쓸 API를 등록하고, 자연어로 필요한 화면을 요청해요. AI는 사용자가 등록한 API의 요청과 응답 스키마를 참고해서 React 코드를 만들어요. 2026년 2월 사내에 공개한 이후 2026년 8월까지 6개월간 프로젝트 439개와 그 하위 페이지 2,418개가 만들어졌어요.

코드는 AI가 작성해 줬지만, 실시간으로 만들어지는 코드가 사용자에게 어드민으로 보이려면 실행하고 보여 줄 환경이 필요했어요. 이 글에서는 TOI가 그 환경을 브라우저 안에 만든 과정을 소개할게요.

어드민을 정책과 화면으로 나눠서 생각하기

어드민에서 지켜야 하는 정책들은 대부분 데이터를 다루는 방식과 관련되어 있어요. TOI로 만든 어드민에서 API를 호출하려면 먼저 해당 API를 TOI에 등록해야 해요. 등록된 API 요청은 TOI 서버를 거쳐 원래 서버로 전달되고, TOI 서버에는 호출 기록이 자동으로 남아요. API별로 개인 정보 마스킹, 다운로드 파일 암호화, 정보 조회 사유 수취 같은 정책을 설정할 수 있고, 필수인 보안 정책들은 자동으로 적용돼요. TOI 서버는 API를 프록시하는 과정에서 이 설정과 정책을 적용해요.

다음 영역은 데이터를 화면에 보여 주고 기능을 동작하게 하는 일이에요. 테이블을 그리고, 필터를 붙이고, 상세 페이지로 이동하는 기능이 여기에 해당해요. TOI는 이 영역을 AI에게 맡겨서, 사용자가 필요한 어드민 화면을 쉽고 빠르게 만들 수 있도록 했어요.

다만 AI가 프론트엔드 코드를 만들었다고 바로 화면이 나타나지는 않아요. 앞에서 나열한 것처럼 코드가 동작하는 서비스가 되려면 코드를 만드는 것 외에도 할 일이 많아요. TOI에서는 AI가 만든 코드를 사용자가 제품에서 실시간으로 확인할 수 있어야 했고, 이를 위해 개발 환경 자체를 브라우저 안으로 가져와야 했어요.

Preview Runtime을 위한 두 가지 시도

AI가 만든 코드를 실행해서 바로 보여 줄 화면이 필요했고, 이를 위해 두 가지 방식을 차례로 시도했어요.

Dev Server

처음에는 개발자에게 익숙한 Dev Server를 사용해서 시도했어요. 서버에 Next.js Dev Server를 띄우고 그 주소를 iframe으로 연결해서 사용자에게 보여 줬어요. 로컬에서 개발하던 방식을 그대로 서버로 옮겼고, 코드가 수정될 때마다 Dev Server가 바라보는 파일이 변경되고 iframe이 갱신됐어요.

코드 변경 내용을 어렵지 않게 실시간으로 보여 줄 수 있었고, PoC에는 적절했어요. 하지만 TOI에서는 여러 사용자가 Preview를 보면서 편집할 수 있어야 하는데, 하나의 Dev Server 프로세스에 연결된 Preview에는 구조적인 한계가 있었어요. Next.js Dev Server는 컴파일 에러가 나면 에러 오버레이를 보여 주는데, 사용자 A가 페이지를 편집하다가 컴파일 에러가 나면 오버레이가 A의 화면에만 나타나지 않고 다른 페이지를 편집하고 있는 사용자에게도 보였어요.

실행 환경을 사용자별로 나누지 않아서 생긴 문제였어요. Dev Server 프로세스를 사용자 수만큼 늘리는 대신, 코드 실행 위치를 각 사용자의 브라우저로 옮겨 서로 격리하기로 했어요.

Sandpack

두 번째 시도에서는 CodeSandbox의 Sandpack을 사용해 코드 실행 위치를 서버에서 사용자 브라우저로 옮겼어요. 기대한 대로 Preview는 사용자마다 독립적으로 실행됐고, 사용자 A가 코드를 편집하다 낸 오류가 다른 사용자의 화면에는 나타나지 않았어요.

대신 예상하지 못한 다른 문제가 생겼는데, 페이지에 진입 후 Preview가 보이기까지 47초가 걸렸어요. Sandpack은 페이지에 진입해서 렌더링을 시작할 때, 프로젝트에 선언한 패키지를 모두 내려받는 식으로 동작했기 때문에 느릴 수밖에 없었어요. 실시간으로 생성/편집하는 코드와 Preview가 중심인 제품에서 허용하기 어려운 사용자 경험이었어요.

사내 패키지를 연결하는 과정에서도 문제가 있었어요. 사내 패키지는 인증된 경우에만 사용할 수 있도록 private하게 관리되고 있었어요. Sandpack은 private npm registry를 지원했지만, 인증 정보를 브라우저 런타임에 노출할 수는 없었어요. 그래서 중간에서 인증을 대신 수행해 주는 Proxy API가 필요했어요.

그런데 패키지를 가져올 때는 패키지 정보를 담은 metadata와, 실제 코드를 압축한 tarball을 순서대로 내려받아요. Proxy API는 이 두 요청 모두에 대응해야 했어요. metadata 요청을 인증해 주는 것만으로는 부족했는데, metadata 안의 dist.tarball이 Proxy API가 아니라 원본 registry를 가리키고 있어서, tarball 요청도 proxy를 거치도록 URL을 다시 바꿔 줘야 했거든요.

패키지 설치는 의존성 그래프를 따라 내려가면서 하위 패키지의 metadata와 tarball을 계속 요청해요. 사내 패키지가 또 다른 사내 패키지에 의존하는 경우도 있어서, 그래프 어느 단계에서 사내 패키지를 만나든 같은 인증과 URL 치환을 적용해야 했어요.

마지막으로 Sandpack Preview는 별도 origin의 iframe에서 실행돼요. 이 iframe에서 API를 호출하면 CORS와 PNA(Private Network Access) 문제가 생겨서, 여기에도 대응이 필요했어요.

Sandpack은 실행 환경을 사용자 브라우저로 옮기는 데는 적합했어요. 하지만 첫 화면까지 걸리는 시간이 너무 길었고, 패키지를 원하는 시점과 방식으로 공급하기도 어려웠어요. 이 문제들을 하나씩 우회하며 Sandpack을 유지하기보다는, 다른 방식으로 문제를 해결하기로 했어요.

Preview Runtime

두 번의 시도를 거치며, 우리가 풀어야 하는 문제가 세 가지로 정리됐어요.

TOI는 이 세 가지를 Preview Runtime을 만들면서 해결했어요. 이제 하나씩 순서대로 소개할게요.

1️⃣ 브라우저에서 코드 빌드하기

먼저 Preview Runtime 시스템에서 어떻게 브라우저 위에서 코드를 빌드할 수 있도록 했는지 설명해 드릴게요.

브라우저에는 파일 시스템이 없어요

실시간으로 생성되는 앱 코드를 브라우저에서 빌드하려면, 빌드 도구가 파일 시스템에서 프로젝트 파일을 찾고 import 경로를 해석할 수 있어야 해요. 예를 들어 ./components/Table이라는 경로를 만나면 실제로 존재하는 ./components/Table.tsx나 ./components/Table/index.tsx 파일로 해석해요. 하지만 브라우저에는 이런 경로를 조회할 프로젝트 파일 시스템이 없어서, 경로와 파일 내용을 연결하는 가상 파일 시스템을 만들었어요.

가상 파일 시스템은 경로에 파일이 있는지 확인하고 그 내용을 가져오는 역할을 해요. 파일은 소유 범위와 변경 주기에 따라 사용자 파일, 프로젝트 공유 파일, Preview 템플릿 파일, Preview Runtime 파일의 네 레이어로 나눴어요.

fileStore는 파일을 요청받으면 앞쪽 레이어부터 has로 확인하고, 처음 찾은 파일의 내용을 get으로 가져와요. 빌드 도구는 이렇게 합친 네 레이어를 하나의 파일 시스템처럼 사용해요.

esbuild-wasm으로 번들 만들기

가상 파일 시스템을 준비했으니 이제 이걸 읽어서 앱 코드를 번들로 만들 차례예요. 빌드 도구로는 esbuild의 WebAssembly 버전인 esbuild-wasm을 사용했어요. 브라우저에서 그대로 실행되고, 플러그인으로 파일 조회 과정을 가로챌 수 있어서 앞에서 만든 가상 파일 시스템을 그대로 연결할 수 있어요. esbuild-wasm으로 TypeScript와 JSX를 브라우저가 실행할 JavaScript로 변환하고, 로컬 import 그래프를 따라가며 하나의 ESM 번들을 만들어요. 변환과 번들링은 worker 옵션으로 Web Worker에서 처리해 메인 스레드의 작업과 분리했어요.

빌드 설정에는 앞에서 만든 가상 파일 시스템을 플러그인으로 넣어요.

createVirtualFsPlugin은 esbuild가 디스크에 묻는 요청을 대신 답해 줘요. onResolve에서 import 경로를 실제 파일 경로로 바꾸고, onLoad에서 그 경로의 내용을 돌려줘요.

한편, 프로젝트에서 사용할 react, date-fns 와 같은 패키지는 external 설정으로 빌드 대상에서 빠지도록 했어요. 대신 뒤에서 설명할 import map을 이용해 실행 시점에 미리 준비해둔 패키지를 연결해요.

2️⃣ 패키지를 미리 준비하기

여기까지 브라우저에서 앱 코드를 빌드하는 방법을 알아봤어요. 이제 번들에 포함하지 않고 남겨 둔 패키지를 미리 준비해서 제공한 방법을 설명할게요.

Import Map으로 패키지 제공하기

빌드한 앱 번들에는 import React from 'react' 같은 import 문이 그대로 남아 있어요. 그런데 'react'라는 이름만으로는 브라우저가 어떤 파일을 불러와야 하는지 알 수 없어요.

브라우저는 이 이름을 실제 파일에 연결하는 표준 방법으로 import map을 제공해요. 예를 들어 아래처럼 정의하면 'react'를 import할 때 react_27397108.js를 불러오게 돼요.

import map을 사용하면 패키지 연결을 번들 밖 JSON 데이터로 표현할 수 있어요. TOI는 패키지를 미리 빌드해 두고, import map으로 연결해서 제공하기로 했어요.

의존성은 패키지 개별 단위로 나뉘지 않아요

처음에는 패키지를 각각 번들링해서 S3에 올려 두고, 프로젝트가 필요한 패키지만 골라 import map으로 연결하려고 했어요. 패키지 매니저가 어떤 문제를 풀어 주는지 충분히 이해하지 못하고 선택한 방법이었어요.

각각 번들링하는 이 방식에서는 패키지 조합에 따라 런타임 오류가 생길 수 있어요. 예를 들어 react-dom은 react에 의존하는데, react-dom을 따로 번들링하면 그 안에 react 코드가 함께 포함돼요. React처럼 모두가 하나의 인스턴스를 공유해야 하는 패키지를 사용할 때, 앱이 참조하는 React와 react-dom이 참조하는 React 인스턴스가 달라지면서 오류가 생기는 거예요.

이렇게 의존성은 패키지 한 개 단위로 깔끔하게 나뉘지 않아요. 어떤 패키지가 싱글톤으로 유지되어야 하는지는 그 패키지만 봐서는 알 수 없고, 함께 설치되는 패키지를 같이 봐야 알 수 있어요. 개별 패키지가 아니라 조합 단위로 관리해야 했어요.

모든 프로젝트에 조합 하나로는 부족해요

처음에는 모든 프로젝트가 같은 버전의 React와 몇 가지 패키지 조합을 고정해서 사용했어요. 이 방법은 초기 단계에는 충분했지만 오래가지는 못했어요. 사용자마다 필요한 패키지가 달라서 추가 요청이 계속 들어왔고, 조합 하나를 모든 프로젝트가 공유하다 보니 패키지를 추가할 때마다 기존 패키지들과 호환되는지를 전체 프로젝트 기준으로 확인해야 했어요. 패키지 버전을 올릴 때도 마찬가지로, 새 버전이 모든 프로젝트에 한꺼번에 적용되기 때문에 일부 프로젝트에만 필요한 업그레이드를 해 줄 방법이 없었어요.

그래서 프로젝트마다 다른 패키지 조합을 사용할 수 있는 구조가 필요했어요.

조합에 이름 붙이기

package.json의 dependencies 전체를 하나의 조합으로 묶고 packageSetHash라는 이름을 붙여 package.json의 사용자 정의 필드로 기록했어요. 패키지의 public entry 목록과 설치 결과로 나온 lockfile의 해시를 함께 해싱했어요.

entry 목록을 정렬해서 넣기 때문에 package.json에 적힌 순서가 달라도 같은 해시가 나와요. 반대로 패키지가 하나라도 바뀌면 lockfile이 바뀌면서 해시도 함께 바뀌어요. 같은 조합인지 문자열로 판별할 수 있게 됐어요.

조합을 만들고 사용하기

패키지 조합은 다음과 같이 준비해요. 먼저 빈 워크스페이스를 만들고 사용자 프로젝트의 package.json을 복사해요. 그다음 yarn install을 실행해서 node_modules와 yarn.lock을 얻어요. 이렇게 확정된 조합을 Vite로 빌드해서 브라우저용 패키지 파일로 만들고, 앞에서 소개한 import map도 importmap.json 파일로 함께 만들어 S3의 packageSetHash 경로에 업로드해요.

여기서 중요한 점은 패키지를 실제로 설치한다는 거예요. peerDependencies 해석과 버전 충돌 확인은 패키지 매니저가 원래 하던 방식대로 처리해요. 복잡한 의존성 해석 규칙을 다시 구현할 필요가 없어졌어요.

준비해 둔 패키지를 브라우저에서 사용하는 방식은 더 단순해요. 프로젝트의 package.json에서 packageSetHash를 읽고, 해시가 가리키는 경로에서 importmap.json을 받아 와요. 이 import map이 앞에서 external로 남겨 둔 import specifier를 실제 파일에 연결해 줘요.

같은 조합을 사용하는 프로젝트는 해시도 같아요. 해당 해시 경로에 패키지 파일이 이미 있으면 다시 만들지 않고, 브라우저도 Cache-Control에 따라 같은 조합의 패키지 응답을 캐시해 재사용해요.

3️⃣ 화면에 보여 주기

패키지와 앱 코드 번들이 모두 준비됐어요. 이제 이걸 실행해서 화면에 보여 줘야 해요.

처음에는 HMR(Hot Module Replacement)처럼 바뀐 모듈만 갈아 끼우는 방식을 검토했어요. 개발 중 자주 사용하는 익숙한 방식이고, 편집할 때마다 변경이 필요한 부분만 다시 그린다는 점이 좋아 보였어요.

하지만 esbuild-wasm은 HMR 기능을 제공하지 않아요. HMR을 구현하려면 어떤 모듈이 변경됐고 그 영향이 어디까지 미치는지 모듈 그래프의 상태를 직접 추적하고 계산해야 했어요. 게다가 TOI는 어드민을 만드는 도구라서, 사용자는 Preview에서 방금 작성한 코드가 화면에 어떻게 나타나는지만 확인하면 돼요. 편집 상태를 이어 가며 조작할 일이 없으니 HMR로 얻는 이점이 크지 않았어요.

그래서 부분 교체 대신 문서 전체를 교체하기로 했어요. 빌드가 끝나면 새 HTML 문서를 만들어 앱을 처음부터 실행하고, iframe을 통째로 갈아 끼워요. 이전 문서의 DOM, React 컴포넌트 상태, 모듈의 전역 값은 모두 새 문서에 영향을 주지 않아요.

문서 전체를 교체하면서 Preview 업데이트는 일종의 트랜잭션 커밋(transactional commit)처럼 동작하게 됐어요. 실행에 실패한 번들은 커밋되지 않으므로 Preview에는 실행에 성공한 가장 최신 화면만 나타나요. 빌드가 실패하거나 완성된 번들을 실행하는 중에 오류가 나면 에러 오버레이로 사용자에게 알려요.

47초에서 1.3초로

Sandpack에서는 Preview를 열 때 패키지 의존성을 찾아 내려받았어요. TOI는 패키지 조합이 바뀔 때만 빌드해서 미리 업로드해 둬요. Preview를 렌더링할 때는 이미 만든 import map과 패키지 파일을 가져오기만 해요. 매번 반복하던 일을 변경이 일어나는 시점에 한 번만 하도록 옮긴 셈이에요.

Preview Runtime을 모두 구축한 이후, Preview에 첫 화면이 나타나기까지의 시간은 1.3초로 측정됐어요.

코드가 제품이 되게 하는 일

어드민 하나를 만들려면 프로젝트 스캐폴딩, 빌드 도구 선택, 인증, 배포, 데이터 마스킹, 호출 로그 기록 등 많은 작업이 필요해요. TOI 사용자는 이 일을 더 이상 직접 할 필요가 없지만, 작업 자체가 없어진 건 아니에요. 어드민 정책은 TOI 플랫폼이 다루고, React 코드는 AI가 생성해요. 패키지는 미리 빌드해서 준비해 두고, 코드의 빌드와 실행은 브라우저의 Preview Runtime이 맡아요.

처음에는 AI가 만든 코드를 어딘가에서 실행하기만 하면 된다고 단순하게 생각했어요. Dev Server와 Sandpack으로 코드를 실행하는 데는 성공했지만, 정말 필요한 건 실행만이 아니었어요. 여러 사용자가 서로 격리된 실행 환경에서 각각의 서비스를 편집할 수 있어야 했고, 프로젝트마다 다른 패키지를 쓸 수 있어야 했어요. 좋은 사용자 경험을 유지할 만큼 충분히 빨라야 했고요.

이 시스템을 구축하기 위해 모든 것을 새로 만들지는 않았어요. 앱 코드 빌드는 esbuild-wasm, 의존성 설치와 버전 해석은 Yarn, 패키지 사전 빌드는 Vite가, 사용하는 패키지 연결은 브라우저 import map이 맡았어요. TOI에서 한 일은 이 기능들을 새로 만드는 것이 아닌, 제품의 요구사항을 고려해서 도구들을 잘 조합하고 문제를 풀어내는 것이었어요.

AI로 코드를 만드는 비용이 낮아질수록, 제품을 만드는 데 정말 중요한 일이 무엇인지 더 잘 드러나요. TOI에서는 어드민이 지켜야 할 정책을 플랫폼이 보장하도록 만들고, 만들어진 코드를 안전하게 실행할 구조를 설계하는 일이었어요. 코드를 만드는 일은 AI가 대신할 수 있게 됐지만, 제품의 가치를 정의하고 좋은 사용자 경험을 만드는 일은 여전히 엔지니어의 역할이에요. TOI에서 코드는 AI가 만들었지만, 그 코드를 제품으로 만든 것은 엔지니어였어요.

안녕하세요. 토스 QA Platform 팀 문성준 입니다.

지난 글에서 저희만의 플랫폼 토션(Tossion)을 소개했는데요. 오늘은 그 위에 올린 이야기, 핫픽스를 다뤄 보려고 합니다. 기준을 세우고, 뒤집고, 다시 세운과정까지요.

새 버전을 배포한 지 얼마 안 돼 알림이 울립니다. 확인해 보니 특정 조건에서만, 그것도 이제 막 배포가 시작돼 1%의 사용자에게서만 나타나는 문제입니다. 지금 바로 핫픽스를 해야 할까요, 아니면 다음 정기 배포까지 기다려도 될까요?

QA라면 한 번쯤 이 갈림길 앞에 서봤을 겁니다. 빨리 고치는 게 정답 같지만, 급하게 낸 핫픽스가 또 다른 버그를 부르기도 하니까요. 그래서 저희에게 핫픽스는 '빨리 고치는 일'이 아니라, '고칠지 말지부터 판단하는 일'입니다. 오늘은 핫픽스를 어떻게 막고, 또 어떻게 관리하는지 이야기합니다.

심각도 한 줄로 나눌 수 없었습니다

원래 핫픽스에도 기준은 있었습니다. Critical, Major, Minor 같은 흔한 심각도 규칙이었죠. 작은 앱이라면 이 정도로 충분합니다.

그런데 토스에서는 이 규칙이 자꾸 어긋났습니다. 사용자가 많다 보니, 아주 낮은 배포율에서 생긴 문제도 실제로는 수많은 사람이 겪습니다. 게다가 화면 하나에 여러 비즈니스 로직이 얽혀 있어서, 같은 'Major'라도 어떤 건 당장 고쳐야 하고 어떤 건 기다려도 됐습니다. 심각도 한 줄로는 나눌 수 없었습니다. 매번 들어오는 핫픽스 요청이 다 달랐으니까요.

그래서 규칙 자체를 다시 짰습니다. 심각도로 줄 세우는 대신, 핫픽스를 할지 말지로 판단하는 구조로 바꿨습니다. 어떻게 판단하는지는 바로 뒤에서 풀어보겠습니다.

그리고 이 규칙은 한 번 정하고 끝이 아닙니다. 매달 지난 핫픽스를 다시 꺼냅니다. 잘 판단한 건 왜 잘됐고, 애매했던 건 무엇 때문에 애매했는지를요. 그러다 보면 기준이 계속 손질됩니다. 어떤 건 더하고, 어떤 건 덜어냅니다. 지금 이 글에서 소개하는 것도 완성된 규칙이 아니라, 그렇게 다듬어 온 현재의 모습입니다.

점진 배포라는 모순

여기에 더 근본적인 모순이 있었습니다.

토스는 새 버전을 한 번에 100% 내보내지 않습니다. 일부 사용자에게 먼저 배포하고, 문제가 없으면 점점 넓혀갑니다. 사용자의 불편을 빠르게 잡아내려는 안전장치죠.

그런데 이 점진 배포가 핫픽스 판단과 정면으로 부딪힙니다. "1%에서만 발생했으니 심각하지 않다"는 판단은, 사실 아직 이 버전을 받지 못한 나머지 99%의 잠재 위험을 보지 않은 것입니다. 지금 1%인 이유가 문제가 작아서가 아니라, 배포가 거기까지 밖에 안갔기 때문일 수 있으니까요. 반대로, 정말 특정 조건에서 그 1%에게만 생기는 문제라면, 이번엔 핫픽스가 부담이 됩니다. 잘 쓰고 있는 99%에게까지 새 빌드를 내보내는 일이라, 문제 하나를 잡으려다 멀쩡한 다수를 새로운 위험에 밀어 넣을 수 있으니까요.

같은 '1%'가 이렇게 정반대로 읽힙니다. 그래서 저희에게 필요했던 건 더 촘촘한 심각도 표가 아니라, 이 숫자를 맥락에 맞게 해석하고 빠르게 '할지 말지'를 결정할 수 있는 판단 구조였습니다.

신중하게 판단합니다

저희는 핫픽스를 우선순위로 나누지 않습니다. 핫픽스를 진행할 것과, 다음 정기 배포에 반영할 것으로 나눕니다.

진행하는 쪽은 분명합니다. 기본 기능을 아예 쓸 수 없거나, 매출에 직접 영향을 주거나, 규제와 얽힌 문제. 반대로 다음 배포로 넘겨도 되는 쪽도 정해뒀습니다. 이용률이 아주 낮은 기능이거나, 특정 조건에서만 생기거나, 우회할 방법이 분명한 경우입니다. 즉, 우선순위가 높다고 무조건 핫픽스를 하는 것이 아니라, 지금 바로 수정해야할 조건에 해당하는지를 봅니다.

판단은 한 사람이 하지 않습니다. 그 주의 배포를 책임지는 릴리즈 마스터 와 품질을 책임지는 큐에이 마스터가 함께 봅니다. 한쪽은 배포 관점에서, 다른 쪽은 품질 관점에서 검토하고, 둘이 합의해야 핫픽스가 나갑니다. 급한 문제는 빌드를 먼저 돌리는 예외를 두되, 최종 배포 결정만큼은 반드시 양쪽 합의를 거칩니다.

한 가지 버린 것도 있습니다. 처음엔 "핫픽스를 결정하면 2~4시간 버퍼를 두고 다른 이슈도 같이 검토하자"는 안이 있었어요. 그런데 시간을 기준으로 두면 핫픽스의 목적과 부딪힙니다. 그래서 시간 기준을 없애고, '충분히 검토했는가'에 집중하기로 했습니다. 목표 문구도 ‘어렵고 안전하게’에서 ‘신중하고 안전하게’로 바꿨습니다. 핫픽스를 어렵게 만드는 게 목적이 아니니까요.

크래시가 나면 빠르게 재현합니다

검증 중에 크래시가 나면, 정작 가장 오래 걸리는 건 수정이 아니라 재현입니다. ‘어떤 상황에서 터졌는지’를 모르면 개발자와 이야기를 시작할 수조차 없으니까요.

그래서 crash-path를 만들었습니다. Claude의 스킬(Skill)로 만든 크래시 분석 도구입니다. 크래시 URL 하나를 넣으면, 로그에 남은 사용자의 행동 기록을 시간 순서대로 되짚어 어느 화면에서 무엇을 하다 죽었는지, 어떤 순서로 하면 재현되는지를 한 장으로 정리해 줍니다. 그 크래시가 났던 기기·OS·메모리 같은 환경까지 함께요.

그런데 Bugsnag(Android)와 Firebase Crashlytics(iOS)는 각각 데이터를 다른 방식으로 줍니다. 그래서 crash-path는 URL 주소만 보고 어느 플랫폼인지를 스스로 판단해, 플랫폼에 맞는 통로로 데이터를 가져옵니다. 사람은 "이거 안드로이드예요, iOS예요" 같은 걸 한 번도 고를 필요가 없습니다. 이렇게 판단에 필요한 질문 자체를 줄였고, 크래시가 감지되면 지능형 AI 봇이 crash-path를 자동으로 실행해 분석 결과를 채널에 바로 올려놓게 했습니다.

여기서 저희가 그은 선이 하나 있습니다. 화면을 무엇이라 부를지, 무엇을 회귀로 볼지 같은 판정은 AI의 추측에 맡기지 않았습니다. 화면 이름을 어떻게 읽을지, 로그의 어떤 패턴을 재현 신호로 볼지를 규칙으로 정해 스킬에 넣어 두고, AI는 그 규칙을 적용해 정리만 합니다. AI가 화면을 멋대로 지어내면 재현 가이드를 믿을 수 없으니까요. 덕분에 결과가 매번 일관될 수 있었습니다.

분석 결과는 개발자와 나누도록 한 덩어리로 보냅니다. 덕분에 재현 방법을 찾느라 시간을 흘려보내지 않고, 바로 개발자와 원인을 논의합니다. 재현이 빨라진 만큼, 고칠지 말지 판단하는 것도 빨라집니다.

남아 있어야 돌아봅니다

여기서부터는 막은 다음의 이야기입니다. 신중하게 판단하고, 크래시를 빠르게 재현하고, 배포 뒤를 지켜보는 데까지가 문제를 막는 과정이었다면, 이제부터는 같은 사고가 두 번 나지 않게 관리하는 일입니다.

그런데 관리를 하려면 먼저 돌아볼 게 남아 있어야 합니다. 그날 왜 그렇게 판단했는지, 무엇으로 고쳤는지가 사라지면 다음 달엔 기억에 기댈 수밖에 없으니까요. 이 일을 처음 시작했을 때 가장 먼저 부딪힌 게 바로 이것이었습니다. 핫픽스 기록이 한군데에 있지 않았습니다. iOS와 Android가 서로 다른 곳에, 서로 다른 형식으로 적고 있었고, 지난 사고 하나를 찾으려면 여기저기를 뒤져야 했습니다.

그래서 흩어져 있던 기록을 한 틀로 맞춰 토션에 모았습니다.

어떤 버전에서 언제 발생했고, 사용자가 겪은 증상은 무엇이며, 기술적 원인과 원인 종류는 무엇이고, 무엇으로 고쳤고 어떻게 막을지까지. 제각각이던 기록을 같은 항목으로 정리하고 나니, 비로소 한자리에 놓고 견줘 볼 수 있게 됐습니다. 그리고 이걸 특정 담당자만 보는 게 아니라 누구나 열어 볼 수 있게 했습니다. 기록은 쌓아두는 것보다 함께 보는 게 중요하니까요.

토션에 쌓는 건 진행한 핫픽스만이 아닙니다. 하지 않기로 한 것도 함께 쌓습니다.

앞에서 저희 기준은 우선순위가 아니라 진행하느냐 다음 배포로 넘기느냐라고 했는데요. 그래서 넘기기로 한 건에는 왜 넘겼는지 사유를 함께 남깁니다. 이용률이 낮아서, 특정 조건에서만 생겨서, 우회할 방법이 있어서처럼요. 언뜻 안 한 일은 남길 게 없어 보이지만, 저희에겐 이게 다음 판단의 교보재가 됩니다.

비슷한 상황이 또 왔을 때, 지난번엔 이런 이유로 넘겼다는 근거를 꺼내 볼 수 있으니까요. 판단이 사람 머릿속에만 있으면 그 사람이 자리에 없을 때 흔들리지만, 사유가 쌓이면 기준이 됩니다. 안 한 판단도 판단이고, 그 판단에도 근거가 남아 있어야 다음 판단도 일관될 수 있습니다.

그런데 이 기록을 어떻게 남기느냐에서, 저는 한 번 크게 틀렸습니다. 핫픽스가 끝나면 왜 생겼고 어떻게 막을지를 남겨야 하는데, 그 방식을 잘못 잡았습니다.

처음 세운 가설은 이랬습니다. 사후기록을 일부러 번거롭게 만들면, "이거 굳이 핫픽스까지 해야 하나?" 하는 자각이 생겨서 핫픽스가 줄지 않을까?

결과는 정반대였습니다. 기록이 번거로워지자 사람들은 행동이 아니라 기록을 줄였습니다. 핫픽스는 그대로인데 기록만 부실해졌어요. 나중에야 알았습니다. 마찰을 행동 앞이 아니라 기록 앞에 둔 게 실수였다는 걸요. 마찰은 언제나 가장 가까운 것부터 회피하게 만듭니다. 품질 문화는 장치 하나로 움직이지 않는데, 저희는 사후기록 하나만 조이려 했던 겁니다.

그래서 방향을 뒤집었습니다. 기록을 어렵게 만드는 대신, 쉽게 만들고 맥락을 풍부하게 채우기로요. 핫픽스는 대부분 채널의 대화에서 시작되니, 그 논의 맥락을 지능형 AI 봇이 사후기록 초안에 미리 채워둡니다. 사람은 처음부터 쓰는 게 아니라, 채워진 초안을 검토하고 빠진 것만 보탭니다. 기록의 부담은 낮아지고, 논의 맥락은 오히려 더 잘 남습니다.

같은 사고를 두 번 내지 않으려면

기록을 모으는 건 시작일 뿐입니다. 쌓아두기만 해서는 핫픽스가 저절로 줄지 않으니까요. 줄이려면 현황을 보고 무엇을 바꿀지를 정해야 합니다. 그래서 매달 한 번, Android, iOS, QA가 함께 모이는 자리를 만들었습니다.

이 자리에서 하는 일은 세 가지입니다. 지난달 핫픽스를 함께 돌아보고, 되풀이되는 원인에는 재발방지 액션을 정하고, 앞서 정했던 액션이 실제로 지켜졌는지 확인합니다. 이번 달에 새 다짐 하나를 더 얹고 끝나는 게 아니라, 저번 달 다짐이 지켜졌는지를 매번 되짚습니다. 핫픽스를 줄이는 건 장치 하나가 아니라, 이렇게 매달 돌아보는 반복이 하는 일이었습니다.

그 확인이 가장 크게 걸리는 데가 재발 방지입니다. 재발 방지는 문서에 "이렇게 막겠습니다"라고 적는 걸로 끝나기 쉽습니다. 적어두고 아무도 안 하면 그만이니까요. 저희는 여기서 한 걸음 더 갑니다. 실제로 이행됐는지까지 추적합니다.

토션에서 재발 방지는 핫픽스와 별개의 항목으로 관리됩니다. 어떤 원인을 겨냥한 조치인지, 무엇을 했는지, 증적은 어디 있는지가 남습니다. 그리고 그 조치를 이슈 티켓으로 연결해두면, 티켓이 실제로 닫혔는지를 시스템이 주기적으로 확인해 이행 상태를 자동으로 갱신합니다. 사람이 "했다"고 체크하는 게 아니라서, 이 상태는 화면에서 손으로 바꿀 수도 없습니다.

이 기록들은 타임라인 위에 쌓입니다. 정기 배포와 핫픽스, 재발 방지 조치가 한 축에 나란히 놓여서, 언제 무엇이 터졌고 그 뒤에 무엇을 했는지가 한눈에 보입니다. 하겠다고 적어놓고 미룬 게 있으면, 다음 달 그 자리에 그대로 미이행으로 올라옵니다. 재발 방지가 '적어둔 다짐'이 아니라 '끝까지 확인하는 약속'이 되는 이유입니다.

이 모든 기록은 결국 지표가 됩니다. 핫픽스는 감으로 관리할 수 없으니, 남긴 기록을 숫자로 봅니다.

원인을 여섯 가지(코드 결함, 의존성·SDK, 배포 실수, 환경, 외부 API, 기타)로 나눠 어디서 자주 터지는지 봅니다. 어떤 원인이 되풀이되는지가 쌓이면, 다음에 무엇을 먼저 막아야 할지가 보입니다.

프로세스를 정비하고 이 관리 체계를 갖춘 뒤로, 토스 앱의 핫픽스는 줄어들고 있습니다.

완성된 규칙이 아니라, 계속 다듬는 규칙

지금까지 소개한 것들은 처음부터 이 모습이 아니었습니다. 시간 버퍼를 두자던 규칙도, 사후기록을 번거롭게 만들자던 시도도, 앞에서 이야기한 대로 부딪히고 뒤집으며 지금 자리에 왔습니다. 그래서 이 프로세스에는 '완성'이 없습니다. 매달 조금씩 더하고 덜어내며, 지금도 바뀌고 있습니다.

돌아보면, 글머리에서 모순이라 불렀던 것도 마찬가지였습니다. 점진 배포와 핫픽스는 애초에 모순이 아니었어요. 점진 배포는 문제를 좁은 곳에서 먼저 만나게 하고, 핫픽스는 그렇게 드러난 문제를 빠르게 막습니다. 사용자의 피해를 줄인다는 같은 목적을, 앞과 뒤에서 나눠 맡을 뿐입니다. 정말 부딪혔던 건 배포 방식이 아니라, '1%'라는 같은 신호가 상황에 따라 정반대로도 읽힐 수 있다는 점이었습니다. 저희가 만든 건 그 둘을 잇는 판단이었습니다.

핫픽스는 없는 게 가장 좋습니다. 하지만 매주 새 버전을 내보내는 이상, 0이 되기는 어렵습니다. 그래서 저희의 일은 세 가지로 정리됩니다. 굳이 안 해도 될 핫픽스는 하지 않고, 해야 할 핫픽스는 신중하고 안전하게 하고, 한 번 난 사고는 두 번 나지 않게 만드는 것. 빠르게 고치는 것보다 먼저 필요한 것은, 지금 고쳐야 하는 문제인지 제대로 판단하는 일입니다.

안녕하세요, 토스증권 AI 데이터 플랫폼 팀에서 ML 엔지니어로 일하고 있는 황호익입니다.

이번 글에서는 토스증권 안에서 추천과 검색이 어떤 방향으로 진화하고 있는지 이야기해보려고 해요. 추천은 어떻게 배치 중심에서 실시간 개인화로 바뀌고 있는지, 검색은 어떻게 키워드와 필터를 넘어 RAG와 그래프 RAG로 확장되고 있는지 순서대로 다룰게요.

완성된 정답이라기보다는, 시스템을 만들면서 마주친 고민들이라고 봐주시면 좋겠습니다.

토스증권 AI 데이터 플랫폼 팀의 미션

토스증권의 모든 AI 서비스가 공통적으로 접근할 수 있는 탄탄한 데이터 생태계를 제공하자.

AI 제품이 많아질수록 각 서비스가 필요한 데이터를 각자 수집하고, 각자 가공하고, 각자 검색하는 방식에는 한계가 생깁니다. 데이터 품질을 맞추기도 어렵고, 비슷한 문제를 여러 팀이 반복해서 풀게 되거든요.

그래서 이런 기반을 만들고 있어요.

오늘 이야기할 추천과 검색도 결국 이 공통 기반 위에서 함께 진화하고 있는 문제들입니다.

추천

예전에는 배치와 클러스터로 충분했어요

토스증권 추천에는 비교적 명확한 문제가 많았습니다. 개인화 뉴스 추천, 관심 종목 추천, 커뮤니티 인기글 추천 같은 것들이요.

이때는 유저와 아이템 데이터를 모아 배치로 처리하고, 유저를 클러스터링해서 클러스터별 추천 리스트를 미리 계산해두는 방식으로도 꽤 많은 문제를 풀 수 있었어요. 유저 DB에서 여러 원천 데이터를 배치 스케줄로 가져와 유저별 클러스터 정보를 만들고, 그걸 기반으로 추천 아이템 리스트를 만들어 Redis나 MongoDB 같은 저장소에 넣어두는 식이었죠.

중요한 건 이 방식이 틀렸다는 게 아닙니다. 당시에는 제품 생애주기도 빠르고 추천해야 하는 콘텐츠 종류도 지금보다 단순했기 때문에, 배치 중심·클러스터 중심의 접근이 현실적인 선택이었어요.

그런데 네 가지가 바뀌었어요

서비스가 성장하면서 추천이 마주하는 문제가 조금씩 달라지기 시작했습니다.

1️⃣ 유저의 관심사가 훨씬 빠르게 변해요 사용자는 앱 안에서 여러 화면을 탐색하고, 특정 종목을 보고, 뉴스를 읽고, 커뮤니티 글을 봅니다. 그 순간마다 관심 맥락이 계속 달라져요.

2️⃣ 시장과 종목 이벤트가 계속 움직여요 금융 서비스에서는 같은 사용자라도 장중에 관심을 가져야 하는 주제가 계속 변할 수 있습니다.

3️⃣ 콘텐츠 자체가 다양해졌어요 뉴스, 커뮤니티, AI 콘텐츠 등 사용자가 탐색할 수 있는 콘텐츠가 계속 늘어나고 있어요.

4️⃣ 기술적인 조건도 바뀌었어요 토스증권의 실시간 데이터·머신러닝 플랫폼이 성장하면서, 예전에는 비용 때문에 시도하기 어려웠던 고도화된 추천 시스템을 이제는 구축해서 운영해볼 수 있는 환경이 만들어졌습니다.

이런 배경에서 추천의 문제 정의가 이 사용자가 원래 좋아할 만한 것을 제공하는 것에서, 지금 이 사용자의 맥락에서 필요한 것을 제공하는 방향으로 이동했어요.

그래서 추천은 리스트가 아니라 루프가 됐어요

지금 이 사용자의 맥락에서 필요한 것을 제공하려면, 유저의 행동 이벤트와 아이템 변경 이벤트가 계속 들어와야 하고, 그에 대한 유저의 피드백도 피처 스토어와 벡터 인덱스에 반영되어야 합니다. 추천 서비스는 그 위에서 노출할 콘텐츠를 찾고, 유저가 좋아할 만한 순서대로 보여주고요.

그래서 추천은 정적인 리스트가 아니라, 실시간 이벤트와 피드백을 계속 흡수하는 루프 형태의 시스템이 됩니다.

흐름을 조금 더 자세히 보면,

필연적으로 이런 시스템에는 관측과 운영·디버깅 도구도 필요해집니다. 학습 데이터가 잘 만들어지고 있는지, 인덱스가 잘 갱신되고 있는지, 왜 특정 결과가 추천되었는지 확인할 수 있어야 하니까요.

운영하면서 마주친 두 가지 고민

임베딩 모델을 바꾸면 벡터 저장소 운영이 따라와요

추천을 고도화할수록 유저의 취향과 아이템의 맥락을 몇 가지 규칙만으로 표현하기 어려워집니다. 임베딩은 이런 복잡한 신호를 하나의 표현 공간에 담아, 대규모 후보에서 관련 있는 아이템을 효율적으로 찾게 해줍니다.

그런데 임베딩 기반 추천을 실제 트래픽에 붙일 때는 모델 성능만 보면 안 됐어요. 임베딩 모델을 계속 고도화할 수 있도록 열어두는 순간, 벡터 저장소 운영도 같이 따라옵니다.

임베딩 모델이 바뀌면 기존 벡터와 새 벡터가 같은 공간에 있다고 보기 어려워요. 그래서 이런 것들이 필요했습니다.

벡터 DB를 검색 성능만으로 검증할 수 없었어요

추천에서 유사 아이템을 찾기 위한 벡터 검색은 반드시 필요했어요. 그런데 사용자의 과거 선호 아이템이나 최근 행동을 피처로 쓰기 위해, 여러 아이템 임베딩을 한 번에 가져오는 멀티겟 연산도 발생합니다.

과거 아이템의 임베딩을 대량으로 조회하는 워크로드에서는 고차원 벡터의 응답 생성으로 JVM 메모리 압력이 커질 수 있었습니다. 그래서 검색 지연 뿐 아니라 mget 처리량과 GC 추이도 실제 요청 패턴으로 검증해야 했습니다.

검색, 그리고 RAG

데이터를 가져오는 방식이 파편화되고 있었어요

LLM을 활용하는 서비스가 하나둘 생기면서 비슷한 구조가 반복됐습니다. LLM으로 답변을 만들려면 결국 어떤 데이터를 가져와야 하거든요. 뉴스, 공시, 리포트 같은 것들이요.

그런데 서비스마다 그 방식이 조금씩 달랐어요.

여기서 기존의 키워드 검색이나 필터 기반 검색이 항상 나쁜 건 아니에요. 오히려 명확한 조건을 알고 있을 때는 굉장히 강력합니다. 하지만 사용자가 처음부터 정확한 검색어를 알고 있지 않거나, 특정 상황을 설명하는 뉴스처럼 맥락적으로 찾고 싶을 때는 한계가 분명했어요.

LLM 서비스는 늘어나는데 데이터를 가져오는 방식은 파편화되는 조짐. 저희는 이 지점을 문제로 봤습니다.

RAG를 '검색을 제품화하는 문제'로 봤어요

RAG를 단순히 LLM에 문서를 붙이는 기술로 보기보다, 검색을 제품화하는 문제로 보기 시작했어요.

LLM이 좋은 답변을 만들려면 좋은 컨텍스트를 함께 전달해야 합니다. 그러려면 사용자의 질문이 들어왔을 때 이런 판단이 필요해요.

이 과정이 서비스마다 파편화되면 품질도 흔들리고 운영 부담도 커집니다. 특히 LLM은 사실과 다른 정보를 생성할 수 있기 때문에, 답변이 검색된 문서에 잘 그라운딩되어 있는지 확인하는 일도 공통으로 중요해지고요.

그래서 RAG를 공통 플랫폼으로 제공할 수 있다고 봤습니다.

뉴스 RAG 파이프라인

사용자가 "오늘 미국 증시 요약해줘"처럼 질문합니다. 동시에 그 질문을 더 잘 이해하기 위한 단계가 시작돼요.

질문 이해. 이 질문이 어떤 카테고리의 뉴스를 원하는지 분류하고, 날짜 조건과 검색 범위를 만들어내고, 임베딩을 생성해 쿼리 벡터를 만듭니다. 이렇게 만들어진 조건들을 합쳐 Elasticsearch 쿼리를 구성해요.

하이브리드 검색. 검색은 하나의 방식만 쓰지 않습니다. 텍스트 검색과 벡터 검색을 조합하고, 메타데이터 필터를 함께 적용해 질문과 관련된 후보 뉴스를 찾아요.

리랭킹. 검색 결과는 리랭커 모델을 통해 한 번 더 걸러내는 동시에 중요한 순서로 정렬합니다.

최종적으로 정제된 결과만 각 서비스의 생성 단계로 전달돼요.

이 흐름에 포함된 모델은 대부분 LLM을 호출하는 방식으로 시작했지만, 우선순위에 따라 중요한 모델부터 하나씩 내재화하는 방식으로 구축했습니다.

RAG를 만들면서 마주한 것들

벡터 검색은 키워드 중심 질의에서 한계가 있었어요 금융 특화 임베딩 모델을 학습했음에도, 모든 회사·제품·금융 전문 용어에 대해 학습이 고루 일어나기는 굉장히 어렵습니다. 특히 사용자가 전통적인 키워드 검색 쿼리를 던진 경우에 이 문제가 더 잘 드러났어요.

텍스트 검색은 사전 관리가 중요했어요 형태소 분석기가 아직 인식하지 못하는 새로운 금융 이벤트 관련 키워드들이 있었습니다. 이런 경우에는 사전을 업데이트하는 방식의 운영도 필요했어요.

리랭커로 마지막 노이즈를 줄였어요 의도가 확실한 질문이 들어왔는데 불필요한 뉴스가 한두 건 섞여 반환되면, 사용자는 "그럴 수 있지"라고 이해하기보다 시스템 자체의 신뢰도를 의심하게 됩니다. 이 부분은 LLM을 파인튜닝한 리랭커를 두면서 해결할 수 있었어요.

메타데이터는 또 하나의 검색 신호가 되었어요 뉴스 카테고리를 잘 분류하는 모델을 만들고, 유저 쿼리가 들어오면 함께 분류한 뒤 태그가 매칭되면 더 높은 점수를 주었습니다. 이걸로 검색 정확도를 높일 수 있었어요. 그리고 잘 구축된 분류 체계는 RAG 말고도 여러 제품에서 활용할 수 있었습니다.

결국 RAG의 검색 품질에는 하나의 은탄환이 존재하지 않았어요. 서로의 단점을 보완하는 모듈들이 점진적으로 추가되면서 개선되는 흐름이었습니다.

제품은 달라도 흐름은 하나였어요

이렇게 만들어진 RAG 플랫폼은 하나의 제품에서만 쓰지 않았습니다. 뉴스 RAG만 예로 들어도 이런 니즈가 있었어요.

겉으로 보면 서로 다른 제품의 요구사항이에요. 그런데 플랫폼 관점으로 열어두면 모두 자연어 검색 API로 들어오고, 내부에서는 메타데이터 태그로 범위를 제어한 뒤 하이브리드 검색과 리랭킹을 수행하는 공통 흐름을 타게 됩니다.

제품은 달라도, 컨텍스트를 만드는 흐름은 하나의 RAG 플랫폼으로 공통화될 수 있었어요.

그래프 RAG

문서의 유사도만으로 답할 수 없는 질문들

앞에서는 필요한 문서를 잘 찾고 그걸 컨텍스트로 만드는 흐름을 봤습니다. 그런데 금융 도메인에는 비슷한 문서들을 잘 찾는 것만으로 충분하지 않은 질문들이 있어요.

관계를 따라가야 하는 질문들이죠. 그래서 그래프 RAG는 RAG의 연장선이긴 하지만, 문서를 잘 찾는 문제라기보다 파편화된 금융 지식 속에서 관계를 찾아내어 지식화하는 문제로 봐야 했습니다.

이 글에서 다루는 범위

전제가 하나 있어요.

토스증권에서는 회사·종목·제품·이벤트·테마를 연결하는 금융 지식그래프 구축이 진행되고 있었습니다. 일반적인 GraphRAG 솔루션이 그래프 구축과 검색을 함께 다룬다면, 여기서는 이미 정의된 금융 온톨로지 위에서 제품이 사용할 검색기를 만드는 데 집중했습니다.

따라서 엔티티 추출이나 링킹 과정은 다루지 않습니다. 이 글의 범위는 사용자 질문과 관련된 서브그래프를 찾아 반환하는 검색 모듈입니다.

그래프 검색기는 두 단계예요

시작 지점 찾기. 사용자 쿼리가 들어오면 앞서 설명한 검색 파이프라인을 활용한 방식으로 Elasticsearch를 사용해 관련 엔티티 후보를 찾습니다.

그래프 탐색. 반환된 시작 지점에서 출발해 그래프 위에서 연결된 노드를 탐색하며 후보 경로를 확장하고 선별해나갑니다.

이때 모든 관계를 다 따라갈 수는 없어요. 어떤 규칙으로 탐색할 것인지 정해야 하고, 이 규칙을 만들어내는 일이 검색 알고리즘의 핵심이 됩니다.

후보 경로가 5,000만 개로 늘어났어요

저희가 구축한 지식 그래프의 특성상, 의미 있는 서브그래프를 만들려면 3홉 이상 탐색해야 했습니다. 그런데 홉이 늘어날수록 탐색 경로가 기하급수적으로 늘어나요.

아무 전략 없이 수행하면 하나의 노드에서 출발한 경로가 이렇게 됩니다.

이 후보들을 모두 메모리에 유지한 채 점수화하고 정렬하는 작업은 Neo4j의 트랜잭션 메모리로 감당하기 어려웠습니다.

결국 문제는 얼마나 깊이 탐색할지가 아니라, 각 홉에서 어떤 경로를 일찍 버릴지였습니다.

이를 해결하기 위해 Beam Search에서 착안한 단계별 후보 제한 방식을 적용했습니다. 한 홉씩 관계를 확장하고 경로에 점수를 부여한 뒤, 상위 후보만 다음 홉에서 다시 확장했습니다. 최대 탐색 깊이와 홉별 후보 수를 제한하고, 불필요한 노드와 관계도 확장 전에 제외했습니다.

덕분에 중간 후보 수를 통제하면서 3홉 탐색을 안정적으로 수행할 수 있었습니다. 다만 일찍 제외된 경로는 다시 살아날 수 없기 때문에, 어떤 경로에 높은 점수를 줄 것인지가 다음 과제가 되었습니다.

어떤 경로를 남길 것인가

어떤 경로가 사용자 질문과 더 관련 있는지를 점수로 표현해야 했습니다. 질문과의 관련도를 중심에 두고, 금융 도메인에서 중요하게 보는 신호를 함께 반영했어요.

시가총액과 최신성이 검색 결과를 결정하는 것은 아닙니다. 질문과의 관련성이 비슷한 후보들 사이에서, 금융적으로 더 의미 있는 경로가 앞에 남도록 돕는 보조 신호로 사용했습니다.

우선해야 할 경로를 검색 파라미터로 제어했어요

질문과의 관련도가 높더라도, 제품마다 중요하게 보는 관계의 흐름은 달랐습니다. 예를 들어 어떤 제품에서는 다른 경로보다 기업과 기업 사이의 관계를 우선해서 보여주고 싶을 수 있어요.

이를 위해 특정 노드 유형의 순서와 일치하는 경로에 가산점을 주는 파라미터를 만들었습니다. 내부적으로는 이를 path_preference라고 불렀습니다. 관련 없는 경로를 완전히 제외하는 대신, 제품이 선호하는 경로가 탐색 과정에서 더 오래 살아남게 하는 방식입니다.

덕분에 검색기를 제품별로 따로 만들지 않고도, 같은 그래프 위에서 서로 다른 탐색 의도를 반영할 수 있었습니다.

같은 탐색 로직도 Cypher 실행 형태에 따라 비용이 달랐어요

Neo4j에도 쿼리 플래너가 있지만, 그래프 탐색은 시작 노드와 관계 분포에 따라 중간 후보 수가 크게 달라집니다. 논리적으로 비슷한 쿼리라도 실행계획에 따라 메모리 사용량과 처리 시간이 달라질 수 있어, 실제 실행 결과를 보며 최적화해야 했습니다.

PROFILE에서는 인덱스 사용 여부뿐 아니라 예상 행 수와 실제 Rows의 차이, 관계 확장 지점의 DB Hits, 연산자별 메모리 사용량을 확인했습니다. 결국 Cypher 최적화는 후보가 어느 지점에서 늘어나는지 찾고, 다음 탐색 전에 줄이는 것이었습니다.

그래프 검색의 품질을 결정한 것

그래프 검색의 품질은 그래프를 얼마나 깊게 탐색하느냐보다, 어디서 시작해 어떤 경로를 남기느냐에 달려 있었습니다.

관련 있는 시작점을 찾고, 각 홉에서 후보 수를 제한하고, 질문과 금융 도메인에 맞는 경로에 점수를 부여했습니다. 제품마다 중요하게 보는 관계가 다를 때는 경로 선호도를 추가로 반영했고요.

최종 결과에는 엔티티뿐 아니라 탐색한 관계 경로도 함께 담았습니다. 덕분에 결과가 어떤 연결을 통해 발견됐는지 추적하고, 제품에서 이를 근거로 활용할 수 있었습니다.

마치며

이번 글에서는 추천, RAG 검색, 그래프 검색을 만들며 마주한 문제와 선택을 소개했습니다. 서로 다른 시스템이었지만, 세 사례에서 반복해서 확인한 점은 같았습니다.

AI 제품의 품질은 모델 성능만으로 결정되지 않았습니다. 필요한 데이터를 어떻게 갱신할지, 어떤 후보를 남길지, 그리고 그 과정을 어떻게 관측하고 안정적으로 운영할지가 함께 중요했습니다.

보편적인 해답을 제시하기보다, 실제 시스템을 만들며 어떤 문제를 만났고 어떤 선택을 했는지 나누고 싶었습니다. 이 경험이 AI 제품을 만들 때 모델 바깥의 시스템을 바라보는 작은 힌트가 되었으면 좋겠습니다.

읽어주셔서 감사합니다.

테크톡톡(Tech Talk Talk)은 테크 업계 종사자들의 함께 교류하고 성장하는 네트워킹 및 지식공유 포럼이에요.

토스증권의 기술과 경험을 나누는 행사로, 토스증권의 엔지니어들이 직접 기술적 고민과 시행착오를 통한 배움, 그리고 성장의 여정을 공유해요. 세션 강연 뿐 아니라 실시간 질의응답을 통해 참여자들과 인사이트를 나누며, 같은 분야의 동료들과 함께 배우고 성장할 수 있는 열린 기술 교류의 장이에요!

LLM 서빙 생태계는 빠르게 바뀌고 있습니다. 불과 수년 전만 해도, LLM을 배포하는 것 자체가 허들인 경우가 많았어요. 하지만, 지금은 다양한 곳에서 on-premise LLM을 다양하게 사용하고 있습니다. 토스증권도 마찬가지로 다수의 오픈 소스 LLM, 직접 튜닝한 모델을 서비스에 활용하고 있습니다. 이런 상황에서, LLM을 단순히 서빙하는 것보다, 잘 띄우는 것이 더 중요해졌습니다.

평소에는 조용하던 팀의 알림 채널이 어느 날 갑자기 알림이 쏟아지는 날이 있습니다. 이 알림들은 여러 에러가 함께 묶여서 온 거예요. 100건 가까운 에러고, 대부분 타임아웃이라는 것까지는 알 수 있지만 이 알림만으로는 왜 이런 일이 생겼는지 알 수 없어요.

“어떤 지표를 봐야 이 알림의 원인을 알 수 있을까?”

2년 전, LLM 서빙을 처음 시작했을 때 풀어야 했던 문제는 두 가지였습니다.

1. 지표가 달라졌어요

기존 머신러닝 모델은 입력을 받아 한 건의 출력을 내놓는 구조였어요. 그래서 단 건의 응답 시간, 초당 몇 건의 트래픽을 처리하는지가 핵심 모니터링 지표였습니다.

그런데 LLM은 토큰을 순차적으로 생성해요. 단 건의 응답 시간이나 처리량은 변동성이 심하고, 애초에 통제할 수 있는 영역이 아닙니다. 그래서 지표를 이렇게 바꿨어요.

• 처리량: 초당 처리 건수 → 초당 생성 토큰 수
• 응답 시간: 최종 결과물까지의 시간 → 첫 번째 토큰이 나오기까지의 시간(TTFT)

2. 서빙 자체가 어려웠어요

토스증권은 쿠버네티스, Argo CD 같은 여러 기술 스택 위에서 움직여요. 그 위에 각자의 플랫폼을 얹어 모델을 서빙하고, 거기서 나온 로그와 메트릭을 자체 대시보드로 관찰하곤 했습니다.

문제는 이게 전부 서비스 개발자 개인의 역량에 의존했다는 점이에요.

그래서 ML 플랫폼을 직접 구축했습니다. 어려운 부분을 줄이고, 로그와 메트릭을 정규화해서 하나의 패널에서 볼 수 있게요. 서버 모니터링은 두 갈래로 나눴어요.

• Grafana — 메트릭을 수집해 추이와 이상을 탐지
• Kibana — 단건 로그를 확인

여기까지 만들고 나서, 대부분의 문제를 미리 예상하고 쉽게 해결할 수 있을 거라고 생각했습니다.

그런데 예상하지 못한 문제들이 생겼어요

앞서 구축한 모니터링만으로는 그 문제가 ‘왜’ 생겼는지 알 수 없었습니다. 원인을 파악하려면 어떤 지표를 봐야 할까? LLM 친화적인 지표를 이미 만들었는데도 부족했으니, 그 이상은 뭐가 있을까?

조사해보니 vLLM이나 SGLang 같은 서빙 프레임워크가 제공하는 지표들이 있었어요. 이걸 하나의 대시보드에 통합했습니다. 예전엔 헬스 상태, 오류 건수, 레이턴시 같은 일반적인 서버 대시보드였다면, 여기에 LLM에 특화된 지표를 얹은 거예요.

이 시스템을 갖추고 나서야 비로소 원인을 찾을 수 있게 된 사건이 세 가지 있습니다.

사건 1. 비어 있는 캐시

서비스 팀의 머신러닝 엔지니어분이 자신이 쓰는 모델을 서비스로 내보내려는데, 확인해보니 종종 타임아웃이 발생한다고 요청을 주셨어요. 그래서 먼저 알림이 온 시간과 트래픽이 몰리는 시간을 비교해봤어요.

그런데 둘이 일치하지 않았습니다. 원인이 트래픽이 아니라는 뜻이었죠.

지표들을 쭉 살펴보다가 시선을 잡아끄는 게 하나 있었어요. Prefix Cache Hit Rate였습니다. 옆의 지표들은 값이 나오는데, 이것만 값이 없었어요.

Prefix Cache가 뭐냐면

LLM은 토큰을 순차적으로 생성하고, 트랜스포머 구조에서 이전 문자열들에 대한 Key와 Value를 계속 참조합니다. 이걸 매번 계산해야 하는데 값은 똑같아요. 그래서 캐시 메모리에 저장해 두 번 계산하지 않게 하는 게 KV 캐시입니다.

KV 캐시는 하나의 시퀀스 안에서만 작동해요. 그런데 실제로 쓰다 보면 시스템 프롬프트처럼 앞부분을 공유하는 요청이 아주 많습니다. 서로 다른 요청이라도 앞쪽 KV 캐시는 동일한 경우가 많죠. 그걸 재사용하려고 쓰는 게 Prefix Cache고, Hit Rate는 그게 얼마나 재사용됐는지를 뜻해요. 높을수록 계산을 덜 하니 빨라집니다.

그런데 이 값이 0이었어요.

원인은 두 가지 중 하나였는데

지표 수집이 잘못됐거나, 아니면 실제로 요청들이 전부 달라서 히트가 안 났거나.

첫 번째는 아니었어요. 다른 모델에서는 정상적으로 값이 나왔거든요. 두 번째를 확인하려고 로그를 봤는데, 요청들이 많이 다르긴 했지만 그래도 어느 정도는 히트가 나야 하는 상황이었습니다.

이상해서 탐색을 시작했고, 재미있는 걸 발견했어요. 세팅을 잘못한 게 아니라, 사용 중이던 모델의 특성상 Prefix Caching이 기본적으로 꺼지는 설정이었습니다. 다른 모델들은 기본으로 켜져 있는데 이 모델만요.

다시 활성화해서 재배포했어요. 결과는 이랬습니다.

• TTFT: 20초 가까이 걸리던 경우가 있었는데, 적용 후 약 1/10 수준으로 감소
• Prefix Cache Hit Rate: 90% 이상 기록

사실 단순한 문제예요. 하지만 Prefix Cache Hit Rate라는 지표를 보고 있지 않았다면 발견하는 것 자체가 훨씬 어려웠을 겁니다.

사건 2. 완벽한 알리바이

또 알림이 쭈르륵 올라왔어요. 앞선 교훈대로 vLLM·SGLang이 제공하는 LLM 지표들을 확인했습니다.

그런데 이상하게도 특이 상황이 없었어요. TTFT가 조금 바뀌긴 했는데 차이가 20ms 수준이었고, 그마저도 P99였습니다. 메트릭상으로는 완벽한 알리바이였죠.

메트릭 문제가 아니라고 판단하고 로그로 시선을 옮겼습니다. 취합해보니 이상한 점이 하나 있었어요. finish_reason이 length 였습니다.

length는 저희가 지정한 상한(예: 최대 N토큰)을 넘어서 그냥 끊겼다는 뜻이에요. 즉 모델이 원하지 않는 말을 불필요하게 뱉어냈다는 의미죠.

요즘 많이 쓰는 리즈닝(thinking) 모델에서 이런 일이 꽤 발생합니다. 리즈닝을 훨씬 길게 하는 경향이 있으니까요. 그런데 신기한 건, 저희는 이걸 막으려고 리즈닝 토큰 개수를 제한하는 옵션을 이미 켜뒀다는 점이었어요. 그런데도 그게 실패하고 계속 생성됐습니다.

문제가 된 로그들의 출력을 하나하나 열어봤어요. 그러다 눈길을 끄는 문자열을 발견했습니다. 내용 자체는 중요하지 않고, 끝에 붙은 </think> 가 중요했어요.

이건 리즈닝이 끝났음을 알리는 스페셜 토큰입니다. 그런데 이게 리즈닝 구간이 아니라, 리즈닝이 끝나고 실제 출력을 뱉어야 하는 content 시점에 등장하고 있었어요.

여기까지 오니 더 손쓸 방법이 없어서 다시 탐색했고, vLLM의 버그임을 확인했습니다. 이미 다른 사람들이 리포트한 문제였고, 해당 이슈에서는 해결할 수 없다는 답과 함께 워크어라운드가 제시돼 있어서 그대로 적용했습니다.

결과는 에러율이 약 0.2%에서 0.02% 수준으로 감소했습니다.

사건 3. 사라진 처리량

트래픽이 몰리는 시간에 처리량이 부족해서 밀린다고 서버 개발자분이 그래프와 함께 메시지를 주셨어요.

LLM은 GPU라는 비싼 자원을 다량 쓰는 모델이라, 파드를 하나 더 띄우는 것 자체가 비쌌어요. 그래서 증설을 결정하기 전에 하나만 확인하고 가자고 했습니다.

우리가 GPU를 충분히 쓰고 있는가?

메트릭으로 돌아갔어요. 크게 보면 문제가 없어 보였는데, 자세히 보니 KV Cache 사용량이 매우 작았습니다. 생성 TPS는 거의 1,000에 가깝고 Prefix Cache도 아주 많이 쓰고 있어서 전반적으로 조밀하게 돌고 있었는데, KV 캐시 사용량만 1%도 되지 않는 수준이었어요.

메모리에 여유가 있으니 더 많은 요청을 받을 수 있겠다고 판단했습니다. 파드를 증설하기 전에 어디까지 동시성(Concurrency)을 받을 수 있는지 테스트해봤어요. 허용 범위 안에서 "동시성 20까지"까지 받을 수 있다는 걸 확인했습니다.

이 근거로 자원을 두 배로 쓰지 않고 트래픽을 4배까지 받을 수 있다는 힌트를 얻었어요.

그래도 다 해결되지는 않아요

물론 지표가 있다고 모든 문제가 풀리는 건 아닙니다. 문제 대부분이 저희가 의존하는 vLLM·SGLang 같은 프레임워크에 디펜던시가 걸려 있거든요.

• 특정 옵션 조합에서 content 값이 아예 반환되지 않는 버그
• 저희가 설정한 대로 LLM이 동작하지 않는 경우
• 릴리스 노트에 "이 문제를 해결했다"고 적혀 있어 적용했더니, 오히려 CPU 스로틀링이 걸려 느려지는 부작용

그래서 미리 다 파악하는 방식으로 가지 않아요. 여러 대시보드로 문제를 파악하고, 탐색을 통해 원인을 발견하는 형태로 대응합니다.

문제를 다루는 네 단계

1. 발견. 중앙화된 모니터링과 로깅으로 타임아웃, finish_reason으로 인한 생성 중단, 레이턴시 급증, 메모리 포화 같은 신호를 탐지하고 알림을 받습니다.

2. 관찰. 알림을 받으면 지표로 들어가 문제를 관찰해요. 메트릭으로 이상치를 못 찾으면 Kibana 등에서 개별 로그를 확인합니다.

3. 가설과 검증. "이런 경우에 문제가 생기고 이런 경우엔 안 생기니 이렇게 해보자"는 가설을 세우고, 변경한 옵션·모델·설정을 ML 플랫폼으로 배포해 스트레스 테스트로 검증합니다.

4. 반영과 롤백. 서비스에 반영하되, 예상 못 한 부작용에 대비해 빠르게 롤백할 수 있도록 시스템을 갖춰둡니다.

마지막으로

LLM의 세계는 너무 빨리 변합니다. 모델만 바뀌는 게 아니라 서빙 프레임워크, 서빙 옵션, 호출 방법까지 계속 바뀌어요. 이걸 전부 따라가는 건 현실적으로 불가능합니다.

그래서 저희는 모두 따라가는 방식 대신, 최대한 많은 지표를 펼쳐두고 문제를 빨리 파악해 원인을 추정하고 빠르게 대응하는 시스템을 갖추기로 했어요.

여러 지표를 두고 동적으로 빠르게 대응할 수 있는 시스템을 만드는 것. 그게 LLM을 그냥 서빙하는 것과 잘 서빙하는 것 사이의 간극을 메우는 일이라고 생각합니다.

✅ 이번 아티클은 토스증권 Tech Talk Talk 세션을 바탕으로 재구성되었습니다.

안녕하세요. 토스에서 광고주가 쓰는 대시보드를 만들고 있는 프론트엔드 개발자 김동희입니다.

저희 팀이 만드는 건 광고주를 위한 화면이에요. 캠페인을 만들고, 예산을 넣고, 어제 쓴 돈이 얼마나 성과로 돌아왔는지 확인하는 곳이죠.

말하자면 '데이터를 보는 도구'를 만듭니다. 그리고 도구를 만드는 일은, 겉으로 보이는 것보다 훨씬 프론트엔드다운 문제들을 던져줘요. 오늘은 그중 하나, 필터 한 번 누를 때마다 서버를 기다리던 대시보드를 고친 이야기를 해보려고 해요.

결론부터 말하면 저희는 서버가 하던 필터링·정렬·검색·페이지네이션을 전부 브라우저로 가져왔습니다. 그런데 흥미로웠던 건, 이 결정으로 얻은 게 속도만이 아니었다는 점이에요.

광고주는 대시보드를 '한 번' 보지 않아요

먼저 광고주가 이 화면에서 실제로 무엇을 하는지 짚어볼게요.

광고 대시보드에는 캠페인 → 광고세트 → 소재라는 3단계 계층이 있어요. 캠페인은 ‘이 예산으로 이런 목표를 달성하겠다’를 정하는 단위, 광고세트는 그 안에서 누구에게 언제 보여줄지를 정하는 단위, 소재는 실제로 사용자 눈에 보이는 이미지와 문구예요. 캠페인 하나에 광고세트 여러 개가, 광고세트 하나에 소재 여러 개가 붙습니다.

이 화면은 성과를 깊게 파고드는 분석 도구는 아니에요. 캠페인·광고세트·소재를 관리하면서 상태를 확인하는 곳에 가깝습니다.

광고주는 여기서 이런 걸 합니다.

한 번 보고 끝나는 화면이 아니에요. 가설을 세우고, 걸러보고, 아니다 싶으면 되돌아가는 탐색 도구에 가깝습니다.

문제는 저 모든 동작이 서버 호출이었다는 것입니다.

한 번의 기다림은 참을 만해요. 그런데 탐색은 한 번이 아니죠. 필터 걸고, 정렬 바꾸고, 페이지 넘기고, 다시 필터 풀고. 열 번이면 수 초가 대기로만 쌓입니다. 그리고 이 시간이 만드는 진짜 비용은 대기 그 자체가 아니라 탐색 포기예요. "이 조합도 한번 볼까?" 하는 시도를 사용자가 하지 않게 되거든요.

느린 도구는 덜 쓰이는 게 아니라, 다르게 쓰입니다.

미리 말씀드리면 이건 저희가 지표로 확인한 게 아니라, 화면을 만들고 써보면서 세운 가정이에요. 다만 이 가정을 받아들이면 고쳐야 할 대상이 달라집니다. 응답 시간이 아니라, 사용자가 시도해볼 수 있는 횟수가 되거든요.

그런데 문제는 속도만이 아니었어요

여기까지만 보면 흔한 성능 개선 이야기입니다. 저희가 이 구조를 바꾸기로 한 진짜 이유는 따로 있었어요.

성능과 무관해 보이는 버그·요구사항이 계속 쌓이고 있었는데, 하나씩 뜯어보니 전부 뿌리가 같았습니다. 클라이언트가 전체 데이터를 갖고 있지 않다는 것이에요.

1. 성과가 0인 항목이 목록에서 사라져요

노출수 기준으로 정렬하면, 노출수가 0인 캠페인이 결과에서 아예 빠졌어요. 버그처럼 보이지만 서버 입장에서는 자연스러운 동작이었습니다. 성과 데이터는 중간 집계 테이블에서 나오는데, 집행되지 않은 캠페인은 애초에 그 테이블에 행이 없거든요. 없는 항목을 전부 0으로 채워 내려주는 건 집계 성능에 좋지 않고요.

그런데 광고주 입장에서 ‘노출이 0인 캠페인’은 없어져야 할 데이터가 아니라 가장 먼저 봐야 할 데이터입니다. 뭔가 잘못 세팅된 캠페인일 가능성이 높으니까요.

2. "캠페인 1234가 몇 페이지에 있지?"에 답할 수 없어요

특정 ID가 몇 번째 항목인지는 전체 순서를 알아야 계산할 수 있는데, 클라이언트는 지금 보고 있는 페이지밖에 갖고 있지 않았어요. 커서 기반 페이지네이션이라 서버에 물어볼 수단도 없었고요. 커서 방식은 ‘이 항목 다음 100개’처럼 직전 위치를 기준으로 다음 묶음을 받아오는 방식이라, 응답에 전체 순번이 담기지 않거든요.

물론 서버가 순번을 못 세는 건 아니에요. 순위를 계산해서 내려주는 API를 따로 만들면 됩니다. 다만 정렬 기준마다 그 API가 하나씩 필요했고, 그건 바로 다음에 나올 3번 문제와 정확히 같은 비용 구조였어요. 그래서 특정 ID로 바로 이동하는 기능은 계속 백로그에 남아 있었습니다.

3. 서버가 지원하지 않는 정렬은 불가능해요

"노출 상태(운영중/일시중지)로 정렬해주세요" 같은 요청이 올 때마다, 먼저 서버 API에 정렬 키를 추가해야 했어요. 화면에 이미 보이고 있는 값인데도요.

4. URL에 담긴 선택 상태를 검증할 수 없어요

저희 대시보드는 선택 상태를 URL에 담습니다. ?campaignIds=1&adsetIds=10&adIds=100 같은 식으로요. 링크로 공유하면 같은 화면이 열리게 하려고요.

그런데 클라이언트에 계층 정보가 없으니, 광고세트 10이 정말 캠페인 1의 자식인지 확인할 방법이 없었어요. 누가 URL을 손으로 고치거나, 오래된 링크를 열면 앞뒤가 안 맞는 화면이 나옵니다.

네 가지 문제를 나란히 놓고 보니 답이 명확해졌어요. 각각을 서버 API 스펙 추가로 하나씩 막는 건 가능했지만, 그건 같은 뿌리에서 계속 자라날 문제의 잎사귀만 잘라내는 일이었습니다.

클라이언트가 전체 데이터를 갖고, 목록의 기준을 클라이언트가 정하면 - 네 문제가 한꺼번에 정리됩니다.

결정: 진입할 때 전부 받고, 그다음은 브라우저에서

그래서 저희는 이렇게 바꿨어요.

필터링·정렬·검색 응답 시간은 수백 ms에서, 기다린다는 느낌이 없는 수준으로 내려갔습니다.

"그거 데이터 많으면 안 되는 거 아니에요?"

맞아요. 그래서 이 결정에서 가장 중요한 건 아키텍처가 아니라 전제 조건이었어요. 전제가 깨지면 이건 좋은 결정이 아니라 나쁜 결정이 됩니다.

즉 저희가 답해야 했던 질문은 "클라이언트 필터링이 좋은가?"가 아니라 "저희 데이터에 상한이 있는가, 그리고 그 상한을 숫자로 확정할 수 있는가?"였어요. 위의 2만 건은 캠페인·광고세트·소재를 전부 합한 수입니다.

상한을 확정할 수 있으면 그다음은 계산 문제가 돼요. 최악의 경우가 정해지니 메모리도, 연산 시간도, 초기 로딩도 미리 재볼 수 있거든요. 반대로 상한을 못 정하는 서비스라면 — 데이터가 사용자 수만큼 무한정 늘어나는 구조라면 — 이 결정은 하면 안 돼요. 언젠가 반드시 깨지기 때문입니다.

그래서 저희가 제일 먼저 한 일은 아키텍처를 그리는 게 아니라, 저희 데이터가 실제로 어디까지 가는지 세어보는 것이었습니다. 이 숫자를 먼저 확정하지 않고 구조부터 그렸다면, 잘 만든 틀린 설계가 나왔을 거예요.

API를 쪼갠 이유

전체 데이터를 받느라 첫 화면이 느려지면 아무 의미가 없죠. 그래서 응답 성격에 따라 API를 쪼갰어요.

쪼개고 나니 캐시 수명도 따로 정할 수 있게 됐어요. Metadata는 5분, 성과는 5초입니다. 캠페인 이름이나 계층은 자주 바뀌지 않지만 성과 숫자는 계속 갱신되니까요. 하나의 API였다면 둘 중 하나에 맞춰야 했을 텐데, 대개는 짧은 쪽에 맞추게 되고 그러면 잘 바뀌지도 않는 데이터까지 계속 다시 받게 됩니다.

이렇게 나누니 세 가지가 자연스럽게 풀렸습니다.

첫째, 점진적 렌더링이 가능해졌어요. Metadata가 도착하는 순간 표를 그리고, 나머지 컬럼은 스켈레톤 UI로 둡니다. 사용자는 가장 느린 API를 기다리는 대신 가장 빠른 API의 속도로 화면을 보게 돼요.

둘째, 성과가 0인 항목이 사라지지 않게 됐어요. 표에 어떤 행이 있는지는 Metadata가 정하고, 성과는 그 행에 ID로 붙는 값일 뿐이에요. 그래서 성과가 없는 캠페인도 행은 그대로 남습니다.

문제를 "성과가 0인 항목을 서버가 내려주게 하자"가 아니라 "목록의 주인이 누구인지 정하자"로 바꿔서 푼 셈이에요.

셋째, 컬럼을 덧붙일 자리가 생겼어요.

"목록의 주인은 Metadata이고, 나머지는 ID 기준으로 붙는다"는 규칙을 세우고 나니, 부가 컬럼 API는 특별한 존재가 아니라 그 규칙을 따르는 또 하나의 컬럼 공급자가 되더라고요. 네 번째, 다섯 번째가 와도 똑같고요.

그래서 표에 새 정보를 붙이는 일이 구조 변경이 아니라 추가가 됐어요. API를 하나 더 호출하고, ID로 병합하고, 도착하면 스켈레톤을 풀면 끝입니다. 표의 골격도, 필터·정렬 로직도 건드리지 않아요. 거꾸로 그 API가 실패하거나 느려도 나머지 화면은 멀쩡하고요. 성과 API가 실패하면 "최신 성과를 불러오지 못하고 있어요"라는 안내만 띄우고 표는 그대로 둡니다. 단일 API였다면 화면 전체가 에러로 갔을 상황이, 이젠 컬럼 하나가 비는 일이 된 거예요.

API를 쪼갠 동기는 속도였는데, 실제로 남은 건 표에 무엇이든 덧붙일 수 있는 자리였습니다.

그런데 여기엔 청구서가 딸려 와요

Metadata를 먼저 그리기로 한 순간, 데이터가 여러 번에 나누어 도착하는 화면이 됩니다.

표는 이미 떠 있는데, 데이터는 아직 도착하는 중이에요.

화면 설계를 그리는 단계에서 바로 보이는 문제였어요. 표는 떠 있는데 클라이언트가 가진 데이터는 계속 불어나죠. 이 어긋남은 두 가지 모양으로 나타났습니다.

첫째, 조작이 데이터보다 앞설 수 있어요. 성과 컬럼이 아직 스켈레톤인데 성과 기준 정렬을 누르면, 존재하지 않는 값으로 줄을 세우게 됩니다. 그래서 아직 도착하지 않은 컬럼은 정렬을 잠가둡니다. 이미 도착한 Metadata 컬럼은 그대로 정렬할 수 있고, 나머지는 값이 도착하는 대로 하나씩 풀려요.

둘째, 화면이 데이터를 따라가야 해요. 이쪽이 더 성가셨습니다. 새 응답이 병합되는 순간, 지금 보고 있는 100건은 다시 계산돼야 해요. 스켈레톤 자리에 값이 들어가야 하니까요. 그다음 응답이 도착하면 또 한 번. 데이터가 도착할 때마다 "다시 그려"라고 호출하는 방법도 있었지만, 그건 호출을 빠뜨리면 조용히 낡은 화면이 남는 코드입니다. 표에 붙는 API가 늘어날수록 잊지 말아야 할 지점도 같이 늘어나고요.

그래서 이 갱신을 캐시 키에 맡겼습니다. 새 데이터가 병합될 때마다 데이터 버전이 올라가고, 화면이 결과를 보관할 때 쓰는 캐시 키에 그 버전을 넣어뒀어요. 버전이 바뀌면 키가 바뀌고, 키가 바뀌면 이전 결과는 더 이상 쓰이지 않아서 화면은 데이터를 다시 요청합니다. 누구도 "데이터 왔으니 다시 그려"라고 말해주지 않아도요. 스켈레톤이 풀리는 것도 그 결과로 따라오는 일이 됐어요.

점진적 렌더링은 ‘먼저 보여주기’라기보다 ‘불완전한 상태를 정식 상태로 인정하기’에 가깝습니다. 로딩 스피너 하나를 스켈레톤으로 바꾸는 일이 아니라, 데이터가 절반만 있는 시간을 설계에 포함시키는 일이에요.

(이 방식이 최선인지는 저희도 계속 들여다보고 있습니다.)

10만 건을 메인 스레드에서 정렬하면 어떻게 될까요?

여기서부터가 프론트엔드의 영역입니다.

10만 건 배열을 filter → search → sort → slice 하는 일을 메인 스레드에서 하면 오래 걸려요. 그동안 클릭도 입력도 큐에 쌓인 채 처리되지 않고, 리렌더도 멈춥니다. 그리고 이건 한 번으로 끝나지 않아요. 검색어를 한 글자 칠 때마다, 필터를 하나 더 걸 때마다 반복되고, 그 위에 React 리렌더가 얹혀요.

서버를 기다리는 시간과는 성격이 다릅니다. 응답을 기다리는 동안 화면은 살아 있어요. 스크롤도 되고 다른 버튼도 눌립니다. 반면 연산이 메인 스레드를 잡고 있는 동안은 화면이 통째로 굳어요.

그래서 데이터와 연산을 통째로 Web Worker로 보냈습니다. 한 가지 짚고 갈 게 있어요. Worker가 연산을 빠르게 만들어주지는 않습니다. 같은 코드가 다른 스레드에서 돌 뿐이에요. 달라지는 건 그동안 메인 스레드가 비어 있다는 점입니다. 연산이 얼마나 걸리든 스크롤도 되고 버튼도 눌리고, 리렌더도 멈추지 않아요.

Worker를 고른 이유는 연산을 줄이려는 게 아니라, 연산하는 시간과 화면이 굳는 시간을 떼어놓으려는 것이었습니다. 참고로 Worker 안에서 한 번의 필터링·정렬·검색·페이지네이션은 10ms 남짓에 끝나요.

이 구조는 저희가 자체 개발한 데이터 계층이에요. 역할은 세 가지로 나눴어요.

조율과 통신을 굳이 나눈 이유는 하나예요. Worker가 죽는다는 사실을 조율 계층이 몰라도 되게 하려고요. 재생성·타임아웃·상태 확인이 전부 통신 계층 안에서 끝나서, 바깥에서는 그냥 데이터를 요청하는 코드로 보입니다.

그런데 왜 Worker가 직접 데이터를 받아오지 않나요?

위 그림을 보면 바로 걸리는 지점이 있어요. 어차피 데이터를 Worker가 들고 있을 거면, 처음부터 Worker가 API를 부르면 되지 않나? 메인 스레드를 한 번도 안 거쳐도 될 텐데요.

저희도 그 구조를 먼저 그려봤어요. 그런데 막힌 건 성능이 아니라 API 클라이언트였습니다. 저희 API 호출은 공통 HTTP 클라이언트를 거쳐요. 인증뿐 아니라 공통 에러 처리, 재시도 같은 게 전부 여기에 얹혀 있고요. Worker에서 직접 요청을 보내려면 이 계층을 Worker 쪽에 한 벌 더 두거나 별도 경로를 만들어야 했습니다. 같은 규칙을 두 곳에서 관리하게 되는 거죠. 전송 몇 번을 아끼려고 낼 값은 아니라고 봤어요.

대신 지금 구조에서 메인 스레드가 실제로 치르는 값을 따져봤습니다. 응답을 받아 Worker로 넘기는 일, 그게 전부예요. 본문을 해석하고 다루는 건 전부 Worker 몫이고요. 게다가 그 넘기는 일조차 API마다 한 번씩, 진입할 때가 전부입니다. 그 한 번을 어떻게 싸게 넘기는지는 바로 뒤에서 이야기할게요.

그래서 지금은 이 구조를 유지하되, 다음 개선 때는 HTTP 클라이언트를 Worker에서도 쓸 수 있는 형태로 정리해보려고 해요. 이건 "이게 정답이다"가 아니라, 지금 구조에서 메인 스레드가 치르는 값이 충분히 작다고 판단한 결과입니다.

Worker를 쓰면 따라오는 세 가지 함정

Worker는 ‘무거운 일 넘기면 끝’이 아니에요. 넘기는 비용이 따라옵니다.

1️⃣ 직렬화 비용. postMessage는 기본적으로 구조화 복제(Structured Clone)를 합니다. 보내는 쪽 데이터를 통째로 복사해서 받는 쪽에 새로 만드는 방식이에요. 10만 건을 매번 복사하면 Worker로 옮긴 이득이 사라집니다.

→ 그래서 초기 데이터는 응답을 res.arrayBuffer()로 받아 Transferable(ArrayBuffer)로 소유권만 넘깁니다. 메인 스레드는 본문을 파싱조차 하지 않아요. 복사 없이 버퍼의 주인을 바꿔버리는 방식이라, 보낸 쪽은 그 버퍼를 더 이상 쓸 수 없게 되는 대신 복사 비용이 0이에요. 이후 Worker가 돌려주는 건 현재 페이지 100건뿐입니다. 처음에 넘어간 전체 데이터와 비교하면 무시해도 될 크기예요. 위 그림의 화살표 두 개가 비대칭인 이유예요. 큰 건 진입할 때만 건너가고, 그다음부터는 작은 것만 오갑니다.

2️⃣ 메모리 이중화. 메인 스레드와 Worker가 같은 데이터를 각각 들고 있으면 메모리를 두 배로 씁니다.

→ 전체 데이터는 Worker에만 둡니다. 메인 스레드는 지금 화면에 그릴 100건만 알아요. 전체 데이터를 클라이언트로 가져왔는데도 React가 들고 있는 양은 이전과 똑같은 셈이에요.

3️⃣ 비동기 복잡도. Worker 통신은 요청과 응답이 자동으로 짝지어지지 않는 이벤트 기반이에요.

→ 통신 계층이 요청 ID와 Promise를 짝짓는 일을 전담해서, 바깥에서는 그냥 await 하는 함수처럼 보이게 감쌌습니다.

Worker가 죽으면요?

이게 실무에서 제일 중요한 질문이었어요. 데이터를 Worker에 다 넣어뒀는데 Worker가 죽으면 화면이 통째로 빈 상태가 되니까요.

먼저 죽었다는 걸 알아야 해요. Worker에 5초마다 Ping을 보내고, 3초 안에 답이 없으면 죽은 걸로 봅니다. 사용자가 보낸 요청이 처리 중일 때는 이 검사를 건너뛰어요. 그 요청에는 이미 10초 타임아웃이 걸려 있으니까요.

죽은 걸 확인하면 Worker를 정리하는데, 그다음이 두 갈래로 갈립니다. 기준은 "지금 답을 기다리는 사람이 있는가"예요.

• 대기 중인 요청이 있으면 → 그 요청들을 전부 실패시켜 ErrorBoundary로 올려보냅니다. 사용자가 "다시 시도"를 누를 때 복구해요. 누군가 화면 앞에서 기다리고 있는 상황이라면, 조용히 처리하는 것보다 무슨 일이 있었는지 알리는 게 맞다고 봤어요.
• 대기 중인 요청이 없으면 → 사용자가 눈치채기 전에 알아서 복구합니다. 캐시를 무효화하면 데이터 로딩이 다시 돌고, API를 다시 호출해서 받은 버퍼를 새 Worker에 넣어요.

두 번째 경로를 보면 알 수 있듯이, 복구는 ‘캐시만 비우면 끝’이 아니에요. 데이터가 Worker에만 있으니, Worker가 죽었다는 건 데이터가 없어졌다는 뜻입니다. 서버에서 다시 받아오는 것 말고는 방법이 없어요. 진입할 때 했던 일을 그대로 한 번 더 하는 셈입니다. 이게 "전체 데이터를 클라이언트에 둔다"는 결정에 딸려 온 비용이에요.

그리고 죽은 순간의 정황을 같이 남깁니다. 대기 중이던 요청이 무엇이었는지, 탭이 백그라운드였는지, 그 시점 메모리 사용량은 얼마였는지. 메모리 부족으로 죽은 건지 다른 이유인지 나중에 판단하려면 이게 있어야 하거든요.

못 만들던 기능이 만들 수 있는 기능이 됐어요

여기까지가 구조 이야기예요. 이제 앞에서 세운 네 가지 문제로 돌아가볼게요. 저는 이 작업에서 이 부분이 제일 재미있었습니다.

1. 성과가 0인 항목이 사라지지 않아요

목록의 주인을 Metadata로 정하면서 자동으로 해결됐어요. 서버에 "성과가 없는 항목도 0으로 채워서 내려달라"고 요청할 필요가 없어졌고, 집계 테이블은 집계 테이블대로 남겨둘 수 있었습니다.

2. "캠페인 1234가 몇 페이지에 있지?"에 답할 수 있어요

전체 배열을 갖고 있으니 답이 두 줄이에요. 배열을 들고 있는 쪽이 Worker이니, 이 계산도 Worker 안에서 돌아갑니다.

광고주가 어디선가 받은 캠페인 ID를 붙여넣으면, 그게 몇 페이지에 있든 바로 그 행으로 갑니다. 이 기능을 위해 추가한 서버 API는 없어요. 예전엔 이 두 줄을 쓸 수 없어서 기능 자체가 백로그에 있었습니다.

3. 서버가 모르는 기준으로도 정렬할 수 있어요

"노출 상태로 정렬해주세요" 같은 요청이 오면 비교 함수 하나를 추가하면 끝이에요. 서버 API 스펙 변경도, 배포 순서 조율도 필요 없습니다. 화면에 이미 보이는 값이라면 그 값으로 정렬할 수 있어요.

4. URL에 담긴 선택 상태를 검증할 수 있어요

Metadata에 부모 ID가 있으니, 진입할 때 ?campaignIds=1&adsetIds=10 같은 조합이 실제 계층과 맞는지 한 번 확인합니다. 광고세트 10의 부모가 캠페인 1이 아니면 그 선택은 버리고요. 오래된 링크를 열어도 앞뒤가 맞는 화면이 뜹니다.

네 개를 나란히 놓고 보면 공통점이 있어요. 전부 "서버에 무엇을 더 요청할까"가 아니라 "이미 가진 데이터로 무엇을 계산할까"의 문제가 됐습니다. 데이터를 어디에 두느냐를 바꿨을 뿐인데요.

고려했지만 선택하지 않은 것들

결정만큼 중요한 게 안 한 결정이라고 생각해서, 기각한 선택지도 남겨뒀어요.

Virtual Scrolling

큰 목록 이야기가 나오면 거의 자동으로 따라오는 카드죠. 하지만 저희는 100건 단위 페이지네이션을 씁니다. 한 번에 그리는 건 100행이고, 이 정도면 컬럼이 수십 개여도 DOM(Document Object Model) 부하가 병목이 아니라는 걸 확인했어요. Virtual Scrolling은 수천 개 행을 한 화면에 스크롤로 펼칠 때 필요한 도구고, 저희 UX는 그런 모양이 아니었습니다.

"데이터가 많다"와 "DOM이 많다"는 다른 문제인데, 자주 같은 문제로 취급돼요.

IndexedDB 캐싱

전체 데이터를 받는다면 브라우저에 저장해뒀다가 다음에 재활용하고 싶어지죠. 그런데 기각했습니다.

지금 필요 없는 걸 만들지 않는 것도 설계라고 봤어요.

감수하기로 한 것

트레이드오프가 없는 결정은 대개 결정이 아니라 취향이라고 생각해요. 저희는 위 세 가지를 알고 골랐습니다.

광고 도메인 프론트엔드는 이런 문제를 풀어요

이 글은 결국 대시보드 하나를 고친 이야기지만, 광고 도메인에서 프론트엔드가 마주치는 문제의 생김새를 꽤 잘 보여준다고 생각해요.

프론트엔드가 화면만 그리는 일처럼 느껴져 아쉬웠다면, 이런 문제들이 꽤 반가우실 거예요. 저는 그래서 이 도메인이 재밌습니다.

결정은 문서로 남습니다

저희는 이렇게 내린 판단을 코드와 문서에 남깁니다. 결정 문서에는 고른 선택지뿐 아니라 기각한 선택지와 그 이유가 같이 들어가고, 코드 주석에는 ‘왜 이 조건에서는 검사를 건너뛰는지’ 같은 판단이 남아요. 아직 확정되지 않은 부분에는 ‘변경 가능성 있음’이라고 적어두고요.

사실 이 글의 절반은 그때 남겨둔 문서에서 그대로 나왔습니다. 아티클을 쓰려고 새로 정리한 게 아니라, 이미 있던 걸 꺼낸 거예요.

아직 못 푸는 문제

지금 구조에서 가장 아픈 곳은 첫 진입이에요. 필터도 정렬도 즉시 끝나지만, 그 즉시가 시작되기까지가 느립니다. 진입할 때 전체 데이터를 받아야 하니까요.

점진적 렌더링으로 ‘표가 뜨는 시점’은 앞당겼지만, ‘표가 완전히 살아나는 시점’은 여전히 늦어요. 그리고 데이터가 많은 계정일수록 더 느립니다. 이 구조의 이득을 가장 크게 보는 계정이 비용도 가장 많이 내는 셈이에요.

곤란한 건 이걸 쉽게 버릴 수 없다는 점입니다. 이 글에서 이야기한 이득이 전부 ‘클라이언트가 전체 데이터를 갖고 있다’는 한 가지에서 나오거든요. 첫 페이지만 먼저 받는 식으로 진입을 빠르게 만들면, 그 순간 ID로 페이지를 계산하는 것도 URL 계층을 검증하는 것도 다시 불가능해집니다.

그래서 지금은 ‘전제를 지키면서 진입만 빠르게 할 수 있는가'를 보고 있어요. 아직 답은 없습니다.

이 글을 읽으면서 "나라면 이렇게 했을 텐데" 싶은 지점이 있었다면, 그 얘기를 듣고 싶어요.

읽어주셔서 감사합니다.

안녕하세요, 토스에서 광고 SDK와 게임 광고 서비스를 개발하는 Frontend Developer 정윤호입니다.

토스 지면에 게임 광고가 적었던 이유

토스 지면(앱 안에서 광고가 노출되는 자리)에는 게임 광고 집행이 유독 적었습니다. 원인은 소재 유형이었어요. 게임 회사의 사용자 확보(UA, User Acquisition) 마케팅에서, 앱을 설치하기 전에 광고 안에서 게임을 직접 해 보는 플레이어블 광고(Playable Ads)가 주목받는 광고 유형인데, 토스 지면이 이 유형을 받지 못했어요.

광고에 실려 나가는 콘텐츠를 업계에서는 소재(크리에이티브)라고 불러요. 광고 플랫폼 Moloco는 자사 상위 미국 게임 광고주 사례에서 플레이어블 소재가 노출 천 회당 설치 수(IPM, Installs Per Mille)를 49%, 광고비 대비 수익(ROAS, Return On Ad Spend)을 25% 끌어올렸다고 소개해요. 게임 광고주는 성과로 매체를 선택하니, 이 소재 유형을 받지 못하는 지면에 예산을 배정할 이유가 약했던 거예요.

그래서 문제를 다시 정의했습니다. "게임 광고 영업이 안 됐다"가 아니라 "게임 광고주가 쓰는 소재 유형을 우리 지면이 받지 못했다"는 것으로요.

보통의 앱은 광고 네트워크의 상용 SDK(Software Development Kit)를 붙여 플레이어블 지원을 통째로 얻어요. 토스는 광고 시스템을 서버부터 직접 만들어 왔기 때문에 그 위에 서드파티 SDK를 얹으면 통합도 통제도 어긋나요. 광고를 선택하는 시스템을 직접 만든 이상, 화면에 띄우는 쪽도 직접 만드는 게 좋은 방향이라고 판단했어요.

그렇게 플레이어블 광고를 직접 구현한 여정을 소개할게요.

플레이어블 광고의 구조

우선 플레이어블 광고가 어떻게 돌아가는지부터 볼게요. 플레이어블 광고 한 편이 화면에 뜨기까지의 흐름은 이렇습니다.

소재는 HTML 파일 하나에 게임 한 판이 통째로 담긴 형태이고, 등록 시점에 단일 HTML, 5MB 제한을 검사받아요. 광고를 화면에 붙이고 떼는 권한, 클릭과 노출을 기록하는 권한은 네이티브 앱에 있어요.

브릿지 JS(JavaScript)는 광고 소재와 네이티브 앱 사이의 통신을 맡아요. 둘은 서로를 모르는 코드라 직접 대화할 방법이 없어요. 소재가 호출할 API(Application Programming Interface)를 제공하고, 광고의 상태를 들고, 메시지를 양방향으로 나르는 게 브릿지 JS의 일이에요.

광고 한 편이 뜨고 닫히기까지의 이벤트 순서예요. 사용자에게는 광고 한 편이 떴다 닫히는 단순한 경험이지만, 그 뒤에서는 구성요소들이 이렇게 이벤트를 주고받고 있어요.

브릿지 JS 규약으로 MRAID를 선택한 이유

위에서 설명했던 브릿지 JS가 소재에게 제공할 API 규약은 어떻게 정해야 할까요? 소재는 토스만 보고 만들어지는 자산이 아니라서, 저희 마음대로 정할 수 없었어요.

제작사는 같은 소재를 Meta, Google 같은 광고 네트워크(광고주와 지면을 연결해 광고를 유통하고 중개하는 사업자) 여러 곳에 제출해요. 실제로 소재는 각 네트워크의 규약에 맞춰 만들어지는데, 그 규약이 서로 달라서 지면마다 소재를 다시 만들어야 해요.

클릭(CTA, Call To Action)은 설치로 이어지는 전환의 입구라, 소재 성과 지표 가운데 중요한 이벤트예요. 소재마다 클릭을 알리는 함수가 다르면 집계 입구가 갈라져서 일관성과 신뢰도가 함께 흔들려요. 그래서 모든 규약을 받는 만능 컨테이너 대신, 규약 하나를 선택해 깊게 지원하기로 했어요.

선택한 표준은 MRAID(Mobile Rich Media Ad Interface Definitions)입니다. 표의 Meta와 Google은 광고주 접점부터 소재를 그리는 SDK까지 수직 통합한 덕분에, 독자 규약을 강제할 수 있는 예외적인 사업자예요. Moloco처럼 Meta 규약을 따라가는 곳도 있어요. 그래도 그 밖의 인앱 광고 생태계에서는 IAB(Interactive Advertising Bureau) Tech Lab이 관리하는 MRAID가 표준으로 널리 쓰이고, AppLovin처럼 지원을 필수로 요구하는 네트워크가 있을 만큼 소재 수급에도 유리했어요.

결정적이었던 건 공급 구조예요. 스펙상 소재는 브릿지 JS를 쓸 때 <script src="mraid.js"> 한 줄만 선언하고, 실제 브릿지 JS 파일은 광고를 띄우는 호스트가 공급해요. 인터페이스는 표준으로 고정하되 구현은 호스트가 진화시킬 수 있다는 뜻이라 저희에게 꼭 맞았어요. 그림 1에서 본 브릿지 JS 주입이 바로 이 구조의 구현이에요. 스펙이 정한 파일 이름을 따라, 지금부터는 브릿지 JS를 mraid.js라고 부를게요.

다만 MRAID 전체를 구현하지는 않았어요. 기준은 하나였어요. "실제로 서빙할 소재가 호출하는 API만 만든다." 스펙에는 배너 확장(expand), 사진 저장(storePicture) 같은 기능이 가득한데, 기능마다 유지 비용이 함께 따라오기 때문이에요.

호출하는 소재가 없는 API는 구현하지 않되, 미지원 호출이 들어와도 크래시 대신 supports() false와 error 이벤트로 답하게 했어요. Google 모바일 광고 SDK도 getLocation()은 항상 -1을 반환하고 storePicture는 제거했다고 명시할 만큼, 부분 구현은 업계의 일반적인 선택이에요.

이 기준 덕분에 나중에 MRAID 3.0을 지원할 때도 스펙 전체를 따라갈 필요가 없었어요. 3.0 소재가 실제로 새로 호출하는 API는 두 개뿐이었고, 그 둘만 더해서 표준의 메이저 버전 업그레이드가 백여 줄로 끝났어요.

mraid.js의 네 가지 모듈

그렇게 좁힌 API 표면을 받치는 mraid.js의 내부를 모듈 네 개로 구성했어요.

mraid.js는 표준 API를 구현한 객체를 window.mraid 전역으로 정의하고, 소재는 이 전역을 호출해요. 게임 엔진과 에셋을 걷어내면, 소재가 사용하는 표준 패턴은 이 형태예요.

소재는 mraid.js의 존재를 전제하고, 시작 시점은 상태와 이벤트로 묻고, 밖으로 나가는 요청은 mraid.open() 하나로 보내요. 이 계약을 호스트 쪽에서 받치는 게 네 모듈이에요.

송신부는 자바스크립트에서 네이티브로 가는 방향의 규약이 전부예요.

메시지는 { command, payload } JSON 문자열 하나로 통일하고 플랫폼 채널만 분기해요. 브릿지가 없으면 경고만 남기고 광고는 계속 동작해요. 제작사가 일반 브라우저에서 소재를 미리보기로 여는 상황까지가 정상 동작 범위이기 때문이에요.

수신부는 네이티브의 호출을 mraid.nativeInvoke(event, payload)라는 단일 진입점으로 받아요. iOS와 Android가 문자 그대로 같은 규약을 호출하고, 이벤트와 페이로드 쌍은 TypeScript 판별 유니온(Discriminated Union) 타입으로 강제해요. 구현이 계약에서 어긋나면 컴파일 단계에서 드러나요.

본체에서 중요했던 결정은 상태 소유권이에요. 실제로 오가는 상태는 loading → default → hidden인데, mraid.js는 네이티브가 준 값을 검증 없이 반영하고 이벤트만 발사해요. 광고 뷰가 화면에 있는지, 사용자가 백그라운드로 나갔는지는 네이티브만 알기 때문이에요. 그림 2의 ready가 이 원칙의 출발점이에요. 네이티브가 초기 상태를 한 번에 밀어 넣으면, mraid.js는 상태를 default로 바꾸는 stateChange부터 준비 완료를 알리는 ready, 노출 상태를 알리는 viewableChange까지 연쇄로 발사해요.

mraid.close()도 같은 원칙 위에 있어요. 광고를 닫는 함수처럼 보이지만 실제로는 요청일 뿐이라 제거 권한은 네이티브에 있고, 최소 시청 시간 전의 닫기 요청은 무시돼요. 거꾸로 네이티브가 광고 뷰를 걷어낼 때는 stateChange('hidden')이나 viewableChange(false)를 먼저 발사해서, 소재가 사운드를 멈추고 씬을 정지할 기회를 줘요.

MRAID 표준을 벗어나는 요구 다루기

mraid.js가 브릿지로서 표준에 없는 요구까지 감당해야 할 때도 있어요. 대표가 엔드카드(End Card)예요. 게임이 끝난 뒤 설치를 한 번 더 권하는 마무리 화면인데, MRAID에는 없는 토스 지면만의 기능이에요. 광고주는 이 화면을 소재에서 쓰고 싶어 하고, 보여줄 타이밍은 게임 진행을 아는 소재만 알아요. 소재가 호스트에게 알릴 통로가 필요했어요.

이 통로를 표준 API인 window.mraid에 끼워 넣어도 될까요? 저희는 끼워 넣지 않았어요. mraid.js는 주입될 때 전역 객체를 둘 설치해요. 표준 API를 구현한 window.mraid, 그리고 표준 밖 기능을 담당하는 window.tossPlayableAds예요.

표준을 지키는 쪽과 넘어서는 쪽을 분리해 두면, 어느 한쪽을 바꿔도 다른 쪽이 흔들리지 않아요.

엔드카드를 쓰려는 소재는 플레이어블 광고가 종료되는 순간 tossPlayableAds를 호출하고, 요청을 받은 네이티브가 엔드카드 UI를 노출해요.

빈 화면을 거르는 rendered 신호

웹뷰에 빈 화면이 떠 있는 동안도 광고 노출일까요? 노출(Impression)은 돈과 직결되는 숫자라 답을 대충 정할 수 없었어요.

캔버스 게임 엔진은 HTML 로드가 끝난 뒤에도 폰트와 이미지를 디코딩하고 씬을 조립해요. 첫 프레임까지 사용자에게 보이는 건 아무것도 없는 화면이라, 이때 노출 판정을 시작하면 빈 화면만 보고 이탈한 사용자도 노출로 집계돼요.

그래서 표준 밖 신호를 하나 만들었어요. 그림 2에서 ready와 나란히 달리던 rendered, 웹이 "실제로 그려졌다"를 스스로 감지해 네이티브로 보고하는 신호예요.

이 신호는 네이티브가 노출 판정을 시작하는 선행 조건으로 삼도록 설계했어요. 최소 시청 시간을 재는 스킵 타이머도 rendered를 받은 뒤에야 시작해요. 판정이 이르면 빈 화면을 보던 시간이 시청 시간에 포함되고, 늦으면 이미 게임 중인 사용자가 광고를 닫지 못해요.

문제는 "그려졌다"를 한 번에 알려 주는 단일 신호가 브라우저에도 표준에도 없다는 것이었어요.

그래서 각자 다른 것을 보장하는 신호 다섯 개를 순서대로 통과시키기로 했어요.

다섯 신호가 각각 보장하는 범위는 이렇습니다.

어느 하나도 충분조건이 아니지만 순서대로 통과시키면 "빈 화면인데 노출로 셌다"의 확률이 실용적인 수준까지 내려가요. 준비 신호(폰트, 이미지, 첫 페인트)를 2초 타임아웃과 경쟁시킨 건, 이미지 하나가 판정 전체를 붙잡아 두지 못하게 하기 위해서예요.

이와 별도로 2.3초 안전망 타이머가 항상 돌아요. 감지가 다 실패해도 source: 'timeout'으로 반드시 한 번 발사해요. 감지 로직의 실패가 광고 노출 자체를 막으면 안 되기 때문이에요.

rendered는 어떤 경로로 몇 ms 만에 감지됐는지를 { source, latencyMs }에 실어 보내요. 타임아웃 폴백 비율이 올라가면 어느 신호가 약한지 추적할 수 있어요.

소재를 믿지 않는 구조

소재는 외부에서 제작한 코드인데 저희 SDK와 같은 window, 같은 자바스크립트 컨텍스트를 공유해요. iframe 같은 문서 경계도 없어요.