<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[SpoonLabs - Medium]]></title>
        <description><![CDATA[Blog for SpoonLabs - Medium]]></description>
        <link>https://medium.com/spoontech?source=rss----bb1e592ad19a---4</link>
        <image>
            <url>https://cdn-images-1.medium.com/proxy/1*TGH72Nnw24QL3iV9IOm4VA.png</url>
            <title>SpoonLabs - Medium</title>
            <link>https://medium.com/spoontech?source=rss----bb1e592ad19a---4</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Tue, 17 Nov 2026 03:17:36 GMT</lastBuildDate>
        <atom:link href="https://medium.com/feed/spoontech" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[우리의 iOS 인앱 결제 불법 환불을 막기 위한 시도]]></title>
            <link>https://medium.com/spoontech/%EC%9A%B0%EB%A6%AC%EC%9D%98-ios-%EC%9D%B8%EC%95%B1-%EA%B2%B0%EC%A0%9C-%EB%B6%88%EB%B2%95-%ED%99%98%EB%B6%88%EC%9D%84-%EB%A7%89%EA%B8%B0-%EC%9C%84%ED%95%9C-%EC%8B%9C%EB%8F%84-0d85f3954a11?source=rss----bb1e592ad19a---4</link>
            <guid isPermaLink="false">https://medium.com/p/0d85f3954a11</guid>
            <category><![CDATA[tech]]></category>
            <dc:creator><![CDATA[Joe]]></dc:creator>
            <pubDate>Mon, 04 May 2026 08:25:40 GMT</pubDate>
            <atom:updated>2026-04-11T07:49:24.877Z</atom:updated>
            <content:encoded><![CDATA[<p>안녕하세요 SpoonLabs 에서 Business Platform Team 백엔드 서버 개발을 맡고있는 Joe(원주호) 입니다. <br>저는 iOS 앱의 주 수익원인 인앱 결제에 관해서 이야기를 하려고 합니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*FeR_NR6_u9_jD7C6QKJVlA.png" /><figcaption>인앱 서비스 느낌?</figcaption></figure><h4>iOS 인앱 결제에 대해 먼저 이야기 해보자</h4><p>iOS 앱에서 유료 콘텐츠를 판매하려면 대부분 <strong>Apple의 인앱 결제(In-App Purchase)</strong>를 사용하게 됩니다.</p><p>이건 단순히 결제 수단 하나를 붙이는 문제라기보다, 결제와 환불, 그리고 그 이후의 모든 흐름을 Apple의 시스템 안으로 맡기는 선택 입니다.</p><p>사용자가 앱에서 상품을 선택하고 결제를 누르면, 실제로 돈이 오가는 순간은 서비스가 아니라 <strong>Apple App Store</strong>에서 일어납니다.</p><p>결제 승인, 카드 정보 처리, 영수증 발급까지 모두 Apple의 책임이며, <strong>서비스는 그 결과를 받아서 “이 사용자가 무엇을 샀는지”를 확인하고 구매에 대한 서비스내 재화를 지급하는 역할을 맡습니다.</strong></p><p>조금 더 보태어 말하면, 앱 서비스 제공자는 결제를 <strong>직접 처리하지 않습니다</strong>.</p><p>대신 <strong>Apple이 “결제는 완료됐다”</strong>고 알려주면, 그 말을 믿고 아이템을 지급하거나 구독 권한을 열어주는 구조입니다.</p><h4>결제 흐름은 어떨까?</h4><p>흐름 자체는 복잡하지 않습니다.</p><p>앱 접속 - 결제 상품 선택 - iOS가 익숙한 App Store 결제 화면 노출 - 결제 끝 (Apple 의 영수증을 발급)</p><p>그 다음 부터가 서비스의 역할입니다.<br>이 영수증 (또는 결제 주문번호 등)을 서버에서 검증하고, 문제가 없으면 해당 사용자에게 구매 상품에 대한 아이템 또는 권한을 제공합니다.</p><p>여기까지 보면 꽤 깔끔한 구조처럼 보입니다.<br>사용자는 안전하게 결제할 수 있고, 서비스는 민감한 결제 정보를 직접 다루지 않아도 됩니다.<br>Apple이 제공하는 이 구조 덕분에 iOS 결제 경험이 일관되게 유지되는 것도 사실입니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/720/1*uBdJ9esrCz2jzPg4QI9cSQ.png" /></figure><h4>하지만</h4><p><strong>결제와 관련된 모든 최종 결정권은 Apple이 가진다</strong>는 점입니다.</p><p>서비스는 결제를 승인하거나 거절할 수 없고, 환불 역시 서비스가 아니라 Apple의 정책에 따라 처리됩니다.</p><p>사용자가 환불을 요청했는지, 어떤 사유로 승인되었는지조차<br>서비스 입장에서는 알기 어려운 경우가 많습니다.</p><p>이건 단순한 기술적 제약이라기보다,<br>Apple이 사용자 경험과 소비자 보호를 최우선에 두고 설계한 결과에 가깝습니다.</p><p>사용자는 앱마다 환불 정책을 찾아다닐 필요 없이<br>Apple 계정 하나로 결제 내역과 환불을 관리할 수 있고,<br>문제가 생기면 서비스가 아니라 Apple에 바로 요청할 수 있습니다.</p><h4>그럼 진짜 문제는 무엇인가?</h4><p>진짜 문제는 Apple 이 제공하는 IAP 시스템을 악용하는 유저가 존재한다는 것입니다.</p><p>사용자 아이템 구매 후 전부 소진 상태 이후 서비스에 어떤 요청도 하지 않은 채, Apple에 직접 인앱 결제 환불을 요청하는 상황입니다.</p><p>그리고 이 환불은 Apple 기준으로는 <strong>정상적인 절차</strong>입니다.<br>문제는 그 환불이 처리되는 동안,</p><p>혹은 처리된 이후에도<br>서비스는 그 사실을 즉시 알지 못할 수 있다는 점입니다.</p><p>환불은 끝났는데,<br>사용자는 여전히 아이템을 쓰고 있고,</p><p>구독 권한도 살아 있고,<br>서비스는 아무 일도 없었다는 듯 정상적으로 리소스를 제공합니다.</p><p>사용자 입장에서는 환불을 받았고,<br>Apple 입장에서도 정책에 맞게 처리했다.</p><p>하지만 서비스 입장에서는 그제야 질문이 생깁니다.</p><blockquote><em>“이 상황을 언제, 어떻게 알아야 했을까?”</em></blockquote><h4><strong>환불을 “알 수 있는” 거의 유일한 방법</strong></h4><p>이 질문에 대한 답을 찾다 보면, 결국 하나의 기능으로 수렴하게 됩니다.</p><p>바로 <strong>App Store Server Notifications</strong>입니다.</p><p>Apple은 인앱 결제와 관련된 주요 상태 변경이 발생했을 때,</p><p>해당 이벤트를 <strong>서버 간 통신 방식으로 전달해주는 기능</strong>을 제공하는데<br>결제 완료, 구독 갱신, 해지, 그리고 우리가 관심을 가질 수밖에 없는 <br><strong>환불 관련 이벤트</strong> 역시 여기에 포함이 됩니다.</p><p>중요한 점은,<br>이 알림이 앱으로 오는 것이 아니라 <strong>서비스 서버로 직접 전달된다는 것</strong>입니다.</p><p>즉, 환불을 포함한 결제 상태 변화는<br>“사용자가 앱을 실행했을 때”가 아니라<br><strong>Apple이 판단을 내린 시점에 서버가 먼저 알 수 있는 구조 </strong>라는 것 입니다.</p><h4>그래서 서버가 필요해진다</h4><p>App Store Server Notifications를 사용하려면,<br>서비스는 반드시 <strong>알림을 수신할 서버 엔드포인트</strong>를 준비해야 합니다.</p><p>Apple은 결제 또는 구독의 특정 이벤트가 발생하면<br>사전에 등록된 URL로 <strong>HTTP POST 요청</strong>을 보내고,<br>그 요청에는 결제 또는 구독의 어떤 변화가 일어났는지가 담겨 있습니다.<br>여기서부터 선택의 문제가 생깁니다.</p><ul><li>이 알림을 단순히 로그로만 남길 것인가</li><li>아니면 서비스의 상태를 실제로 변경하는 트리거로 사용할 것인가</li></ul><p>불법 환불, 혹은 서비스 입장에서 통제되지 않은 환불을 다루려면<br>후자를 선택할 수밖에 없습니다.<br>결국 <strong>“알림을 받는 서버”</strong> 가 아니라,<br><strong>“알림을 이해하고 반응하는 서버” </strong>를 만들어야 했습니다.</p><h4>Notification이 알려주는 것들</h4><p>App Store Server Notifications는 생각보다 많은 정보를 제공합니다.</p><p>다만, 그만큼 <strong>해석을 잘못하면 위험한 이벤트</strong>도 많습니다.</p><p>예를 들어 다음과 같은 종류들이 있습니다.</p><ul><li>결제가 최초로 완료되었을 때</li><li>구독이 정상적으로 갱신되었을 때</li><li>사용자가 구독을 해지했을 때</li><li>환불이 승인되었을 때</li><li>환불로 인해 결제 트랜잭션이 무효화되었을 때</li></ul><p>문제는,<br>이 이벤트들이 “사용자 행동” 기준이 아니라<br><strong>Apple의 상태 머신 기준</strong>으로 전달된다는 점입니다.</p><p>즉, 해지와 환불은 전혀 다른 이벤트고,<br>환불 역시 모든 경우가 같게 처리되지는 않습니다.</p><h4>환불 Notification을 그대로 믿을 수 있을까</h4><p>환불 관련 Notification을 처음 마주했을 때,<br>가장 먼저 든 생각은 이것이었습니다.</p><blockquote><em>“이 이벤트가 오면 바로 권한을 회수하면 되는 걸까?”</em></blockquote><p>하지만 실제로는 그렇게 단순하지 않았습니다.</p><p>환불 Notification은 종종</p><ul><li>이미 사용된 아이템에 대해 늦게 도착하기도 하고</li><li>일시적인 상태 변화만 알려주기도 하며</li><li>이후 다른 이벤트로 다시 상태 변경</li></ul><p>즉, <strong>Notification은 ‘결론’이 아니라 ‘신호’에 가깝다.</strong></p><p>그래서 다음과 같은 방식으로 대응하기로 했습니다.</p><h3>선택한 대응 방식</h3><p>첫째,<br>Notification 수신 자체는 <strong>항상 성공하도록</strong> 설계했습니다.<br>이 단계에서 실패하면, 그다음은 아예 기회가 없기 때문입니다.</p><p>둘째,<br>Notification을 받았다고 해서<br>즉시 사용자 상태를 변경하지는 않았습니다.<br>대신 해당 트랜잭션에 대해 <strong>서버에서 다시 한 번 검증</strong>하였습니다.</p><p>셋째,<br>환불로 최종 판단이 내려진 경우에만<br>아이템 회수와 같은 실질적인 조치를 수행했습니다.</p><p>이 과정은 복잡하게 보이지만,<br>환불이라는 이벤트가 가진 불확실성 및 상태에 맞는 정확한 처리를 고려한다면 이 정도의 대응은 필요하였습니다.</p><h4>환불 이후, 서비스는 무엇을 할 수 있었을까</h4><p>환불을 알게 된 이후의 대응은 생각보다 단순하면서도 조심스러웠습니다.<br>이미 결제는 취소됐고, Apple의 판단은 끝난 상태이었습니다.</p><p>이 시점에서 서비스가 할 수 있는 일은 <strong>“되돌릴 수 없는 것을 되돌리려 애쓰는 것”</strong>이 아니라,</p><p><strong>지금 이 상태를 어떻게 정리할 것인가</strong>에 가깝습니다.<br>환불이 최종 확정된 경우에만<br>다음과 같은 조치를 단계적으로 적용했습니다.</p><ul><li>제공된 아이템 회수</li><li>회수가 불가능하다면 서비스내 사용자 플래그 처리 (제제)</li></ul><p>여기서 중요한 원칙은 하나 입니다.</p><p><strong>환불 이전에 사용된 것까지 소급 하지 않는다</strong>는 점이다.</p><p>이미 소비된 리소스를 다시 회수하려고 하면,<br>기술적으로도 복잡해지고 사용자 경험도 급격히 나빠집니다.<br>그래서 우리는 “환불 이후의 상태” 에만 집중하기로 했습니다.</p><h4>그렇다면, 환불을 당하기 전에 할 수 있는 일은 없을까</h4><p>이쯤 되면 자연스럽게 이런 질문이 생깁니다.</p><blockquote><em>“환불이 일어난 다음이 아니라,</em></blockquote><blockquote><em>그 전에 뭔가 할 수 있는 건 없었을까?”</em></blockquote><p>Apple은 이 질문에 대해 하나의 선택지를 제공합니다.<br>바로 <strong>Send Consumption Information </strong>입니다.</p><h4>Apple Send Consumption Information</h4><p><a href="https://developer.apple.com/documentation/appstoreserverapi/send-consumption-information">https://developer.apple.com/documentation/appstoreserverapi/send-consumption-information</a></p><p>Send Consumption Information은<br><strong>해당 인앱 결제 상품이 실제로 얼마나 소비되었는지</strong>를<br>서비스가 Apple에 전달할 수 있는 기능입니다.</p><p>예를 들어,</p><ul><li>아이템이 이미 사용되었는지</li><li>구독 혜택을 충분히 제공받았는지</li><li>사용자에게 제공된 아이템이 소모성인지, 비소모성인지</li></ul><p>이런 정보를 Apple에 전달함으로써,<br>환불 심사 과정에서 <strong>추가적인 판단 근거</strong>로 활용될 수 있습니다.</p><p>중요한 점은,<br>이 기능이 환불을 <strong>막아주는 장치</strong>는 아니라는 것입니다.</p><p>Apple은 여전히 사용자 중심으로 결정을 내리고,<br>Consumption Information은 어디까지나 참고 자료에 가깝습니다.</p><p>즉, 보내지 않는다고 해서 바로 불리해지는 것도 아니고,<br>보낸다고 해서 환불이 반드시 거절되는 것도 아닙니다.</p><h4>그럼에도 불구하고 이 기능을 적용한 이유</h4><p>서비스에서 Apple에게 사용자 환불에대한 의견을 전달할수 있는 거의 유일한 통로 이기 때문입니다.</p><h4>결국, 완벽한 환불 방어는 불가능하다</h4><p>iOS 인앱 결제에서<br><em>“</em><strong><em>사용자의 Apple 불법 환불을 100% 방어하는 것은 불가능하다.”</em></strong></p><p>이건 기술의 문제가 아니라,<br>플랫폼 구조와 정책의 문제에 가깝습니다.</p><p>다만, 아무것도 하지 않을 것인지,<br>아니면 할 수 있는 최선을 다할 것인지는 서비스의 선택입니다.</p><p>비록 불법 환불을 100% 막지는 못하지만,</p><ul><li>환불을 최대한 빨리 인지하려고 했고</li><li>환불 이후의 손실을 줄이려고 했으며</li><li>환불 이전에 제공한 가치를 설명하려고 했다</li></ul><p>이 모든 선택은<br>“완벽한 방어”가 아니라<br><strong>“감당 가능한 운영”을 위한 결정</strong>이었습니다.</p><h3>끝으로</h3><p>iOS 인앱 결제 환불 문제는<br>어느 날 갑자기 해결될 이슈가 아닙니다.<br>하지만 이 구조를 이해하고 대비하는 것만으로도,</p><p>서비스는 훨씬 덜 흔들리게 될것이고 사용자 역시 점점 불법적인 환불이 서비스내 패널티를 받는다는 학습을 하게 되어 악의적인 환불 신청이 없어질것이라 생각이 듭니다.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=0d85f3954a11" width="1" height="1" alt=""><hr><p><a href="https://medium.com/spoontech/%EC%9A%B0%EB%A6%AC%EC%9D%98-ios-%EC%9D%B8%EC%95%B1-%EA%B2%B0%EC%A0%9C-%EB%B6%88%EB%B2%95-%ED%99%98%EB%B6%88%EC%9D%84-%EB%A7%89%EA%B8%B0-%EC%9C%84%ED%95%9C-%EC%8B%9C%EB%8F%84-0d85f3954a11">우리의 iOS 인앱 결제 불법 환불을 막기 위한 시도</a> was originally published in <a href="https://medium.com/spoontech">SpoonLabs</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[벡터의 중심에서 의미를 외치다 : Vector Clustering Centroid]]></title>
            <link>https://medium.com/spoontech/%EB%B2%A1%ED%84%B0%EC%9D%98-%EC%A4%91%EC%8B%AC%EC%97%90%EC%84%9C-%EC%9D%98%EB%AF%B8%EB%A5%BC-%EC%99%B8%EC%B9%98%EB%8B%A4-vector-clustering-centroid-b96ac530bbc7?source=rss----bb1e592ad19a---4</link>
            <guid isPermaLink="false">https://medium.com/p/b96ac530bbc7</guid>
            <category><![CDATA[vector]]></category>
            <category><![CDATA[spoonradio]]></category>
            <category><![CDATA[tech]]></category>
            <category><![CDATA[spoonlabs]]></category>
            <category><![CDATA[clustering]]></category>
            <dc:creator><![CDATA[임용근]]></dc:creator>
            <pubDate>Thu, 09 Apr 2026 10:03:05 GMT</pubDate>
            <atom:updated>2026-04-04T07:16:18.529Z</atom:updated>
            <content:encoded><![CDATA[<p>안녕하세요.</p><p>스푼랩스 Business Platform Team의 임용근(Whale 🐳)입니다.</p><p>이제 완연한 봄이네요. 캠핑의 계절이 또 돌아왔습니다. 🏕️<br>(사실 저에게는 사계절이 전부 캠핑 시즌입니다 😅)</p><p>이번 겨울에도 어김없이 몇 번의 감성 캠핑을 다녀왔습니다.</p><p>역시 머리를 비우는 데에는 솔캠만한 취미가 없는 것 같습니다.<br>(와이프와 아들은 겨울 캠핑은 춥다며… 혼자 가라네요. 😇)</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0rCwRZD6n0z9VAnhxdG1dA.jpeg" /></figure><p>그나저나 <a href="https://medium.com/spoontech/rag-%EB%8F%84%EC%9E%85%EA%B8%B0-%EC%B1%97%EB%B4%87%EC%9D%84-%EB%A7%8C%EB%93%A4%EB%8B%A4-%EC%A1%B0%EC%9A%A9%ED%9E%88-%EA%B7%B8%EB%A6%AC%EA%B3%A0-%EB%82%AD%EB%A7%8C%EC%A0%81%EC%9C%BC%EB%A1%9C-e96841c87979">RAG-도입기</a> 작성 이후, 정말 오랜만에 블로그를 쓰게 되었습니다.</p><p>이번 글은 무려 6개월 전에 초안을 써두고, 이제야 완성하게 된 글입니다. 🤪</p><p>정신없이 업무에 치이다 보니 한동안 잊고 있었는데, 문득 생각이 나서 이렇게 텐트 안에서 눈 내리는 풍경을 보며 블로그 작성을 이어가고 있습니다.</p><p>이 분위기에서 쓰는 블로그도… 나름 괜찮네요 🙂</p><h4>자랑하기</h4><p>아참 그리고 RAG-도입기를 작성 이후 신기한일이 일어났습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ZM4EHCsp1ahMWcEEC9q3dw.png" /><figcaption>캬~ 이거 뭐.. 사인이라도 연습해야하나? ㅋ</figcaption></figure><p>ㅋㅋ 참.. 살다보니 제가 작성한 블로그가 추천을 받다니!!! 훗~</p><p>… 그냥 그렇다구요. (<a href="https://devground.hanbit.co.kr/2025/05/27/%eb%8d%b0%eb%b8%8c%eb%a0%88%ed%84%b0-%ec%9b%94%ea%b0%84%ec%9d%b4%ec%8a%88-%ed%94%84%eb%a1%ac%ed%94%84%ed%8a%b8-%ec%97%94%ec%a7%80%eb%8b%88%ec%96%b4%eb%8a%94-%ec%99%9c-%ec%82%ac%eb%9d%bc%ec%a1%8c/">링크</a>)<br>(오랜만에 다시 읽어보니 수정할곳이 조금 보이기도 합니다.)</p><p>이 글을 처음 쓰기 시작했을 때 가장 이해하고 싶었던 개념이 하나 있었습니다.</p><p>바로 <strong>Vector Clustering Centroid</strong>입니다.</p><p>… 확~ 와닿지 않죠? 저도 처음 접했을때.. 접을 뻔 했습니다.</p><p>시작하기 앞서 간단하게 “<strong>Vector Clustering”</strong>이 어떤 개념인지 짚어보겠습니다.</p><p>이해하기 쉽게 예를 하나들어 볼까요.</p><p>올림픽에 출전한 선수를 뽑아야 하는데, 아무나 뽑을 순 없잖아요?</p><p>그래서 전국 각 지역에서 예선전을 치르고, 해당 지역에서 대표들이 올라와 다시 경합을 벌여서, 최종적으로 국가대표를 1명 ~ n명까지 선발합니다.</p><p>이렇게 뽑힌 국가대표는 한 나라의 얼굴이 되고 이미지가 되고 실력이 되는 것 이겠죠?</p><p>한국은 쇼트트랙을 잘하고, 양궁을 잘하고, 유도를 잘하고 …</p><p>대한민국이라는 나라의 올림픽 역사를 더 들여다보면 많은 정보들이 있을텐데 올림픽 관점에서 중심이 되는 내용은</p><p><strong>올림픽에서 메달을 몇개를 획득했고, 무엇을 잘하느냐</strong>가 관건입니다.</p><p>이렇게 국가대표를 선발하는 과정과 어떠한 문서의 기본적인 요약을 추출하는 과정과 같다고 생각합니다.</p><p>그럼 지금부터 무엇을 설명하려는지 감은 오시지요?</p><h3>그럼 저걸 왜 하느냐?</h3><p>위에 언급했듯이 아무나(키, 외모, 나이 등으로) 뽑으면 그 대상자들이 어마어마하게 많을테고, 한명씩 걸러내는것도 일이고 비용도 많이 들고, 변별력도 없습니다. 즉, 무엇보다 시간과 비용이 많이 듭니다.</p><p>반면에, 각 지역마다 최종대표를 선발하는 방법은, 동시다발적으로 이루어지고 시간과 비용도 아낄수 있는 방법이죠.</p><p>이것을 문서에 적용해보면, 두꺼운 문서를 비교적 저렴한 비용으로 한눈에 어떤 문서인지 알기쉬울 것이고, 그 외 다른 관점으로도 활용할 수 있을 것 같습니다.</p><h4>💡알아두기</h4><blockquote>- 이 블로그에서는 LLM Model이 자주 언급되며, 비용 관련 비교를 위해 Claude Sonnet 4.5와 Haiku 4.5를 사용합니다.</blockquote><blockquote>- 아쉽지만 개념과 Flow에 대한 설명이기 때문에 구현코드는 없습니다.</blockquote><blockquote>- Vector Embedding 의 과정은 RAG 의 그것과 같은 Flow입니다. <br>관련 지식을 채우시려면 “<a href="https://medium.com/spoontech/rag-%EB%8F%84%EC%9E%85%EA%B8%B0-%EC%B1%97%EB%B4%87%EC%9D%84-%EB%A7%8C%EB%93%A4%EB%8B%A4-%EC%A1%B0%EC%9A%A9%ED%9E%88-%EA%B7%B8%EB%A6%AC%EA%B3%A0-%EB%82%AD%EB%A7%8C%EC%A0%81%EC%9C%BC%EB%A1%9C-e96841c87979">RAG 도입기</a>”에서 “<strong>Chunking 이란?</strong>” 챕터를 꼭 읽어보시기 바랍니다.</blockquote><h3>시작하기</h3><p>RAG(Retrieval-Augmented Generation) 시스템을 구축하고 운영하면서 가장 큰 고민 중 하나는 바로 <strong>‘Data의 양과 비용’</strong>이었습니다.</p><p>LLM에게 풍부한 컨텍스트를 주고 싶지만, 무턱대고 긴 문서를 다 밀어 넣기엔 토큰 비용이 무섭고 모델의 컨텍스트 윈도우 제한도 발목을 잡곤 하죠. (2026년 3월 기준 요즘 클로드에서는 100만 토큰 Context Event 도 하고 그러네요~ ㅎ )</p><p>또한 “lost in the middle” 현상으로 인해 꼼꼼하게 살펴본다는 보장도 없죠.</p><p>새롭게 만드는 <strong>어떠한 프로젝트 </strong>에서 활용 중인, <strong>Vector Embedding의 Centroid(중심점)</strong>를 이용해 대용량 Data를 효율적으로 요약하고 토큰을 획기적으로 절약한 경험을 공유해보려 합니다.</p><p>실제로 여러 서비스에서 사용중인것 같고, NotebookLM도 비슷한 접근을 사용하지 않을까 추측합니다.</p><p>NotebookLM을 사용해보신 분들은 한번쯤 보셨을거에요.</p><p>문서 용량이 수백MB인 파일을 업로드 하면 해당 파일의 내용을 4~5줄로 요약을 해줍니다.</p><p><strong>⭐️ 궁금한점</strong></p><ol><li>어~ 좋네.. 그런데 저 파일의 내용을 모두 LLM으로 보낸다고?</li><li>비용 엄청 나올텐데, 구글이라 가능한건가?</li><li>수백만명이 사용하는데 비용 괜찮은가?</li><li>LLM말고 다른 무언가를 사용하는건가?</li><li>혹시 다른 방법이 있는건가?</li><li>어떻게 하는것일까?</li></ol><p>참.. 별거 아닌 기능같아 보이는것에 꽂혀서 머리속에 많은 질문들이 쏟아져 나왔습니다.</p><p>내가 아는 경험적 지식으로는 답이 나오질 않았거든요.</p><p>뭐.. Global 기업이니 비용걱정 없이 사용하나보다~ 생각하면 마음 편한데.. 그건 아닐것 같다는 생각으로 접근하게 되었습니다.</p><h4>마주한 고민들</h4><p>다들 잘 아시다시피 사람이 단시간에 파악하기 어려운 수준정도로 Data의 양이 많아지면, LLM을 활용한 요약 작업은 탁월한 결과를 제공해주지만 다음과 같은 문제들이 있습니다.</p><ul><li><strong>토큰 비용의 압박</strong>: 수만 라인의 로그나 긴 대화 내역을 그대로 요약하면 비용이 폭발적으로 증가합니다.</li><li><strong>정보의 중복</strong>: 비슷한 내용이 반복되는 Data의 경우, LLM이 같은 말을 반복해서 읽게 되어 효율이 떨어집니다.</li><li><strong>핵심 맥락 소실</strong>: 단순히 앞부분만 잘라서(Truncation) 넣으면 문서 전체의 중요한 흐름을 놓치게 됩니다.</li></ul><p><em>“어떻게 하면 전체 Data의 ‘의미’는 유지하면서, LLM에게 전달할 분량만 쏙쏙 골라낼 수 있을까?”</em>의 질문에서 여러가지 방법을 생각해봤습니다.</p><ul><li>일정 부분을 나누어 요약을 진행하고 최종적으로 나온 요약들을 재요약을 한다. (Map-Reduce Summarization)<br>👉 비용 증가.<br>👉 RAG로 WIKI 검색 구축 당시 실제로 해본 기법인데, Token사용률이 어마어마 합니다.</li><li>랜덤으로 특정 문서의 일부를 추출하여 요약 진행함.<br>👉 비용은 안정적 / 품질은 떨어짐.</li><li>특정용어로 검색 후, 문서를 필터링 함.<br>👉 태그 / 제목등을 문서에서 추출하여 LLM으로부터 Tag를 수집<br>👉 LLM으로부터 얻은 TAG로 문서를 필터함.<br>👉 비교적 저렴한 비용 / 품질 보장할 수 없음 (제목과 내용이 다른경우) / 복잡도 증가</li></ul><p>그렇게 고민만 하던 어느날 구글링을 통해 얻은 힌트 “<strong>Vector Clustering</strong>”</p><p>RAG를 관심있게 살펴 보셨다면 한번쯤은 접해보셨을 용어라고 생각합니다.</p><h3>Vector Clustering이란?</h3><blockquote><strong><em>Vector는 사람이 직관적으로 이해하기는 어렵지만, Data의 다양한 특징과 의미를 여러 차원의 숫자로 표현한 것입니다.</em></strong></blockquote><blockquote><strong><em>벡터 클러스터링은 서로 비슷한 의미를 가진 벡터들을 모아서 그룹으로 나누는 것입니다.</em></strong></blockquote><p>즉, 숫자로 표현한 어떤 의미를 갖는 Data의 군집으로 나눈것을 벡터 클러스터링이라고 합니다.</p><p>적절한 예시가 될지는 모르겠으나, 동호회 같은 개념이 떠오르네요.</p><p>예를 들어, 수백명이 모여있는 회사에 동호회가 있다고 생각해봅시다.</p><p>등산을 좋아하는 사람들은 등산 동호회에, 게임을 좋아하는 사람들은 게임 동호회에 모이듯, Vector Clustering도 비슷한 특징을 가진 Data들을 같은 그룹으로 묶는것입니다.</p><h4>비슷한지 어떻게 알지?</h4><p>그렇죠!!!???</p><p>[0.23232, -0.4553, …] 처럼 되어있는 숫자 배열일 뿐인데, 얘네들이 서로 어떻게 비슷한지 아는가?</p><p>모르고 지나가도 구현하는데는 문제는 없는데.. 이 궁금증이 해결되기 전까지 진행하기란 쉽지 않았습니다. (그냥.. 제가 못참는것같아요 ㅎ)</p><p>RAG를 하면서 많은 글을 읽어봤을때에는 Vector의 저 값들이 무엇을 의미하는지 명확하게 말해주는곳은 많지 않았습니다. (지금은 AI가 답변을 아주 잘해주네요 🤣 )</p><p>그저 제가 이해한대로 설명을 드리자면, 저 숫자배열은 위도/경도와 같은 위치를 나타내는 값이라 생각해봅시다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/869/1*KR6slTSN2mcP3lkmRtWVjw.png" /><figcaption>각 도시의 위도와 경도</figcaption></figure><p>우리는 이미 세계지도가 머리속에 있어서 서울, 도쿄, 로마가 어디에 있는지 떠오르겠지만, 수도이름을 살짝~ 가리시고 숫자만 보고 떠올려 보시겠어요?</p><p>위도/경도만 가지고 어느지역인지 정확하게 떠오르신다면…⁉️<br>(당신은 누구십니까?? )</p><p>Vector 숫자 배열도 비슷하다고 보시면됩니다.</p><p>숫자는 직접 해석할 수는 없지만, 벡터 전체는 의미를 표현합니다.</p><p>그럼 이 Vector들이 어떤 위치를 갖고 그 위치에 어떤 값이 있는가?</p><p>아쉽지만 각각의 Vector를 통해 어떤 값이 들어가있는지는 알 수 없습니다.</p><p>유사도 알고리즘을 통해 거리가 인접한지 판별할 수 있으며, 가까울수록 비슷한 군집임을 예측할 수 있는것이죠.</p><p>이때 벡터 간의 각도를 기준으로 유사도를 계산하는 <strong>Cosine Similarity</strong> 같은 방법을 사용합니다.</p><p>그래서 Vector 1, Vector 2, Vector 3 ~ Vector n을 놓고 비교를 해보면 가까운녀석들끼리 뭉치는 경향을 예상할 수 있습니다.</p><p>다음 스크린샷처럼 테스트를 해보았습니다.</p><p>1,536차원의 Vector를 2, 3차원으로 압축하여 거리를 분석한 결과를 나타내는데요.</p><p>차원을 확~ 줄이니 위치에 대한 손실도 많이 발생하지만 어느정도의 거리관계는 유지됩니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*L3FAK6TvLz2-xeDiLwuwig.png" /><figcaption>확인용으로 가볍게 만들어서 사용중인 Vector 분포도. 이름도 “고래 중심잡기” ㅋ</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/769/1*NqGAdhuovHNa5eo2oNtVMw.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/770/1*3duC1PFTshAidj7ZZJDhLQ.png" /></figure><p>순위 16, 17, 18을 보면, 임의로 넣어둔 관련성이 낮은 Data들이 가장 하위로 밀려난 것을 확인할 수 있습니다.</p><p>이는 벡터 간의 유사도를 기반으로 거리를 계산하기 때문에, 의미적으로 멀리 떨어진 Data일수록 낮은 점수를 받게 되기 때문입니다.</p><p>또한 MMR(Maximal Marginal Relevance)을 적용하면서, 단순 유사도뿐 아니라 다양성까지 함께 고려되기 때문에, 관련성도 낮고 정보 가치도 떨어지는 Data들이 자연스럽게 후순위로 정렬됩니다.</p><p>Vector Clustering에 대해 간단하게 짚어 보았는데, 어느정도 감이 오시나요? 😀</p><h3>Vector Clustering.. 너 뭐 돼?</h3><p>자~ 다시 본론으로 돌아와서..</p><p>그래서? Vector Clustering로 뭘 할 수 있는걸까요?</p><p>지금까지 이야기만 들어서는, 도대체 저걸로 무엇을 할 수 있는거지?</p><p>Vector Clustering 이라는 키워드로 다행히 어렵지 않게 다양한 정보를 얻을 수 있었습니다.</p><p>그런데 자료를 찾아보면 극강의 난이도가 펼쳐집니다. 당시에는 거의 논문만 나왔거든요. 😆</p><p>전체 Data를 단순히 텍스트만 자르는 대신, Data의 <strong>’의미적 밀집도’</strong>를 활용하기로 했고, 그것이 바로 <strong>Embedding Vector들의 중심점(Centroid)</strong>을 찾는 방식입니다.</p><h4>어떻게 흘러가나?</h4><p><strong>Vector Clustering (Grouping)</strong></p><ol><li>전체 Data를 의미 단위로 쪼개고(Chunking),</li><li>이를 Vector로 변환(Embedding)합니다. (여기까지 RAG의 흐름과 같습니다.)</li><li>K-Means 같은 알고리즘을 사용해 <strong>유사한 의미를 가진 Data끼리 그룹으로 묶습니다.</strong></li></ol><p><strong>중심점(Centroid) 추출</strong></p><p>각 그룹(Cluster)에 속한 벡터들의 평균값을 계산하여 Centroid를 구합니다.</p><p><strong>대표 Data선정</strong></p><p>Centroid에 가장 가까운 실제 데이터(Chunk)들만 추출합니다. 이렇게 하면 각 그룹의 대표 선수들만 뽑히게 되는 셈이죠.</p><p>이미 구현한 기능을 돌려보고 결과를 가지고 이야기를 이어 나가겠습니다.</p><p>예시로 인터넷에 공개되어있는 80 Page분량의 pdf 파일 Canon Manual 을 사용했습니다. <a href="https://files.canon-europe.com/files/soft03-48482/Manual/EOS_100_User_Manual_EN.pdf">EOS_100_User_Manual_EN </a>(12MB)</p><pre>📊 총 80페이지 처리 시작<br>✅ [1/80] OCR 완료 (26자)<br>✅ [2/80] 텍스트 추출 (347자)<br>✅ [3/80] 텍스트 추출 (2289자)<br>✅ [4/80] 텍스트 추출 (550자)<br>✅ [5/80] 텍스트 추출 (267자)<br>✅ [6/80] 텍스트 추출 (1726자)<br>🔍 [7/80] OCR 처리 중 (텍스트 부족: 0자 &lt; 50자)<br>✅ [7/80] OCR 완료 (1525자)<br>🔍 [8/80] OCR 처리 중 (텍스트 부족: 0자 &lt; 50자)<br>✅ [9/80] OCR 완료 (497자)<br>...<br>🔍 [79/80] OCR 처리 중 (텍스트 부족: 0자 &lt; 50자)<br>✅ [79/80] OCR 완료 (58자)<br>🔍 [80/80] OCR 처리 중 (텍스트 부족: 0자 &lt; 50자)<br>✅ [80/80] OCR 완료 (2144자)</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/926/1*AhlKzB_brEk-kOBKGFyIjg.png" /><figcaption>PDF Parser와 OCR 진행중입니다. (두구두구~ 😝)</figcaption></figure><p>결과</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*uNGSrURe9JdchY6C3nFOQw.png" /><figcaption>짜잔~ 만족할만한 요약수준인가요?</figcaption></figure><p>Canon EOS 100 매뉴얼에 대한 간략한 요약을 추출했습니다.</p><p>어떠세요? 저 요약만 보고 이 문서가 어떤 문서인지 한눈에 알 수 있나요?</p><p>당연히 Canon User Manual 이니까 저런 내용이 나오겠거니~ 생각 할 수 있지만 제목으로 본문 내용을 유추할 수 없는 문서라면 어떨까요?</p><p>다음 2번째 예시입니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/398/1*TOQ-7cE80MiBVfHCAmHK5Q.png" /><figcaption>페이오니아 API 문서</figcaption></figure><p>페이오니아 API 문서로 예시를 들었고, Text / OCR 분류하여 처리하기 때문에, 상당시간 걸리지만 이 PDF가 무슨 내용을 담고 있는지에 대한 내용은 파악하는데 무리는 없어보입니다.</p><p>3번째 예시입니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/359/1*dPpYGamOCmLHnZjERxmVYQ.png" /><figcaption>부장님!!! 제..제목이 일본어인데요..!!??</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/400/1*qiKQOxrjiX5CbA-hFFAVvA.png" /><figcaption>캬~ 미쳤다리..</figcaption></figure><p>일본어를 접해보지 않으신분들이 회사업무의 일환으로 일본어 문서를 봐야 한다고 가정합시다. (가끔.. 막~막~ 시키고 그러잖아요!!?? )</p><p>이게 무슨 내용의 문서인지 사전 정보가 전혀 없을때, Vector Clustering Centroid 기술을 사용한다면 적은 비용으로 대략적으로 어떤 문서인지 친절하게, 그것도 자국 언어인 한글로 요약을 해줍니다.</p><p>기능적으로 봐도 꽤나 쓸모가 있어보입니다. <br>(아.. 개행이 부자연스러운건 예쁘지 않을 수 있습니다. ㅎ)</p><p><strong>“토큰은 줄이고, 정확도는 그대로” </strong>이 방식을 프로젝트에 적용해본 결과, 놀라운 변화가 있었습니다.</p><p>토큰 사용량 80% 이상 절감효과를 볼 수 있었고, 중복되거나 부차적인 데이터를 사전에 필터링함으로써 LLM에 전달하는 입력 Token이 획기적으로 줄일 수 있었습니다.</p><h3>비용이 얼마나 줄어들까?</h3><p>그렇다면 비용이 얼마나 줄어들길래 제가 이렇게나 호들갑일까요?</p><p>예를들어, 하나의 문서가 있다고 가정하겠습니다.</p><p>문서는 어떠한 웹소설이고 전체 문자수 1,000,000개로 가정합니다. (실제로 테스트한 문서의 최대 문자수는 <strong>373만</strong>이었으나, 계산하기 편하게 100만으로 진행하겠습니다.)</p><p><strong>백만 글자를 그대로 LLM에 넣어 요약</strong>할 경우, 비용은 다음과 같습니다.</p><p><strong>토큰 수 추정</strong></p><ul><li>1,000,000글자 ≈ 250K~500K 토큰 (영문 ~250K, 한국어 ~400K~500K)</li><li>4~5줄 요약 출력 ≈ ~100~200 토큰 (무시할 수준)</li><li>한국어 기준 ~400K 토큰으로 계산 진행</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*5-Qi-K8UPlAf_ClGXXoNxA.png" /><figcaption>실제로 400K tokens을 한번에 LLM으로 보낼수는 없습니다.</figcaption></figure><p>어떤 내용의 문서인지, 대략적으로 파악하기 위한 비용치고는 꽤 비싸네요. 😅</p><p>그렇다면 <strong>Vector Clustering Centroid 방식</strong>으로 하면 어떨까요?</p><p>청크하기 (한국어 기준)</p><ul><li>1,000,000자 ÷ 2,000자 = 500 청크</li></ul><p>임베딩 (500 청크 전체)</p><ul><li>500 × 2,000자 ≈ 400K토큰</li><li>임베딩 비용: ~$0.008 ~ $0.024 (약 35원)</li></ul><h4>Centroid LLM 비용 추정</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*UKm9LCiL6hfI9VCtFrIZRA.png" /></figure><h4>비교(K=50 기준)</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4VWiSy69Y78CTszHSV8n0A.png" /></figure><blockquote><strong>※ 절감율은 절대적인 수치가 아닙니다. token수에 따라 비용도 달라지므로 대략적인 추정정도로 생각해주시기 바랍니다.</strong></blockquote><p>최종적으로 절감율을 보게 되면 약 88%정도로 비용이 낮아짐을 볼 수 있습니다.</p><p>이는 단순히 글자수 / token 수 / 공식 비용으로 산출한 결과이므로 정확하진 않을 수 있으나, 어느정도의 절감효과를 볼 수 있는지 알 수 있는 Data입니다.</p><p>그냥 겁나게 싸지는겁니다. 😍</p><h3>어떻게 진행하는가?</h3><h4>Vector Clustering Centroid</h4><p>대용량 문서를 순서대로 일정 크기의 그룹으로 나눈 뒤, 각 그룹의 centroid에 가장 가까운 청크를 대표로 추출하여 LLM에 전달하는 요약 기법입니다.</p><h4>1. 원문 분할 (Chunking)</h4><p>1,000,000글자 문서를 2,000글자 단위로 나누면 <strong>500개의 청크</strong>가 생성됩니다.</p><h4>2. Embedding</h4><p>500개 청크를 각각 벡터로 변환합니다.</p><blockquote><em>비용: 약 </em><strong><em>$0.008 ~ $0.024</em></strong><em> (대략 10~30원 수준)</em></blockquote><h4>3. 순차적 그룹 분할</h4><p>500개의 Embedding 데이터를 문서 순서대로 30개씩 하나의 그룹으로 묶습니다.</p><blockquote><em>500 청크 / 30 청크 = 약 </em><strong><em>17개의 그룹<br></em></strong><em>A = 1~30, B = 31~60, … Q = 481~500</em></blockquote><h4>4. Centroid 계산</h4><p>17개의 그룹 각각에 대해 포함된 벡터들의 <strong>평균(centroid)</strong>을 계산합니다.</p><h4>5. 대표 청크 선택</h4><p>각 그룹의 centroid와 <strong>코사인 유사도가 가장 높은 실제 청크</strong>를 1개씩 선택합니다.</p><p>👉 총 <strong>17개의 대표 청크</strong>가 추출됩니다.</p><h4>6. LLM 전달량</h4><p>17 × 2,000 = <strong>34,000글자</strong>가 LLM에 전달됩니다.</p><h4>비용 추정</h4><p>Embedding 비용 제외, LLM 비용만 산출하였습니다. 20,000 토큰 기준, output 2,000 토큰을 가정하였습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4jV0ZdNaY-FIGTnmBJBIoA.png" /></figure><p>그룹 크기(N)에 따라 품질과 비용이 비례합니다. N이 작을수록 대표 청크 수가 많아져 품질은 올라가지만 비용도 증가합니다.</p><p><strong>순차 분할 방식</strong>은 문서의 흐름(순서)을 보존하는 장점이 있지만, 의미적 경계와 그룹 경계가 일치하지 않을 수 있다는 한계가 있습니다</p><p>위 예시에서 보여준 결과가 위 흐름으로 동작한 결과입니다.</p><p>어때요? 별로 어렵지 않죠?</p><p>자.. 이제 끝!!!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/233/1*Uepyy2SQGmeZ9cJA9-eZRQ.png" /><figcaption>ㅋㅋㅋㅋㅋ</figcaption></figure><blockquote><strong>잠깐, 고백 하나 하겠습니다.</strong></blockquote><blockquote>위에서 보여드린 방식은 사실 의미 기반 클러스터링이 아니라, 순서 기반으로 나눈 구간 안에서 centroid를 계산한 것입니다.</blockquote><blockquote>잘못 이해하고 만든 방식이 의외로 잘 작동한 케이스였죠.<br>(비하인드 스토리 참고 😅)</blockquote><p><strong>그렇다면 진짜 의미 기반으로 클러스터링하면 어떻게 될까요?</strong></p><p>잠깐 정리해보면, Centroid 를 추출하기 위한 방법으로 몇가지 있지만, 제가 사용했던 선별 방식은 크게 3가지로 나눌 수 있습니다.</p><p>이쁘게 그릴 자신이 없어서 AI 한테 설명을 주고 그려달라고 했더니 잘 만들어 주었습니다. 🤣</p><h4>Centroid-based Summarization</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/610/1*Q4IvvhjHEL8PYdpnbkgPnw.png" /></figure><p>Centroid-based Summarization(Radev et al., 2004)의 아이디어를 RAG에 적용한 방식입니다. 전체 벡터의 centroid를 구하고, 인접한 chunk n개를 추출하여 LLM에 전달합니다.</p><p>어릴때 다방구, 오징어게임 같은거 할때 “나랑 놀사람 여기여기 👍 붙어라~ “ 라고 크게 외치면서 친구들 모았던 기억이 나네요. 🥹</p><h4>Sequential Chunk Grouping 기반 (가칭)</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/609/1*lM3I_Y8jXuXWIUQShieM6Q.png" /><figcaption>순차적 청크 그룹핑(?)</figcaption></figure><p>앞서 보여드렸던 3가지 예시가 이방법으로 진행된 것입니다.</p><p>[비하인드 스토리]</p><p>Centroid-based Summarization을 구현하려다 제가 잘못 이해하고 만든 것이 이 순차적 그룹핑 방식이었습니다.</p><p>실수였지만 결과는 꽤 만족스러웠고, 비용도 저렴했습니다. <br>찾아보니 유사한 접근을 사용하는 사례도 있더고 하더라구요. 🤣</p><p>다만 다양한 문서로 테스트해보지는 않았기 때문에, 정확도는 다소 떨어질 수 있을 것 같습니다.</p><h4>K-Means Clustering + Centroid Selection 방식</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/608/1*dEzSVowuWUoUYawr6HROtQ.png" /></figure><p>이번 블로그 주제에 해당하는 방식입니다.</p><p>어떤 주제를 가지는지 모르는 Vector들을 우선 특정 주제로 분류(Clustering)합니다.</p><p>나뉘어진 각 Cluster에서 중심값(Centroid)을 계산하는데, 이 Centroid는 평균값이기 때문에 Cluster 안에 똑같은 값을 가진 Vector는 없을 거에요. (있다면 정말 우연이겠죠.)</p><p>그래서 이 Centroid와 가장 가까운 Chunk를 선별하고, 이렇게 선별된 데이터가 요약에 사용될 Source가 됩니다.</p><h4>그럼 진짜로~ 해볼까요? 🚗</h4><p>진행하기전 “고래 중심잡기&quot;를 이용하여 K-Means Clustering을 실행해서 내용 중간중간에 이해하기 쉽도록 삽입했습니다. 😀</p><h4>K-Means Clustering + Centroid Selection</h4><p>대용량 문서를 의미 단위로 클러스터링한 뒤, 각 클러스터의 대표 청크만 추출하여 LLM에 전달함으로써 비용과 품질의 균형을 맞추는 요약 기법입니다.</p><p>비용보다는 흐름을 설명하기 위해이번에는 실제 존재하는 문서로 테스트를 해보겠습니다.</p><p>테스트 문서는 <a href="https://asia.canon/en/support/0304778501">Canon User Manual</a>로 했습니다. 구글에서 “canon manual pdf” 검색 후, 제목으로 특정하기 어려운 녀석으로 일부러 골라봤습니다.</p><p>그리고 고래 중심잡기 툴을 이용하여 K-Means Clustering 분포도도 함께 첨부했습니다.</p><h4>1. 원문 분할 (Chunking)</h4><p>2,000글자 단위로 나누면 총 2<strong>08개의 청크</strong>가 생성됩니다.</p><h4>2. Embedding</h4><p>208개 청크를 각각 벡터로 변환합니다.</p><h4>3. K 값 결정</h4><p>클러스터 수 K는 경험적으로 아래 휴리스틱을 사용합니다.</p><blockquote><strong><em>K = √(청크 수)</em></strong></blockquote><p>수학적 증명이 있는 것은 아니며, 실무에서 균형이 잘 맞는다고 알려진 경험치입니다. √208 ≈ 14이므로, <strong>K = 14</strong>가 기준이 됩니다.</p><h4>4. K-Means 클러스터링</h4><p>208개 벡터를 K=14개 클러스터로 분류합니다. 각 클러스터에는 N개의 벡터가 포함됩니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gBDnoGw0JGZe1d02yzveGQ.png" /><figcaption>어느정도 분포 되었지만 눈으로만 봐도 실루엣 스코어는 높지 않아보이네요 ^^;;</figcaption></figure><h4>5. Centroid 계산</h4><p>각 클러스터에 포함된 벡터들의 <strong>평균(centroid)</strong>을 구합니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*hLGIpnDy5dbORZR3_R07Fg.png" /><figcaption>오잉??</figcaption></figure><p>값이 나오지 않는게 당연합니다. 앞서 설명했듯이 Vector의 평균이기 때문에, 문서에는 없는 Vector입니다. (있다면 엄청난 우연)</p><h4>6. 대표 청크 선택</h4><p>계산된 centroid와 <strong>코사인 유사도가 가장 높은 실제 청크</strong>를 각 클러스터에서 1개씩 선택합니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vS8jQlMMDc6KRuyquFLU-g.png" /><figcaption>아래로 길어서.. 스샷을 다 찍지 못했지만 14개 맞습니다. ㅎ. Cluster 2는… Why?</figcaption></figure><p>👉 총 14<strong>개의 대표 청크</strong>가 추출됩니다.</p><h4>7. 토큰 수 추정</h4><p>14× 2,000 = 28,000 글자가 되어야 하는데, 실제로 글자 카운트 해보니 공백 포함 <strong>22,841</strong>입니다. 왜 정확히 28,000이 아닌지 RAG-도입기에서 설명되고 있으니 참고해주세요~<br>이 문서는 영어이니 Token으로 약 7,000토큰으로 추정됩니다.</p><h4>비용 추정</h4><p>7,000 토큰 기준, output 2,000 토큰을 가정하였습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*qCgYfb7wn4MTXFk7XBOLvw.png" /></figure><p>그래서 결과는?</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*a_X5vO_6KjvRUZ7iVgJwtA.png" /><figcaption>스캐너 관련 내용이었군요~</figcaption></figure><blockquote>K 값을 문서마다 자동으로 최적화하려면, <strong>Silhouette Score</strong>를 활용하여 탐색 범위 내 최적 K를 선택할 수 있습니다.</blockquote><blockquote>LLM에 다수의 청크를 전달할 때 <strong>Lost in the Middle</strong> 현상(중간 위치 정보의 반영률 저하)이 발생할 수 있으므로, 중요도 기반 재정렬(relevance-based reordering)이나 map-reduce 방식의 병행을 권장합니다. <br>(RAG-도입기 블로그에 재정렬 참고)</blockquote><p>비용은 약 75원 이하로 꽤나 합리적인 가격이 도출됩니다.</p><p>그럼 앞서 진행한 일본어 문서로도 K-means clustering 테스트를 해보았습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*5YYboUy9dASXCQ9N2GcGNg.png" /><figcaption>K-Means Clustering 결과</figcaption></figure><p>내용은 거의 비슷합니다.</p><p>프롬프트는 정리되지 않았기에 앞으로 수정해나가면 될일이니 큰 문제는 되지 않을 것 같습니다.</p><p>결과의 정리가 잘 되어 있어서 그런지 K-Means Clustering (K=2)가 가장 좋아보입니다.</p><p>사실 이건 충분히 설명이 가능한 결과입니다.</p><p>lost in the middle 현상이 있을수 있고, 정보파편화가 발생할 수 있으며 문서 자체의 주제 수가 억지로 만들어낸 결과일수도 있습니다. 여러가지 생각할 수 있는 부분이 있다고 생각됩니다.</p><p>K=5로 해서 다시 테스트를 돌려보고, NotebookLM과 비교 해보았습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/853/1*YF_-fTPkIXNPfbWxjilRzg.png" /></figure><p>무엇이 더 낫다의 기준은 사용자마다 다를 것 같습니다.</p><p>K=5는 아직 프롬프트 최적화가 부족하지만, 프롬프트 지침을 통해 세부 항목을 구조적으로 정리하는 방식으로 결과를 도출했습니다.</p><p>반면 NotebookLM은 문서 전체의 맥락을 자연스러운 문장으로 재구성하는 스타일입니다.</p><p>즉, 구조화된 정리와 자연스러운 서술 중 어떤 스타일을 선호하느냐에 따라 호불호가 갈릴 것 같습니다.</p><h3>낭만적인 요약을 꿈꾸며</h3><p>데이터가 많다고 해서 무조건 다 읽어야 하는 것은 아닙니다. 데이터 속에 숨겨진 ‘<strong>의미의 중심</strong>’을 잘 찾아내는 것만으로도 우리는 훨씬 똑똑하고 경제적으로 AI를 활용할 수 있습니다.</p><p>이번에 다룬 Centroid-based 요약 방식은 현재 준비하고 있는 (그리고 언젠가 사용 될) 핵심 로직으로 발전하길 기대하며, 혹시 비슷한 비용 고민을 하고 계신 분들이 있다면 이 방식이 작은 실마리가 되길 바랍니다.</p><p>이 글이 같은 고민을 하고 있는 분들에게 조금이나마 도움이 되었으면 좋겠습니다.</p><p>끝까지 읽어주셔서 감사합니다.</p><h3>COOKIE</h3><p>다음 블로그는 남몰래 만들고 있는 프로젝트와 관련된 내용을 준비하고 있습니다.</p><p>Claude Code / Codex 등으로 인해, Vibe Coding이 대중화되면서, 개발 직군간의 허들이 사라지고 있는것 같습니다.</p><p>전문성을 따지면 비교대상은 아니지만 흉내정도는 낼수있고 약간의 지식만으로도 훌륭한 무언가를 만들어 낼 수 있다니 말이죠.</p><p>블로그 본문에서도 잠깐씩 언급 된 “<strong>고래 중심잡기</strong>”도 개인적인 호기심과 아이디어로 만들어낸 결과물입니다. AI 아니었으면 하루이틀만에 뚝딱 만들어내진 못했을 것 같아요. 세상이 엄청 빠르게 변하고 있음을 새삼 실감합니다.</p><p>그런 흐름 속에서 저도 업무에 필요한 툴 포함해서 몇개 만들어 봤는데요.</p><p>그중 하나 Chrome Extension인 “GalpiDock”입니다.</p><p>링크 : <a href="https://chromewebstore.google.com/detail/galpidock/ifcoljegdeikcebflnbemjgegoaohcca?hl=ko&amp;utm_source=ext_sidebar">galpiDock(갈피독) 설치하기</a></p><p>아직 미흡한 부분이 있지만, 퇴근 후 집으로 출근하면 조금씩 개선하고 있으니 기대해주세요~</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b96ac530bbc7" width="1" height="1" alt=""><hr><p><a href="https://medium.com/spoontech/%EB%B2%A1%ED%84%B0%EC%9D%98-%EC%A4%91%EC%8B%AC%EC%97%90%EC%84%9C-%EC%9D%98%EB%AF%B8%EB%A5%BC-%EC%99%B8%EC%B9%98%EB%8B%A4-vector-clustering-centroid-b96ac530bbc7">벡터의 중심에서 의미를 외치다 : Vector Clustering Centroid</a> was originally published in <a href="https://medium.com/spoontech">SpoonLabs</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[ClickHouse 도입기: “빠른 분석 DB를 들이면 모든 게 해결될 줄 알았다”]]></title>
            <link>https://medium.com/spoontech/clickhouse-%EB%8F%84%EC%9E%85%EA%B8%B0-%EB%B9%A0%EB%A5%B8-%EB%B6%84%EC%84%9D-db%EB%A5%BC-%EB%93%A4%EC%9D%B4%EB%A9%B4-%EB%AA%A8%EB%93%A0-%EA%B2%8C-%ED%95%B4%EA%B2%B0%EB%90%A0-%EC%A4%84-%EC%95%8C%EC%95%98%EB%8B%A4-7d5a6eb60e4f?source=rss----bb1e592ad19a---4</link>
            <guid isPermaLink="false">https://medium.com/p/7d5a6eb60e4f</guid>
            <category><![CDATA[clickhouse]]></category>
            <category><![CDATA[clickhouse-replication]]></category>
            <category><![CDATA[soonlabs]]></category>
            <category><![CDATA[tech]]></category>
            <dc:creator><![CDATA[Beaver Lee]]></dc:creator>
            <pubDate>Thu, 29 Jan 2026 03:05:37 GMT</pubDate>
            <atom:updated>2026-01-29T03:05:35.956Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XrEftnbQgBNei4u-8-r2Ow.png" /></figure><p>안녕하세요. SpoonLabs에서 DBA로 일하고 있는 Beaver(이선영)입니다.</p><p>SpoonLabs의 데이터 분석 환경은 1일 1회 생성되는 <strong>RDS 스냅샷 기반 데이터</strong>에 의존해 왔습니다. 이 방식은 운영 DB의 부하를 줄여준다는 확실한 장점은 있었지만, 비즈니스가 성장함에 따라 다음과 같은 한계를 가지고 있었습니다.</p><ul><li>실시간에 가까운 분석이 불가능하다.</li><li>데이터 양이 증가할수록 분석 쿼리 성능이 급격히 저하된다.</li><li>긴급한 분석이 필요할 경우, 운영 DB 접근에 대한 부담과 리스크가 존재한다.</li></ul><p>이러한 문제를 해결하기 위해 운영 DB와 분리된 <strong>분석 전용 저장소</strong>를 도입하기로 결정했고, 여러 솔루션을 검토한 끝에 ClickHouse를 선택했습니다.</p><h3>왜 ClickHouse였을까?</h3><p>처음 아키텍처를 검토할 때는 ClickHouse뿐 아니라 Apache Druid, Apache Pinot과 같은 다른 OLAP 솔루션들도 함께 비교 대상으로 두었습니다. 각 솔루션은 저마다 장점을 가지고 있고 특히 Apache Pinot은 실시간 분석에 특화된 구조로 잘 알려져 있습니다.</p><p>Apache Pinot은 Controller, Broker, Server, Zookeeper로 구성된 분산 아키텍처를 기반으로 합니다. 쿼리 처리 계층과 데이터 저장 계층이 명확히 분리되어 있어 수평 확장이 유연하고, 실시간으로 사용자 화면에 노출되는 분석 지표를 제공하는 데 강점을 보입니다. 이러한 특성 덕분에 대규모 실시간 사용자 분석이 필요한 환경에서는 충분히 매력적인 선택지가 될 수 있습니다.</p><p>실제 데이터와 쿼리 패턴을 기준으로 테스트를 진행한 결과, Apache Pinot과 ClickHouse 간에 체감할 수 있을 만큼의 쿼리 성능 차이는 관찰되지 않았습니다. 두 솔루션 모두 현재 요구사항 수준에서는 지연 없이 안정적인 응답 속도를 제공했습니다.</p><p>실시간 사용자 대면 분석 지표를 제공하는 것이 핵심 요구사항이 아니며, 주된 사용 목적은 내부 분석과 운영 지표 조회에 있습니다. 이러한 맥락에서 Apache Pinot의 복잡한 구성 요소와 리소스 요구사항은 필요 이상으로 크다고 판단했습니다. 반면 ClickHouse는 비교적 단순한 운영 구조를 유지하면서도 충분한 단일 쿼리 성능을 제공해 전체 시스템의 관리 부담을 줄이는 데 유리했습니다. 이에 따라 최종 OLAP 엔진으로 ClickHouse를 선정했습니다.</p><h3>Clickhouse를 선택한 이유</h3><p>수많은 분석용 데이터베이스 중에서 SpoonLabs는 최종적으로 ClickHouse를 선택했습니다. 그 이유는 다음과 같습니다.</p><h4>압도적인 읽기(Read) 성능</h4><p>ClickHouse를 도입한 가장 큰 목적은 BI 대시보드와 분석 쿼리를 안정적으로 지원하는 것이었습니다. 대용량 데이터에 대한 집계 성능은 무엇보다 중요한 기준이었고, 실제 테스트에서도 ClickHouse는 기대 이상의 결과를 보여주었습니다.</p><p>20GB 규모의 동일한 테이블을 기준으로 테스트했을 때, PostgreSQL에서는 76,590 ms가 소요된 반면 ClickHouse에서는 2ms만에 결과를 반환했습니다.</p><h4>높은 압축률을 통한 비용 효율성</h4><p>ClickHouse는 Apache 2.0 라이선스 기반의 오픈소스이면서도, 컬럼 기반 저장 구조와 MergeTree 엔진의 백그라운드 병합을 통해 높은 데이터 압축률을 제공합니다.</p><p>MergeTree 계열 엔진은 데이터를 컬럼 단위로 저장하고, 파트 병합 과정에서 반복적으로 재압축을 수행합니다. 실제 운영 환경에서는 병합이 충분히 진행된 이후 원본 데이터 대비 약 <strong>70–90% 수준의 압축률</strong>을 기대할 수 있었으며, 이는 스토리지 비용 절감뿐 아니라 디스크 I/O 감소에도 큰 도움이 됩니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*nXb0onCt19DlWSU9.png" /><figcaption><a href="https://clickhouse.com/docs/merges#what-are-part-merges-in-clickhouse">https://clickhouse.com/docs/merges#what-are-part-merges-in-clickhouse</a></figcaption></figure><h4>SQL 호환성</h4><p>ClickHouse는 SQL 기반 쿼리를 지원하기 때문에, 기존 RDBMS에 익숙한 팀원들이 별도의 학습 없이 바로 분석 쿼리를 작성할 수 있었습니다. 이는 도입 초기의 학습 비용을 크게 낮춰 주었고, 빠른 적용에 큰 도움이 되었습니다.</p><h4>활발한 커뮤니티와 빠른 발전 속도</h4><p>ClickHouse는 매달 새로운 릴리즈가 이루어질 만큼 빠르게 발전하고 있으며, <a href="https://github.com/ClickHouse/ClickHouse">GitHub</a>와 Slack을 통해 이슈에 대한 피드백도 비교적 빠르게 받을 수 있습니다. 이러한 활발한 커뮤니티와 개발 속도는 장기적으로 기술 스택을 유지하는 데 있어 중요한 신뢰 요소였습니다.</p><h4>장기적인 확장성</h4><p>마지막으로, 향후 데이터 규모가 폭발적으로 증가할 경우 <a href="https://clickhouse.com/cloud">ClickHouse Cloud</a>로 이전해 엔터프라이즈급 기술 지원을 받을 수 있다는 점도 고려했습니다. 초기 선택이 장기적인 확장성을 제한하지 않는다는 점은 중요한 판단 기준이었습니다.</p><h3>Cloud DBA가 Self-Managed를 만났을 때</h3><p>저는 클라우드 환경에서 DBA 커리어를 시작했고, Aurora와 같은 관리형 DB에 익숙한 상태였습니다. 그래서 처음에는 단순히 <strong><em>“서버 몇 대 띄우고 ClickHouse 설치하면 끝나겠지”</em></strong> 라고 생각했습니다. 하지만 실제 구축 과정은 예상과 전혀 달랐습니다.</p><h4>1. ClickHouse 클러스터 구조 이해하기</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*9BxjELpIfIvO5UkH" /><figcaption><a href="https://clickhouse.com/docs/architecture/replication">https://clickhouse.com/docs/architecture/replication</a></figcaption></figure><ul><li><strong>Replica:</strong> 동일 Shard 내 데이터 복제본</li><li><strong>Shard:</strong> 데이터를 분산 저장하는 단위</li><li><strong>ClickHouse Keeper:</strong> 메타데이터 관리 및 노드 간 합의(Consensus) 담당 (ZooKeeper 역할)</li></ul><p>운영 환경에서는 고가용성을 위해 Shard + Replica + Keeper 구성이 필수였습니다. 특히 <strong>Keeper</strong>는 Raft 알고리즘 기반의 합의가 필요하여 <strong>홀수 개수</strong>의 노드가 필요했고, <strong>ClickHouse Server</strong>는 Shard와 Replica 구성을 고려하여 <strong>짝수 개수</strong>의 노드가 필요했습니다. 저희는 최종적으로는 아래와 같은 구조로 운영을 시작했습니다.</p><p><strong><em>&gt; 구성:</em></strong><em> ClickHouse Server 4대 </em>(2 Shards × 2 Replicas) <em>+ ClickHouse Keeper 3대</em></p><h4>2. 예상치 못했던 성능 병목과 인프라 재설계</h4><p>ClickHouse는 비교적 낮은 사양에서도 잘 동작한다고 알려져 있지만, 프로덕션 환경에서 안정적인 데이터 병합과 빠른 조회를 보장하기 위해서는 권장 사양 준수가 중요했습니다. (참고: <a href="https://clickhouse.com/docs/operations/tips">ClickHouse Operations Tips</a> )</p><ul><li><strong>최소 사양 (Test/Dev):</strong> 2 vCPU, 8GB RAM</li><li><strong>권장 사양 (Production):</strong> 4 vCPU, 16GB RAM 이상</li></ul><p>운영 환경에서 테스트를 시작한 후, 일부 무거운 쿼리와 배치 작업에서 예상보다 느린 속도가 발생하였습니다. 특히 <strong>디스크 I/O와 CPU 사용률이 함께 상승</strong>하는 현상이 반복되었습니다. 문제를 분석하면서 단순히 ClickHouse 설정만의 문제가 아니라 <strong>기본 인프라 스펙이 ClickHouse의 워크로드 특성을 받쳐주지 못하고 있다</strong>는 결론을 내렸습니다. 이에 다음과 같이 인프라를 전면 재설계했습니다.</p><ul><li>AMI 변경: Amazon Linux 2023 + Graviton</li></ul><p>기존 x86 기반 AMI에서 al2023-graviton-image로 변경하여 <strong>Graviton(ARM) 기반 인스턴스</strong>를 도입했습니다. ClickHouse는 CPU 연산 비중이 높은 워크로드가 많기 때문에, <strong>Graviton의 가성비와 연산 성능</strong>이 큰 이점으로 작용했습니다. 실제로 동일 스펙 대비 CPU 사용률과 처리 속도 모두 개선 효과를 확인할 수 있었습니다.</p><ul><li>스토리지 변경: IOPS / Throughput 설정</li></ul><p>ClickHouse는 대용량 데이터 스캔과 MergeTree 엔진의 백그라운드 병합 과정에서 지속적인 디스크 I/O를 발생시킵니다. 초기 설정 상태에서는 대규모 SELECT 및 Merge 작업이 동시에 발생할 때 EBS Throughput이 지속적으로 상한에 도달하며 그래프상에서도 처리량이 급격히 치솟았다가 떨어지는 패턴이 반복적으로 관찰되었습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*sbACOYZIw7GA4g7XNq-98w.png" /><figcaption>Throughput Before</figcaption></figure><p>이에 따라 EBS 볼륨 설정을 조정해 IOPS와 Throughput을 명시적으로 상향했습니다. 기존 gp3 기본 설정 대비 약 두 배 수준으로 확장하여, <strong>IOPS 5,000, Throughput 250 MB/s</strong>로 설정했습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Q_Q_FJ-Lsj-SutBZgc8_Pg.png" /><figcaption>Throughput After</figcaption></figure><p>이후에는 Throughput이 상한에 장시간 고정되는 현상이 없어졌으며 대규모 SELECT 쿼리와 Merge 작업이 동시에 수행되는 구간에서도 디스크 I/O가 보다 안정적으로 유지되는 것을 확인할 수 있었습니다. 결과적으로 쿼리 지연이 완화되었습니다.</p><h4>3. 성능 이슈: Keeper와의 동거</h4><p>운영 중 서버 성능 이슈가 발생하여 병목 지점을 추적하던 중 흥미로운 사실을 발견했습니다.</p><blockquote><strong><em>“Keeper 프로세스가 없는 노드의 성능이 가장 좋다.”</em></strong></blockquote><p>ClickHouse Server와 Keeper를 같은 노드(EC2 인스턴스)에 띄워 사용하다 보니, Keeper가 CPU와 I/O 자원을 점유하며 DB 성능에 간섭을 일으키고 있었습니다. 정석대로라면 Keeper 전용 서버를 분리해야 했지만, 그러기 위해서는 총 7대(Server 4 + Keeper 3)의 인스턴스가 필요했습니다.</p><p>비용을 계산해 보니 서버 7대보다 ClickHouse Cloud의 비용이 동일 비용으로 더 나은 퍼포먼스를 낼 것으로 예상되었습니다. 따라서 무작정 서버를 늘리기보다는 효율적인 자원 활용방안으로 찾기로 했습니다.</p><ul><li><strong>Keeper 관련 설정 변경</strong></li></ul><p>Keeper 가 자원을 독점하지 못하도록 docker 레벨에서 제한을 걸었습니다.</p><pre>    deploy:<br>      resources:<br>        limits:<br>          cpus: &#39;2.0&#39;<br>          memory: 4G<br>        reservations:<br>          cpus: &#39;0.5&#39;<br>          memory: 1G</pre><p>Keeper 설정 파일에서 패킷 사이즈와 배치 처리 크기를 조정했습니다.</p><pre>&lt;keeper_server&gt;<br>  &lt;max_packet_size&gt;33554432&lt;/max_packet_size&gt;<br>  &lt;max_requests_batch_size&gt;10000&lt;/max_requests_batch_size&gt; <br>&lt;/keeper_server&gt;</pre><ul><li><strong>ClickHouse 내부 설정</strong></li></ul><p>users.xml 을 통해서 병렬/분산 처리에 대한 임계치를 수정하였습니다.</p><pre>&lt;max_insert_block_size &gt;20000000&lt;/max_insert_block_size&gt;<br>&lt;max_block_size&gt;20000000&lt;/max_block_size&gt;<br><br>&lt;distributed_aggregation_memory_efficient&gt;1&lt;/distributed_aggregation_memory_efficient&gt;<br>&lt;connect_timeout_with_failover_ms&gt;3000&lt;/connect_timeout_with_failover_ms&gt;</pre><p>추가로 <strong>Refresh MV(Materialized View)</strong>를 적극 활용하여 조회 성능을 최적화했고, 현재는 안정적인 성능을 유지하고 있습니다. 장기적으로는 리소스 격리와 유연한 관리를 위해 Kubernetes(K8s) 환경으로의 전환도 검토 중입니다.</p><h4>4. 스토리지 Full 이슈: 범인은 로그</h4><p>구축이 완료되었다고 안심했을 때, 또 다른 복병을 만났습니다. 바로 <strong>디스크 용량 부족(Disk Full)</strong> 알람이었습니다. 데이터 저장 공간은 넉넉히 산정했다고 생각했는데, 확인해 보니 <strong>로그 파일</strong>들이 디스크를 점유하고 있었습니다.</p><ul><li><strong>ClickHouse &amp; Keeper 로그:</strong> 기본 설정으로는 로그가 계속 쌓이게 되어 있었습니다. Log Rotation 정책을 적용하여 주기적으로 오래된 로그를 삭제/압축하도록 설정했습니다.</li></ul><pre>&lt;logger&gt;<br>    &lt;!-- Rotation policy<br>         See https://github.com/pocoproject/poco/blob/poco-1.9.4-release/Foundation/include/Poco/FileChannel.h#L54-L85<br>      --&gt;<br>    &lt;size&gt;1000M&lt;/size&gt;<br>    &lt;count&gt;10&lt;/count&gt;<br>&lt;/logger&gt;</pre><ul><li><strong>Docker 컨테이너 로그:</strong> ClickHouse를 Docker로 띄웠는데, Docker 자체의 json-file 로그가 무제한으로 쌓이고 있었습니다. Docker 데몬 설정에서 max-size와 max-file 옵션을 추가하여 해결했습니다.</li></ul><pre>version: &#39;3&#39;<br>services:<br>  name:<br>    ...<br>    logging:<br>      options:<br>        max-file: &quot;5&quot;<br>        max-size: &quot;50m&quot;</pre><h3>마치며</h3><p>온프레미 환경을 직접 처음 구축하면서 수많은 시행착오를 겪었지만, 덕분에 ClickHouse의 내부 동작 원리와 인프라 구성을 깊이 있게 이해할 수 있는 값진 시간이었습니다.</p><p>현재 SpoonLabs는 이 시스템을 기반으로 실시간에 가까운 데이터 분석 환경을 제공하고 있으며 앞으로도 데이터 기반 의사결정을 지원하기 위해 파이프라인을 지속적으로 고도화할 예정입니다.</p><p>더 나아가, 안정적인 운영 환경을 확보하기 위한 다양한 방안을 모색 중이며 그 일환으로 Kubernetes로의 이관 또한 긍정적으로 검토하고 있습니다.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=7d5a6eb60e4f" width="1" height="1" alt=""><hr><p><a href="https://medium.com/spoontech/clickhouse-%EB%8F%84%EC%9E%85%EA%B8%B0-%EB%B9%A0%EB%A5%B8-%EB%B6%84%EC%84%9D-db%EB%A5%BC-%EB%93%A4%EC%9D%B4%EB%A9%B4-%EB%AA%A8%EB%93%A0-%EA%B2%8C-%ED%95%B4%EA%B2%B0%EB%90%A0-%EC%A4%84-%EC%95%8C%EC%95%98%EB%8B%A4-7d5a6eb60e4f">ClickHouse 도입기: “빠른 분석 DB를 들이면 모든 게 해결될 줄 알았다”</a> was originally published in <a href="https://medium.com/spoontech">SpoonLabs</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[클로드-스킬(Claude Skills)로 만드는 조직 표준 기반 코딩 에이전트]]></title>
            <link>https://medium.com/spoontech/%ED%81%B4%EB%A1%9C%EB%93%9C-%EC%8A%A4%ED%82%AC-claude-skills-%EB%A1%9C-%EB%A7%8C%EB%93%9C%EB%8A%94-%EC%A1%B0%EC%A7%81-%ED%91%9C%EC%A4%80-%EA%B8%B0%EB%B0%98-%EC%BD%94%EB%94%A9-%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8-3531284de6d7?source=rss----bb1e592ad19a---4</link>
            <guid isPermaLink="false">https://medium.com/p/3531284de6d7</guid>
            <category><![CDATA[tech]]></category>
            <category><![CDATA[claude-code-skills]]></category>
            <category><![CDATA[claude-code]]></category>
            <dc:creator><![CDATA[SangminKim]]></dc:creator>
            <pubDate>Thu, 29 Jan 2026 01:47:09 GMT</pubDate>
            <atom:updated>2026-01-29T01:47:07.646Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*TdqtmIpIqwroVqoT.jpg" /></figure><p>최근 소프트웨어 개발 생태계에서 AI는 단순한 보조 도구를 넘어 생산성의 핵심 축으로 자리 잡고 있습니다. ChatGPT를 필두로 시작된 변화는 이제 단순한 기술 학습이나 코드 조각 생성을 넘어, 개발자의 의도를 이해하고 복잡한 작업을 수행하는 ‘코딩 에이전트’의 시대로 진화했으며, 다양한 업무 분야에서 폭넓게 활용되고 있습니다.</p><p>스푼랩스에서도 이러한 빠른 변화에 맞춰 AI 도구 활용을 적극적으로 권장하고 있으며, 이를 뒷받침하기 위한 환경과 지원도 함께 제공하고 있습니다. 이러한 지원을 바탕으로 백엔드 개발팀은 클로드-코드(Claude-Code)를 주요 도구로 활용하며 개발 과정 전반에서 실질적인 도움을 받고 있습니다.</p><p>이번 글에서는 클로드-코드(이하 클로드)를 사용하면서 마주한 현실적인 문제들과, 이를 해결하기 위해 클로드-스킬(Claude-Skills)을 활용한 경험을 공유합니다.</p><h3>해결해야 했던 문제들</h3><p>최근 바이브 코딩을 통해 무엇을 만들었다거나, AI로 개발자의 역할이 대체될 수 있다는 주장들이 쉽게 소비되고 있습니다. 그러나 이러한 사례들은 대부분 맥락이 단순한 예제나 단발성 프로젝트에 국한된 경우가 많습니다. 실제 기업 환경의 개발에는 외부 모델이 알 수 없는 사내 규칙과 내부 시스템 맥락이 다수 포함되어 있어, AI가 이를 즉시 이해하고 그대로 적용하기에는 어려움이 따릅니다.</p><p>설령 AI가 내부 시스템의 맥락을 충분히 이해하고 있다고 가정하더라도, 프로덕션 환경의 개발을 전적으로 AI에 맡기기에는 여전히 현실적인 제약이 존재합니다. AI는 많은 작업을 빠르게 처리할 수 있지만, 서비스에 영향을 미치는 결정과 그 책임까지 대신할 수는 없습니다. 따라서 AI가 작성한 코드는 사람의 검토와 판단을 전제로 하게 됩니다.</p><blockquote>물론 이러한 사람의 판단과 결정이 필요한 영역들 역시, 언젠가는 AI로 대체될 수 있다는 가능성을 부정하지는 않습니다. 다만 현재 시점에서는, 그리고 적어도 당분간은 시스템 맥락과 운영 환경, 그리고 예외 상황까지 고려하는 인간의 의사결정을 전제로 한 구조적 장치와 운영 전략이 여전히 필요하다고 판단했습니다.</blockquote><p>이러한 문제의식을 바탕으로, 크게 두 가지 해결책이 필요하다고 판단했습니다.</p><p><strong>첫째 — </strong>클로드는 사내에서 사용 중인 커스텀 라이브러리를 이해하고 활용할 수 있어야합니다. 내부 라이브러리에는 반복적인 보일러플레이트(Boilerplate)를 줄이기 위한 추상화뿐 아니라, 서비스 안정성을 위한 보호 장치와 내부 통신 규약이 함께 포함되어 있습니다. 따라서 서비스 개발에서는 내부 라이브러리 사용은 필수적입니다.</p><p><strong>둘째 — </strong>클로드는 일관된 코딩 컨벤션을 따르는 코드 스타일을 유지하는 해야합니다. 클로드를 비롯한 LLM은 확률 기반 모델이기 때문에, 동일한 요청에도 결과가 달라질 수 있습니다. 이러한 변동성은 코드 스타일의 일관성을 해치고, 코드 리뷰 부담을 크게 증가시킵니다.</p><blockquote>클로드는 기존 프로젝트 내 코드가 존재할 경우, 이를 기반으로 스타일을 분석하고 일관된 코드를 작성하려고 합니다. 그러나 스푼랩스와 같은 마이크로서비스 환경에서는 새로운 서비스가 자주 생성되며, 초기 단계에는 기준이 될 코드 베이스가 없는 경우가 많습니다. 이로 인해 서비스마다 서로 다른 스타일의 코드가 작성되기 쉽습니다.</blockquote><h3>CLAUDE.md 를 이용한 시도</h3><p>처음에는 이 문제를 해결하기 위해 CLAUDE.md 파일에 내부 코딩 규칙과 라이브러리 가이드를 하나씩 추가해 나갔습니다. 클로드가 이를 인지해 우리가 원하는 형태의 코드를 생성하는 모습을 보며 가능성을 느꼈고, 조금씩 내용을 정리하며 확장해 나갔습니다.</p><p>그러나 시간이 지날수록 파일의 크기는 과도하게 커졌고, 이렇게 누적된 내용은 수정과 관리 모두를 어렵게 만들었습니다. 또한 세션 시작 시 자동으로 시스템-프롬프트(System-Prompt)에 포함되는 CLAUDE.md 의 특성으로 인해, 파일이 커질수록 실제 작업과 무관한 내용까지 매번 컨텍스트에 함께 포함되는 비효율이 발생했습니다.</p><p>이후 이러한 문제 개선을 위해서 아래와 같은 방법들을 추가로 적용해 보았지만, 결과적으로 근본적인 문제를 해결하지는 못했습니다.</p><h4><a href="https://code.claude.com/docs/en/memory#modular-rules-with-claude/rules/">.claude/rules/</a></h4><p>.claude/rules/ 디렉토리는 CLAUDE.md의 일부 내용을 분리해 관리할 수 있도록 제공되는 구조로, 코드 스타일이나 테스트 규칙처럼 성격이 다른 지침을 파일 단위로 모듈화할 수 있습니다. 이를 통해 문서의 가독성과 관리 편의성은 어느 정도 개선할 수 있었습니다.</p><pre>&lt;--! .claude/rules/ 디렉토리 구성 예 --&gt;<br><br>your-project/<br>├── .claude/<br>│   ├── CLAUDE.md           # Main project instructions<br>│   └── rules/<br>│       ├── code-style.md   # Code style guidelines<br>│       ├── testing.md      # Testing conventions<br>│       └── security.md     # Security requirements</pre><p>하지만 클로드는 실행 시 .claude/rules/ 하위의 모든 규칙 파일을 한 번에 로드하기 때문에, 규칙을 분리하더라도 컨텍스트 사용량 자체는 줄어들지 않았습니다. 결과적으로, 컨텍스트 낭비라는 핵심 문제는 그대로 남아 있었습니다.</p><h4><a href="https://code.claude.com/docs/en/memory#path-specific-rules">Path-specific rules</a></h4><p>.claude/rules/ 파일에 정의된 paths프론트매터(Frontmatter)는 규칙의 적용 대상을 특정 경로로 제한합니다. 이를 통해 클로드는 해당 경로의 파일을 처리할 때만 규칙을 로드하게 되며, 모든 규칙을 상시 로드하는 구조를 피할 수 있을 것처럼 보였습니다.</p><pre>&lt;--! src/api 경로에 파이썬 파일에 접근하는 경우에만 규칙을 적용 --&gt;<br><br>---<br>paths: src/api/**/*.py<br>---<br><br># API Development Rules<br>- All API endpoints must include input validation<br>- Use the standard error response format<br>- Include OpenAPI documentation comments</pre><p>그러나 프로젝트 구조가 바뀔 때마다 경로 조건을 함께 관리해야 했고, 규칙과 적용 범위 간의 관계를 한눈에 파악하기도 어려웠습니다. 결과적으로 컨텍스트 사용량은 일부 줄었을지 몰라도, 관리 복잡성은 다른 형태로 전가되었습니다.</p><h3>클로드-스킬의 등장</h3><p>저는 클로드를 사용하며 가능한 한 최신 버전을 유지하려고 합니다. 업데이트를 통해 더 나은 컨텍스트 처리 방식이나 모델 성능 개선이 이루어지면, 그만큼 이전보다 더 나은 코드를 작성할 수 있지 않을까 하는 기대가 있기 때문입니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*fY3FXuZOY-3xqralPdyxUQ.png" /></figure><p>그러던 중 <a href="https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md">릴리스 노트</a>를 확인하다가 클로드-스킬이 새롭게 추가되었다는 내용을 발견했습니다. 공식문서는 스킬을 다음과 같이 정의합니다.</p><ul><li>클로드-스킬이란, 클로드의 동작을 확장하기 위한 모듈형 기능으로, 특정 작업 목적에 맞는 지침과 메타데이터, 그리고 필요 시 실행 가능한 리소스를 하나의 단위로 정의합니다. 클로드는 사용자의 요청을 처리하는 과정에서 이러한 스킬을 자동으로 선택하고 활용합니다.</li></ul><p>해당 내용을 확인하는 과정에서, 기존의 CLAUDE.md 기반 접근 방식이 가지던 한계를 보완할 수 있는 새로운 개념이라는 인상을 받았고, 현재 이를 적극적으로 도입해 활용하고 있습니다.</p><p>앞서 정의만 놓고 보면 다소 추상적으로 느껴질 수 있기 때문에, 각 특성을 중심으로 실제로 어떤 의미를 가지는지 차례대로 살펴보겠습니다.</p><h4>- 기능 단위 모듈화(Modular Capabilities)</h4><p>클로드-스킬에 각 스킬은 .claude/skills 디렉토리 아래에 독립적인 폴더 형태로 정의합니다. 이때 디렉토리 이름이 곧 스킬의 이름이 되며, 클로드는 이 이름을 기준으로 스킬을 식별합니다. 각 스킬 디렉토리에는 반드시 SKILL.md 파일이 포함되어야 하며, 이 파일을 통해 스킬의 목적과 동작 방식이 정의됩니다.</p><p>SKILL.md는 크게 두 부분으로 구성됩니다. 상단에는 스킬의 name, description과 같은 메타 정보를 담는 프론트매터가 위치하고, 하단에는 클로드가 실제로 수행해야 할 작업 지침을 서술하는 본문이 이어집니다.</p><pre>&lt;!-- SKILL.md 파일 구조 예시 --&gt;<br><br>---<br>name: your-skill-name<br>description: Brief description of what this Skill does and when to use it<br>---<br># Your Skill Name<br>## Instructions<br>Provide clear, step-by-step guidance for Claude.<br>## Examples<br>Show concrete examples of using this Skill.</pre><p>스킬 디렉토리에는 SKILL.md 외에도, 작업 수행에 필요한 추가 지식·규칙·가이드를 담은 다양한 형태의 파일을 함께 포함할 수 있습니다. 이러한 참조 파일들은 하나의 스킬 디렉토리 안에서 모듈화된 구조로 관리되며, 스킬이 수행해야 할 작업을 구체화하는 역할을 합니다.</p><p>SKILL.md에는 스킬에서 사용할 수 있는 참조 파일과 그 목적이 명확히 정의되어야 합니다. 이러한 정보가 제공되어야만 클로드가 작업 흐름에 따라 필요한 파일을 선택적으로 참조할 수 있습니다.</p><p>이 구조를 통해 스킬은 하나의 독립적인 기능 단위로 관리될 수 있습니다.</p><pre>&lt;!-- 스킬 디렉토리 구조 예시 --&gt;<br><br>my-skill/<br>├── SKILL.md (required)<br>├── reference.md (optional documentation)<br>├── examples.md (optional examples)<br>├── scripts/<br>│   └── helper.py (optional utility)<br>└── templates/<br>    └── template.txt (optional template)</pre><blockquote>참조 파일은 단순한 텍스트 파일부터 이미지, PPT 파일 등 다양한 형식을 지원하며 디렉토리 구조도 자유롭게 구성할 수 있습니다.</blockquote><h4>- 모델 자율 호출 (Model Invoked)</h4><p>클로드는 사용자 프롬프트가 주어지면, 클로드-스킬의 SKILL.md 파일 프론트매터에 정의된 description 과 연관성을 판단한 뒤, 적합한 스킬을 자동으로 사용합니다.</p><p>description에는 스킬이 무슨(What) 작업을 수행하며, 어떤 상황(When)에서 사용되어야 하는지가 3인치 관점으로 명확히 드러나야 합니다. description의 품질은 클로드의 스킬 선택 정확도를 좌우하는 핵심 요소입니다. 추가적인 ‘효율적인 <em>description</em> 작성 법’은 다음 <a href="https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#writing-effective-descriptions">링크</a>에서 확인할 수 있습니다.</p><h4>- 점진적 컨텍스트 로딩 (Progressive Disclosure)</h4><p>앞서 하나의 스킬은 SKILL.md파일(프론트매터와 본문)과, 이를 보조하는 다양한 참조 파일로 구성될 수 있다고 설명했습니다. 클로드는 이러한 구성 요소를 한 번에 모두 읽지 않고, 정해진 규칙에 따라 3단계로 나누어 점진적으로 접근함으로써 불필요한 컨텍스트 사용을 줄입니다.</p><p><strong>1단계 </strong>— 클로드는 각 스킬의 SKILL.md 전체를 항상 로드하지 않고, 프론트매터에 정의된 메타 정보만을 기본 컨텍스트로 유지합니다. 이후 사용자 프롬프트가 전달되면, 앞서 설명한 ‘모델 자율 호출’ 기준에 따라 사용할 스킬을 판단합니다.</p><p><strong>2단계</strong> — 특정 스킬 사용이 확정되면 클로드는 해당 스킬의 SKILL.md 본문을 읽어 실제 작업에 필요한 지침을 확인합니다.</p><p><strong>3단계 </strong>— 클로드는 본문에 지침을 확인하는 과정에서 참조 파일이 필요하다 판단되는 경우에만 필요한 파일을 추가로 읽어 컨텍스트에 포함합니다.</p><pre>[Skill 컨텍스트 로딩 단계]<br><br>1단계: SKILL.md 프론트매터<br>- 로드 시점: 항상<br>- 내용: 스킬 name, description<br>- 목적: 사용 가능한 스킬 판단<br><br>2단계: SKILL.md 지침<br>- 로드 시점: 스킬 사용 결정 시<br>- 내용: SKILL.md 본문<br>- 목적: 실제 작업 지침 확인<br><br>3단계: SKILL.md에 명시된 참조 파일 <br>- 로드 시점: 정보가 필요할 때<br>- 내용: 예시, 규칙, 템플릿<br>- 목적: 필요한 경우에만 컨텍스트 확장</pre><p>이러한 구조를 통해, SKILL.md에는 필수적인 지침만을 명확히 정의하고, 그에 파생되는 상세 정보는 참조 파일을 통해 필요할 때만 읽도록 구성할 수 있습니다.</p><pre>&lt;!-- 참조 파일 명시 예시 --&gt;<br><br>For advanced usage, see [reference.md](reference.md).<br>Run the helper script:<br>```bash<br>python scripts/helper.py input.txt<br>```</pre><p>‘점진적 컨텍스트 로딩’을 효과적으로 유지하기 위해, SKILL.md 본문은 가능한 간결하게 작성하는 것이 중요하며, 내부적으로는 500라인 이하로 유지하는 것을 권장합니다. 이를 초과하는 상세한 설명이나 예시는 참조 파일로 분리함으로써, 컨텍스트 낭비를 줄이고 스킬의 볼륨 증가로 인한 비효율을 효과적으로 관리할 수 있습니다.</p><p>참조 파일의 참조 깊이는 1단계 깊이(1 Depth)로 제한하는 것을 권장합니다. 중첩된 참조 구조에서는 파일 내용이 부분적으로만 로드되어 의도하지 않은 동작이 발생할 수 있습니다.</p><blockquote>‘점진적 컨텍스트 로딩’을 적용하더라도, 한 번 로드된 파일은 컨텍스트에 그대로 포함됩니다. 따라서 무엇을 언제 읽게 할지뿐만 아니라, 애초에 어떤 내용을 담느냐 역시 중요합니다. <em>SKILL.md</em>와 참조 파일에는 꼭 필요한 정보만을 명확하게 작성하고, 클로드가 이미 알고 있을 만한 일반적인 설명은 과감히 제외하는 것이 컨텍스트 관리 차원에서는 바람직합니다.</blockquote><h4>- 결정적 처리(Deterministic Processing)</h4><p>결정적 처리란, 같은 입력이 주어졌을 때 언제 실행하더라도 항상 동일한 결과를 반환하는 처리 방식을 의미합니다. 반면 클로드를 비롯한 LLM은 본질적으로, 동일한 질문이라 하더라도 실행 시점이나 컨텍스트에 따라 결과가 달라질 수 있는, 비결정적 처리를 수행합니다.</p><p>하지만 실제 개발 과정에서는 처리 기준이 명확하게 정의되어 있고, 결과의 일관성이 중요한 영역이 존재합니다. 이러한 요구를 충족하기 위해 클로드-스킬은 스크립트(Script)를 활용한 결정적 처리를 지원합니다.</p><p>결정적 처리가 필요한 작업은 스크립트로 분리하고, 클로드는 스크립트를 언제 실행할지와 그 결과를 어떻게 활용할지만 판단합니다. 스크립트 내부 내용은 컨텍스트에 포함되지 않으며, 클로드는 정의된 실행 방식에 따라 이를 호출할 뿐입니다.</p><pre>&lt;!-- 결정적 처리를 위해 워크플로우 중 스크립트를 실행하는 예시 --&gt;<br><br>## Workflow<br><br>### Step 1: Paramter Validation<br>Verify the URL and HTTP method provided by the user.<br><br>### Step 2: Execute Test Script<br>Run the following command using bash_tool:<br>```bash<br>python scripts/test_api.py \<br>  --url &quot;URL_PROVIDED_BY_USER&quot; \<br>  --method GET<br>```<br><br>### Step3 : Analyze Results<br>Analyze the script output and report the results back to the user</pre><p>스킬에서 스크립트를 활용하면 결정적 처리를 보장하면서도 응답 성능과 컨텍스트 사용 효율을 함께 개선할 수 있습니다. 프롬프트 기반 처리에서는 전체 맥락 분석이 필요하지만, 동일한 작업을 스크립트로 분리하면 이러한 비용 없이 빠르고 일관된 처리가 가능합니다.</p><blockquote>예를 들어 문서 내의 모든 <em>foo</em>라는 단어를 <em>bar</em>로 변경하는 작업은 처리 기준이 단순하고 명확한 작업입니다. 이러한 작업을 프롬프트로 처리할 경우, 클로드는 전체 문서를 분석하며 변경을 수행해야 하지만, 스크립트로 분리하면 입력 파일과 변경 규칙만 전달해 빠르고 결정적인 처리가 가능합니다.</blockquote><h3>‘모델 자율 호출’ 성능 개선</h3><p>스킬은 ‘모델 자율 호출’ 특성에 따라, 사용자 프롬프트의 의도와 스킬의 목적 간 연관성을 기준으로 자동으로 선택되어야 합니다. 그러나 실제로 스킬을 정의하고 사용해보면, 기대와 달리 의도한 스킬이 자동으로 선택되지 않는 경우가 적지 않습니다. 이로 인해 프롬프트 실행을 중단한 뒤, 스킬을 명시적으로 지정하여 다시 실행해야 하는 상황이 빈번하게 발생했습니다.</p><p>처음에는, 이러한 현상이 잘못 작성된 description이 원인이라 생각하여, 모범 사례를 기준으로 여러 차례 개선을 시도해 보았습니다. 그러나 ‘모델 자율 호출’ 성능은 잘 개선되지 않았습니다.</p><p>이러한 현상에 대해 조사해본 결과, 이는 저만의 문제가 아니라 많은 사용자들이 공통적으로 겪고 있는 현상임을 확인할 수 있었습니다. 그리고 그 과정에서 훅(Hook)을 활용해 연관된 스킬을 사용하도록 유도하는 방식을 발견하게 되었습니다.</p><p>작동 원리는 직관적입니다. 사용자 프롬프트가 입력되면 클로드는 정의된 훅을 트리거(Trigger)하여 스크립트를 실행합니다. 해당 스크립트는 스킬 프론트메터를 읽어 클로드에게 직접 제시하고 프롬프트와의 적합성을 평가하게 한 뒤, 적합한 스킬의 사용을 명시적으로 요구합니다.</p><h4>UserPromptSubmit 이벤트-훅 설정</h4><p>~/.claude/settings.json 에 아래와 같이 UserPromptSubmit 훅-이벤트에 스크립트 실행 명령어를 작성합니다. UserPromptSubmit 이벤트는 사용자가 프롬프트를 전송하면 자동으로 발생되는 이벤트입니다. 즉, 사용자가 프롬프트를 입력하면 클로드가 이를 처리하기 전에 해당 스크립트가 자동으로 실행됩니다.</p><pre>&lt;!-- ~/.claude/settings.json --&gt;<br><br>{<br>  ...<br>  &quot;hooks&quot;: {<br>    &quot;UserPromptSubmit&quot;: [<br>      {<br>        &quot;hooks&quot;: [<br>          {<br>            &quot;type&quot;: &quot;command&quot;,<br>            &quot;command&quot;: &quot;python ~/.claude/hooks/skill-activation-prompt.py&quot;<br>          }<br>        ]<br>      }<br>    ]<br>  }<br>}</pre><h4>스킬 사용 유도 스크립트</h4><p>훅에 등록된 스크립트는 명시적으로 프로젝트와 홈(Home) 디렉토리의.claude/skills 내부를 순환하면서 모든SKILL.md 메타프론터의 name과 description을 읽어 아래와 같이 출력합니다. 이렇게 표준 출력(stdout)으로 전송된 내용은 시스템 리마인더(System-Reminder)로서 클로드에게 주입됩니다.</p><pre>Available skills in this project:<br><br>• kotlin-test-guide<br>  └─ This skill should be used when writing or reviewing Kotlin test code. Provides common testing patterns and verification rules.<br>• kotlin-dev-guide<br>  └─ This skill should be used when writing or reviewing Kotlin production code (not test code). Provides essential coding rules and patterns.<br><br>INSTRUCTION:<br>   1. Review the user prompt above<br>   2. For EACH skill listed, ask yourself: Is this skill needed for the task?<br>   3. Use the Skill tool to activate ONLY the skills that are relevant<br>   4. You may use multiple skills if needed, or none if no skills apply<br><br>IMPORTANT: Check skills BEFORE responding to the user</pre><blockquote>훅을 활용한 스킬 트리거 방식에는 여러 전략이 존재합니다. 제가 선택한 방식은 클로드에게 “이러한 스킬이 존재하니, 잊지 말고 필요 시 활성화해 달라”고 리마인드하는 비교적 간접적인 접근이었습니다.</blockquote><blockquote>반면, 스크립트에서 사용자 프롬프트와 스킬 간의 연관성을 직접 분석·판단해 특정 스킬 사용을 지시하는 접근 방식도 존재합니다. 현재로서는 간접적인 방식만으로도 충분하다고 판단했지만, 상황에 따라 보다 직접적이고 강제적인 방식이 필요해질 수 있습니다.</blockquote><blockquote>좀 더 강력한 스킬 강제화가 필요한 경우 첨부된 <a href="https://www.reddit.com/r/ClaudeAI/comments/1oivjvm/claude_code_is_a_beast_tips_from_6_months_of/?share_id=xgILJBys0BxT3Wpy5t6ij&amp;utm_content=2&amp;utm_medium=ios_app&amp;utm_name=ioscss&amp;utm_source=share&amp;utm_term=1">링크</a>를 참조하시면 좋을 것 같습니다.</blockquote><p>훅 설정 이후, 코틀린 코드 리팩토링을 요청했을 때 실제로 출력된 클로드의 아웃풋 메시지 입니다. 클로드가 스크립트에서 시스템-리마인더로 전달한 내용을 인지하고 의도한 스킬을 활성화는 것을 확인할 수 있습니다.</p><pre>&gt; @DefaultStickerService.kt 리펙토링 해줘<br><br>Available skills in this project:<br>• kotlin-test-guide<br>  └─ This skill should be used when writing or reviewing Kotlin test code. Provides common testing patterns and verification rules.<br>• kotlin-dev-guide<br>  └─ This skill should be used when writing or reviewing Kotlin production code (not test code). Provides essential coding rules and patterns.<br><br>INSTRUCTION:<br>   1. Review the user prompt above<br>   2. For EACH skill listed, ask yourself: Is this skill needed for the task?<br>   3. Use the Skill tool to activate ONLY the skills that are relevant<br>   4. You may use multiple skills if needed, or none if no skills apply<br><br>IMPORTANT: Check skills BEFORE responding to the user<br><br>∴ Thinking…<br><br>  사용자가 DefaultStickerService.kt 파일을 리팩토링해달라고 요청했습니다. 이 파일은 이미 읽었고, 사용자가 IDE에서 열어놓은 상태입니다.<br>  먼저 Kotlin 프로덕션 코드를 작성/리뷰할 때는 kotlin-dev-guide 스킬을 사용해야 합니다. 시스템 리마인더에서도 관련 스킬을 활성화하라고 했습니다.<br>  파일을 살펴보니:<br>  1. 컨트롤러 클래스로 베리 트레이스 정보를 조회하는 API 엔드포인트를 제공<br>  2. suspend 함수 사용 (코루틴)<br>  3. 날짜 범위 조회 파라미터들<br>  4. 페이징 처리<br>  먼저 kotlin-dev-guide 스킬을 활성화한 후, 코드를 리뷰하고 리팩토링 제안을 해야 합니다.<br><br>⏺ 코드를 리팩토링하기 전에 Kotlin 개발 가이드를 참고하겠습니다.</pre><blockquote>클로드는 사용자 프롬프트를 해석할 때, 자체 판단에 따라 충분한 맥락이 이미 확보되었다고 인식하면 스킬 호출을 생략하는 경향이 있습니다.</blockquote><blockquote>이로 인해 내부 코딩 규약처럼 모델이 일반적인 패턴으로 처리할 수 있다고 판단하는 스킬은 자동 호출되지 않는 경우가 많았습니다.</blockquote><blockquote>반면, 내부 데이터베이스 조회처럼 클로드가 사전에 알 수 없는 정보를 필요로 하는 스킬에서는 자동 호출 성능이 상대적으로 높게 유지되었습니다.</blockquote><h3>클로드 서브-에이전트(Sub-Agent)와 스킬</h3><p>스킬은 처음 접하면 서브 에이전트의 역할과 쉽게 혼동될 수 있습니다. 저 역시 처음에는 “서브 에이전트와 스킬의 본질적인 차이가 무엇일까?”, “서브 에이전트를 기능 단위로 쪼개면 그게 곧 스킬 아닌가?”라는 생각을 했습니다.</p><p>하지만 고민 끝에 두 개념을 다음과 같이 구분하게 되었습니다. 스킬은 지식 그 자체를 담는 단위이고, 서브 에이전트는 그 지식을 실제로 활용해 일을 하는 작업자입니다. 하나의 서브 에이전트는 여러 스킬을 동시에 사용할 수 있으며, 이를 조합해 하나의 작업 흐름을 완성합니다.</p><p>정리해보면, 서브 에이전트의 역할은 여러 스킬을 바탕으로 작업의 흐름과 실행 방식을 조직하고 실제 작업을 수행하는 주체라고 이해할 수 있습니다. 하지만 이 관점이 유일한 정답이라고 보기는 어렵습니다. 스킬과 서브 에이전트가 서로를 어떻게 참조해야 하는지에 대해서는 사용자마다 해석이 다르고, 지금도 활발한 논의가 이어지고 있습니다.</p><blockquote>실제로 최근 접한 클로드 관련 해커톤 공고에 아래와 같은 내용이 포함되어 있었고, 이를 통해 이러한 고민이 저 혼자만의 문제는 아니라는 점을 다시 한번 확인할 수 있었습니다.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/637/1*dpaQHfHOEOr8J9aIdSeWJw.png" /><figcaption>클로드 관련 해커톤 모집 공고 일부</figcaption></figure><h3>클로드-스킬 팀 자산으로 확장하기</h3><p>작성한 스킬은 내부 공유를 전제로 하여 GIT 저장소를 통해 관리하고 있습니다. 모든 규칙을 초기 단계에서 완벽하게 정의하기보다는, 필요에 따라 스킬을 하나씩 추가하며 점진적으로 확장하려고 합니다. 신규 스킬 추가나 기존 스킬 수정 사항은 PR 기반으로 공유되며, 리뷰 과정을 통해 변경 이력을 관리합니다.</p><p>개별 개발 환경에는 해당 저장소를 풀(Pull)한 뒤, 제공되는 스크립트를 실행하여 설치합니다. 이 스크립트는 ~/.claude 디렉토리에 필요한 파일들을 심볼릭-링크(Symbolic-link) 형태로 연결하며, 이후 스킬 변경이나 규칙 추가 시에도 최신 버전을 풀하는 것만으로 즉시 반영할 수 있도록 설계하고 있습니다.</p><h4>신규 스킬 생성</h4><p>클로드 공식 저장소에는 <a href="https://github.com/anthropics/skills/tree/main/skills/skill-creator">skill-creator</a>라는 스킬이 제공됩니다. 이 스킬은 신규 스킬 생성 시 모범 사례에 따른 기본 구조를 자동으로 생성해 주어, 초기 설정에 대한 부담을 크게 줄여줍니다. 이를 통해 구성원들도 비교적 쉽게 새로운 스킬이나 참조 파일을 추가하며 스킬 생태계를 확장해 나갈 수 있을 것으로 기대합니다.</p><h3>마치며</h3><p>클로드-스킬은 어떤 특별한 신규 기능은 아닙니다. LLM이라는 자유도가 매우 높은 환경에서는 유사한 동작은 다른 방식으로도 충분히 구현할 수 있습니다. 다만 클로드-스킬의 핵심적인 의미는 이러한 접근을 클로드 내부 표준으로 정의함으로써, 사용자가 정해진 규칙에 따라 보다 일관되고 쉽게 활용할 수 있도록 했다는 점에 있습니다.</p><p>AI 자체는 이제 누구나 사용할 수 있지만, 이를 조직의 개발 환경에 맞게 일관되게 활용하는 것은 전혀 다른 문제입니다. 개인의 프롬프트 역량에 의존하는 방식은 한계가 있으며, 이를 보완하기 위해서는 공통의 기준과 구조가 필요합니다. 클로드-스킬은 이러한 기준을 팀 단위로 확장할 수 있는 효과적인 방법이라고 생각됩니다.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3531284de6d7" width="1" height="1" alt=""><hr><p><a href="https://medium.com/spoontech/%ED%81%B4%EB%A1%9C%EB%93%9C-%EC%8A%A4%ED%82%AC-claude-skills-%EB%A1%9C-%EB%A7%8C%EB%93%9C%EB%8A%94-%EC%A1%B0%EC%A7%81-%ED%91%9C%EC%A4%80-%EA%B8%B0%EB%B0%98-%EC%BD%94%EB%94%A9-%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8-3531284de6d7">클로드-스킬(Claude Skills)로 만드는 조직 표준 기반 코딩 에이전트</a> was originally published in <a href="https://medium.com/spoontech">SpoonLabs</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AI에 진심인 AWS, re:Invent 현장후기]]></title>
            <link>https://medium.com/spoontech/2025-aws-re-invent-ai-%EB%8C%80%EA%B2%A9%EB%8F%99-%EC%8B%9C%EB%8C%80-2496cd24ed0d?source=rss----bb1e592ad19a---4</link>
            <guid isPermaLink="false">https://medium.com/p/2496cd24ed0d</guid>
            <category><![CDATA[tech]]></category>
            <category><![CDATA[aws]]></category>
            <category><![CDATA[spoonlabs]]></category>
            <category><![CDATA[reinvent]]></category>
            <dc:creator><![CDATA[Daniel Nam]]></dc:creator>
            <pubDate>Mon, 12 Jan 2026 02:31:08 GMT</pubDate>
            <atom:updated>2026-01-12T03:18:03.633Z</atom:updated>
            <content:encoded><![CDATA[<p>안녕하세요.</p><p>SpoonLabs SRE팀에서 DevOps 엔지니어로 일하고 있는 Daniel(남태윤)입니다. 이번에 회사에서 좋은 기회를 주셔서 <strong>2025 AWS re:Invent</strong>를 다녀올 수 있었는데요.</p><p>결론부터 말씀드리면, 개발자라면 꼭 한번은 가봐야 할 행사라고 생각합니다. 전 세계 개발자 6만 명이 모인다는게 어떤 느낌인지 직접 경험하니, 글로벌 스케일이 무엇인지 체감할 수 있었습니다.</p><p>AI 관련 발표가 쏟아졌고, 개인적으로는 DevOps 관점에서 에이전트 도구들이 가장 인상 깊었습니다. 그 이야기를 하나씩 풀어보겠습니다.</p><h3>라스베가스 첫인상</h3><p>긴 비행 끝에 라스베가스에 도착했을 때는 솔직히 모두 녹초 상태였습니다. &quot;숙소 도착하면 바로 자야지” 생각했는데, 야경을 보고 마음이 바뀌었습니다.</p><p>낮에 보면 평범한 도시었으나, 밤에는 완전히 다른 세계더라고요.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*eUDN1PzouxjyYm4RsBL63w.png" /></figure><p>도착 당일 <strong>Beer Peak</strong>라는 곳에서 맥주 한 잔 하면서 분수쇼를 구경했는데요. 아직도 첫날 분위기와 야경은 잊을 수가 없습니다. 분수 야경을 보기엔 여기가 제일 좋았던 것 같습니다. 다만 가격은… 맥주 값에 야경 값이 많~이 포함되어 있기에 다음에 가실 분들도 부디 야경을 충분히 즐기셔야 할 것 같습니다. 😨 그래도 첫날 기념으로 좋은 추억을 만들 수 있었습니다.</p><h3>Opening Keynote</h3><p>다음 날부터 본격적으로 re:Invent가 시작됐습니다. 오프닝 키노트는 첫날이 아닌 둘째 날부터 시작했는데요. 전 세계 개발자들이 한 공간에 모여 새로운 기술 발표를 기다리는 모습을 보니, 진짜 글로벌 스케일이구나 싶었습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-Eyy7QS-ZUqLUA5ESnNaBg.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*j67ctcNzXBxCS1KNXWAsKA.png" /></figure><p>이번 키노트는 거의 AI 관련 서비스 특집이었습니다. 가장 인상 깊었던 내용을 중점으로 하나씩 정리해보겠습니다.</p><h4>AI 인프라 확장</h4><p>첫번째 발표는 AI 인프라 이야기였습니다. 요즘 TPS는 Transaction Per Second보다 <strong>Token Per Second</strong>로 더 많이 쓰이는 것 같습니다. ChatGPT, Claude 같은 생성형 AI가 등장하면서 “1초에 토큰을 얼마나 생성하느냐”가 중요해진 거죠.</p><p>이런 트렌드에 맞춰 AWS에서 신규 기능을 선보였습니다.</p><ul><li><strong>NVIDIA</strong> 기반 신규 EC2 인스턴스</li><li><strong>AI Factories</strong> : 고객 데이터센터에 AWS가 AI 인프라를 완전 관리형으로 제공</li></ul><p>어딜가나 AI하면 NVIDIA 항상 따라오는 것 같은데요. AWS에서도 역시나 NVIDIA의 새로운 신규 인스턴스 타입을 대대적으로 홍보하고 EXPO에서도 부스가 위치해 있는 것을 보면서 새삼 트렌드를 다시 한번 느낄 수 있었습니다.</p><p>AI Factories의 경우 규제나 데이터 이슈로 클라우드를 못 쓰는 기업들이 있는데, 이런 곳에서 클라우드의 편리함을 온프레미스에서 누릴 수 있는 서비스를 출시했습니다. 비용적인 측면도 고려해야 하겠으나 앞으로 얼마나 더 많은 기업들이 채택할지 기대됩니다.</p><h4>Bedrock에 모델 대거 추가</h4><p><strong>Amazon Bedrock</strong>에 18개 신규 모델이 추가됐습니다. Google, OpenAI, Mistral, NVIDIA, Qwen 등 업체의 최신 모델들이 포함되어 라인업이 상당히 다양해졌습니다. 그중에서도 가장 주목받은 건 AWS 자체 모델인 <strong>Amazon Nova 2</strong>입니다.</p><p>종류도 다양하고, 가격 대비 성능이 업계 최고 수준이라고 합니다. 솔직히 실제 성능은 직접 써봐야 알겠지만, 가격 측면에서는 확실히 메리트가 있어 보였습니다.</p><p>앞으로 점점 더 <strong>Bedrock 사용 비중이 늘어나는 만큼 간단한 일상 질의는 Nova가 실행하고 복잡한 분석은 타 모델을 사용</strong>한다면 비용 최적화가 가능하지 않을까 싶습니다.</p><h4>Agent 도구 출시</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_hvpDkY9CL8ypGYyV5y3ig.png" /></figure><p>개인적으로 <strong>이번 발표에서 가장 눈이 갔던 파트</strong>입니다. AWS가 이번에 공개한 에이전트들입니다</p><ul><li><strong>Kiro</strong> (자율형 에이전트)</li><li><strong>Security Agent</strong></li><li><strong>DevOps Agent</strong></li></ul><p>여기서 AWS에서는 <strong>프론티어 에이전트(Frontier Agent)</strong>라는 개념이 추가 되었는데요.</p><blockquote><em>“목표를 스스로 이해하고 달성하는 자율형 AI 에이전트”</em></blockquote><p>해당 개념이 일반 GPT나 Gemini와 다른 점은 단순 질의응답 수준이 아니라, 프로젝트 중심으로 <strong>팀원처럼 같이 일할 수 있다</strong>는 점입니다.</p><p>발표를 보면서 그럼 DevOps 엔지니어는 이제 필요 없는거 아닐까? 라고 생각들었습니다만, 저와 같은 고민을 하신 분들이 벌써 Medium에 많은 글들을 올려주셨더라고요. 솔직히 말하면 진짜 그 정도 퍼포먼스가 나올지는 직접 써봐야 알 것 같습니다. 현재 Virginia 리전에서만 PoC로 사용 가능하다고 하여 테스트 해보고 있는데요. 다음 기회에 후기를 남겨보겠습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*SqqeOX4WAsWS33yA2xQxfg.jpeg" /></figure><p>이외에도 여러 서비스가 새롭게 출시됐습니다. Database Saving Plan, S3 Vector DB 등 다양한 신규 기능이 발표 되었는데요. 다만, 이런 기능들은 비중 있게 다뤄지진 않았습니다. 발표자가 10분 안에 무려 25개 서비스를 소개하는 이벤트가 있었을 정도로, 정말 간략하게 기능만 훑고 넘어갔습니다.</p><p>그만큼 지금 AWS가 AI에 얼마나 집중하고 있는지를 보여주려는 의도가 아니었나 싶습니다.</p><h3>Session 영어 울렁증 시작</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*CGCuu14AM4zoy1MnRB52Cw.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*5cCcNcZ0NNEbXA4kh2YEiQ.png" /></figure><p>모든게 다 영어인 세션… 내용을 다 이해 할 수 있을까?</p><p>그런데 막상 세션장에 들어가보니, 저뿐만 아니라 세계 모든 사람들이 비슷하게 어려워하는 것 같더라고요. 발표자가 중간중간 재밌는 농담을 던지지만 몇몇 사람만 웃을 뿐, 대부분의 사람들은 이해하지 못하고 몹시 진지한 표정으로 발표 화면만 응시하고 있었습니다. 저 또한 그 중 한명이었기에 조금은 위안이 되었습니다.</p><p>다행히 요즘은 여러 앱 또는 서비스를 통해 어느 정도 극복할 수 있는 방법들이 많습니다.</p><p><strong>세션 발표의 경우</strong>, 클로바 노트 또는 Notion을 이용해 녹음했고, 세션 종료 후 텍스트로 변환된 내용을 읽으면서 놓쳤던 부분들을 이해 할 수 있었습니다. 다행인건 대부분의 세션이 며칠 후 AWS 공식 채널에 업로드되기 때문에, 현장에서 완벽하게 이해하지 못했더라도 나중에 자막과 함께 다시 볼 수 있다는 점이 위안이 되었습니다.</p><p><strong>Hands-On 세션의 경우</strong>는 오히려 언어 장벽이 덜했습니다. 직접 화면을 보면서 따라 하는 실습 위주라서, 발표자의 말을 100% 이해하지 못하더라도 화면에 표시되는 단계별 가이드와 실제 AWS 콘솔 조작을 보면서 충분히 따라갈 수 있었습니다. (Hands-On의 경우 영상으로도 제공되지 않기 때문에 개인적으로 좀 더 많이 신청했으면 하는 아쉬움이 있습니다)</p><h3>re:Invent 꿀팁 &amp; 그 외 이야기</h3><p>다음에 가실 분들을 위해 몇 가지 팁을 남겨봅니다.</p><h4>세션 예약은 미리, 그리고 많이</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*IqPPlijaxSX013O1_tBP2Q.png" /></figure><p><strong>AWS Events 앱</strong>을 통해 세션 정보를 미리 확인하고 동시간 대 최대한 많이 예약하는 걸 추천드립니다. 또는 예약 이외에도 참여하지 못했을 때 여러 대안들을 생각해야 하는데요. 인기 있는 주제의 경우 현장에서 기다려도 입장하지 못하는 경우가 발생합니다. 따라서 해당 시간대의 대안 세션들을 알고 있어야 re:Invent를 좀 더 알차게 즐기실 수 있습니다.</p><h4>Hands-On 세션 주의사항</h4><p>Hands-On 세션은 <strong>정해진 시간에만 입장</strong>할 수 있습니다. 다른 세션의 경우 발표 및 토론이기 때문에 예정된 시간보다 조금 늦게 가더라도 참여할 수 있습니다. 하지만 Hands-On의 경우 늦으면 입장 자체가 불가능해서 내용을 볼 수조차 없습니다. 시간 맞춰서 가시길 강력 추천드립니다.</p><h4>식사는 AWS가 챙겨줍니다</h4><p>아침과 점심은 걱정하지 않으셔도 됩니다. AWS가 제공합니다.<br>다만, 각 호텔별로 음식 메뉴와 퀄리티가 조금 다릅니다.</p><p>개인적으로는 이동 동선과 식사 퀄리티를 생각했을 때 <strong>CESARS Forum</strong>이 가장 좋았습니다. 다음에 가실 분들은 한번 참고해보셔도 좋을 것 같습니다.</p><h4>라스베가스 러닝 코스</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1009/1*NTp5tJlx2_0LGwPscTdlsA.png" /></figure><p>일정 마지막 날 Las Vegas를 러닝 해볼 수 있었는데요.🏃<br>숙소에서 출발해 Las Vegas 전광판이 있는 곳까지 달리면서 풍경과 경치를 온전히 즐길 수 있었습니다. 참고로 코스 목적지인 Las Vegas 전광판 앞에 엘비스 프레슬리 코스프레 아저씨를 만나실 수 있는데요. 주저하지 말고 사진 찍어달라고 요청하셔도 됩니다. 무료로 커플이나 개인을 재밌게 사진 찍어주시더라고요.</p><p>또한, 비록 참여는 못했지만 AWS에서 주관하는 5k 러닝 스케쥴도 있으니 다음에 가실 분들은 참고해 보셔도 좋을것 같습니다. 😀</p><h3>새로운 동기부여</h3><p>처음 가본 re:Invent는 기대 이상이었습니다. 규모도 규모지만, 다양한 세션과 많은 개발자들이 기술에 대한 열정이 대단하다고 느껴졌습니다. 시니어 인도 개발자는 문제를 해결하기 위해 자리에서 필기구를 꺼내 설명하고 Expo에서 만난 Resolve AI 서비스 개발자는 필요한 기능은 2주만에 만들어 줄 수 있다라는 자신감을 보여줬습니다.</p><p>이런 열정을 직접 보고 나니, 저도 다시 한번 자극을 받게 되었는데요. 다시 일상으로 돌아와, SpoonLabs 일원으로서 어떻게 기여할 수 있을지 고민하며 한 걸음 더 나아가보려 합니다.</p><p>SpoonLabs 화이팅!💪🏻</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2496cd24ed0d" width="1" height="1" alt=""><hr><p><a href="https://medium.com/spoontech/2025-aws-re-invent-ai-%EB%8C%80%EA%B2%A9%EB%8F%99-%EC%8B%9C%EB%8C%80-2496cd24ed0d">AI에 진심인 AWS, re:Invent 현장후기</a> was originally published in <a href="https://medium.com/spoontech">SpoonLabs</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AWS reInvent 2025, 이렇게까지 뽕을 뽑을 줄은…]]></title>
            <link>https://medium.com/spoontech/aws-reinvent-2025-%EC%9D%B4%EB%A0%87%EA%B2%8C%EA%B9%8C%EC%A7%80-%EB%BD%95%EC%9D%84-%EB%BD%91%EC%9D%84-%EC%A4%84%EC%9D%80-d8da6519f153?source=rss----bb1e592ad19a---4</link>
            <guid isPermaLink="false">https://medium.com/p/d8da6519f153</guid>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[spoonlabs]]></category>
            <category><![CDATA[las-vegas]]></category>
            <category><![CDATA[reinvent]]></category>
            <category><![CDATA[aws]]></category>
            <dc:creator><![CDATA[Hyungjin]]></dc:creator>
            <pubDate>Fri, 09 Jan 2026 11:30:26 GMT</pubDate>
            <atom:updated>2026-01-09T11:30:25.665Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Qoyjad3e8XnpkC1A0Lab5w.png" /><figcaption>AWS Opening Keynote</figcaption></figure><p>안녕하세요! Spoonlabs ML Engineer Jin(박형진)이라고 합니다.</p><p>회사에서 좋은 기회를 주셔서 올해 라스베가스에서 열린 AWS re:Invent 2025에 참석하고 왔습니다..! 👏👏</p><p>실제로는 5일이었는데, 한 2주 정도 갔다 온 거 같거든요?ㅎ 하루를 이틀처럼 보냈던 그 꽉찬 이야기를 전해드릴까 합니다..!</p><p>그런데 남의 후기 보는거 쉽지 않잖아요?</p><p>각 파트별 요약만 먼저 보시고, 관심있는 부분만 보셔도 감사하겠습니다! 이제 글도 숏폼화 해야죠..!ㅎ</p><p>다소 필력이 좋지 않으니 읽어보실 때 너그러운 감상 부탁드립니다.! 🙂</p><h3>전체 소감 요약</h3><h4>re:Invent 2025 in Las Vegas, “이 정도면 뽕 뽑았다..!”</h4><ul><li>지인짜~ 잠 줄여가면서 열심히 세션 꽉꽉 채워듣고, 열심히 놀았습니다. 기대보다 훨씬 더 좋은 경험이었습니다.</li></ul><h4>뭐가 제일 좋았어? 뭐가 다른데? “전세계라는 규모 그 자체”</h4><ul><li>re:Invent에서 가장 인상 깊었던 건, 전 세계의 개발자들을 직접 만나고 같은 고민을 나눌 수 있었다는 점이었어요. 또 수천 명이 함께하는 키노트 세션이 특히 인상적이었고 행사 전체가 하나의 축제처럼 느껴졌습니다.</li></ul><h4>직접 일정짜서 가는 건 어땠어? “직접 일정을 구성한 게 더 많은 걸 볼 수 있는 계기가 되었습니다!”</h4><ul><li>일정을 짜기 위해서 세션을 탐색 했던 덕에, 행사 당일 발생하는 변수에 맞춰 유동적으로 다양한 세션을 들을 수 있었습니다! 장소와 시간에 따라 이벤트가 다양하기 때문에 어느 정도의 유연성을 갖추어 준비하는 게 좋습니다!</li></ul><h4>누군가 가는 걸 고민 한다면? “무조건 가라!”</h4><ul><li>가기 전에는 “컨퍼런스가 다 비슷하겠지”라고 생각했는데, 직접 가보니 완전히 달랐습니다. 행사에 참여하다보니 영어를 더 잘했다면 훨씬 더 즐길 수 있었을 것 같다는 아쉬움도 들었습니다. 그래도 비슷한 고민을 가진 사람들이 어떻게 문제를 해결했는 지를 직접 보고 들을 수 있었던, 정말 좋은 경험이었습니다.</li></ul><h4>목차 및 요약</h4><blockquote>Keynote</blockquote><ul><li>Opening Keynote, 위치선정 미쳤다!</li><li>한국기업이 AWS Keynote 발표를?</li></ul><blockquote>AWS 행사 후기</blockquote><ul><li>Expo는 기업 설명회이자 네트워킹 자리!</li><li>Sports Forum: 앉아만 있지말고 움직여..!</li><li>rePlay: 순수한 개발자들의 애프터 파티</li></ul><blockquote>세션 후기</blockquote><ul><li>reInvent 에서만 들을 수 있는 강의에 집중하세요! “Chalk Talk &amp; Workshop”</li><li>조금 부끄럽더라도 세션을 기다리면서 네트워킹을 해야하는 거 같아요!</li></ul><blockquote>탐방도 잊지 마세요</blockquote><ul><li>그랜드 캐년: 정말 미쳤다. 무조건 경비행기로 가세요..!</li><li>스피어 공연: 외관이 더 나을 수도 있어요..! 가격대비 만족감은 좀..</li><li>MnM &amp; 코카콜라</li></ul><blockquote>그 외 꿀 팁</blockquote><ul><li>호텔(컨퍼런스)관련 꿀팁</li><li>셀프 호텔 투어 / 호텔 식사 / 벨라지오 호텔 분수</li><li>물가 / 인앤아웃 &amp; 치폴레 / 면세점 주류 vs 현지 리쿼샵</li></ul><blockquote>끝으로..</blockquote><blockquote>Keynote</blockquote><h4>Opening Keynote 위치선정 미쳤다!</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Vx7mQi1OxhfjGN_zdsTsyg.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*LehKMejhBSCqTBztPIXgXQ.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*9l1vCpzH2TMndwj6mBsPRQ.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*FoHfHgzFbPHALOHu5jZz5Q.png" /></figure><p>사실 Keynote는 유튜브에 공개되기 때문에 거기서만 경험해볼 수 있는 건 아닙니다. 그런데 현장감은 다릅니다! 콘서트홀 같은 공간에 수천명의 개발자가 모여서 즐기는 강연을 들으니, 마치 개발자들의 축제현장같이 느껴지기도 합니다! 연설 전에는 DJ가 노래를 틀어주기도 하구요! 세션 중간중간 다같이 환호하기도 합니다! 운이 좋게도 앞좌석을 선점할 수 있었는데요! 콘서트 앞자리 마냥 더욱 현장감을 느낄 수 있어서 좋았습니다!</p><h4>한국기업이 AWS Keynote 발표를?</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*E-404Btij31_ZzclpEIm2A.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JqHpdqNipghEP97JjshMJQ.png" /></figure><p>Keynote가 특별하게 느껴졌던 이유 중 하나는 한국기업이 발표하는 모습을 볼 수 있었기 때문이 아닐까 싶습니다.</p><p>Twelvelabs가 Multi-modal 모델인 Merengo, Pegasus를 Keynote 세션에서 발표하였고, 관련 내용을 전세계 개발자 앞에서 공유하는 모습을 볼 수 있었는데요! Multi-modal에 관심이 많은 저희 Spoonlabs로써 같이 응원하게 되더라구요! AI 기술력을 가진 한국기업 모두 화이팅입니다!</p><blockquote>AWS 행사 후기</blockquote><h4>1. Expo는 기업 설명회이자 네트워킹 자리!</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*2f0zqVnQ0QNas9tlqIu-Gg.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*YTg_BNggrzfIIPIyRTwyng.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ewNIV3GUbngUAvXtM8AvUA.png" /><figcaption>AWS reInvent Expo</figcaption></figure><p>Expo도 꼭 경험해야하는 공간이었습니다.!</p><p>Antropic(Claude), Attlasian 등 이미 회사에서 사용하고 있는 기업들이 현재 보유하고 있는 기술과 몰랐던 서비스들에 대해서 들을 수 있고, 평소 궁금했던 부분들을 질문해 볼 수 있었습니다!</p><p>새로운 기업을 알기에도 좋은 곳입니다. 저는 Antropic 바로 옆에 있던 Resolve AI란 회사를 새로이 알게 되었는데요! 이 기업의 경우 <strong>클라우드 인프라 운영을 자동화하겠다</strong>는 목적을 가진 회사였고, 기술력에 대한 자부심도 대단했습니다! 빗버킷 안되는거 같은데? 라고 질문하니 “우리한테 컨택해 2주 안에 해결해줄게” 하는 에너제틱한 모습도 정말 인상깊었습니다! 한번 눈여겨볼 기업들을 탐방해볼 수 있는 기회가 되지 않을까 싶습니다.!</p><h4>2. Sports Forum: 앉아만 있지말고 움직여..!</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*h_AUNCxL7iapTbtKiXe4Kg.png" /></figure><p>중간중간 너무 세션만 듣지 말라고 Sports Forum 공간도 꾸며져 있었는데요! 탁구대도 있었고, F1차량 바퀴를 수리해보거나, 실제 F1게임을 해보는 곳, VR을 통해서 농구해보는 곳, 실제 농구 골대에 공을 던지는 액티비티 활동도 있었습니다! 다양한 운동활동도 즐겨보시면 좋을 거 같습니다!</p><h4>3. rePlay: 순수한 개발자들의 애프터 파티</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*b60H4q_5_rFpTxPpog-bxw.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*wITTuNuTxKX5uBXNwoZN9A.jpeg" /><figcaption>rePlay 현장사진</figcaption></figure><p>모든 세션이 마무리되고 목요일 저녁에 열리는 rePlay(애프터 파티)에 참석했습니다! 장소는 베네시안에서 차량기준 약 10분 정도 떨어진 곳에서 하구요! 셔틀을 운영합니다! 내리자마자 신나는 노래와 분위기가 모두를 신나게 만들었습니다! 장소에서는 대형 단체 배구에 그네타기, 미끄럼틀 타기, 동물 화면과 달리기 대결 등 동심으로 돌아갈 수 있는 게임들이 여기저기 있었습니다! 다양한 먹거리와 체험거리도 많으니, 편하게 즐겨보시는 걸 추천드립니다!</p><blockquote>세션 후기</blockquote><h4>reInvent 에서만 들을 수 있는 강의에 집중하세요! “Chalk Talk &amp; Workshop”</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*RIsuCvE4_cEnNlWQzAbZ0A.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*IfqckV__AIW8YVhAmwWg9w.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4FG2R2szWi-yCaac06Ym2A.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Gq5yGztPSV5YoVsBerVoHw.png" /><figcaption>Chalk Talk &amp; Workshop 현장 분위기</figcaption></figure><p>저는 이번 컨퍼런스에서 총 11개의 세션을 들었습니다! 그 중에서 실제로 도움이 되는 세션들은 뭐였냐? <strong>토론 중심으로 세션인 Chalk Talk</strong>와 <strong>실습을 진행하는 Workshop</strong> 이었습니다.! 실무 개발자분들이 발표하고 실습 강연을 하기 때문에 더욱 심도 있게 물어볼 수 있는 시간이 주어집니다! 실제 고민을 해결하고 싶으신 분들께 추천드립니다!</p><p>영어를 잘 못하더라도 괜찮습니다! 제가 질문하지 않더라도, 전세계 개발자들이 자신들이 가지고 있는 문제들을 해결하기 위해서 적극적으로 질문하고 해결방법을 찾아갑니다! 그것만 귓동냥으로 듣더라도 정말 도움이 많이 되더라구요! <br>전세계에서 모이다보니, 내가 하던 고민을 똑같이 고민하는 케이스를 꽤나 볼 수 있었습니다! 같은 고민을 이야기하고 해결방법을 나눠본다는 것이 인상깊은 경험 중 하나였습니다!</p><h4>조금 부끄럽더라도 세션을 기다리면서 네트워킹을 해야하는 거 같아요!</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*YTg_BNggrzfIIPIyRTwyng.png" /></figure><p>저도 낯을 가리는 편이라 네트워킹을 어려워하는 편인데요! 세션을 기다리다가 만나게 된 인연이 있었습니다! 샌프란시스코에서 헬스케어 회사에서 클라우드 아키텍처를 담당하던 분이었는데, 같이 있던 Spoonlabs SRE팀 Daniel과 같이 이야기하는 모습을 볼 수 있었습니다.</p><p>내가 겪고 있는 문제가 이건데, 그 문제를 너는 어떻게 해결하고 있냐, 나는 이렇게 해결해보고 있다 등 평소에 들을 수 없었던 이야기들을 나눌 수 있더라구요!! 저는 옆에서 듣기만 했지만 그런 경험들이 매우 중요하다고 느꼈습니다. 저게 방법이 될 수 있겠다. 해결책을 위한 토론과정이 더 나은 결과물을 만들 수 있을텐데, 나는 지금 그게 약하구나 라는 셀프피드백 과정도 거칠 수 있었습니다!</p><blockquote>탐방도 잊지 마세요</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*F_58b81rD5IynBoS-7QOuw.jpeg" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*oBy1OSoKyKgOjcHVCatwxw.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vV-I1PO0vZhUAOAFeZcM-g.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*X1SeYnH2Ick8yOlmsVcsAA.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*qdgzTKbmSqBLuj931kUcBw.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*VhTaGV0AmprrX5rhJiEA9Q.png" /></figure><h4>1. 그랜드 캐년: 정말 미쳤다. 무조건 경비행기로 가세요..!</h4><p>가장 기억에 남는 활동 중 하나가 아닐까 싶습니다! 그랜드 캐년 풍경은 말할것도 없습니다! 컴퓨터 그래픽이라고 해도 믿을 정도로 그 규모가 말도 안되더라구요!</p><p>또 그것만큼 신기했던 경험은 경비행기 였습니다! 처음탈 때 덜컹덜컹하는게 무서우면서도 재밌더라구요! 경비행기를 타고 그랜드 캐년으로 향하면서 보는 밖 풍경도 너무 좋았습니다!</p><h4>2. 스피어 공연: 외관이 더 나을 수도 있어요..! 가격대비 만족감은 아쉽네요..</h4><p>스피어도 나름 좋았어요! 라스베가스 도착하면서 차타고 다니다보면 쉽게 마주할 수 있는데, 외관이 동글동글하니 정말 귀엽습니다! 저는 오즈의마법사 쇼를 봤는데요! 처음에 16K 화면에 놀라는데, 이후에는 일반 상영과 크게 다를게 없어 조금 아쉬웠달까요? 한번쯤은 경험할만하다! 정도인거 같습니다!</p><h4>3. MnM &amp; 코카콜라</h4><p>역시 라스베가스 기념품으로는 MnM과 코카콜라죠! 기대하시는 딱 그 모습입니다! 관련 굿즈 정말 많구요! 지인분들 선물 사가기에 정말 괜찮습니다! 추가적으로 개인적으로 기념품 사시려면 바로 인근에 ABC Store도 꽤나 괜찮은 기념품이 많으니 같이 둘러보시길 바랍니다!</p><blockquote>그 외 꿀팁</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Xtcb-hZuqrPsJj_01zayLg.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*CY6uTOmur5UqfpAe97Yl5Q.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ob-SfK7UniPCfEqSGvNzKg.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*wfQYi1ww3IFc0snHI_J2wg.png" /></figure><h4>1. 호텔(컨퍼런스)관련 꿀팁</h4><ul><li>컨퍼런스 <strong>호텔마다 아침/점심 메뉴와 메뉴 퀄리티가 다른거</strong> 아시나요?! 입에 맞는 호텔 찾으셔서 즐겨보시는 것도 소소한 재미가 됩니다! 개인적으로는 시저스 포럼(Caesars Forum) 호텔이 가장 괜찮았습니다!</li><li><strong>벨라지오 호텔 분수</strong>는 지나가면서 꼭 보세요! 30분에 한번씩 하기 때문에, 걸어다니시면 언제고 한번씩 보실 수 있을 겁니다!</li><li><strong>호텔 투어</strong>도 잊지마세요! 라스베가스는 호텔투어 많이 하시더라구요! 저희는 벨라지오 호텔 로비 -&gt; 베네시안 실내 운하 → AWS re:Play에 참석하는 코스를 밟았는데, 알차게 구경할 수 있었습니다!</li></ul><h4>2. 물가 미쳤다.. 미국 햄버거 세트가 40$</h4><ul><li>정말 최소로 먹어도 30$씩 해서 정말 부담스러웠습다.. 최대한 호텔식사와 네트워킹 자리 저녁을 활용해서 횟수를 줄였던거 같아요! <strong>컨퍼런스 행사장에 가시면 조식, 중식, 간식, 커피 모두 공짜</strong>이기 때문에 거기서 드시면서 버티시는 것을 추천드립니다!</li></ul><h4>3. 인앤아웃 &amp; 치폴레: 평소 가던 음식점들의 원조집을 먹어봤다..! 그리고 그 외 맛집 탐방..ㅎ</h4><ul><li>제가 평소에 크라이치즈버거와 쿠차라를 가곤 했는데요! 아니 글쎄 이 두 집이 각각 인앤아웃과 치폴레를 벤치마킹한 음식점이라는 걸 듣고 깜짝 놀랐습니다! 왜냐면 제가 먹다가 “여기 크라이치즈버거/쿠차라 랑 비슷한데요?” 하니깐 주변에서 알려주시더라구요! 뭔가 더 반가웠달까요? 어떻게 다른지 먹고 비교해보시는 것도 좋을 거 같습니다!</li></ul><h4>4. 라스베가스, LA 모두 면세점 주류가 훨씬 비싸니깐 현지 리쿼샵에서 사세요 제발..!</h4><ul><li>저는 돌아가는 길에 면세점에서 주류를 구매하려했는데, 국내 가격보다 비싸더군요..ㅠ 개인시간 활용하셔서 리쿼샵 방문하시면 훨씬 저렴한 가격에 만날 수 있다고 하니, 공항 면세점 보다는 현지 리쿼샵을 추천드립니다!</li></ul><blockquote>끝으로..</blockquote><p>Spoonlabs는 미디어 IT 회사입니다! 오디오 스트리밍 서비스인 스푼라디오와 숏폼드라마 플랫폼인 비글루를 운영중입니다!</p><p>예상하시는 바와 같이 회사 내에서 Multi-modal에 대한 니즈는 점점 더 커지고 있습니다. 조금은 한계점이 있는 상황에서 관련한 식견을 넓힐 기회를 주신 회사에 감사드리며, 앞서 경험한 경험들과 세션들에서 얻은 정보들이 회사에 녹아들 수 있도록 만들어보겠습니다!</p><p>관련하여 세션들에서 얻은 인사이트들도 한차례 올려보도록 하겠습니다!</p><p>긴 글 읽어주셔서 감사합니다!!</p><blockquote>P.S. 박 모씨..</blockquote><p>가끔 행사장을 돌아다니시다가 경제언론사 등에 인터뷰를 하게 되는 영광?을 누리실 수도 있습니다ㅋㅋㅋ</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/283/1*9pb6VvsxJqanpixsUuXQsg.png" /><figcaption>박모씨의 등장</figcaption></figure><ul><li><a href="https://www.mk.co.kr/news/it/11482001">https://www.mk.co.kr/news/it/11482001</a></li><li><a href="https://www.fnnews.com/news/202512020926549863">https://www.fnnews.com/news/202512020926549863</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d8da6519f153" width="1" height="1" alt=""><hr><p><a href="https://medium.com/spoontech/aws-reinvent-2025-%EC%9D%B4%EB%A0%87%EA%B2%8C%EA%B9%8C%EC%A7%80-%EB%BD%95%EC%9D%84-%EB%BD%91%EC%9D%84-%EC%A4%84%EC%9D%80-d8da6519f153">AWS reInvent 2025, 이렇게까지 뽕을 뽑을 줄은…</a> was originally published in <a href="https://medium.com/spoontech">SpoonLabs</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[2025 AWS re:Invent — Amazone Bedrock AgentCore]]></title>
            <link>https://medium.com/spoontech/2025-aws-re-invent-amazone-bedrock-agentcore-18e2fdaa7f50?source=rss----bb1e592ad19a---4</link>
            <guid isPermaLink="false">https://medium.com/p/18e2fdaa7f50</guid>
            <category><![CDATA[amazon-bedrock]]></category>
            <category><![CDATA[tech]]></category>
            <category><![CDATA[spoonlabs]]></category>
            <category><![CDATA[reinvent]]></category>
            <category><![CDATA[aws]]></category>
            <dc:creator><![CDATA[Youbin]]></dc:creator>
            <pubDate>Fri, 09 Jan 2026 09:56:55 GMT</pubDate>
            <atom:updated>2026-01-09T09:56:37.651Z</atom:updated>
            <content:encoded><![CDATA[<h3>2025 AWS re:Invent — Amazone Bedrock AgentCore</h3><p>안녕하세요. SpoonLabs Service Platform Team 에서 서버 개발을 담당하고 있는 Sophia(신유빈)입니다.</p><p>SpoonLabs는 구성원의 자기계발과 다양한 경험을 통해 성장할 수 있도록 국내외 주요 컨퍼런스 및 세미나 참여를 적극적으로 지원하고 있습니다. 덕분에 저는 올해 꿈꿔왔던 AWS re:Invent에 다녀오게 되었습니다!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HO_aLhR2Kr-JFQYp-lfmow.jpeg" /><figcaption>AWS re:Invent 에 가다!</figcaption></figure><p>이전에 다녀오신 동료분들로 부터 행사 규모에 대해 전해 들었지만 실제로 마주한 스케일은 상상 그 이상이었습니다. AWS re:Invent 행사 기간 동안 느낀 점과 인상 깊었던 기술에 대한 인사이트를 공유하고자 합니다.</p><h3>AWS re:Invent 란?</h3><p>AWS re:Invent는 단순한 컨퍼런스가 아닌 아마존 웹 서비스가 매년 미국 라스베가스에서 개최하는 세계 최대 규모의 클라우드 기술 흐름을 이끄는 큰 행사입니다. 올해 6만명이 넘는 전 세계 개발자와 기술 리더들이 모입니다. Keynote 부터 다양한 세션, Expo, re:Play, 액티비티(스포츠 포럼, 세션 가는 사이사이 즐길 수 있는 다양한 활동들)들이 많이 준비되어 있었습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*e_L5TJL2tjPT6ibcih5WFg.jpeg" /><figcaption>AWS 세션, 엑스포, 스포츠 세럼 등</figcaption></figure><h3>KeyNote with CEO Matt Garman</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*DYbXPWkrNaBRTZqpDwBSaQ.jpeg" /><figcaption>AWS re:Invent KeyNote</figcaption></figure><p>AWS re:Invent 의 둘째 날, 가장 기대했던 CEO KeyNote 세션이 있었습니다. KeyNote 의 현장감을 느끼기 위해 아침 일찍부터 메인 행사장으로 향했습니다. 일찍 갔음에도 이미 많은 사람들로 놀랐지만 함께 간 SRE 팀의 Daniel 이 빠르게 자리를 찾아주셔서 덕분에 무대와 가까운 명당자리에서 KeyNote를 들을 수 있었습니다. (Daniel, 다시 한번 감사합니다!🙌)</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*SSv0SU_FuJSeJ76qejwjVQ.jpeg" /><figcaption>KeyNote 오프닝! 너무 잘보인다~</figcaption></figure><p>올해 KeyNote 핵심 키워드도 AI였습니다. 작년보다 훨씬 더 구체적이고 선도적인 AI 관련 또는 접목된 서비스들이 소개되었습니다. AI 학습에 최적화되고 비용 효율적인 새로 출시된 AI 칩(Trainium 4)에 대한 소개부터 고성능 서버(나노미터 AI 칩을 탑채한 Amazon EC2 Trn3 UltraServers 랙)의 모습까지 직접 보면서 기술 설명을 들었습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/620/1*HTEWq1wVMooK0TZr7q2TJQ.png" /><figcaption>EC2 접속할 때마다 하드웨어는 상상속에만 있었는데 AWS 최첨단 하드웨어의 모습!</figcaption></figure><p>무엇보다 기술 소개 마다 서두에 던져진 메세지인 “Why Not?” (왜 안되겠어?) 이 인상깊었습니다. 상상하는 것이 있다면 주저 말고 실행하라는 그 단순하면서도 강력한 물음이 현재의 AWS를 있게 한 것이 아닌가 싶었습니다. 혁신적인 기술은 이러한 도전적인 마인드셋에서 시작된다는 것을 느끼며 저 또한 개발자로서 스스로에게 끊임없이 ‘Why Not?’이라는 질문을 던져 보아야겠다 다짐했습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*L23bB6zB5iR4k_ZwGew4Zg.png" /><figcaption>WHY NOT? 왜 안되겠어?</figcaption></figure><h3>Bedrock의 전례 없는 성장세</h3><p>KeyNote 에서 기억에 남는 것은 Amazon Bedrock의 폭발적인 성장이었습니다. 현재 SpoonLabs 서비스에서도 Bedrock을 활발히 활용하고 있기에, 작년 출시된 이후 Bedrock이 얼마나 많은 기업과 서비스의 핵심 요소로 자리 잡았는지 직접 확인할 수 있었습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Uf0ZIqzhl3zNhNWIPkOZXA.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*H1WKCd2aUECGL7eGssv60w.png" /><figcaption>Amazon Bedrock 사용 고객사들</figcaption></figure><p>현장에서 발표된 데이터에 따르면, Bedrock 사용 고객사는 작년보다 무려 2배 이상 늘어났다고 합니다. 전 세계 모든 산업 분야와 규모의 기업들이 사용중입니다. 특히 세계에서 가장 규모가 큰 AI 애플리케이션 상당 수가 Bedrock을 기반으로 실행되고 있으며, 1조 개 이상의 토큰을 처리하는 고객사만 50곳이 넘는다고 설명했습니다.</p><p>그렇다면 이후에 소개된 Amazon Bedrock AgentCore 에 대해 살펴보겠습니다.</p><blockquote>💡 여기서 잠깐! Bedrock과 AgentCore에 대해 잠깐 쉽게 짚고 넘어가겠습니다.</blockquote><blockquote>- Amazon Bedrock : AI 모델들의 백화점으로 이해하면 쉽습니다. 복잡한 설치 과정 없이 Amazon, Anthropic, Mistral 등 다양한 회사에서 만든 강력한 인공지능 모델(LLM)들을 서비스에서 쉽게 가져다 쓸 수 있도록 해주는 AWS의 핵심 AI 플랫폼입니다.</blockquote><blockquote>- Bedrock AgentCore: Bedrock 모델들을 활용해 ‘실제 업무를 수행하는 똑똑한 비서(AI 에이전트)’를 구축하고 운영할 수 있게 돕는 기능입니다. 단순한 대화를 넘어, 필요한 정보를 스스로 탐색하거나 시스템에 직접 명령을 내리는 등 복잡한 작업을 스스로 수행합니다.</blockquote><h3>Amazon Bedrock AgentCore</h3><p>가장 진보된 에이전트 플랫폼 제공하여 개발자가 AI 에이전트를 안전하고 확장 가능하게 구축, 배포 및 운영하도록 지원합니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*5MK63SGMFBw4b7LsPLb5Ig.png" /><figcaption>Amazone Bedrock AgentCore</figcaption></figure><p>AgentCore가 제공하는 핵심 기능과 특징은 다음과 같습니다.</p><h3>특징</h3><ul><li>Runtime : 격리된 세션 환경에서 에이전트가 안전하게 실행될 수 있도록 런타임을 제공합니다.</li><li>Memory : 에이전트가 문맥을 파악하는 데 필요한 단기 기억과 장기 기억을 관리합니다.</li><li>Gateway : 에이전트가 도구, 데이터 및 다른 에이전트까지 쉽게 검색하고 안전하게 연결할 수 있도록 제공합니다.</li><li>Identity : 안전한 인증 제공합니다.</li><li>Observability : 배포된 에이전트 워크플로우에 대한 실시간 가시성을 제공합니다.</li><li>Code Interpreter : 안전한 코드 실행 환경에 접근할 수 있도록 해줍니다.</li><li>Managed Browser : 에이전트가 인터넷에 쉽게 접근할 수 있도록 관리형 브라우저 서비스를 지원합니다.</li></ul><p>AgentCore 는 에이전트 구축을 위한 기능을 제공한다는 점에서 AWS만의 차별화된 제품입니다. 개방적이고 모듈식으로 설계되어 Bedrock에 포함된 다양한 모델이나 OpenAi 모델과 함께 사용 가능합니다.</p><h3>Policy in AgentCore: 더 안전하고 정교한 에이전트 제어</h3><blockquote>“에이전트 행동에 대한 통제권 확보”</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*neP6bJTxOZPIrABfAl1vcg.png" /><figcaption>Policy in AgentCore</figcaption></figure><p>에이전트가 자율적으로 업무를 수행할 때 가장 우려되는 부분은 보안과 통제권일 것입니다. 이번에 새롭게 소개된 AgentCore의 Policy는 에이전트가 도구 및 데이터와 상호작용하는 방식을 실시간으로 제어할 수 있는 강력한 보안 계층을 제공합니다.</p><h3>주요 특징</h3><ul><li>API, Lambda, MCP 서버 또는 타사 서비스 등 어떤 도구에 액세스할 수 있는지 지정할 수 있습니다. 어떤 행동을 수행할 수 있는지, 어떤 조건에서 수행할 수 있는지 정의 가능합니다.</li><li>에이전트가 도구나 데이터에 대한 액세스 권한을 받기 전에 모든 에이전트 작업을 이 정책에 따라 실시간으로 평가합니다.</li><li>세분화된 권한이 포함된 정책을 사용하여 AgentCore 게이트웨이 도구 호출이 실행되기 전에 가로채어 에이전트 작업에 대한 명확한 경계를 정의합니다.</li><li>복잡한 코드가 아닌 자연어를 사용해 정책을 작성할 수 있어, 누구나 간편하게 세밀하고 고도화된 보안 정책을 생성할 수 있다는 점이 큰 장점입니다.</li></ul><p>“어떤 조건에서 어떤 행동을 허용할 것인가”에 대한 명확한 기준을 제시함으로써, 개발자가 안심하고 에이전트에게 복잡한 업무를 위임할 수 있는 환경을 만들어 줍니다.</p><p>즉, 에이전트가 액세스할 수 있는 도구와 액세스 방식을 정의하는 정책을 설정할 수 있습니다.</p><h3>AgentCore Evaluations : AI 품질을 수치화하다</h3><blockquote>“AI 품질 관리 자동화”</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*9eagT3KglJxrTjXc-Glnjg.png" /><figcaption>AgentCore Evaluations</figcaption></figure><p>일반적인 소프트웨어와 달리, 에이전트가 올바른 판단을 내리고 있는지, 혹은 적절한 도구를 사용해 업무를 처리하고 있는지 실시간으로 측정하기가 매우 어렵기 때문입니다.</p><p>Agent 는 테스트 단계에서도 확인이 어려워 실제 어떻게 반응하고 대응하는지 운영에서 경험해봐야 압니다. 결국 지속적인 모니터링을 통해 예상치 못한 행동을 빠르게 발견하고 대응하는 것이 품질 관리의 핵심인데 AgentCore Evaluations는 이러한 고민을 해결하기 위해 등장한 AI 품질 관리 자동화 서비스입니다.</p><h3>특징</h3><ul><li>개발자가 실제 사용자 데이터를 바탕으로 에이전트의 성능을 상시 점검할 수 있도록 지원합니다.</li><li>정확성이나 유용성 등의 기준에 대한 내장 평가 도구와 서비스의 특성에 맞춘 사용자 지정 평가를 사용하여 실제 사용자 행동을 기반으로 agent 품질을 모니터링합니다.</li><li>평가 결과는 Amazon CloudWatch에 시각화되어 한곳에서 제공됩니다. 또한 평가 점수에 대한 알림 및 경보를 설정하여 에이전트 품질을 사전에 모니터링하고 지표가 허용 가능한 임계값을 벗어날 경우 대응할 수 있습니다.</li></ul><h3>Kiro Autonomous Agent : 가상 개발자 팀원</h3><p>KeyNote 뿐 아니라 들었던 세션([<em>Generative AI, agents, MCP, and the future of AI-powered software development</em>])에서도 등장한 Kiro Autonomous Agent는 개발의 패러다임이 완전히 변화하고 있음을 실감하게 해주었습니다.</p><p>이른바 ‘바이브 코딩(Vibe Coding)’이라 불리는 스펙 기반 개발의 실현이었습니다. Kiro는 단순한 코드 어시스턴트를 넘어 다음과 같은 역할을 수행하는 가상 팀원이었습니다.</p><ul><li>자율적인 문제 해결: 복잡한 작업이 할당되어도 전체 컨텍스트를 유지하며 스스로 작업을 완수합니다.</li><li>개발 전주기 자동화: 신규 기능 구현부터 버그 픽스까지, 개발 과정의 반복적인 작업들을 대신 처리합니다.</li><li>핵심 가치에 집중: 엔지니어가 번거로운 구현 작업에서 벗어나, 서비스의 핵심 아이디어와 아키텍처 설계에만 몰두할 수 있는 환경을 제공합니다.</li></ul><p>결국 AI는 이제 단순한 ‘모델 호출’의 단계를 지나, 스스로 판단하고 실행하며 운영까지 자동화하는 단계에 접어들었습니다. Kiro와 같은 자율형 에이전트가 현업에 도입된다면 개발 생산성을 획기적으로 높이는 것은 물론 전체 개발 주기를 약 20~30% 이상 절감할 수 있을 것으로 예상했습니다.</p><h3>AWS re:Invent 세션 참여 꿀팁</h3><ul><li><strong>AWS 앱 필수!<br></strong>예약하거나 좋아요한 세션을 캘린더로 확인할 수 있어서 스케줄 체크하기 좋습니다. 행사 중간중간 새로운 신규 트랙 세션이 추가되는 경우도 있으니 자주 볼수록 좋은 정보를 얻을 수 있습니다!</li><li><strong>예약에 실패했어도 포기하지 마세요 (Walk-up)</strong><br>인기 세션은 금방 마감되지만 현장에서 줄을 서서 대기하는 ‘Walk-up’ 라인이 별도로 있으니 세션 시작 전 조금 일찍 도착하면 들을 수 있습니다.</li><li><strong>호텔 간 이동 시간은 넉넉하게</strong><br>라스베이거스의 여러 호텔에서 세션이 나누어 진행되다 보니 셔틀버스를 타고 이동해야 하는 경우가 많습니다. 지도를 보면 가까워 보여도 물리적인 거리가 꽤 되기 때문에, 호텔 간 셔틀버스로 이동이 필요하다면 최소 30분 이상의 여유를 두는 것이 좋습니다. 예약을 했더라도 제시간에 도착하지 못하면 자리가 보장되지 않으니 세션을 선택할 때 장소 간의 동선도 꼭 고려해 보세요!</li><li><strong>리모트(Remote) 세션 적극 활용</strong><br>듣고 싶은 세션이 너무 멀리서 열린다면 현재 위치한 호텔이나 근처 호텔에서 리모트로 시청할 수 있는 세션이 있는지 확인해 보세요. 동일한 이름의 세션이 동시에 중계되는 경우도 있습니다.</li></ul><h3>마치며</h3><p>이번 AWS re:Invent는 개발자로서뿐 아니라 개인적으로도 한 단계 성장할 수 있었던 정말 감사한 시간이었습니다. “정말 세상에 개발자가 많구나!”라는 것을 새삼 실감할 수 있었고 잠자는 시간을 아껴서라도 모든 것을 경험하고 싶었던 만큼 알찬 일주일을 보낸 것 같습니다.</p><h4>잊지 못할 순수한 축제 re:Play</h4><p>거의 마지막 날 밤에 진행되는 re:Play 에 호기심에 가봤는데 거대한 스케일의 축제장이었습니다. 화려한 조명과 분위기랑 음악에 신이 나면서도 그속에서 달리기, 배구, 스케이팅 등 순수함이 느껴지는 뒷풀이었습니다. 함께 간 SRE 팀 Daniel, DT 팀 Jin과 어른이가 되고는 해보기 어려운 폭신폭신한 장애물 달리는 정말 잊지 못할 즐거운 추억이 되었습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*DEP4f5JGwRe2-TQX6gKtTw.jpeg" /><figcaption>AWS re:play</figcaption></figure><h4>아쉬움이 남긴 새로운 동기부여</h4><p>물론 아쉬움도 남습니다. 나름대로 스픽을 하고 갔지만 실제로 귀도 잘안열리고 입도 잘 안떨어졌습니다. 현장에서 외국 개발자들과 네트워킹을 하지 못한 점은 아쉽습니다. 그리고 키노트와 세션 모두 영어 자막으로 제공되기 때문에 ‘귀를 더 확실히 뚫어야겠다’ 다짐을 하게 되었습니다.</p><p>하지만 세션 도중 “레거시 시스템 때문에 고민인 분 계신가요?”라는 질문에 국적 불문하고 수많은 개발자가 우르르 손을 드는 모습을 보며 “모두 비슷한 고민을 하며 나아가고 있구나”라는 묘한 유대감과 위안을 얻기도 했습니다.</p><h4>SpoonLabs의 미래를 꿈꾸며</h4><p>변화에 빠르게 대응하고 적응하는 회사인 SpoonLabs 답게 스푼 라디오(Spoon)와 비글루(Vigloo) 서비스가 더욱더 성장하고 대박났으면 좋겠습니다. 머지않은 미래에 AWS re:Invent 키노트 무대 위, ‘서비스 활용 기업’ 목록에 SpoonLabs 브랜드 로고가 올라가는 그날을 상상해 봅니다.</p><p>화이팅!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XZx4zom9YSE2Tqw7rXZ3JA.jpeg" /><figcaption>AWS 칠판에 SpoonLabs 딱!!!!</figcaption></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=18e2fdaa7f50" width="1" height="1" alt=""><hr><p><a href="https://medium.com/spoontech/2025-aws-re-invent-amazone-bedrock-agentcore-18e2fdaa7f50">2025 AWS re:Invent — Amazone Bedrock AgentCore</a> was originally published in <a href="https://medium.com/spoontech">SpoonLabs</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AI로 만드는 사용자 중심 테스트 파이프라인 — 비글루 앱인토스 개발 기록]]></title>
            <link>https://medium.com/spoontech/ai%EB%A1%9C-%EB%A7%8C%EB%93%9C%EB%8A%94-%EC%82%AC%EC%9A%A9%EC%9E%90-%EC%A4%91%EC%8B%AC-%ED%85%8C%EC%8A%A4%ED%8A%B8-%ED%8C%8C%EC%9D%B4%ED%94%84%EB%9D%BC%EC%9D%B8-%EB%B9%84%EA%B8%80%EB%A3%A8-%EC%95%B1%EC%9D%B8%ED%86%A0%EC%8A%A4-%EA%B0%9C%EB%B0%9C-%EA%B8%B0%EB%A1%9D-64733da93a4c?source=rss----bb1e592ad19a---4</link>
            <guid isPermaLink="false">https://medium.com/p/64733da93a4c</guid>
            <category><![CDATA[testing]]></category>
            <category><![CDATA[tech]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Seoyong Lee]]></dc:creator>
            <pubDate>Tue, 28 Oct 2025 09:26:53 GMT</pubDate>
            <atom:updated>2025-10-28T14:42:25.354Z</atom:updated>
            <content:encoded><![CDATA[<h3>AI로 만드는 사용자 중심 테스트 파이프라인 — 비글루 앱인토스 개발 기록</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Isn7HovCgBQcFhTDLNuEyQ.jpeg" /><figcaption>Photo by <a href="https://unsplash.com/ko/@muriel_1">Muriel Liu</a><strong> </strong>on <a href="https://unsplash.com/">Unsplash</a></figcaption></figure><p>안녕하세요. 스푼랩스 개발자 Drew입니다. 이번 글에서는 앱인토스 입점을 위한 미니 서비스 개발 과정에서 AI를 활용해 테스트 파이프라인을 구성했던 경험을 공유하고자 합니다.</p><h3>새롭게 시작된 프로젝트</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XJWft6t6du-8bbrUYXH2Dg.png" /><figcaption><a href="https://toss.im/tossfeed/article/outsight-appsintoss">앱인토스 관련 토스 공식 블로그</a></figcaption></figure><p>올 초 금융 슈퍼앱 토스가 미니앱을 준비 중이라는 소식이 들려왔습니다. 미니앱은 기존 앱 안에 외부 서비스가 입점하는 구조로, 토스의 대규모 트래픽을 바탕으로 신규 서비스를 실험할 수 있는 상생 생태계입니다. 숏폼 드라마 서비스 비글루도 국내 사용자 확보에 도움이 될 것으로 판단해 빠르게 입점을 결정했습니다.</p><p>그러나 앱인토스 입점을 위해서는 토스 SDK를 사용해 웹 서비스를 처음부터 새로 개발해야 했습니다. 이를 계기로 기존 기능을 사용자 중심으로 재검토하기로 했습니다.</p><p>기존 웹 서비스는 로그인, 시청, 결제 등 핵심 기능을 빠르게 추가하며 확장해 왔습니다. 그러나 규모가 커질수록 다음과 같은 한계가 드러났습니다.</p><ul><li>신규 기능 개발 시 정상 동작 여부 확인에만 집중한 테스트가 진행되었습니다.</li><li>개발과는 별도로 매번 테스트 케이스를 작성해야 해서 팀의 부담이 커졌습니다.</li><li>기능별 효과 검증이 어려워 유지·제거에 대한 의사결정이 쉽지 않았습니다.</li><li>사용자 만족과 이탈의 원인을 정확히 파악하기 어려웠습니다.</li></ul><p>기획·디자인·개발을 차례로 진행했지만, 릴리스 전까지는 실제 사용 행태를 가늠하기 어려웠고 서비스 전반을 관통하는 핵심 기준이 필요하다고 느꼈습니다. 고민 끝에 개발 전 과정을 하나로 묶을 축을 ‘사용자’로 삼기로 했습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/981/1*piZbMjDgq_kST2QcIFsjmw.png" /></figure><h3>사용자 입장에서 생각해보기</h3><p>무엇을 만드는 사람들은 너무 깊이 몰입하다 보면 자칫 생산자 관점으로 생각하기 쉬워지는 것 같습니다. 주로 겪는 패턴은 다음과 같습니다.</p><blockquote><em>기능을 만듭니다 → 사용자가 안 씁니다 → 왜 안쓰는지 물어봅니다 <br></em>(생산자 중심 접근)</blockquote><p>일단 만들고, 왜 안 쓰는지 물어보는 수수께끼 같은 과정이 반복됩니다. 관점을 바꿔서 이 모든 과정이 사용자에서부터 출발했다면 어땠을까요?</p><blockquote><em>사용자의 문제를 찾습니다 → 문제를 해결하기 위한 기능을 만듭니다 → 문제를 실제로 해결하는지 확인합니다 <br></em>(Problem-Solution Fit)</blockquote><p>”사용자의 어떤 문제를 해결하려고 만드는가?” 라는 질문에서 출발하면 결과물은 명확해집니다. 이러한 방식은 이후의 성공 여부를 객관적으로 판단할 기준도 함께 제공합니다.</p><p>사용자 중심으로 사고하면 테스트를 포함한 전반적인 업무 방식도 자연스럽게 달라집니다.</p><ul><li>테스트는 단순한 기능 검증을 넘어, 사용자에게 필요한 가치가 제공되는지 확인하는 과정으로 발전합니다.</li><li>사용자 관점에서 인수 기준(AC, Acceptance Criteria)을 정리하면, 쉽게 실행 가능한 테스트 케이스로 확장할 수 있습니다.</li><li>기능별 목표 지표가 명확히 관리되며, 이를 토대로 개선 방향을 체계적으로 도출할 수 있습니다.</li><li>궁극적으로는 사용자 관점에서 만족 요인과 이탈 요인을 더 정확하게 파악할 수 있습니다.</li></ul><h3>AI가 주는 실행력</h3><p>그렇다면 사용자의 가치를 팀이 공유할 수 있는 공통 언어로 표현하는 최선의 방법은 무엇일까요? 우리는 이를 <strong>User Story</strong> 형태로 정리하기로 했습니다.</p><p>User Story는 애자일 조직에서 사용자 관점의 요구사항을 간결하게 표현하는 방식으로, 예시와 같이 <strong>“누가–무엇을–왜”</strong> 구조를 따릅니다.</p><blockquote><strong><em>[신규유저]</em></strong><em>로서 </em><strong><em>[가입 장벽을 낮춰 빠르게 시작하기]</em></strong><em> 위해 </em><strong><em>[토스 로그인을 이용해 가입/로그인]</em></strong><em>하고자 한다.</em></blockquote><p>이를 활용하면 다음과 같은 장점이 있습니다.</p><ul><li><strong>가치 정렬·우선순위화</strong>: 모든 스토리를 동일한 기준에서 비교할 수 있습니다.</li><li><strong>측정 가능성 내장</strong>: KPI와 연결해 곧바로 실험 설계로 확장됩니다.</li><li><strong>테스트 자동화 친화적</strong>: 인수 기준(AC, Acceptance Criteria)으로 확장해 테스트 케이스와 연결됩니다.</li><li><strong>커뮤니케이션 효율</strong>: PM, 디자이너, 개발자가 동일한 포맷으로 협업합니다.</li></ul><p>처음부터 User Story를 기반으로 개발했더라면 더 좋았겠지만, 이미 구현된 기능을 재정리하는 것만으로도 이해와 개선에 큰 도움이 되었습니다.</p><p>다만 현실은 간단하지 않았습니다. 가장 큰 장벽은 기획을 문서로 정리하는 데 드는 시간이었습니다. 이러한 작업이 정규 기능 개발과 동등한 중요도로 인정받기 어려워, 자연스레 User Story 도입의 우선순위가 낮아지고 번번이 미뤄졌습니다.</p><p>이때 주목한 것이 <strong>AI</strong>였습니다. 이미 코드 작성에는 Cursor 등 AI 도구를 적극 활용하고 있었기에, User Story도 초안을 AI로 생성하면 효율적일 것이라 판단했습니다. User Story는 형식이 정해져 있으므로, 자연어 기획을 구조화된 산출물로 변환하는 작업에서 AI가 강점을 보일 것이라 예상했습니다.</p><blockquote>“문서화가 병목이라면, AI로 User Story·AC·테스트 초안을 자동화해 도입 비용을 낮추자.”</blockquote><h3>진행 과정</h3><p>먼저 필요한 과정을 사람과 AI의 역할로 구분해 파이프라인으로 정리했습니다.</p><p>🙍🏻: 사람의 개입이 필요한 과정 / 🤖: AI 활용 비중이 높은 과정</p><ol><li><strong>🙍🏻 사용자 정의 (🙍🏻 90% / 🤖 10%)<br>- </strong>KPI·시장 맥락은 사람 고유영역 AI는 정리 보조.</li><li><strong>🤖 기능 분석 및 단위 분할 (🤖 70% / 🙍🏻 30%)<br>- </strong>Epic / Feature / Story 추출은 AI가 수행, 최종 구조는 사람이 확정</li><li><strong>🙍🏻 User Story 작성 (🙍🏻 80% / 🤖 20%)<br>- </strong>가치·KPI·범위 결정은 사람이 담당, AI는 문장 다듬기.</li><li><strong>🤖 User Story 하위 AC 작성 (🤖 60% / 🙍🏻 40%)<br>- </strong>1차 생성은 AI, 확인 및 Edge 보강은 사람.</li><li><strong>🤖 AC 기반 테스트 생성 (🤖 80% / 🙍🏻 20%)<br>- </strong>테스트 코드 및 시트 생성 자동화는 AI 주도.</li><li><strong>🙍🏻 구현 검증 (🙍🏻 80% / 🤖 20%)<br>- </strong>AI는 리포트 요약, 최종 가치 전달 판단은 사람.</li></ol><h3>1. 🙍🏻 사용자 정의</h3><p>첫 번째 단계로 기능을 사용하는 사용자를 다음과 같이 구분했습니다.</p><ul><li>신규유저: 가입 후 7일 이내의 사용자로 시청 기록 및 결제 이력이 없는 사용자</li><li>무료유저: 시청 기록이 1건 이상 있지만 결제 이력이 없는 사용자</li><li>결제유저: 90일 이내에 결제 이력이 있는 사용자</li><li>헤비유저: 30일 이내에 10일 이상 시청했거나, 결제 이력이 2건 이상인 사용자</li></ul><p>사용자는 핵심 KPI인 ‘결제’를 기준으로 구분했습니다. 이렇게 정의한 페르소나는 테스트 과정에서 특정 기능을 점검할 때 ‘사용자의 기본 조건’으로 다시 활용됩니다.</p><h3>2. 🤖 기능 분석 및 단위 분할</h3><p>다음 단계에서는 AI를 이용해 전체 기능을 파악하고 단위별로 구분하는 작업을 진행했습니다. 신규 기능 개발의 경우 정해진 요구사항을 바탕으로 구체화할 수 있지만, 이미 만들어진 기능을 이관해야 하는 상황에서는 다른 접근이 필요했습니다. 이를 위해 기존 Figma 디자인 시안을 ChatGPT에 입력하고, 특정 프롬프트를 적용하여 기능을 기준에 따라 구분해 보았습니다.</p><pre># Figma 기반 기능 추출 prompt<br><br>[목표]<br>Figma 시안을 근거로 Epic과 User Story 단위의 Feature를 식별한다.<br>세부 컨트롤(버튼/토글/속성)은 하나의 상위 행동으로 묶는다. 근거(UI 단서)와 신뢰도를 함께 제시한다.<br><br>[입력]<br>- 시안: {이미지 또는 Figma 링크/페이지/프레임}<br>- 맥락(선택): {도메인/타깃/플랫폼}<br>- 제외(선택): {브랜딩/타이포/카피 등 비기능}<br><br>[정의 &amp; 범위]<br>- Epic: 인증/검색/홈/결제/플레이어/라이브러리 등 상위 도메인.<br>- Feature(=User Story 레벨): 사용자가 “의미 있는 목표”를 달성하는 단위.<br>  - 예) “검색 결과를 필터링하고 탐색한다”, “재생 설정을 조정한다”<br>  - 비예) “자막 토글”, “화질 버튼” (→ ‘재생 설정’으로 묶기)<br><br>[식별/병합 규칙]<br>- 3~7개 Feature/Epic으로 제한(너무 세분화 금지).<br>- 같은 목표에 기여하는 컨트롤은 하나로 통합.<br>- 화면 패턴/라벨/아이콘 등 ‘UI 단서’가 없으면 생성 금지.<br><br>[네이밍]<br>- Epic: UpperCamelCase (예: Search, Authentication)<br>- Feature 이름: 동사+명사, User Story 톤 (예: “Manage Recent Searches”)<br><br>[산출물]<br>1) Epic 목록(요약)<br>   - 각 Epic: 1문장 설명<br>2) Feature 테이블(간단)<br>   | Epic | Feature 이름 | UI 단서(최대 3) | 신뢰도(0.0~1.0) |<br>   - UI 단서: 버튼/아이콘/라벨/프레임명 등 핵심 근거만 요약</pre><p>위 과정을 통해 다음과 같은 결과물을 도출했습니다.</p><pre># 1) Epic 목록(요약)<br><br>* **Authentication** — 소셜 로그인과 동의 화면으로 초반 진입을 처리.<br>* **Home** — 홈 피드에서 섹션 캐러셀/카드로 프로그램을 탐색.<br>* **Search** — 검색 입력·최근검색·필터링으로 콘텐츠를 찾는다.<br>* **ProgramDetail** — 작품 정보 확인 후 에피소드를 선택해 시청으로 이어간다.<br>* **Playback** — 세로 피드 재생 중 핵심 컨트롤과 재생 설정을 조정한다.<br>* **Monetization** — 페이월에서 멤버십/코인 구매로 잠금을 해제한다.<br>* **Library** — 좋아요/기록/다운로드를 한 곳에서 관리한다.<br>* **Settings** — 앱 정보/가이드와 일반 설정을 확인·수정한다.<br><br># 2) Feature 테이블(간단)<br><br>| Epic           | Feature 이름                    | UI 단서(최대 3)                     | 신뢰도  |<br>| -------------- | ----------------------------- | ---------------------------------- | ---- |<br>| Authentication | Sign in with Social Account   | Apple/Google 버튼, 로고, “시작하기” CTA | 0.95 |<br>| Authentication | Accept Terms &amp; Permissions    | 약관 안내 화면, 체크/CTA, 단계형 구성      | 0.82 |<br>| Home           | Browse Home Rails             | 가로 캐러셀, 섹션 타이틀, 썸네일 카드       | 0.91 |<br>| Home           | Open Program from Card        | 카드 탭, 카드 타이틀/메타, 상세로 연결      | 0.90 |<br>| Home           | Use Top Entry (Hero/Shortcut) | 상단 히어로/퀵영역, 메인 CTA             | 0.72 |<br>| Search         | Manage Recent Searches        | 검색 입력창, 최근 검색 뱃지, ‘전체삭제’      | 0.92 |<br>| Search         | Filter &amp; Explore Results      | 필터 칩/토글, 결과 그리드/리스트, 정렬 라벨   | 0.84 |<br>| Search         | Open Result Detail            | 결과 카드 탭, 상세 화면 전환               | 0.90 |<br><br># ... 중략</pre><p>결과물에는 각 기능별 신뢰도를 표시하도록 했으며, 신뢰도가 낮은 기능을 중심으로 실제 Feature 존재 여부를 검증하는 과정을 거쳤습니다. 물론 AI가 처음부터 완벽하게 작성해 주지는 않았지만, 처음부터 직접 정리하는 것보다 훨씬 빠르게 전체 기능을 Epic / Feature 단위로 구조화할 수 있었습니다.</p><h3>3. 🙍🏻 User Story 작성</h3><p>앞선 결과를 바탕으로 각 Feature의 세부 User Story 생성을 진행했습니다.</p><p>정확도를 높이기 위해 Epic·Feature 산출물과 Figma 시안 이미지를 함께 입력하는 등 여러 방법을 시도했고, 가능한 많은 정보를 제공해 재작업의 가능성을 줄이려 노력했습니다.</p><pre># prommpt<br><br>[목표]<br>주어진 Figma 시안 기반 Feature 테이블만을 근거로, 각 Feature에서 User Story를 최대한 많이(중복 없이) 생성한다.<br>스토리는 버튼/속성 수준으로 쪼개지지 않으며, ‘의미 있는 목표’ 단위로 묶는다.<br><br>[입력]<br>- Epic/Feature 테이블: | Epic | Feature 이름 | UI 단서(최대 3) | 신뢰도 |<br>- (선택) 우선 Epic/Feature: {예: Playback, Search}<br>- (선택) 최소 신뢰도: {예: 0.70}<br>- (선택) max_per_feature: {기본 6}<br><br>[출력 형식]<br>- Epic/Feature별로 그룹핑하여 아래 형식만 사용:<br>  - [페르소나]로서 [가치]를 얻기 위해 [목표]를 하고자 한다.<br>  - (선택) UI 단서: {라벨/아이콘/프레임명 최대 3개}<br>  - (선택) 신뢰도: {0.0~1.0}<br>- 한국어로만 작성. 한 줄당 한 스토리. 불릿 사용.</pre><p>다음은 이렇게 생성된 결과물입니다.</p><pre>## Home / Open Program from Car<br><br>* \[탐색중유저]로서 결정 피로를 줄이기 위해 카드 메타 정보를 보고 상세로 진입하고자 한다.<br>  * UI 단서: {카드 탭, 카드 타이틀/메타, 상세로 연결}<br>  * 신뢰도: 0.90<br><br>* \[재방문유저]로서 이어보기 편의를 위해 최근 본 프로그램 카드를 눌러 상세로 이동하고자 한다.<br>  * UI 단서: {카드 탭, 카드 타이틀/메타}<br>  * 신뢰도: 0.90<br><br>* \[탐색중유저]로서 오판을 줄이기 위해 썸네일과 타이틀 일치 여부를 확인하고 상세로 들어가고자 한다.<br>  * UI 단서: {카드 타이틀/메타, 상세로 연결}<br>  * 신뢰도: 0.90<br><br>## Playback / Show Next-Episode Prompt<br><br>* \[시청자]로서 시청 지속을 위해 엔드카드의 “다음” CTA/카운트다운으로 자동 이어보기를 하고자 한다.<br>  * UI 단서: {엔드카드, “다음” CTA/카운트다운}<br>  * 신뢰도: 0.72<br><br>* \[시청자]로서 휴식을 위해 카운트다운을 취소하고 현재 영상에 머물고자 한다.<br>  * UI 단서: {엔드카드, “다음” CTA}<br>  * 신뢰도: 0.72<br><br>* \[재방문유저]로서 회차 스킵을 방지하기 위해 다음으로 가기 전 요약을 확인하고자 한다.<br>  * UI 단서: {엔드카드, “다음” CTA}<br>  * 신뢰도: 0.72<br><br># ... 중략</pre><p>검토 결과, 첫 번째 User Story는 비교적 신뢰도는 높았지만 제공 가치 표현이 ‘편의를 위해’, ‘오판을 줄이기 위해’처럼 모호했습니다. 두 번째 User Story는 아예 존재하지 않는 기능을 추론한 환각(hallucination) 사례로 드물지만 종종 발생했습니다.</p><p>이를 개선하기 위해 대표적인 사용자 가치 10가지를 설정했고, 해당 가치에 기반해 스토리를 생성하도록 프롬프트를 수정했습니다. 동시에 작성 원칙과 절차도 함께 보완했습니다.</p><pre># User Story 생성 프롬프트<br><br>[목표]<br>주어진 **Figma 시안 기반 Feature 테이블**만을 근거로, 각 Feature에서 **중복 없이** ‘의미 있는 목표’ 단위의 User Story를 최대화한다. **UI 단서로 증명 가능한 흐름만** 생성한다.<br><br>[입력]<br>* Epic/Feature 테이블: `| Epic | Feature 이름 | UI 단서(최대 3) | 신뢰도 |`<br>* (선택) 우선 Epic/Feature: `{예: Playback, Search}`<br>* (선택) 최소 신뢰도: `{예: 0.70}`<br>* (선택) `max_per_feature` (기본 6)<br><br>[핵심 원칙]<br>1. **증거 우선(Required Evidence)**: 각 스토리는 테이블의 **UI 단서**가 가리키는 **행동/화면 전환/상태**가 **명시적으로** 있을 때만 생성한다.<br>   * 최소 조건: **단서 ≥1 + 그 단서로 유도되는 구체 행동 1개**.<br>   * 단서가 행동을 지시하지 않으면 **생성 금지** 또는 “(검토 필요)”로 표시.<br>2. **가치 단어 금지/제한**: 모호한 가치 표현은 사용 금지. 아래 **가치 사전** 중 **하나만** 선택해 대괄호에 그대로 사용한다(동의어/창작 금지).<br>3. **굵기 유지**: 버튼/토글 등 원자 단위로 쪼개지지 말고 **의미 있는 목표**로 묶는다(예: “재생 설정(자막/속도/화질) 조정”).<br>4. **탐색·행동·회복·대안 경로 다양성**: 각 Feature마다 이 관점들을 **최소 3개, 최대 `max_per_feature`**까지 고르게 다룬다.<br>5. **중복 금지**: `(가치 + 목표)` 조합이 동일하면 1개만 남기고, 변형은 괄호로 보조.<br>6. **신뢰도 필터**: 입력 테이블의 신뢰도가 최소값 미만이면 **생성하지 않음**(또는 맨 끝에 “(검토 필요)” 표시).<br>7. **창작 금지(No-creation Policy)**: 테이블/단서에 없는 기능(예: 자동 로그인, 자동 요약, 추천 학습 등) 추정 금지. **UI가 곧 근거**다.<br><br>[가치 사전(고정 목록, 정확히 이 표기만 사용)]<br>* **재탐색 비용 절감**<br>* **시청 지속/이탈 방지**<br>* **개인화/제어감**<br>* **발견 가능성 향상**<br>* **결제 마찰 감소**<br>* **신뢰/안심**<br>* **데이터/시간 절약**<br>* **오류/빈 상태 회복**<br>* **접근성/포용성 향상**<br><br>[출력 형식]<br>* Epic/Feature별 그룹핑. 한 줄당 한 스토리. 한국어. 불릿 사용.<br>## {Epic} / {Feature 이름}<br>- [페르소나]로서 [가치]를 얻기 위해 [목표]를 하고자 한다.<br>  - UI 단서: {단서1, 단서2, 단서3}<br>  - 신뢰도: 0.XX<br><br>[생성 절차]<br>1. **필터링**: (선택) 우선 Epic/Feature와 최소 신뢰도로 테이블을 거른다.<br>2. **행동 검증**: 각 Feature의 UI 단서가 유도하는 **구체 행동**을 1개 이상 식별한다(매핑 가이드 활용). 행동이 불가하면 **생성 금지/검토 필요**.<br>3. **스토리 설계**: 탐색/행동/회복/대안 경로 관점에서 후보를 만들되, 각 후보마다 **가치 사전에서 1개**를 정확히 매핑.<br>4. **굵기 조정**: 세부 컨트롤은 상위 목적(예: “재생 설정 조정”)으로 통합.<br>5. **중복 제거**: `(가치+목표)` 기준으로 중복 제거.<br>6. **형식화**: 출력 형식에 맞춰 UI 단서(최대 3)와 신뢰도(입력값)를 기입.<br>7. **검수**: 아래 체크리스트를 통과하지 못하면 해당 라인 삭제.</pre><p>원하는 결과물이 나올 때까지 프롬프트 수정과 재생성을 반복했고, 이 중 신뢰도가 높은 결과물을 선별해 다시 표 형태로 정리했습니다. 이렇게 구조화하니 중요 KPI 기준으로 바로 정렬·분석할 수 있어 훨씬 효율적이었습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*NzqF-WUS0IktSsybetTTQA.png" /></figure><h3>4. 🤖 User Story 하위 AC 작성</h3><p>다음 단계에서는 각 User Story에 대한 세부 정의를 작성했습니다. 아래는 그중 검색 기능에 대한 상세 문서 예시입니다.</p><pre># Epic: 검색<br><br>## Feature: 추천 태그<br><br>### SRCH-002<br><br>**User Story**  <br>[신규유저]로서 [컨텐츠 선택을 돕기] 위해 [추천 태그를 이용]하고자 한다.<br><br>## Acceptance Criteria<br>- [ ] 검색 페이지 추천 태그 영역에 5개의 추천 검색어가 표시된다.<br>- [ ] 추천 태그는 페이지 새로고침 시 변경된다.<br>- [ ] 추천 태그를 클릭하면 검색어로 입력되고 검색 결과가 표시된다.<br>- [ ] 추천 태그를 클릭하면 최근 검색 좌측에 태그가 추가된다.</pre><p>위 Story의 세부 동작을 Acceptance Criteria(AC, 인수 조건)로 다시 정리했고, 이제 구현과 테스트가 가능한 수준까지 정의가 완료되었습니다. AC는 Gherkin 문법에 맞춰 작성했습니다. Gherkin은 BDD(Behavior-Driven Development)에서 쓰는 사람이 읽기 쉬운 테스트 서술 언어로, 도메인 용어로 시나리오를 표현하면서도 자동 테스트로 바로 연결되도록 설계되어 있습니다.</p><ul><li>Feature: 기능(문제/가치) 단위의 설명</li><li>Background: 모든 시나리오에 공통인 전제 조건</li><li>Scenario: 하나의 행동과 결과를 검증하는 최소 단위</li><li>Given / When / Then: 전제 / 행동 / 기대 결과 (관찰 가능한 결과만 작성)</li><li>Tags(@ui, @refresh): 실행/분류용 라벨</li></ul><pre>Feature: Recommend Tag (SRCH-002)<br>  사용자는 추천 태그를 통해 빠르게 검색을 시작할 수 있다.<br><br>  Background:<br>    Given 나는 검색 페이지에 있다<br><br>  @suggestions @ui<br>  Scenario: 추천 태그 5개가 표시된다<br>    When 추천 태그 영역이 로드된다<br>    Then 추천 태그가 정확히 5개 표시된다<br><br>  @suggestions @refresh<br>  Scenario: 페이지 새로고침 시 추천 태그가 변경된다<br>    Given 현재 추천 태그 목록을 A로 기록한다<br>    When 페이지를 새로고침한다<br>    Then 새로운 추천 태그 목록을 B로 기록한다<br>    And A와 B는 동일하지 않아야 한다<br><br>  @suggestions @search<br>  Scenario: 추천 태그 클릭 시 입력 및 결과 표시<br>    Given 추천 태그 목록에 &quot;로맨스&quot;가 있다<br>    When 추천 태그 &quot;로맨스&quot;를 클릭한다<br>    Then 검색 입력창에 &quot;로맨스&quot;가 입력된다<br>    And &quot;로맨스&quot;에 대한 검색 결과가 표시된다<br><br>  @suggestions @recent<br>  Scenario: 추천 태그 클릭 시 최근 검색 좌측에 추가<br>    Given 추천 태그 목록에 &quot;액션&quot;이 있다<br>    And 최근 검색 섹션이 비어 있거나 존재한다<br>    When 추천 태그 &quot;액션&quot;을 클릭한다<br>    Then 최근 검색 섹션의 가장 왼쪽에 &quot;액션&quot; 뱃지가 추가된다</pre><p>이렇게 작성된 Gherkin 기반 AC는 그대로 테스트 소스가 되어, 요구–구현–검증을 한 줄로 연결해 줍니다.</p><h3>5. 🤖 AC 기반 테스트 생성</h3><p>AI로 생성한 결과물을 활용해서 최종적으로 테스트 작성을 진행하였습니다. AC는 그 자체로 이미 요구사항을 명확하게 표현하고 있어 이를 테스트 케이스로 변환하는 것은 크게 어렵지 않았습니다.</p><h4>Unit Test (React + Jest) 생성 자동화</h4><p>클라이언트 유닛 테스트의 경우 AC를 테스트의 단일 소스로 설정하고, AI에게 테스트 스켈레톤을 생성하게 했습니다. 각 AC를 <em>Given-When-Then</em>으로 분해하고 이를 AAA(Arrange-Act-Assert)에 1:1 매핑하는 방식으로 작성하였습니다.</p><pre>[목표] 아래 AC를 Jest+RTL 단위 테스트로 변환. AAA(Arrange-Act-Assert) 주석 포함.<br><br>[제약]<br>- user-event 사용<br>- 셀렉터는 getByTestId 우선<br>- API 호출은 msw로 스텁(필요 시)<br>- 테스트명은 &quot;&lt;AC ID&gt;: &lt;요약&gt;&quot; 형식 <br>...</pre><p>아래 예시는 SRCH-001의 두 가지 AC를 그대로 변환한 것입니다. 첫 테스트는 Enter 입력 시 최근 검색어가 좌측부터 추가되는지, 두 번째는 15자 이상이면 말줄임표(…) 처리가 되는지를 검증합니다.</p><pre>// __tests__/search.unit.spec.tsx<br>// SRCH-001-AddByEnter: 최근 검색어가 좌측부터 추가된다<br>import { render, screen } from &#39;@testing-library/react&#39;<br>import user from &#39;@testing-library/user-event&#39;<br>import { SearchPage } from &#39;@/features/search/SearchPage&#39;<br><br>describe(&#39;Search - Recent Searches&#39;, () =&gt; {<br>  test(&#39;SRCH-001-AddByEnter: 입력 후 Enter 시 좌측부터 추가&#39;, async () =&gt; {<br>    // Arrange<br>    render(&lt;SearchPage /&gt;)<br>    const input = screen.getByTestId(&#39;search-input&#39;)<br><br>    // Act<br>    await user.type(input, &#39;drama{enter}&#39;)<br><br>    // Assert<br>    const badges = screen.getAllByTestId(&#39;recent-badge&#39;)<br>    expect(badges[0]).toHaveTextContent(&#39;drama&#39;)<br>  })<br><br>  test(&#39;SRCH-001-TrimLongText: 15자 이상이면 … 처리&#39;, async () =&gt; {<br>    // Arrange<br>    render(&lt;SearchPage /&gt;)<br>    const input = screen.getByTestId(&#39;search-input&#39;)<br><br>    // Act<br>    await user.type(input, &#39;superlongkeywordhere{enter}&#39;)<br><br>    // Assert<br>    const first = screen.getAllByTestId(&#39;recent-badge&#39;)[0]<br>    expect(first.textContent).toMatch(/…$/) // ellipsis 적용<br>  })<br>})</pre><h4>통합 테스트 시트 생성 자동화</h4><p>다음으로 기능 단위의 흐름(여러 컴포넌트/서비스 연동)을 검증하기 위해, AC를 하나로 모아 표준 포맷의 통합 테스트 시트로 생성하였습니다. AC 형태가 이미 잘 정리되어 있어 어렵지 않게 시트로 변환할 수 있었습니다.</p><pre># AC → 테스트 시트 변환 프롬프트 (TSV / Markdown)<br><br>&gt; **목적:** AC 입력을 받아 **탭 구분(TSV)** 테스트 시트 행으로 변환한다.<br>&gt; **출력은 반드시 헤더 1줄 + 데이터 행들만** 포함한다(설명 문장 금지).<br><br>## 헤더(정확히 이 순서/표기)<br><br>```tsv<br>TC ID Epic Feature Story 전제(Precondition) 시나리오(요약) 기대 결과(Expected)<br>```<br><br>## 규칙<br><br>1. **한 AC = 최소 1행.** 분기/값 예시(Examples)가 있으면 **예시별로 별도 행**을 만든다.<br>2. **TC ID**: `{Story}-{두자리번호}` (예: `MY-001-01`, `MY-001-02` …). 스토리마다 **01부터** 시작.<br>3. **전제(Precondition)**: 실행 전 상태/데이터를 **간결**히 요약(로그인, 페이지 진입 가능, 서버 값 등).<br>4. **시나리오(요약)**: **단계까지 통합한 한 문장**으로, 비개발자도 읽고 바로 실행 가능하게 작성(불필요한 반복 금지).<br>5. **기대 결과(Expected)**: **관찰 가능한 단정형 한 줄**(예: “타이틀 노출, 뒤로가기 정상 복귀”).<br>6. **금지 사항**: 단계/증빙/우선순위/상태 등 **추가 컬럼 금지**, 설명 문장 출력 금지.<br>7. **언어**: 한국어.<br>8. **형식 강제**: 모든 셀은 **탭 문자로만** 구분, 줄 끝 공백 없음.<br><br>## 입력 형식<br><br>```<br>Acceptance Criteria:<br>- [ ] {AC1}<br>- [ ] {AC2}<br>- ...<br>```<br><br>## 출력 형식<br><br>* **첫 줄 = 헤더 1줄**, 이후 **데이터 행들만** TSV로 출력.</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/787/1*3iSA8_A3CO1itLxPuVucrg.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/360/1*Zu84epvp57TJ9wqPcpYvIg@2x.jpeg" /></figure><h4>시트 기반 Appsheet 테스터 앱 개발</h4><p>마지막으로 시트로 정리한 내용을 AppSheet(노코드 앱 빌더)로 감싸 앱을 만드는 과정까지 시도해 보았습니다. AppSheet는 Google Sheets를 데이터 원천으로 삼고, 뷰·폼·액션·자동화를 클릭 몇 번으로 구성할 수 있어, 코드 없이도 실행 가능한 QA 워크플로우를 만들도록 도와줍니다. QA가 끝나면 이에 대한 데이터를 시각화 하여 보고서로 보여주도록 구성할수도 있습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/986/1*_FGITfns_yC97DmG4zPFHA.png" /></figure><p>이를 통해 결과적으로 “스프레드시트 편집 및 수동 공유”의 번거로움이 사라지고, 누구나 동일한 폼으로 일관되게 테스트를 기록할 수 있게 되었습니다.</p><h3>추가 활용 가능성</h3><p>정리된 User Story와 AC는 미래에 다음과 같이 활용될 가능성이 있습니다.</p><ul><li><strong>AC 기반 TDD</strong> — 작성한 AC를 바로 테스트로 변환하고 개발을 진행하면 사후 테스트 작성 부담을 줄일 수 있습니다.</li><li><strong>Cursor AI 개발 맥락 전달</strong> — AC·이벤트 스키마 등을 컨텍스트로 주입해 조금 더 정확하고 목적 지향적인 코드 제안을 받을 수 있습니다.</li><li><strong>AC 기반 디자인 자동화</strong> — AC를 기반으로 Figma AI 등을 이용해 와이어프레임을 생성하면 디자인–개발 싱크를 유지하면서 빠르게 기능을 구체화 할 수 있습니다.</li><li><strong>AC 기반 릴리즈 노트 자동화</strong> — AC ID를 연결해 변경/추가 기능에 대한 릴리즈 노트를 자동으로 작성할 수 있습니다.</li></ul><h3>마무리</h3><p>지금까지 AI를 활용한 서비스 개발 과정에 대해 공유드려 보았습니다. 이번 시도를 통해 단순히 기능을 만드는 단계를 넘어서 사용자에게 어떤 가치를 전달할지 더욱 선명하게 바라보는 시간을 가질 수 있었습니다.</p><p>AI는 이제 단순히 결과물을 빠르게 만들어내는 도구를 넘어, 생각을 정리하고 아이디어를 날카롭게 다듬어주는 든든한 파트너가 될 수 있음을 확인했습니다. 그러나 AI가 진정한 힘을 발휘하려면, 사람의 맥락과 경험이 더해지는 과정이 반드시 필요합니다.</p><p>각 팀의 상황에 맞게 AI와 협업하는 방식을 탐구해 갈수록, 더 정교하고 의미 있는 결과물을 만들어갈 수 있을 것으로 기대합니다.</p><p>감사합니다.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=64733da93a4c" width="1" height="1" alt=""><hr><p><a href="https://medium.com/spoontech/ai%EB%A1%9C-%EB%A7%8C%EB%93%9C%EB%8A%94-%EC%82%AC%EC%9A%A9%EC%9E%90-%EC%A4%91%EC%8B%AC-%ED%85%8C%EC%8A%A4%ED%8A%B8-%ED%8C%8C%EC%9D%B4%ED%94%84%EB%9D%BC%EC%9D%B8-%EB%B9%84%EA%B8%80%EB%A3%A8-%EC%95%B1%EC%9D%B8%ED%86%A0%EC%8A%A4-%EA%B0%9C%EB%B0%9C-%EA%B8%B0%EB%A1%9D-64733da93a4c">AI로 만드는 사용자 중심 테스트 파이프라인 — 비글루 앱인토스 개발 기록</a> was originally published in <a href="https://medium.com/spoontech">SpoonLabs</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[RAG 도입기 — 챗봇을 만들다, 조용히 그리고 낭만적으로…]]></title>
            <link>https://medium.com/spoontech/rag-%EB%8F%84%EC%9E%85%EA%B8%B0-%EC%B1%97%EB%B4%87%EC%9D%84-%EB%A7%8C%EB%93%A4%EB%8B%A4-%EC%A1%B0%EC%9A%A9%ED%9E%88-%EA%B7%B8%EB%A6%AC%EA%B3%A0-%EB%82%AD%EB%A7%8C%EC%A0%81%EC%9C%BC%EB%A1%9C-e96841c87979?source=rss----bb1e592ad19a---4</link>
            <guid isPermaLink="false">https://medium.com/p/e96841c87979</guid>
            <category><![CDATA[rags]]></category>
            <category><![CDATA[spoonlabs]]></category>
            <category><![CDATA[spoonradio]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[tech]]></category>
            <dc:creator><![CDATA[임용근]]></dc:creator>
            <pubDate>Wed, 07 May 2025 09:57:38 GMT</pubDate>
            <atom:updated>2025-05-07T09:57:38.395Z</atom:updated>
            <content:encoded><![CDATA[<h3>RAG 도입기 — 챗봇을 만들다, 조용히 그리고 낭만적으로…</h3><p>안녕하세요.</p><p>스푼랩스 Business Platform Team의 임용근(Whale 🐳)입니다.</p><p>요즘 캠핑하기 너무 좋은 날씨입니다.</p><p>가끔 혼자 캠핑가서 쉬다 오는데요, <br>이날도 교외로 나가 한적한 캠핑장에서 맥주 한캔과 함께 노트북 두드리며 이 글을 쓰고 있습니다.</p><p>조금 낭만적이기도 하고요. 😎</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*91jEVzdUw0wZ51IcvLrIdw.jpeg" /><figcaption>버즈의 민경훈이 운영하는 “집밖으로” 캠핑장 — 2박3일 푹 쉬다 왔습니다. ✌️</figcaption></figure><p>지난 포스트 이후 어느덧 반년이 흘렀네요.</p><p>그동안 정말 바쁘게, 정신없이 보낸 것 같습니다.</p><ul><li>AI 관련 세미나 참석 (MS 세미나)</li><li>AWS AI 세미나 참석</li><li>사내 세미나 발표 진행</li><li>그리고 오늘 소개드릴, <strong>RAG 기반 챗봇 개발</strong></li></ul><p>이전 글에서는 다음과 같은 고민을 남겼었죠.</p><ul><li>RAG 아키텍처를 어떻게 구성하지?</li><li>검색 대상은 어떤 데이터를 써야 할까?</li><li>품질은 어떻게 끌어올릴까?</li><li>고급 구성은 언제 시도해볼까?</li><li>Slack 같은 외부 시스템과 연동해볼 수 있을까?</li></ul><p>질문 하나하나에 부딪히고, 하나씩 답을 찾으면서 만든 게 이번 포스트의 주제이자 결과물입니다.</p><p>이제는 실제 서비스로 동작하는 RAG 기반 챗봇이 만들어졌습니다. 물론 아직은 조금 서툰 “아기봇”이지만요. 👶</p><p>이번 포스트에서는 “FAQ 기반의 ChatBot을 어떻게 Spring AI + AWS로 구현했는가”에 대한 과정을 6단계로 나눠서 정리합니다.</p><p>구조 자체는 특이하거나 멋진 구조는 아니지만, 실무에서 바로 써먹을 수 있는 구성으로 굉장히 심플하고 실용적이라고 생각합니다.</p><p>LangChain, LangGraph가 대세인 요즘이지만, 저희가 사용한 기술 스택은 다음과 같습니다</p><ul><li>Kotlin / SpringBoot</li><li>Spring AI</li><li>AWS OpenSearch</li><li>AWS Bedrock (Claude Sonnet 3.5 v2)</li></ul><p>RAG라는 기술을 접하면서, (무리하게😅) 세가지를 준비했으나!!</p><p>세가지 모두 이 포스트에서 다루기에는 양이 너무 방대하여, 나누어 진행하도록 하겠습니다.</p><ul><li>(오늘주제) ChatBot — FAQ (자주하는 질문) 질의 요약</li><li>WIKI(Confluence)</li><li>Text To SQL</li></ul><p>사실 순서로 보면 WIKI 부터 하였으나, 사내 서비스에 적용할 정도로 품질을 올리는게 쉽지 않더라구요.</p><p>혼자 해결할 수 있는 부분은 어느정도 해두었으나, 전사적으로 규칙을 정할 필요가 있어, 서두르지 않고 천천히 진행하고 있습니다.</p><p>또한, 매출 통계 / 추이 / 분석으로 Text To SQL(TTS)도 함께 진행예정입니다.</p><p>지난 반년동안 진행해오면서 TTS에 대한 정보도 접하고 있는데요. 방향을 살짝 틀어야 할것같아, 제 TODO LIST에 고이 모셔두었습니다.</p><h3>ChatBot</h3><p>챗봇이라는 단어, 요즘은 너무 흔하죠.</p><p>병원 예약부터 쇼핑몰까지 어디에나 있는 기능이 되었습니다.</p><p>솔직히 1년 전만해도 저도 안일하게 생각했던 것 같습니다.</p><blockquote><strong>카테고리별로 정해진 답변만 하면 되는 거 아냐? <br>생각보다 단순하겠는데?</strong></blockquote><p>하지만 직접 만들고 보니 생각이 완전히 달라졌습니다.</p><p>모든 챗봇이 그렇지는 않겠지만, LLM과 결합한 챗봇은 <strong>단순한 정답형 QA(Question/Answer) 그 이상</strong>이더라고요.</p><ul><li>검색된 문서 조각을 문맥에 맞게 합치고,</li><li>관련도를 평가해서 필터링하고,</li><li>정밀하게 설계한 Prompt를 기반으로</li><li>LLM이 최종 응답을 생성하는 일련의 과정.</li></ul><p>이걸 직접 다뤄보지 않으면 결코 알 수 없었던 구조와 복잡성이 있었습니다.</p><p>RAG는 검색 기반 QA나 문서 요약 같은 기능을 만들 때 거의 필수에 가깝습니다.</p><p>그리고 챗봇은 그 흐름을 <strong>가장 자연스럽게 구현하고 실험해볼 수 있는 좋은 주제</strong>였습니다.</p><p>크게 새로울 건 없지만, 실전 연습용으로는 완벽한 예제로서, 검색부터 응답 생성까지, RAG의 전 단계를 모두 거치는 구조였기에 정말 많은 시행착오가 있었고, 그 과정을 이 글에 담아보려고 합니다.</p><h3>RAG 아키텍처, 어떻게 설계했을까?</h3><p>이번 글에서는 스푼랩스에서 진행한 챗봇 프로젝트, 일명 <strong>스푼봇</strong>의 전체적인 네트워크 구성을 소개하려고 합니다.</p><p>구조 자체는 실제보다 조금 단순화했지만, 전체 흐름을 이해하는데엔 무리가 없도록 재구성했습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*7vi8sWST6VkA2pQH" /><figcaption>CHATBOT 기본 구성</figcaption></figure><p>아마 많은 분들이 예상하셨겠지만, 이러한 아키텍처는 어디서나 비슷비슷한 모양새를 하고 있죠.</p><p>이제 각 구성 요소들이 어떤 역할을 하고 있는지 살펴보면서, 중간중간 디테일도 함께 이야기 해보겠습니다. 🐳</p><h4>주요 구성 요소</h4><h4>User</h4><p>바로 여러분입니다. 질문을 입력하는 최종 사용자죠.</p><h4>DB</h4><p>고객지원팀에서 관리하는 FAQ 데이터들이 저장되어 있는 곳입니다.</p><h4>Batch</h4><p>‘Batch’라는 이름의 별도 서버가 있습니다. 이 서버는 DB에서 FAQ 데이터를 가져와서, 정제한 다음 OpenSearch에 적재하는 일을 맡고 있습니다.</p><p>한마디로, 데이터 준비 담당자라고 보면 됩니다.</p><h4>ChatBot Server</h4><p>실제로 RAG가 수행되는 핵심 서버입니다.<br> 사용자의 질문을 받아 OpenSearch와 LLM을 오가며 응답을 생성하죠.</p><h4>OpenSearch</h4><p>이전 블로그에서도 소개했었죠. <br>벡터 기반 Text Embedding과 키워드 기반 검색을 함께 수행하는 <strong>Hybrid Search 엔진</strong>입니다.</p><p>저희는 임베딩 모델을 <strong>Cohere</strong>로 바꿔서 사용하고 있습니다.</p><h4>S3</h4><p>동의어 사전과 사용자 정의 사전이 저장되어 있는 저장소입니다.</p><p>이 데이터는 OpenSearch 패키지를 통해 로딩되도록 설정되어있습니다.</p><h4>AWS Bedrock</h4><p>LLM(대규모 언어 모델) API를 제공해주는 AWS 서비스입니다.</p><p>저희는 <strong>Anthropic Claude Sonnet 3.5 v2</strong> 모델을 사용 중입니다.</p><p>이 구조에서 특히 중요한 건 <strong>Batch 서버</strong>와 <strong>ChatBot 서버</strong>입니다.</p><p>이 두 영역에 시간을 가장 많이 들였고, 아마 이 글을 보시는 분들도 이 부분이 제일 궁금하실 거라 생각해요. 😆</p><p>그래서 다음 글에서는 이 두 서버가 어떤 형태로 데이터를 처리하고, RAG 흐름 안에서 어떤 역할을 하는지 좀 더 깊게 다뤄보려고 합니다.</p><h3>Batch 부터 뜯어봅시다!</h3><p>RAG 아키텍처 구성 중, 가장 처음이 되는 <strong>Batch 파트</strong>부터 살펴보려 합니다.</p><p>데이터를 로드하고 <strong>쿵짝쿵짝(🤔)</strong> 처리해서 어딘가로 보내는 구조…</p><p>익숙하시죠? 우리가 잘 아는 <strong>ETL</strong>(Extract, Transform, Load)의 기본 형태입니다. 😉</p><p>스푼봇에서 이 “쿵짝쿵짝”은 두 가지 작업으로 나뉩니다.</p><ul><li><strong>Content 변환 (Converting)</strong></li><li><strong>Chunking (문서 쪼개기)</strong></li></ul><blockquote>순서 중요합니다! Converting → Chunking 순으로 진행해야 해요.</blockquote><h4>Content를 왜 변환해야 할까?</h4><p>현실 속 문서는 정말 다양하죠.</p><p>PDF, EXCEL, PPT, HTML, XML, JSON… 심지어 TXT까지!</p><p><strong>LLM이 제일 잘 이해하는 문서 포맷은 무엇일까요?</strong></p><p>사람 기준으론 Plain Text가 편하고, 시스템 입장에선 JSON이 익숙할 수도 있겠지만..</p><p>LLM들은 <strong>Markdown(MD)</strong> 포맷을 가장 잘 처리하는 걸로 알려져 있습니다. <br>(정답은 아닙니다 😉)</p><p>저희는 위지윅 게시판으로 관리되고 있기 때문에 원본 데이타는 HTML로 관리 하고 있습니다.</p><h4>Markdown이 좋은 이유❓</h4><ul><li>명확한 계층구조 (#, -, &gt;, 1. 같은 마크업 문법)</li><li>강조(굵게/기울임), 인용, 코드 블록 등 표현이 자연스럽고 예측 가능</li><li>의미 전달이 가능(가독성 좋음)</li></ul><p>실제 Anthropic, OpenAI, Cohere 등의 모델들도 문서 입력 시 Markdown 형식에 더 좋은 반응을 보인다고 합니다.</p><p>다만, Text Embedding은 다른이야기 입니다. Plain Text로 넣는게 더 좋다고 생각합니다.</p><p><strong>‘문서 형식보다는 의미의 밀도’</strong>를 더욱 중요시 여기기 때문에 구조적인 표현보다, Plain Text가 더욱 효과적으로 보여집니다.</p><blockquote>⚠️ 주의<br>MD나 Plain Text.. 어떤 방식으로 저장하든 상황에 따라 다를 수 있으므로, 본인에게 맞는 환경에 맞게 진행하면 좋을것같습니다.</blockquote><p>Markdown 변환하는 Kotlin예제입니다. <br>(전.. 거슬리는 부분이 있으면 못참아서 좀.. 빡세게 해두었습니다. 🤣)</p><pre> fun convertToMarkdown(html: String): String =<br>        FlexmarkHtmlConverter<br>            .builder()<br>            .build()<br>            .convert(html)<br><br>            /* 이미지 제거하기 (당장에는 필요없음) */<br>            .replace(Regex(&quot;&lt;img\\b[^&gt;]*?&gt;&quot;), &quot;&quot;)<br><br>            /* a link 제거하기 (당장에는 필요없음) */<br>            .replace(Regex(&quot;&lt;a\\b[^&gt;]*?&gt;.*?&lt;\\/a&gt;&quot;), &quot;&quot;)<br>            .replace(&quot;&lt;br /&gt;&quot;, &quot;&quot;)<br>            .replace(&quot;*** ** * ** ***\n&quot;, &quot;&quot;)<br><br>            /* Markdown 링크 주소 제거: [text](url) → text (당장에는 필요없음) */<br>            .replace(Regex(&quot;&quot;&quot;\[(.*?)\]\([^\)]+\)&quot;&quot;&quot;), &quot;$1&quot;)<br>            <br>            /* 중복 구두점 정리: !!! → !*/<br>            .replace(Regex(&quot;&quot;&quot;([!?.,]){2,}&quot;&quot;&quot;), &quot;$1&quot;)<br>            // 빈 줄 제거<br>            .replace(Regex(&quot;&quot;&quot;(?m)^\s*\n&quot;&quot;&quot;), &quot;&quot;)<br><br>            // 연속된 공백 (스페이스, 탭, 개행 포함) → 공백 1개<br>            .replace(Regex(&quot;&quot;&quot;\s{2,}&quot;&quot;&quot;), &quot; &quot;)<br>            <br>            // 모든 줄에 대해 양쪽 공백 제거<br>            .lines()<br>            .joinToString(&quot;\n&quot;) { it.trim() }</pre><p>FlexmarkHtmlConverter라는 라이브러리를 이용하여 HTML tag는 모두 지워버리고 Markdown으로 변환합니다.</p><p>각자 구현하는 서비스 상황에 맞게 변환을 하시면 되고, 저희는 거의 Text만 남기는 형태로 진행했습니다.</p><p>HTML로 되어있는 문서를 MD로 변환한 결과입니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Z-6-tIBLOBcbgcKHXxjqtw.png" /><figcaption>(좌) MD , (우) PreView — 잘 변환 된것같습니다.</figcaption></figure><h4>Markdown, Plain Text 둘 다 필요한 이유는?📚</h4><p>앞에서 Markdown으로 변환한다고 말씀드렸죠.</p><p>그 이유는 단순히 보기 편하라고 만든 게 아닙니다.</p><p><strong>나중에 RAG에서 참조문서(Parent 문서)</strong>로 활용하기 위해 <strong>Markdown 버전</strong>을 미리 만들어두는 거예요.</p><p>LLM은 구조가 명확한 문서에서 더 풍부한 문맥을 이해하고, 인용 방식도 훨씬 자연스럽거든요.</p><p>그런데…!</p><p>여기서 끝나지 않습니다.</p><p>RAG에서 검색을 위해선 <strong>Text Embedding</strong> 처리가 필요하고, Vector화를 시킬 <strong>Plain Text 버전</strong>이 따로 있어야 해요.</p><h4>준비되는 3종 문서🛠️</h4><p>정리해보면, 최종적으로 아래 <strong>3가지 버전의 문서</strong>가 준비 되어야 합니다.</p><p><strong>HTML 원문</strong></p><ul><li>Data를 가공하기 위해 지속적인 호출에 부담이 없다면 굳이 저장해둘 필요는 없습니다.</li><li>ChatBot의 경우, 이미 원본을 다른 DB에 가지고 있기 때문에 RAG를 위한 원본 데이타는 따로 저장하지 않습니다.</li></ul><blockquote>💡TMI<br>Confluence Crawling을 진행할때 Confluence의 PAGE를 호출할때마다 API를 2~3회Call을 해야하는 부담감이 있어, 원본을 미리 저장해둡니다.</blockquote><p><strong>Markdown (MD)</strong></p><ul><li>LLM에 전달 될 참조용 데이타로서, context를 유지하기 위해 Parent로 활용 될 예정입니다.</li></ul><p><strong>Plain Text</strong></p><ul><li>Text Embedding(Semantic Search)과 Lexical Search에 활용 될 데이타입니다.</li><li>HTML 태그 제거 → 텍스트만 추출합니다.</li></ul><p>참고로, Plain Text로 변환하는 방법은 구글에 예제가 워낙 많아 간단하게 처리할 수 있습니다. (코드는 생략할게요! 😅)</p><h3>Chunking 이란?</h3><p>이번에는 <strong>Chunking</strong>에 대해 알아보겠습니다!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Cie7Auua8LLHepBe9GVcyQ.png" /><figcaption><a href="https://medium.com/data-science/the-art-of-chunking-boosting-ai-performance-in-rag-architectures-acdbdb8bdc2b">The Art of Chunking: Boosting AI Performance in RAG Architectures</a></figcaption></figure><p>Chunking이 뭐죠?</p><p>간단히 말해서, “<strong>덩치 큰 문서를 잘게 나누는 작업”</strong>입니다.</p><blockquote>문서가 얼마나 크길래 굳이 잘라요? 수십 MB 되는 것도 아니잖아요?</blockquote><p>라고 생각하실 수도 있는데요 Chunking은 단순히 <strong>파일 용량이 크기 때문만은 아닙니다.</strong></p><h4>첫번째이유: Token Limit 때문!</h4><p>문서 용량이 크다는 건 <strong>텍스트 양도 많다</strong>는 뜻이고,<br>이는 곧 <strong>Embedding에 넣기엔 너무 크다</strong>는 걸 의미합니다.</p><p>LLM이나 Embedding 모델은 텍스트를 처리할 때 <strong>‘토큰(token)’ 단위</strong>로 다루며, 각 모델은 처리할 수 있는 <strong>최대 token 수가 정해져</strong> 있습니다.</p><p>예를 들어, 저희가 사용하는 <strong>Cohere embed-multilingual-v3.0 모델</strong>은 <strong>512 token</strong>까지만 처리할 수 있습니다. (보통 한글 기준 1 token ≒ 1.5자~2자, 영어는 평균 4자)</p><p>즉, 문서가 너무 길면 모델이 한 번에 처리할 수 없고, 초과된 부분은 <strong>잘리거나 에러가 날 수 있습니다.</strong> ❌</p><p>아래는 512 token 이상의 문자열을 입력했을때 발생하는 에러입니다.</p><pre>{<br>  &quot;took&quot;: 0,<br>  &quot;ingest_took&quot;: 93,<br>  &quot;errors&quot;: true,<br>  &quot;items&quot;: [<br>    {<br>      &quot;index&quot;: {<br>        &quot;_index&quot;: &quot;INDEX&quot;,<br>        &quot;_id&quot;: &quot;DOC_ID&quot;,<br>        &quot;status&quot;: 400,<br>        &quot;error&quot;: {<br>          &quot;type&quot;: &quot;status_exception&quot;,<br>          &quot;reason&quot;: &quot;Error from remote service: {\&quot;message\&quot;:\&quot;Invalid parameter combination. Please check and try again.\&quot;}&quot;<br>        }<br>      }<br>    }<br>  ]<br>}</pre><blockquote>OpenSearch에서는 정확히 어떤 에러인지 확인되지 않아, 원인을 찾는데 꽤나 고생할 수도 있습니다.</blockquote><p>그래서 문서의 내용을 <strong>적절한 길이로 나누는 작업</strong>, 즉 <strong>Chunking이 필수</strong>가 되는것입니다.</p><h4>두번재 이유: 문맥 손실 방지 (RAG 정확도 향상)</h4><p>RAG 시스템에서는 사용자의 질문과 관련 있는 문서 조각(chunk)을 가져와</p><p>LLM에 넣고 답변을 생성합니다.</p><p>그런데…</p><p>만약 중요한 정보가 문단 끝에서 잘려서 다음 chunk로 넘어가버리면 어떻게 될까요? 😨</p><ul><li>검색 정확도가 떨어지고,</li><li>LLM은 문맥을 제대로 이해하지 못하게 됩니다.</li></ul><p>그래서 등장하는 기능이 바로 <strong>Overlap</strong>입니다!</p><h4>Overlap이 필요한 이유</h4><p>Overlap은 <strong>각 chunk를 자를 때 앞뒤 일부 내용을 겹쳐서 포함</strong>시키는 전략입니다.</p><p>예를 들어, 500자씩 자르되 앞뒤로 100자씩 겹치게 구성한다고 생각해봅시다.</p><ul><li><strong>중요 정보가 chunk 경계에 걸려도</strong> 유실되지 않고</li><li>LLM이 <strong>더 일관된 문맥</strong>을 유지할 수 있습니다. 👍</li></ul><blockquote><em>📍 실제로 LLM은 문장의 앞뒤 흐름에 매우 민감하기 때문에, </em><strong><em>적절한 Overlap은 RAG 응답의 품질을 크게 향상</em></strong><em>시켜줍니다.</em></blockquote><h4>그럼 얼마나, 어떻게 자르면 될까?</h4><p>사실 Chunking에도 여러방식이 존재합니다.</p><p>단순히 “<strong>토큰 기준으로 자른다</strong>”는 걸 넘어서, 문맥 유지, 검색 Recall 향상 등 목적에 따라 다양한 기법이 쓰이죠.</p><p>아래 표는 대표적인 Chunking 방식들과 각 특징을 정리한 내용입니다:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*TlooQUSXvGIWV2l5sqRgXg.png" /><figcaption>저희가 사용하는 기법은 노란색으로 표시되어있습니다.</figcaption></figure><p>각 방식은 장단점이 뚜렷하고, 사용하는 목적에 따라 달라질 수 있고, 저희는 3가지 전략을 조합해 Chunking을 진행하였습니다.</p><p>LangChain4J를 기반으로 구현했고, 예시로 기본 chunk 크기를 1000으로 설정했습니다.</p><pre> fun recursiveCharacterTextSplitter(<br>        text: String,<br>        segmentSize: Int = 1000,<br>        segmentOverlapSize: Int = 100,<br>    ): List&lt;String&gt; =<br>        DocumentSplitters<br>            .recursive(segmentSize, segmentOverlapSize)<br>            .split(Document.from(text))<br>            .map { it.text() }</pre><p>이 방식은 문장을 가능한 한 <strong>자연스럽게 끊기지 않게</strong> 자르기 위한 전략입니다. 단순히 1000자에서 “툭” 잘리는 게 아니라, <strong>문맥상 적절한 위치에서 자르도록</strong> 설계되어 있습니다.</p><blockquote><em>예를 들어 1000번째에서 문맥이 어색하게 끊긴다면, 그 전 적절한 위치에서 자릅니다. <br>그래서 “</em><strong>1000자 기준이면 문장이 중간에 잘릴 수도 있지 않나요?</strong><em>”라는 걱정은 안 하셔도 됩니다!! 💡</em></blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/725/1*P9kMS8OZPyobBmNwBu4F2A.png" /><figcaption>스푼 <strong>서비스 이용약관</strong> 일부</figcaption></figure><p>글자수를 1000개로 설정했지만, 그 다음에 올 문장이 1000을 넘어가게 되므로 1000글자가 넘어가는것을 예상하여 891에서 미리 자르게 되는것입니다.</p><p>그 다음에 따라 올 문장도 함께 넣어볼까요?</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/737/1*AoR92KKf-MA2QbLmYCwIgA.png" /><figcaption>스푼 <strong>서비스 이용약관</strong> 일부</figcaption></figure><p>예상대로 다음의 의미있는 문장을 넣으니 1069로 1000을 넘어가게 되네요.<br>(어이쿠, 512 token limit을 넘겨버렸군요!! 😂 )</p><p>LangChain Recursive Splitter는 참 좋은기능인 것 같습니다~</p><p>이렇게 여러 전략을 조합하면 <strong>텍스트 성격에 따른 유연한 Chunking</strong>이 가능해지고, RAG의 검색 정확도와 응답 품질도 훨씬 좋아집니다 💡</p><h4>Chunking 결과, 실제로 이렇게 저장됩니다!</h4><p>앞에서 설명한 <strong>Plain Text 변환 → Chunking → Embedding</strong> 과정을 거친 뒤, 결과는 아래처럼 <strong>OpenSearch에 문서 단위로 저장</strong>됩니다.</p><pre>  {<br>        &quot;_index&quot;: &quot;xxxx&quot;,<br>        &quot;_id&quot;: &quot;2&quot;,<br>        &quot;_score&quot;: null,<br>        &quot;_source&quot;: {<br>          &quot;body_embedding&quot;: [  <br>            0.014633179,<br>            0.01084137,<br>            -0.03918457<br>            ... 총 1024개<br>            ],<br>          &quot;title&quot;: &quot;서비스 이용약관 3.0 ver&quot;,<br>          &quot;body&quot;: &quot;&quot;&quot;1) 이용자는 YouTube 동영상을 라이브 콘텐츠에 통합하여 송출할 수 있습니다.<br>2) 회사의 웹사이트(어플리케이션 포함)는 YouTube API 서비스를 사용하고 있으며, 이용자는 회사의 웹사이트(어플리케이션 포함)를 이용함으로써 , , 을 준수하는 데 동의한 것으로 간주됩니다.<br>.... <br>4. 이용자는 스푼 및 아이템을 이용자 본인의 계정에서만 사용할 수 있으며, 제3자에게 양도, 대여, 매매할 수 없습니다.<br>&quot;&quot;&quot;<br>        }<br>      },<br>      {<br>        &quot;_index&quot;: &quot;xxxx&quot;,<br>        &quot;_id&quot;: &quot;3&quot;,<br>        &quot;_score&quot;: null,<br>        &quot;_source&quot;: {<br>         &quot;body_embedding&quot;: [  <br>            -0.012290955,<br>            -0.0013141632,<br>            -0.04837036,<br>            ... 총 1024개<br>            ],<br>          &quot;title&quot;: &quot;서비스 이용약관 3.0 ver&quot;,<br>          &quot;body&quot;: &quot;&quot;&quot;4. 이용자는 스푼 및 아이템을 이용자 본인의 계정에서만 사용할 수 있으며, 제3자에게 양도, 대여, 매매할 수 없습니다.<br>5. 청소년 이용자는 스푼 구매 서비스 이용을 위하여 법정대리인의 동의를 받아야 합니다. 회사가 정한 절차에 따라 법정대리인의 동의를 받지 않은 경우 스푼 구매 서비스를 이용할 수 없습니다.<br>....<br>6) IAP사업자의 결제 정책에 따라 구매 취소가 거절된 경우&quot;&quot;&quot;<br>        }</pre><h4>여기서 확인할 수 있는 핵심 포인트</h4><p>두 문서 <strong>_id 2번과 3번</strong>을 보면,</p><p>“<strong>4. 이용자는 ~</strong>” 문장이 두 <strong>chunk에 중복</strong>되어 들어간 것을 확인할 수 있습니다.</p><ul><li>이건 앞에서 설명한 <strong>Sliding Window 방식(Overlap)</strong>이 적용된 결과입니다.</li><li>덕분에, 어느 chunk에서 검색되든 중요한 정보가 놓치지 않게 됩니다!</li></ul><p>이렇게 잘라서 넣어두면, RAG에서 질문을 받았을 때 가장 적절한 chunk를 OpenSearch가 찾아내고, 결과를 기반으로 LLM이 답변을 생성하는 흐름이 만들어집니다.</p><h3>ChatBot Server</h3><p>스푼봇의 <strong>ChatBot Server</strong>는 사용자의 질문에 응답을 생성하는 핵심 컴포넌트입니다.</p><p>총 <strong>6단계의 프로세스</strong>를 거쳐 최종 답변을 생성하게 됩니다.</p><ol><li><strong>Retrieve</strong></li><li><strong>Merge</strong></li><li><strong>Score Filter</strong></li><li><strong>Relevance</strong></li><li><strong>Prompt</strong></li><li><strong>Generation (LLM)</strong></li></ol><p>이제 각 단계를 순서대로 살펴보겠습니다.</p><blockquote>이 챕터에서는전 블로그와 관련 된 내용을 포함하고, 설정 및 Query 에서 생략된 부분도 있기 때문에, 이해가 잘 안되시는 분은 KNN 검색 블로그를 미리 한번 읽어보시는것을 추천드립니다.</blockquote><blockquote><a href="https://medium.com/spoontech/aws-opensearch%EC%97%90-%EC%9D%98%EB%AF%B8-%EB%A5%BC-%EB%8B%B4%EC%95%84%EB%B3%B4%EC%9E%90-knn-ac1aa3d35dc1">AWS OpenSearch에 의미를 담아보자</a></blockquote><h3>Retrieve — 관련 문서 검색 🔍</h3><p>사용자의 질의에 가장 관련 있는 chunk들을 찾아오는 단계입니다.</p><p>스푼봇에서는 <strong>OpenSearch 기반의 Hybrid Search</strong>를 사용하고 있습니다.</p><p>Hybrid Search는 <strong>Lexical 검색</strong>(문자 기반 키워드 검색)과 <strong>Neural 검색</strong>(벡터 기반 의미 검색)을 <strong>동시에 수행</strong>하는 방식입니다.</p><blockquote>Semantic과 Neural을 혼용해서 사용하지만 면밀히 구분하자면 다른 의미입니다. Semantic이 상위 개념이지만, 본 블로그에서는 구분없이 사용하겠습니다.</blockquote><p>다음은 실제로 사용 중인 OpenSearch 쿼리 예시입니다:</p><pre>{<br>  &quot;_source&quot;: {<br>    &quot;includes&quot;: [<br>      &quot;title&quot;,<br>      &quot;body&quot;<br>    ]<br>  },<br>  &quot;from&quot;: 0,<br>  &quot;query&quot;: {<br>    &quot;hybrid&quot;: {<br>      &quot;queries&quot;: [ <br>        {<br>          &quot;multi_match&quot;: { <br>            &quot;analyzer&quot;: &quot;korean_analyzer&quot;, <br>            &quot;fields&quot;: [<br>              &quot;title&quot;,<br>              &quot;body&quot;<br>            ],<br>            &quot;minimum_should_match&quot;: &quot;80%&quot;, <br>            &quot;operator&quot;: &quot;or&quot;, <br>            &quot;query&quot;: &quot;스푼 구매방법&quot; <br>          }<br>        },<br>        {<br>          &quot;neural&quot;: {  &lt;-- 7<br>            &quot;body_embedding&quot;: {<br>              &quot;query_text&quot;: &quot;스푼 구매방법&quot;, <br>              &quot;model_id&quot;: &quot;XXXXXXXX&quot;,<br>              &quot;k&quot;: 30<br>            }<br>          }<br>        }<br>      ]<br>    }<br>  },<br>  &quot;size&quot;: 30<br>}</pre><h4>Lexical 검색 (multi_match) 🔠</h4><ul><li><strong>fields:“title”, “body”</strong><br>대상으로 검색합니다.</li><li><strong>analyzer: “korean_analyzer”</strong><br>형태소 분석, 특히 명사 중심으로 토큰화</li><li><strong>minimum_should_match : “80%”<br></strong> 검색어에서 <strong>80% 이상 단어가 일치</strong>하는 경우만 결과로 인정</li><li><strong>operator: “or”</strong><br>필드 간 OR 조건 → <strong>더 유연한 문서 탐색</strong></li></ul><p>예를 들어, 사용자가 “<strong>스푼 구매하는 방법에 대해 설명해줘</strong>”라고 검색하면 형태소 분석 결과로 <strong>스푼, 구매, 방법, 설명</strong> 등의 단어가 추출됩니다.</p><p>여기서 “<strong>설명</strong>”은 검색 정밀도(precision)를 떨어뜨리는<strong> 비핵심 키워드</strong>일 수 있기 때문에, minimum_should_match: 80% 설정으로 <strong>불필요한 단어를 필터링하면서도 유사 문서를 포착</strong>할 수 있습니다.</p><blockquote>minimum_should_match는 정수형 또는 퍼센트 외에도 조건문 형태로 다양하게 설정할 수 있어요.<em><br></em><a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-minimum-should-match.html"><em>공식 문서 보기</em></a></blockquote><p>또한 operator: “or”는 “관련 있을 법한 문서는 다 가져와!” 라는 의도로 설정했습니다.<br>반대로 AND를 쓰면 모든 키워드를 포함해야 하므로, 검색이 너무 협소해질 수 있거든요. 😉</p><h4>Neural 검색 🧠</h4><p>neural 블록은 벡터 기반의 <strong>의미 유사도 검색</strong>을 수행합니다.</p><p>이때 사용되는 벡터는 <strong>Cohere Embedding Model </strong>을 통해 생성되며, OpenSearch의 KNN 기반 검색 기능으로 처리됩니다.</p><ul><li><strong>query_text </strong><br>사용자 질문 그대로 사용</li><li><strong>model_id </strong><br>AWS Bedrock에서 Embedding model을 연결하면 발급되는 고유 식별자 (20자리 문자열)</li><li><strong>k</strong><br>유사도가 가장 높은 상위 K개를 검색</li><li><strong>size</strong><br>최종 응답에 포함할 결과 수</li></ul><p>k = size로 설정하는 이유는, <strong>검색한 결과가 잘리는 걸 방지</strong>하기 위해서입니다.</p><p>예를 들어 k = 10, size = 3이면 3개만 반환되고, k = 5, size = 10이면 최대 5개만 반환되므로 의미가 줄어들겠죠! (해보세요!!! )</p><p>이렇게 Hybrid 방식으로 질의의 <strong>문자적 의미와 의미적 유사성</strong>을 모두 고려하면, 보다 신뢰도 높은 검색 결과를 확보할 수 있습니다.</p><h3>Merge — 검색 결과 정제 및 병합</h3><p>앞선 Retrieve 단계에서, <strong>Lexical Search</strong>와 <strong>Neural Search</strong>를 동시에 수행한 결과, 최대 30개의 chunk가 반환되었습니다.</p><p>이제 다음으로는 해당 chunk들을 바탕으로 <strong>LLM에 입력할 context를 재구성</strong>해야 합니다.</p><h4>Chunk만 보지 말고, Parent 전체 문서를 봐야 할 때</h4><p>많은 경우 단일 chunk만으로는 문맥이 부족하거나 정보가 단편적일 수 있습니다. (위에서 문서를 잘게 뽀개놨죠~)</p><p>예를 들어, <strong>“5. 청소년 이용자는…”</strong> 이라는 문장이 덜렁 나와도 그 앞뒤 조항 없이 단독으로 보면 정확한 의미를 파악하기 어렵죠.</p><p>그래서 저희는 아래 그림처럼, <strong>선택된 chunk가 속한 원본 문서(Parent)</strong>를 찾아 다시 가져오고, 그 Parent 전체 또는 해당 블록 단위를 context로 사용합니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/752/1*SX0zJhf3SP0KiW8ROfFgcA.png" /><figcaption><a href="https://medium.com/data-science/the-art-of-chunking-boosting-ai-performance-in-rag-architectures-acdbdb8bdc2b">퍼왔습니다~ 😁</a></figcaption></figure><ol><li>사용자의 질문을 embedding한 결과</li><li>chunk index에서 관련 있는 chunk들을 검색</li><li>해당 chunk들이 소속된 <strong>Parent 문서를 다시 불러와 </strong>LLM에게 전달할 <strong>context 문서로 구성</strong>합니다</li></ol><p><strong><em>즉, 이때 사전에 만들어 두었던 Markdown 본문을 Load하게 됩니다.</em></strong></p><p>복잡하거나 어려운 부분이 없기에 예시 코드는 패스하겠습니다.</p><h3>Score Filter</h3><h4>Hybrid Search를 쓰는데 min_score 가 안 먹는다??</h4><p>스푼봇 프로젝트를 진행하면서 Retrieve단계에서는 OpenSearch에서 <strong>Hybrid Search</strong>를 쓰고 있었는데요.</p><p>질문에 대한 관련 문서를 <strong>Lexical + Neural</strong> 방식으로 잘 가져오고 있습니다.</p><p>그런데 30개중 관련도가 낮은 문서도 많이 나와서 필요없는 문서는 제외하기로 했습니다.</p><blockquote><strong><em>그럼 min_score 쓰면 되겠네!</em></strong></blockquote><p>그런데… 안 됩니다. 😮</p><p>정확히는, Hybrid Query에서는 min_score가 작동하지 않아요. 😱</p><h4>왜 min_score가 안 되는 걸까?</h4><p>결론부터 말하자면, Lexical 쿼리와 Neural 쿼리의 <strong>score 계산 방식이 완전히 다르기 때문입니다.</strong></p><ul><li>multi_match 쿼리는 <strong>BM25 기반</strong>의 keyword score</li><li>neural 쿼리는 <strong>유클리드 거리 기반의 벡터 유사도</strong></li></ul><p>비유가 적절할지 모르겠으나 <strong>사람이 10초에 가는 거리</strong> vs <strong>빛이 10초에 가는 거리 </strong>단위가 다르니 단순 비교가 안 되는 것과 비슷한 느낌입니다.</p><p>그래서 아래처럼 min_score 설정을 해봤자 아무런 반응이 없습니다.</p><pre>&quot;query&quot;: {<br>  &quot;hybrid&quot;: {<br>    &quot;queries&quot;: [<br>      { &quot;multi_match&quot;: { &quot;query&quot;: &quot;스푼 구매방법&quot;, &quot;fields&quot;: [&quot;title&quot;,&quot;body&quot;] }},<br>      { &quot;neural&quot;: {<br>          &quot;body_embedding&quot;: {<br>            &quot;query_text&quot;: &quot;스푼 구매방법&quot;,<br>            &quot;model_id&quot;: &quot;model_xyz&quot;,<br>            &quot;k&quot;: 30<br>          }<br>      }}<br>    ]<br>  }<br>},<br>&quot;min_score&quot;: 0.3</pre><h4>그럼 어떤 방법이 있을까?</h4><h4>script_score 로 직접 코사인 유사도를 계산한다</h4><p>이건 조금 더 정밀하게 컨트롤하고 싶을 때 쓰는 방식입니다.</p><p>이 방식을 이용하면 Neural Search의 벡터 유사도를 직접 계산해서 점수를 만들고, 그 위에 min_score를 사용할 수 있습니다.</p><pre>&quot;query&quot;: {<br>  &quot;script_score&quot;: {<br>    &quot;query&quot;: {<br>      &quot;bool&quot;: {<br>        &quot;should&quot;: [<br>          { &quot;match&quot;: { &quot;title&quot;: &quot;스푼 구매방법&quot; }}<br>        ]<br>      }<br>    },<br>    &quot;script&quot;: {<br>      &quot;source&quot;: &quot;cosineSimilarity(params.query_vector, doc[&#39;body_embedding&#39;]) + _score * 0.1&quot;,<br>      &quot;params&quot;: {<br>        &quot;query_vector&quot;: [0.1, 0.2, ..., 0.9] &lt;-- 직접 Embedding을 진행 한 후 Array&lt;Float&gt;로 전달<br>      }<br>    }<br>  }<br>}</pre><p>이 방식은 score를 직접 제어할 수 있어서, 아래와 같은 특징들이 가능하다는 장점이 있습니다.</p><ul><li>가중치 조정</li><li>min_score 설정</li><li>필터링 로직 커스터마이징</li></ul><p>하지만 <strong>속도가 느리고, </strong>Cohere Embedding을 <strong>직접 API로 호출해서 벡터를 구한 뒤 전달해야</strong> 합니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*dX0sXsLASA6OuJ9-ORNexw.png" /><figcaption>Cohere Embedding API Test</figcaption></figure><p>즉, Bedrock → 벡터 호출 → 결과 넘김…이라는 흐름이 필요한거죠.</p><p>현재 저희는 <strong>유클리드 거리 기반의 벡터 유사도</strong>방식을 사용하고 있습니다.</p><p>간단하고 빠르고, 적은 데이터에서는 꽤 잘 작동하거든요.</p><p>굳이 Application 중간에 저러한(위 Test Code) 행위(?)를 넣어서 복잡도만 가중 시킬 필요는 없다고 생각했습니다.</p><blockquote>하지만, 검색이나 GPT등에 물어보니 <strong>코사인 유사도 방식이 정확도</strong>가 더 좋다고합니다.<br>이 또한, 상황에 따라 결정하시면 될것같습니다.</blockquote><p>따라서 OpenSearch에서 Hybrid Search 결과를 받아오고, 이후 <strong>애플리케이션에서 _score 기준으로 필터링</strong>하도록 구현했습니다.</p><pre>suspend fun retrive(query: String): List&lt;Documents&gt; {<br>        runCatching {<br>            SearchRequest<br>                .Builder()<br>                .index(INDEX)<br>                .query(getHybridQuery(query))<br>                .source(getSourceConfig())<br>                .from(0) <br>                .size(DEFAULT_SIZE) <br>                .pipeline(SEARCH_PIPELINE)<br>                .build().let { searchRequest -&gt;<br>                    openSearchAsyncClient<br>                        .search(searchRequest, Documents::class.java)<br>                        .await()<br>                        .hits()<br>                        .hits()<br>                   요기 &gt;&gt; .filter { it.score()!! &gt; LIMIT_SEARCH_SCORE } &lt;&lt; 요기<br>                        .sortedByDescending { it.score() }<br>                        .map { it.source()!! }<br>                }<br>        }.onFailure { e -&gt; e.printStackTrace() }.getOrNull().let { result -&gt;<br>            return result ?: emptyList()<br>        }<br>    }</pre><p>예를 들어, LIMIT_SEARCH_SCORE = 0.3 으로 두고 있는데요, 체감상 0.3 이상이면 꽤 정확한 응답이 잘 나옵니다.</p><p>지금은 데이터도 많지 않고, 결과도 꽤 잘 나와서 <strong>간단한 Hybrid 구조 + Applicatrion 필터 방식</strong>으로 충분히 잘 쓰고 있습니다.</p><p>나중에 정밀도가 더 중요해지거나 수만건의 데이타를 취급할때가 도래하면 script_score 방식도 도입도 고려하고 있습니다.</p><p>혹시 비슷한 고민 있으셨던 분들 계신가요?</p><p>다른 설정이나 기준이 있다면 공유해주셔도 대환영입니다 🙌</p><h3>Relevance 평가 — 진짜 관련 있는 문서일까?</h3><p>Hybrid Search를 통해 문서를 검색하고, _score 기준으로 1차 필터링도 끝냈습니다.</p><p>근데 여기서 끝이 아닙니다.</p><p>정말? 진짜로?? 레알??? 혼또니????</p><p>“<strong>이 문서가 사용자의 질문과 관련 있나?</strong>”</p><p>이걸 한 번 더 확인해야, 사용자 질의에 대해 LLM이 참조하는 문서를 기반으로 정확하게 답변을 해줄 수 있습니다. (마지막 면접같은 느낌일까요 😆)</p><p>이걸 저희는 <strong>Relevance 평가 단계</strong>라고 부릅니다.</p><p>점수는 높지만 <strong>“결제 방법”</strong>을 물었는데<strong> “본인 인증” </strong>답변을 하고 있으면 안되겠죠!</p><h4>AWS Bedrock에도 제공하는 기능이 있습니다.</h4><p>AWS에서는 Cohere ReRank라는 걸 제공합니다.</p><p>문서별로 질의와의 관련성을 점수로 매겨주는 기능이죠.</p><p>그런데 저희는 <strong>Cohere Rerank는 사용하지 않고</strong>, <strong>LLM을 직접 Prompt로 호출해서 Relevance를 평가하는 방식</strong>을 택했습니다.</p><p>이 방식(LLM 직접호출)의 장점으로는, <strong>커스터마이징이 자유롭고</strong>, <strong>왜 점수를 그렇게 매겼는지에 대한 설명까지 같이 받을 수 있다는 점</strong>이에요.</p><p>덕분에 체감상 Cohere Rerank보다 더 정밀하고 납득 가능한 결과를 얻을 수 있었습니다.</p><p>물론 Cohere 쪽도 확실한 장점이 있습니다.</p><p><strong>“속도”</strong>입니다. <strong>⚡</strong></p><p>Cohere는 후보 문서 여러 개를 한 번에 보내고, 결과도 한 번에 받아올 수 있어요.</p><p>그래서 10건이면 10건 모두를 한번에 평가해서 Response를 받을 수 있습니다.</p><p>반면 LLM을 직접 호출하는 방식은, 문서 하나당 하나씩 개별로 요청을 보내야 하죠.</p><p>즉, 10건이면 10번 호출해야 합니다.</p><p>저희는 비동기로 처리하고 있어서 전체 처리 시간은 문서 1~2건 처리 시간과 큰 차이는 없습니다.</p><p>그럼에도 개발 효율로 생각했을 때는 Cohere가 훨씬 간결하고 빠른 구조라는 건 확실해요.</p><h4>Relevance에 실제 사용 중인 System Prompt</h4><p>아래는 저희가 서비스에서 사용하고 있는 System Prompt입니다.</p><pre># 당신은 주어진 질의(Query)와 문서(Document)의 관련성을 평가하는 AI 어시스턴트입니다.<br>       <br>아래 제공된 질의와 문서를 분석하고, 관련성 점수를 0(관련 없음)에서 100(매우 관련 있음) 사이로 평가하세요.<br>당신의 응답 형식은 다음과 같아야 합니다:<br>        <br>Relevance: &lt;score&gt;</pre><blockquote>질의(Query)와 문서(Document)를 넣고, <strong>LLM이 직접 “관련성 점수”를 0~100 사이로 응답</strong>하도록 요청하는 방식입니다.</blockquote><p>질문 “스푼 결제 방법&quot;에 대한 결과 예시입니다.</p><p><strong>RESULT_1 — Relevance: 10점</strong></p><pre>&quot;text&quot;: &quot;Relevance: 10\n\n이 문서는 회원가입 시 필요한 본인인증 절차와 관련된 내용을 <br>다루고 있으며, 결제 방법에 대한 정보는 포함되어 있지 않습니다.<br>문서는 주로 본인인증 방법, 개명 시 필요한 절차, 제출 서류 등에 대해 설명하고 있어<br>질의한 &#39;결제 방법&#39;과는 거의 관련이 없습니다.<br>단, 카카오나 토스 언급이 있어 매우 낮은 수준의 관련성만 있다고 판단됩니다.&quot;</pre><p>겉보기에 그럴듯했지만, 실제로는 거의 관련 없음 😅</p><p><strong>RESULT_1 — Relevance: 100점</strong></p><pre>&quot;text&quot;: &quot;Relevance: 100\n\n이 문서는 질의와 매우 높은 관련성을 보입니다. 다음과 같은 이유로 <br>100점을 부여했습니다:<br><br>1. 질문이 \&quot;결제 방법\&quot;에 대해 묻고 있고, 문서는 정확히 결제 방법에 대한 상세한 설명을 <br>제공하고 있습니다.<br><br>2. 문서는 다음과 같은 구체적인 결제 정보를 포함하고 있습니다:  <br>- 신용/체크카드 사용 가능  <br>- 최대 3개까지 카드 등록 가능  <br>- 하이브리드 카드 관련 주의사항<br><br>3. 문서는 최신 정보(2024년 4월 5일 기준)를 포함하고 있어 신뢰성이 높습니다.<br><br>따라서 사용자의 결제 방법 문의에 대해 직접적이고 완전한 답변을 제공하고 있어 관련성이 매우 높습니다.&quot;</pre><p>해당문서는 결제방법에 대한 내용이었고, 정확하게 판단하여 점수를 매겨주었습니다.</p><h4>얼마나 높으면 관련 있다고 볼까?</h4><p>점수 0점부터 100점까지 다음 기준을 적용했습니다.</p><ul><li><strong>Relevance 점수 60 초과</strong> → 관련 있음 → 포함 ✅</li><li><strong>60 이하</strong> → 관련성 낮음 → 제외 ❌</li></ul><p>절대적인 기준은 아니고, <strong>LLM의 버전이나 답변 성향에 따라 달라질 수 있으니 구현하고자 하는 시스템에서 실험이 필요</strong>합니다.</p><h4>몇 개의 문서를 써야 할까?</h4><p>보통 <strong>상위 10~15개의 chunk</strong>만 relevance 평가를 진행합니다.</p><p>그리고 그중에서도 <strong>관련성 점수가 일정 기준(예: 60점)을 넘는 것만 수집하여</strong>, 최종적으로 LLM에게 넘기는 context를 구성하게 됩니다.<br>(60점은 절대적인 기준 점수가 아닙니다.)</p><p>이때 사용되는 chunk 수는 <strong>대략 10건 이하</strong>로 제한하는 편이에요.</p><p>이렇게 제한하는 데에는 몇 가지 이유가 있습니다:</p><ol><li>너무 많은 텍스트를 넣으면 잘리거나, 앞뒤 정보가 혼재되면서 핵심 문맥을 흐릴 수 있습니다.</li><li>chunk 수가 많아지면 관련성이 약한 내용도 섞이기 쉬움</li><li>결국 LLM이 “<strong>무엇을 기준으로 답을 생성해야 하지?</strong>” 혼란스러워지고,</li><li><strong>정확도가 낮아지거나 hallucination이 발생</strong>할 수 있습니다.</li><li>문서 수가 많아질수록 prompt 구조나 formatting에 대한 튜닝도 함께 복잡해집니다.</li></ol><blockquote><em>물론 최신 LLM (예: Claude 3, GPT-4 Turbo)은 긴 context에도 잘 대응하지만, 그럼에도 relevance가 낮은 문서가 섞이면 품질 저하가 생길 수 있기 때문에 </em><strong><em>“적은 문서를 더 정제해서 쓰는 전략”이 여전히 효과적</em></strong><em>입니다.</em></blockquote><p>결론적으로,</p><p>스푼봇 시스템에서는 relevance 기준을 <strong>10개 이하의 chunk(또는 문서)</strong>만 최종 수집하고 있으며, 10개정도가 가장 정확하고 안정적인 흐름을 만들어주고 있다고 판단했습니다.</p><p>하지만 <strong>강조하고 싶은내용은 </strong>절대치가 아닌, 상황에 따라 다를수 있으며 현재 진행중인 프로젝트인 WIKI RAG에서도 기준값이 다르게 지정되고 있습니다.</p><h3>Prompt 하나로 LLM이 다르게 반응한다?</h3><p>요즘엔 “<strong>프롬프트 엔지니어</strong>”라는 직군이 생길 만큼, <strong>LLM에게 어떤 질문을 어떻게 하느냐(Prompt)</strong>는 정말 중요합니다.</p><p>실제로 저희가 개발 과정에서 느낀점입니다.</p><blockquote>모든 시스템을 잘 구성하더라도, 프롬프트 하나로 결과가 달라질 수 있다.</blockquote><p>예를 들어 같은 목적을 가진 문장인데도 이런 차이가 있습니다.<br>(프레이징이 다릅니다.)</p><p>표현이 비슷해 보이지만, 저희 시스템에서는 서로 전혀 다른 방식으로 작동했습니다.</p><ul><li>“웹으로부터 <strong><em>얻은 정보를 바탕으로</em></strong> 채용 정보를 알려줘”<strong><br></strong>LLM이 “내가 참조하는 문서가 웹 기반인지”를 확인하려고 함.</li><li>“웹에서 <strong><em>검색한 정보를 바탕으로</em></strong> 채용 정보를 알려줘”<strong><br></strong>“Web Search 툴”을 실행하려는 흐름으로 이어짐.</li></ul><p>다만 중요한 건, <strong>이 차이가 모델 자체의 판단 때문이 아니라</strong>, <strong>저희 시스템의 Tool Router가 프레이징을 분기 처리</strong>했기 때문입니다.</p><p>즉, 프롬프트가 다른 작은 표현 하나가 <strong>LLM뿐만 아니라 시스템 전체 동작 흐름</strong>까지 좌우할 수 있다는 얘기죠.</p><p>흥미로운 비교도 있었습니다.</p><p><strong>질문</strong>과 <strong>참고문서</strong> 그리고 <strong>System Prompt</strong>, 모든 것이 완전히 동일한 조건에서 단지 LLM만 바꿔서 Relevance 점수를 요청해봤습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/893/1*Xq_ZY1eCw3nyQt_v0QBSeg.png" /><figcaption>HAIKU 3.5 사용한 Relevance: 50점</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/882/1*clH9rSdXFkcysGcALfoJSQ.png" /><figcaption>SONNET 3.5 V2 사용한 Relevance: 100점</figcaption></figure><p>저희 입장에서 봤을 땐 해당 문서는 질의(“프로필링이 머야?”)와 <strong>명확하게 일치하는 핵심 정보를 담고 있었고</strong>, Relevance는 당연히 100점이 나와야 하는 상황이었습니다.</p><p>하지만 Haiku는 50점을 부여했고, 저희가 설정한 필터링 기준(예: 60점 이상) 때문에 해당 문서는 <strong>최종 응답에서 제외</strong>되었습니다.</p><p>사용자 입장에선 어떻게 받아 들일까요?</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*UGvSXXjD_UMjM17kxb2b4Q.png" /><figcaption>꽤나 아픈 로그네요 😭 우린.. 최선을 다했어!!!</figcaption></figure><p><em>이처럼 “</em><strong><em>프롬프트 설계가 잘 되어 있어도, 모델 성능에 따라 결과는 충분히 달라질 수 있다</em></strong><em>”는 걸 직접 체감한 경험이었습니다.</em></p><h4>그렇다면 결국 프롬프트 vs 모델 중 어느것이 더 중요할까?</h4><p>둘 다 중요합니다.</p><ul><li>프롬프트가 명확하고 구조가 좋아야 LLM이 적절하게 이해하고,</li><li>LLM의 성능이 좋아야 애매한 문장도 잘 보완해서 판단할 수 있거든요.</li></ul><p>요약하자면</p><ul><li><strong>좋은 프롬프트</strong>는 성능을 끌어올리는 핵심이고,</li><li><strong>좋은 LLM</strong>은 그런 프롬프트의 효과를 <strong>더 정확하게 구현해주는 도구</strong>입니다.</li></ul><blockquote><strong><em>좋은 시스템</em></strong><em>을 만들고 싶다면, </em><strong><em>정확한 프레이징과 프롬프트, 똑똑한 모델</em></strong><em>을 함께 쓰는 것이 가장 확실한 길입니다.</em></blockquote><p>(여건이 허락한다면 최신 LLM 쓰세요. 속편합니다 😎 )</p><h4>프롬프트 작성, 꼭 혼자 하지 않아도 됩니다</h4><p>프롬프트는 기술이라기보다는 글쓰기와 의사소통의 영역에 가깝습니다.</p><p>그래서 저도 기본적인 구조만 만든 뒤, 다양한 표현은 책을 많이 읽는 분들께 도움을 요청했습니다.</p><p>덕분에 정말 문학작품 같은 챗봇 페르소나 프롬프트가 완성됐어요.</p><p>(※ 내용은 비공개지만… 감동 그 자체였습니다.)</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/762/1*0-ZF5kFnrJdWw8JVRp3FBg.png" /><figcaption>챗봇 페르소나 프롬프트를 작성해주셨습니다.</figcaption></figure><p>그리고 한 가지 조언을 드리자면 직접 써보고 잘 안 되면, 꼭 다른 분들에게 검토를 받아보세요. (Code PR 하듯이 말이죠!)</p><p>저는 디자이너 분께 첨삭을 부탁드린 뒤, 바로 한 방에 원하는 결과가 나와서 살짝 현타가 왔습니다 😅</p><p>프롬프트는 문과/이과의 문제가 아니라, 글 감각과 센스의 문제일지도요.</p><p>(우리 모두 책을 많이 읽읍시다. 📚)</p><h3>Generate LLM</h3><p>이제 모든 것이 준비됐습니다.</p><ul><li>빡세게 선별한 문서 ✅</li><li>최적화된 Prompt ✅</li><li>안정적인 벡터 검색과 필터링 ✅</li></ul><p>이제 우리가 할 일은 단 하나.</p><p>바로 LLM에게<strong> “분석해줘~” </strong>하고 <strong>요청을 보내는 일</strong>입니다.</p><h4>LLM 호출을 위한 설정 — Spring AI 기반</h4><p>특별한 건 없습니다.</p><p>Spring AI의 구조를 활용해 Claude Sonnet 3.5 v2 모델에 연결하고, 문서를 기반으로 LLM 응답을 생성합니다.</p><pre>@Bean<br>fun chatModel(awsCredentialsProvider: AwsCredentialsProvider): ChatModel =<br>    BedrockProxyChatModel<br>        .builder()<br>        .defaultOptions(<br>            ToolCallingChatOptions.builder()<br>                .model(ANTHROPIC_LLM_MODEL_ID)<br>                .temperature(TEMPERATURE)<br>                .maxTokens(MAX_TOKEN)<br>                .build(),<br>        )<br>        .credentialsProvider(awsCredentialsProvider)<br>        .region(Region.US_WEST_2)<br>        .build()</pre><p><strong>주요 파라미터 설명</strong></p><p><strong>model</strong></p><ul><li>AWS Bedrock에서 사용할 Claude 모델 ID를 지정합니다.</li><li>Model 종류는 여기 참고하세요.</li><li><a href="https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html">Supported foundation models in Amazon Bedrock — Amazon Bedrock</a></li></ul><p><strong>temperature</strong></p><ul><li>생성되는 텍스트의 다양성을 조절하는 값입니다.</li><li>0.0에 가까울수록 정확한 정답형 응답</li><li>0.7~1.0은 더 창의적인 표현이나 풍부한 설명에 적합합니다.</li></ul><p><strong>maxTokens</strong></p><ul><li><strong>LLM이 생성할 수 있는 응답의 최대 토큰 수</strong>입니다.</li><li>보낼 수 있는 전체 입력 토큰이 아니라, <strong>LLM이 생성할 수 있는 output 길이의 제한</strong>입니다.</li><li>한글 기준 1토큰 ≈ 약 2자 정도로 계산하면 됩니다.</li></ul><h4>Claude는 200K 토큰 지원한다는데 왜 여긴 8K 제한인가요? 🤔</h4><p>Claude 3 모델은 input + output 합산 기준으로 최대 200,000 토큰까지 처리할 수 있습니다.</p><p>하지만 Spring AI의 기본 설정에서는 일반적인 사용성을 고려해 Response Token limit를 약 8K 정도의 제한을 둡니다.</p><p>그 이유는 다음과 같습니다.</p><h4>왜 제한을 둘까요?</h4><ul><li>속도 문제 ⏱️ — 토큰이 많을수록 응답이 느려짐</li><li>메모리 문제 🧠 — 처리할 텍스트가 많으면 리소스 부담 증가</li><li>비용 문제 💰 — 토큰 요금 폭탄</li><li>품질 문제 🤔 — 너무 긴 context는 오히려 LLM의 답변 품질을 떨어뜨릴 수 있음</li></ul><blockquote>극단적으로 <strong>maxTokens</strong>를 10정도로 설정해보시면 답변이 오다가 잘리는 현상을 보실 수 있습니다.</blockquote><h4>ChatClient로 최종 요청 보내기</h4><p>이제 실제 사용자 질문과 시스템 프롬프트를 조합해 Claude에 요청을 보내는 부분입니다.</p><pre>ChatClient<br>    .builder(chatModel)<br>    .build()<br>    .prompt()<br>    .user(userPrompt)<br>    .system(systemPrompt)<br>//.advisors()<br>//.tools()<br>//.toolContext()<br>    .stream() // 또는 .call()<br>    .content()</pre><p><em>7~9 라인은 다음장에 소개할 기능이기 때문에 잠깐 주석처리 하겠습니다.</em></p><ul><li><strong>call()</strong> — 전체 응답을 한 번에 반환합니다.</li><li><strong>stream()</strong> — 응답을 스트리밍 형태로 받아, 사용자에게 <strong>빠르게 보여줄 수 있는 체감 속도 향상</strong>에 유리합니다.</li></ul><p>실측은 해보지 않았으나, 데이타 모두 전달하는 시간은 비슷할 것 같은데, 사용자 입장에서는 stream을 사용하는것이 답변이 빠르게 전달 되는 것처럼 느껴질 것 같습니다.</p><p>Configuration은 살짝 복잡할 수 있으나, Spring AI ..정말 간결하지 않나요?</p><p>예전에는 AWS SDK를 사용해 직접 Bedrock API 호출을 구현 한적이 있는데, 코드가 정말 복잡했습니다.</p><p>아래는 그 예시입니다.</p><pre>try {<br>    val userMessage = Message.builder()<br>        .content(ContentBlock.fromText(userQuery))<br>        .role(ConversationRole.USER)<br>        .build()<br><br>    val systemMessage = Message.builder()<br>        .content(ContentBlock.fromText(systemPrompt))<br>        .role(ConversationRole.SYSTEM)<br>        .build()<br><br>    val responseStreamHandler = ConverseStreamResponseHandler.builder()<br>        .subscriber(<br>            ConverseStreamResponseHandler.Visitor.builder()<br>                .onContentBlockDelta { chunk -&gt;<br>                    println(&quot;Response Text: ${chunk.delta().text()}&quot;)<br>                }.build()<br>        ).onError { err -&gt;<br>            logger.error(&quot;Error: ${err.message}&quot;)<br>        }.onComplete {<br>            println(&quot;Completed&quot;)<br>        }.build()<br><br>    bedrockRuntimeAsyncClient.converseStream({ request -&gt;<br>        request.modelId(ANTHROPIC_LLM_MODEL_ID)<br>            .messages(userMessage, systemMessage)<br>            .inferenceConfig {<br>                it.maxTokens(MAX_TOKEN)<br>                  .temperature(TEMP)<br>            }<br>    }, responseStreamHandler).get()<br><br>} catch (e: Exception) {<br>    logger.error(&quot;Error invoking LLM&quot;, e)<br>}</pre><p>Spring AI를 활용하면, 이처럼 복잡했던 흐름도 단 몇 줄로 간결하게 구현할 수 있습니다.</p><p>Generate LLM 단계는 지금까지의 모든 흐름인 검색, 필터링, Relevance, Prompt 조합을 마무리짓고 <strong>최종 사용자 응답을 생성하는 핵심 단계</strong>입니다.</p><p>이 구조가 하나의 서버 애플리케이션에서 유기적으로 돌아가며, 스푼봇의 응답 품질을 책임지고 있는 셈이죠.</p><h3>결과</h3><p>이렇게 총 6단계에 걸쳐 RAG 기반의 챗봇을 구축했고, 유관부서 협업으로 아래 화면처럼 서비스를 오픈하게 되었습니다. 🎉🎊🐳</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*CQzqYWPomUM4vC3v9QSd_Q.png" /><figcaption>쑥쑥 건강하게 커야한다!!</figcaption></figure><p>아직은 이제 막 세상에 나온 아기봇입니다. 🍼</p><p>조금 느리고, 가끔은 어설픈 대답도 하지만, 매일같이 고객지원팀이 모니터링하며 질문/답변을 보강해주며, 스푼봇도 계속해서 <strong>학습하고 성장 중</strong>입니다. 👶🤖</p><h3>마치며</h3><p>어떻게 보셨나요?</p><p>“<strong>생각보다 간단한데</strong>?“라고 느끼셨을 수도 있습니다. 사실 저도 처음에는 그렇게 생각했습니다.</p><p>이 방법이 맞는지 확신이 없어 적지 않은 강의를 듣고, 책이나 블로그를 찾아보고, 회사 동료들 질문공세로 괴롭히기도(🤪) 했고, 세미나까지 찾아다니며 해답을 얻기 위해 부단히 노력했었습니다.</p><p>물론 과정이 전혀 수월했던 것은 아니지만, 생각보다 매끄럽게 마무리되어 오히려 허무한 기분마저 들었습니다.</p><p>막상 해보면 단순해 보일 수도 있지만, 그만큼 여러 번의 시행착오와 배움이 있었기에 가능했던 결과라고 생각합니다.😜</p><p>따라서 이 포스트가 RAG를 도입하려는 개발자 분들께 작게나마 도움이 될 수 있다면 정말 기쁠 것 같습니다. 😊</p><p>이번 글에서는 6단계로 설명을 드렸지만, 향후 복잡한 질의까지 처리하기 위한 ‘<strong>사용자 질의 분해</strong>’ 기능까지 포함한다면, 7단계로 보는 것이 더 정확할 것 같습니다.</p><p>다만, 현재의 스푼봇은 아직 초기 단계에 있고, 앞으로 점점 확장되면서 더 복잡한 질의에도 멋지게 답변할 수 있도록 지속적으로 개선해 나갈 예정입니다.</p><p>그리고 다음 블로그에서는 어떤 내용을 다룰지 고민해보았습니다.</p><p>이번 글에서는 다루지 못했던 <strong>Spring AI 기반 Tools와 Advisor 기능 활용 사례</strong>를 소개하고, 가능하다면 ‘사용자 질의 분해’의 구현 방식과 MCP(Model Context Protocol)에 대해서도 함께 이야기해보려 합니다.</p><p>끝까지 읽어주셔서 감사합니다.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e96841c87979" width="1" height="1" alt=""><hr><p><a href="https://medium.com/spoontech/rag-%EB%8F%84%EC%9E%85%EA%B8%B0-%EC%B1%97%EB%B4%87%EC%9D%84-%EB%A7%8C%EB%93%A4%EB%8B%A4-%EC%A1%B0%EC%9A%A9%ED%9E%88-%EA%B7%B8%EB%A6%AC%EA%B3%A0-%EB%82%AD%EB%A7%8C%EC%A0%81%EC%9C%BC%EB%A1%9C-e96841c87979">RAG 도입기 — 챗봇을 만들다, 조용히 그리고 낭만적으로…</a> was originally published in <a href="https://medium.com/spoontech">SpoonLabs</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Serverless Postgres Neon으로 Next.js 환경에서 Short-URL 구현하기]]></title>
            <link>https://medium.com/spoontech/serverless-postgres-neon%EC%9C%BC%EB%A1%9C-next-js-%ED%99%98%EA%B2%BD%EC%97%90%EC%84%9C-short-url-%EA%B5%AC%ED%98%84%ED%95%98%EA%B8%B0-4367fbd95320?source=rss----bb1e592ad19a---4</link>
            <guid isPermaLink="false">https://medium.com/p/4367fbd95320</guid>
            <category><![CDATA[serverless]]></category>
            <category><![CDATA[nextjs]]></category>
            <category><![CDATA[tech]]></category>
            <dc:creator><![CDATA[Seoyong Lee]]></dc:creator>
            <pubDate>Fri, 14 Mar 2025 07:36:35 GMT</pubDate>
            <atom:updated>2025-03-14T07:36:35.656Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MJ_tMFKOog0TUSrIXKjN4Q.jpeg" /><figcaption>Photo by <a href="https://unsplash.com/ko/@steve_j">Steve Johnson</a> on <a href="https://unsplash.com/">Unsplash</a></figcaption></figure><p>안녕하세요. 스푼랩스 비글루 Client Team에서 프론트엔드 개발을 담당하고 있는 Drew(이서용)입니다. 비글루는 글로벌 숏폼 드라마 서비스로 다양한 콘텐츠를 쉽고 빠르게 즐길 수 있도록 iOS / Android 앱과 웹사이트에서 스트리밍 서비스를 제공하고 있습니다. 이번 글에서는 더 많은 사람들이 손쉽게 비글루 콘텐츠에 접근할 수 있도록 프론트엔드에서 서버리스 DB Neon을 이용해 간단한 커스텀 Short-URL을 구현하는 과정에 대해 다루었습니다.</p><h3>Short-URL 도입 계기</h3><p>기존 비글루 웹 서비스 콘텐츠 페이지 URL은 다음처럼 불필요하게 많은 정보를 노출하는 구조로 되어있어 가독성 및 보안 측면에서 적절하지 않았습니다.</p><pre>// 콘텐츠 URL<br>ex) www.video.com/ko/content/10001?season=10001&amp;episode=1</pre><p>이에 비해 타 서비스 웹 URL의 경우 UUID 형태로 정보를 숨기거나 마케팅 용도로 읽을 수 있도록 만드는 등, 유연하게 여러 가지 형태의 URL을 사용하고 있었습니다.</p><pre>// UUID 형태의 타 서비스 콘텐츠 URL<br>ex) www.video.com/content/1523cb9c-f1ad-41f1-81bc-2be08c92d381<br><br>// Semantic한 형태의 타 서비스 콘텐츠 URL<br>ex) www.play.com/ko/ep/41000110515_escape-with-boss-baby</pre><p>이를 보완하기 위해서는 실제 정보를 가진 원본 URL과 외부에 노출되는 URL의 구분이 필요하다는 사실을 알게 되었고, 자체적인 커스텀 Short-URL 도입을 검토하게 되었습니다.</p><pre>// 짧아진 Short-URL<br>ex) www.video.com/content/1fja491</pre><p>일반적으로 Short-URL은 다음 과정을 통해 구현됩니다.</p><h4>1. URL 단축</h4><p>먼저 원본 URL을 대체할 단축된 Short-URL을 생성합니다. Short-URL은 서로 충돌이 발생하지 않도록 crypto나 nanoid와 같은 난수 생성 패키지를 이용해 생성합니다. 생성된 URL은 이후 조회를 위해 서버 저장이 필요합니다.</p><h4>2. URL 조회</h4><p>이제 단축된 URL을 조회하여 실제 URL을 찾을 수 있도록 서버 요청을 구현합니다. 실제 URL로 단순히 Redirect 시킬 수도 있지만, Short-URL을 유지하면서 원본 URL 정보만 가져오고 싶다면 이를 API 요청을 통해 조회하도록 설정할 수도 있습니다.</p><h4>3. 추적 및 통계</h4><p>추가로 Short-URL 변환 시점에 클릭 수 등의 데이터를 수집하도록 설정할 수도 있습니다. 이는 기존 이벤트 트래킹 툴과 연동하면 보조적인 데이터로 활용이 가능합니다.</p><p>이제 구체적인 구현 방법에 대해 살펴보겠습니다.</p><h3>Vercel Storage와 Neon</h3><p>가장 먼저 찾아보았던 것은 Short-URL을 저장하고 불러올 수 있는 DB 서버에 대한 구현 방법이었습니다. 현재 비글루 웹 서비스는 서버사이드 렌더링을 지원하는 React 프레임워크 Next.js를 이용해 개발되었고, Vercel을 통해 배포하도록 구성하였습니다. Vercel의 경우 서비스의 배포뿐만 아니라 Analytics 및 Firewall 등 다양한 기능을 지원합니다. 이 중에서도 Storage 서비스는 서버리스 DB와의 연동을 지원하며 별도의 인프라 환경 구성없이 사용할 수 있다는 장점이 있어서 이를 사용해 보기로 하였습니다.</p><p>참고로 Vercel은 <a href="https://vercel.com/blog/framework-defined-infrastructure">Framework-Defined Infrastructure</a>(FDI)를 표방합니다. FDI는 프레임워크가 인프라 구성을 자동으로 관리하는 개념으로, 개발자가 애플리케이션 코드를 작성하면 해당 프레임워크가 필요한 인프라를 자동으로 설정, 배포, 관리하는 방식입니다. 기존 Infrastructure as Code(IaC)는 개발자가 직접 명시적으로 인프라를 정의하고 관리해야 했지만, FDI는 프레임워크 자체가 인프라 요구사항을 이해하고 자동으로 최적화된 설정을 적용합니다. 인프라가 프레임워크에 종속되는 것이 적절한지에 대해서는 여러 의견이 존재하지만 이에 대해서는 다른 글에서 자세히 다뤄보도록 하겠습니다.</p><p>Vercel Storage에서 자체적으로 제공하는 DB 구성은 다음과 같습니다.</p><ul><li>Edge Config: 저지연(low latency) 데이터 저장소로 읽기 속도가 빠르지만, 설정 저장 등에 더 적합합니다.</li><li>Blob: 객체(Object) 저장소로 이미지, 동영상 파일 저장에 적합합니다.</li></ul><p>위 2가지 DB는 Vercel 콘솔을 통해서 바로 사용이 가능하지만 Short-URL 구현에는 적합하지 않아 보입니다. 다음으로 Storage에서 연결을 제공하는 Marketplace Database Providers를 고려해 보았습니다. Marketplace는 각각 독립적인 제공업체로 구성되어 있으며 Vercel은 이를 쉽게 통합할 수 있도록 지원합니다.</p><ul><li>Neon: PostgreSQL 기반 Serverless DB로 Vercel과 네이티브 연동을 지원합니다.</li><li>Supabase: PostgreSQL 기반으로 Firebase와 비슷하며 Realtime Database 기능을 제공합니다.</li><li>Upstash: Redis 기반 Serverless DB입니다.</li></ul><p>Redis 기반의 Upstash의 경우 영구히 저장되어야 하는 URL 특성상 적합하지 않았고, supabase의 경우 Firebase와 비슷하지만 Short-URL 구현에 사용하기엔 오버스펙이라고 판단하였습니다. Neon의 경우 설정이 간편하고 완전한 serverless로 Short-URL 구현에 가장 적합하다고 생각되어 최종적으로 이를 선택하게 되었습니다.</p><p>Neon의 특징을 요약하면 다음과 같습니다.</p><ul><li>Serverless: 클라우드 환경에서 서버리스 방식으로 운영되며 사용하지 않으면 자동으로 Sleep 상태로 전환하여 비용 절감이 가능합니다.</li><li>Auto-Scaling: 사용량에 따라 자동으로 리소스 할당을 조절하며 트래픽이 급증하면 자동으로 스토리지를 확장합니다.</li><li>Database Branching: Git Branch와 비슷하게 데이터베이스 분기를 생성하고 병합할 수 있습니다. 이를 통해 환경에 따라 DB 복사본을 다르게 적용할 수 있습니다.</li><li>Point-in-Time Recovery: 과거 특정 시점으로의 롤백 기능을 지원합니다.</li><li>Read-Only Replicas: 읽기 전용 DB 복제본 생성이 가능하며 다중 리전을 지원합니다.</li></ul><p>그러나 다음의 단점도 존재합니다.</p><ul><li>Sleep 상태에서 활성화 시 초기 콜드 스타트 지연이 발생할 수 있습니다.</li><li>모든 PostgreSQL extension이 지원되는 것은 아닙니다.</li><li>트래픽이 불규칙할 경우 응답 속도 저하 가능성이 존재합니다.</li></ul><p>위 단점에도 불구하고 Neon은 간단한 서비스를 빠르게 테스트하기에는 적합하다고 생각됩니다. 이제 실제 연동을 진행해 보겠습니다.</p><h3>Neon 설정 및 DB 생성</h3><p>먼저 Vercel Storage에서 Neon 가입 및 DB 생성을 진행합니다.</p><figure><img alt="Vercel Storage 선택 화면" src="https://cdn-images-1.medium.com/max/1024/1*rZuD6xuOcdV548APwMVc1g.png" /><figcaption>Vercel Storage 선택 화면</figcaption></figure><p>회원가입을 진행하면 DB 생성 화면에서 Region과 Plan을 선택합니다. 한국이나 일본 Region은 없어서 가장 가까운 Singapore 리전을 선택하고 무료 플랜으로 생성을 진행하였습니다. 무료 플랜의 경우 10개의 브랜치와 브랜치 별로 500개의 databases, 0.5GB의 storage를 지원합니다.</p><figure><img alt="Neon DB 생성" src="https://cdn-images-1.medium.com/max/1024/1*xXcC1NSfppVrETTx4p6IBQ.png" /><figcaption>Neon DB 생성</figcaption></figure><p>생성을 완료하면 Vercel Storage 페이지에 Neon DB가 추가됩니다. Neon 콘솔로 직접 이동하면 더욱 자세한 설정을 확인할 수 있습니다. Neon 콘솔에선 사용량 모니터링 및 SQL Editor 등 다양한 기능을 지원합니다. 또한 BRANCH 섹션에서 직접 각 브랜치의 Schema와 Table을 설정할 수도 있습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*xXESdB-rqbBbR39QA5-YfQ.png" /><figcaption>Neon Tables Page</figcaption></figure><h3>Prisma 연동</h3><p>Prisma는 TypeScript 환경에서 사용할 수 있는 ORM(Object-Relational Mapping)으로 DB와의 직관적인 상호작용을 위해 사용합니다. Prisma는 특히 타입 안정성과 자동화된 마이그레이션 기능을 제공하며 API Routes등 Next.js의 다양한 기능과 결합이 용이한 것이 장점입니다.</p><p>이제 실제 코드에 Prisma를 적용해 보겠습니다.</p><h3>1. DB URL 환경변수 추가</h3><p>먼저 다음과 같이 환경변수에 DATABASE_URL을 추가합니다.</p><pre>DATABASE_URL=postgresql://user:password@host:port/database</pre><h3>2. Prisma 설정</h3><p>이후 prisma/schema.prisma 경로에 prisma 설정을 추가합니다.</p><pre>datasource db {<br>  provider = &quot;postgresql&quot;<br>  url      = env(&quot;DATABASE_URL&quot;)<br>}<br><br>generator client {<br>  provider = &quot;prisma-client-js&quot;<br>}<br><br>model ShortUrl {<br>  id          String   @id @default(uuid())<br>  shortId     String   @unique<br>  originalUrl String<br>  createdAt   DateTime @default(now())<br>}</pre><p>아래와 같이 간단한 모델도 추가하였습니다.</p><ul><li>id: UUID 기본값 (고유 ID)</li><li>shortId: 단축된 URL의 키 값 (예: abc123)</li><li>originalUrl: 원본 URL 저장</li><li>createdAt: 생성 시간</li></ul><h3>3. Prisma 마이그레이션 실행</h3><p>마지막으로 다음 명령어를 통해 Prisma 마이그레이션을 실행하면 Neon에 테이블이 자동으로 생성됩니다.</p><pre>npx prisma migrate dev --name init</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*CA1vWyBe4Ze7S8cCE6N4Ig.png" /></figure><h3>Next.js Short-URL 조회 및 생성</h3><p>이제 실제 클라이언트 환경에서 Short-URL을 조회하고 생성하도록 구성해 보겠습니다. 먼저 URL의 조회 및 생성 flow는 다음과 같이 구성하였습니다.</p><h4>1. Short-URL 생성</h4><p>API Route를 통해 커스텀 Short-URL 생성</p><ul><li>이미 생성된 Short-URL이 있다면 해당 URL 리턴</li><li>생성된 Short-URL이 없다면 생성 및 DB 저장 후 리턴</li></ul><h4>2. Short-URL 조회</h4><p>Short-URL로 페이지 진입</p><ul><li>DB Original-URL 정보 조회</li><li>조회한 정보를 기반으로 콘텐츠 UI 구성</li></ul><p>이러한 구조를 통해 브라우저에서 Short-URL 요청 시 Original-URL 정보를 조회하고, 이를 기반으로 원하는 컨텐츠를 정상적으로 출력하도록 하는 것이 최종적인 목표입니다.</p><p>이제 Next.js의 API Route를 이용해서 Short-URL 생성 API를 구현해 보겠습니다.</p><pre>// pages/api/shorten.ts<br><br>import { PrismaClient } from &#39;@prisma/client&#39;;<br>import { nanoid } from &#39;nanoid&#39;;<br>import type { NextApiRequest, NextApiResponse } from &#39;next&#39;;<br><br>const prisma = new PrismaClient();<br><br>// 쿼리 파라미터 함수<br>function getQueryParam(<br>  param: string | string[] | undefined,<br>): string | undefined {<br>  return Array.isArray(param) ? param[0] : param;<br>}<br><br>// Short-URL 조회 및 생성 함수<br>async function findOrCreateShortUrl(<br>  originalUrl: string,<br>  customId?: string,<br>): Promise&lt;{<br>  id: string;<br>  shortId: string;<br>  originalUrl: string;<br>  createdAt: Date;<br>}&gt; {<br>  // 1. 기존 short URL이 있는지 확인<br>  const shortUrlEntry = await prisma.shortUrl.findFirst({<br>    where: { originalUrl },<br>  });<br><br>  if (shortUrlEntry) return shortUrlEntry;<br><br>  // 2. 없으면 customId 사용 혹은 새로운 Short ID 생성<br>  const shortId = customId || nanoid(10);<br><br>  if (customId) {<br>    const existingEntry = await prisma.shortUrl.findUnique({<br>      where: { shortId: customId },<br>    });<br>    if (existingEntry) {<br>      throw new Error(&#39;Custom ID already in use&#39;);<br>    }<br>  }<br><br>  // 3. Short URL 생성 및 리턴<br>  return prisma.shortUrl.create({ data: { shortId, originalUrl } });<br>}<br><br>// handler 함수<br>export default async function handler(<br>  req: NextApiRequest,<br>  res: NextApiResponse,<br>): Promise&lt;string | undefined&gt; {<br>  if (req.method !== &#39;GET&#39;) {<br>    res.status(405).json({ error: &#39;Method not allowed&#39; });<br>    return;<br>  }  <br><br>  const url = getQueryParam(req.query.url);<br>  const customId = getQueryParam(req.query.customId);<br><br>  if (!url) {<br>    res.status(400).json({ error: &#39;Invalid URL&#39; });<br>    return;<br>  }<br><br>  try {<br>    const shortUrlEntry = await findOrCreateShortUrl(url, customId);<br>    res.status(200).json({ shortUrl: shortUrlEntry.shortId });<br>  } catch (error) {<br>    console.error(&#39;Error processing URL:&#39;, error);<br>    res.status(500).json({ error: &#39;Failed to process request&#39; });<br>  }<br>}</pre><p>위 코드의 동작은 다음과 같습니다.</p><ol><li>GET /api/shorten?url=&lt;originalUrl&gt; 요청을 받음</li><li>originalUrl을 기반으로 DB에서 shortId를 조회</li></ol><ul><li>기존 short URL이 있으면 해당 URL 리턴</li><li>없으면 새 short URL을 생성 후 리턴 (customId를 명시한 경우 이를 Short-URL로 사용)</li></ul><p>만들어진 커스텀 Short-URL은 Neon의 DB에서 바로 확인할 수 있습니다.</p><p>이제 page 컴포넌트에서 서버사이드에서 Short-URL을 조회하도록 구현해 보겠습니다. 정상적인 조회를 위해서는 먼저 현재 URL이 원본 URL인지, 아니면 Short-URL인지 구분이 필요했습니다. 이는 Dynamic Routes의 slug 값의 형태를 통해서 구분하도록 하였습니다. 또한 정책적으로 Original-URL의 [programId] slug는 <strong>8자리 숫자</strong>로만 구성된다고 가정하였습니다.</p><p>구분을 위해 isEightDigitNumber 함수를 정의합니다.</p><pre>// 8자리 숫자 정규식<br>const isEightDigitNumber = (str: string) =&gt; /^\d{8}$/.test(str);</pre><p>page 컴포넌트에서 getServerSideProps 함수를 통해서 Short-URL인 경우 DB를 조회하도록 합니다.</p><pre>// pages/video/[programId].tsx<br><br>export const getServerSideProps: GetServerSideProps = async ({<br>  req,<br>  locale,<br>  params,<br>}) =&gt; {<br>  const programId = params?.programId;<br><br>  // Next.js 내부 API 요청인 경우 Short URL 조회하지 않음<br>  const isNextJsInternalRequest = req.url?.includes(&#39;_next/data/&#39;);<br><br>  if (isNextJsInternalRequest) {<br>    return {<br>      props: {<br>        programData: null,<br>        locale,<br>      },<br>    };<br>  }<br><br>  let originalProgramId = programId;<br><br>  // 8자리 숫자인 경우 원본 URL로 간주, 그렇지 않으면 Short URL로 처리<br>  const isShortUrl =<br>    programId &amp;&amp;<br>    typeof programId === &#39;string&#39; &amp;&amp;<br>    !isEightDigitNumber(programId);<br><br><br>  if (isShortUrl) {<br>    // Short URL을 DB에서 조회하여 원본 URL 추출<br>    const shortUrlResponse = await prisma.shortUrl.findUnique({<br>      where: { shortId: programId },<br>    });<br><br>    if (shortUrlResponse) {<br>      originalProgramId = shortUrlResponse.originalUrl<br>        .split(&#39;video/&#39;)[1]<br>        ?.split(&#39;?&#39;)[0];<br>    }<br>  }<br><br>  // 프로그램 데이터를 가져오기<br>  const program = await getProgram(originalProgramId);<br><br>  return {<br>    props: {<br>      programData: JSON.stringify(program),<br>      locale,<br>    },<br>  };<br>};</pre><p>이를 통해 최종적으로 Short-URL 접근 시 콘텐츠 정보를 정상적으로 조회할 수 있도록 구현되었습니다.</p><blockquote>ex) Original-URL: www.video.com/video/10000001?season=10000001&amp;ep=1<br>ex) Short-URL: www.video.com/video/custom-url<br> - DB 조회를 통해 Original-URL의 programId 및 기타 정보 획득</blockquote><h3>마무리</h3><p>지금까지 프론트엔드 환경에서 Vercel 및 Neon을 이용해 Short-URL을 간단히 구현하는 방법에 대해 살펴보았습니다. 물론 정식 기능 개발을 위해서는 Neon은 부족한 부분이 있을 수 있습니다. 그러나 가벼운 기능 테스트를 진행하는 경우 Next.js 환경에서 쉽고 빠르게 데이터베이스를 연동할 수 있다는 점은 충분한 장점이라고 생각됩니다. 앞으로 프로젝트를 진행하면서 기회가 될 때마다 다양한 기능들을 사용해 볼 수 있기를 기대합니다.</p><h3>참고</h3><ul><li><a href="https://nextjs.org/docs/pages/building-your-application/routing/api-routes">Next.js — Routing: API Routes</a></li><li><a href="https://neon.tech/">Neon Serverless Postgres — Ship faster</a></li><li><a href="https://vercel.com/docs">Vercel Documentation</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4367fbd95320" width="1" height="1" alt=""><hr><p><a href="https://medium.com/spoontech/serverless-postgres-neon%EC%9C%BC%EB%A1%9C-next-js-%ED%99%98%EA%B2%BD%EC%97%90%EC%84%9C-short-url-%EA%B5%AC%ED%98%84%ED%95%98%EA%B8%B0-4367fbd95320">Serverless Postgres Neon으로 Next.js 환경에서 Short-URL 구현하기</a> was originally published in <a href="https://medium.com/spoontech">SpoonLabs</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>