네, 안녕하세요. 저희 디자인 시스템 이야기 AST와 MCP로 여는 미래 발표를 시작하겠습니다.

네, 안녕하세요. 이번 발표를 맡게 된 배민 공통서비스 웹프론트 개발팀 권현하 이상철입니다.

어, 저희는 우아 공방의 역사에 대해서 먼저 소개를 드리고 그 과정에서 생긴 문제점을 AST와 MCP를 적용하면서 해결해 나간 경험을 공유드린 다음에 우아 공방의 미래를 그려보는 것으로 진행하려고 합니다.

어, 먼저 우아 공방이란 무엇인지 소개를 드리려고 해요.

저희 우아 공방은 우아한형제들의 디자인 시스템이에요.

비즈니스의 성장에 맞는 유연하고 확장 가능한 구조를 갖추기 위해서 세 개의 계층으로 이루어져 있고 그 계층은 코어, 클레이, 몰드입니다.

먼저 코어는 우아 공방의 최소한의 규칙이라고 생각해 주시면 됩니다.

컬러나 타이포그래피 같은 재료에 해당하는 디자인 토큰들과 UX 라이팅 같은 사용성에 기반이 되는 지침들이 있고, 이 재료들로 최소한의 정의만 가지고 있는 코어 컴포넌트들이 있습니다.

그다음은 클레이와 몰드 계층입니다. 클레이는 서비스에 맞는 브랜드 아이덴티티와 사용성 그리고 최소한의 기준과 규칙을 가집니다.

저희 클레이는 블루와 민트 총 두 개로 나뉘어 있는데요.

블루는 사장님 서비스를 담당하고 있고 민트는 배달의민족 앱을 포함한 고객형 서비스를 담당하고 있습니다.

그리고 이러한 클레이를 바탕으로 각 팀 혹은 프로덕트에서 필요한 패턴들을 관리하는 몰드가 존재합니다.

저희 우화 공방은 디자인 시스템 TF 1기가 구성되어 2022년부터 구축되기 시작됐고 2023년 정식 버전 1버전이 배포되었습니다.

그리고 2024년에는 클레이 민트와 블루를 운영하는 것을 포함해서 각 프로덕트별로 몰드를 구성해 오다가 특히 백오피스 제작이 필요한 컴포넌트들을 모아둔 몰드 어드민 가이드를 제공하기 시작했습니다.

그래서 올해에는 민트, 블루 몰드 어드민 가이드를 사용하는 공식 문서와 스토리북, 서포트 채널, 피그마와 같은 가이드를 제공하고 피그마 플러그인, 크롬 익스텐션 같은 도구들을 제공하고 있습니다.

그렇게 우아한 공방이 런칭된 이후로 3년이 지나게 되었는데요.

어, 이번 발표를 준비하면서 저희가 운영하고 있던 서포트 채널을 되돌아봤어요.

저희는 서포트 티켓을 슬랙 채널을 통해서 받고 있고 그 문의 내용을 지라 티켓으로 자동으로 생성해서 담당자를 할당하며 관리를 하고 있었습니다.

왼쪽 차트를 보시면 3년 동안 들어온 서포트 문의가 엄청난 양이라는 것을 알 수 있습니다.

작년만 해도 벌써 1,300개에 다다르고 있고 올해 9월까지만 통계를 내봐도 1,000개에 다다르고 있습니다.

하지만 이 서포트 문의를 처리하는 웹 개발자는 많아야 네 명이었어요.

운영 개선만 해도 시간은 항상 부족했었죠.

이렇게 서포트 문의를 처리하다 보니 과연 우아공방은 잘 사용되고 있나라는 의문이 생기게 되었습니다.

어, 사용처에서 들어오는 다양한 문의들은 다음과 같아요.

이거 수정 부탁드립니다. 이거 어디 있나요?

이거 어떻게 하나요? 이거 추가해 주세요라는 문의들이에요. 이 문의들이 한 번의 일정에 겹쳐서 들어오게 되면 자연스럽게 특정 문의 건은 우선 순위에 따라 일정에 맞추지 못하는 경우가 생깁니다.

하지만 서비스를 개발하다 보면 일정에 맞춰서 꼭 적용해야 되는 경우가 있죠.

그래서 다음과 같은 서비스 개발이 진행되게 됩니다. 왼쪽 화면은 우아공방 언러 컴포넌트를 사용하는 샌드위치 프로덕트의 피그마 가이드입니다.

언러 컴포넌트의 초록색 부분인 헤더와 바디 콘텐츠가 이미 존재하고 주황색 부분인 디스크립션 영역이 아직 구현되지 않는 영역이라고 가정을 해 보겠습니다.

서비스 디자이너는 설명 영역이 필요하지만 업무 우선 순위에 따라서 일정 내에 우아한 공방의 가이드에 추가되지 못하니 우아 공방 컴포넌트를 디테치, 즉 우아한 공방 컴포넌트를 연결을 끊어서 새로운 커스텀 컴포넌트를 추가하게 됩니다.

그리고 해당 가이드는 그대로 서비스 개발자에게 전달되게 되죠.

그러면 서비스 개발자는 어떻게 프로덕트를 개발을 진행하게 될까요?

바로 무적의 디브 같은 커스텀 커스텀 태그가 등장하게 됩니다.

저희 가이드를 벗어난 특정 태그 컴포넌트를 커스텀하게 되죠.

예시를 보시면 스타일 또는 클래스 같은 것으로 사용자의 CSS가 추가가 됩니다.

그 이후에 저희 우아 공방에서 얼럿의 설명 영역을 추가하고 텍스트 컬러를 FGT이라는 디자인 토큰으로 영역을 구성하게 되어도 사용자에서는 앞에서 적용한 라인 스타일링 컬러가 적용되어 있어요.

음, 이번에는 얼럿의 설명 영역이 수정이 필요해지면 어떻게 될까요?

저희가 설명의 텍스트 컬러를 FG 컬터널이라는 다른 디자인 토큰으로 변경을 해도 사용처에서는 여전히 핵스값이 적용되어 있습니다.

그래서 앞선 예시와 같이 디자인에서는 우아 공방 컴포넌트에서 디테치된 컴포넌트들이 생기게 되고 개발에서는 DIV와 같은 커스텀 태그, 우아 공방 컴포넌트를 감싼 커스텀 컴포넌트들이 생겨나게 됩니다.

그렇게 되면 우아 공방이 디자인 업데이트나 버그픽스 같은 업데이트를 진행하게 되어도 사용처에서는 반영되지 않는 상황들이 발생되게 됩니다.

저희는 이런 문제점을 어떻게 해결해 갔는지를 앞으로 공유를 드리려고 합니다.

저희의 목표는 하나. 다시 우아 공방이 쓰이도록 하자는 것입니다.

이를 위해서 우아 공방 사용 현황을 분석하고 분석된 내용을 바탕으로 변화를 이끌어 나가고자 했습니다.

그래서 저희는 먼저 우아공방 애널리틱스를 만들었습니다.

저희의 니즈는 한눈에 우아공방 사용 현황을 보고 싶었고 그 현황을 바탕으로 어떻게 수정할지를 가이드를 드리려고 했습니다.

말 그대로 우아공방 사용 현황 분석 도구라고 생각해 주시면 됩니다.

앞으로 아뜰리에라는 단어를 자주 보실 수 있는데요.

아뜰리에는 우아공방의 영문 이름이라고 생각해 주시면 됩니다.

그러면 저희가 어떻게 분석을 진행하게 되었는지 설명을 드릴게요.

사용 현황 분석은 디자인단과 코드단을 나눠서 분석하게 됐습니다.

디자인은 피그마에서 디자인 토큰과 컴포넌트가 어떻게 사용되는지를 분석하고 개발에서는 코드에서 디자인 토큰과 컴포넌트가 어떻게 사용되는지를 분석했습니다.

먼저 피그마 분석의 시스템 흐름도를 살펴보겠습니다.

스트 JS 배치 서버에서 피그마 REST API를 통해서 피그마 데이터를 가져와서 분석하고 JSON으로 생성해서 S3 버킷에 업로드를 하고 있습니다.

그리고 리액트 대시보드 웹에서는 해당 JSON을 가져와 대시보드를 렌더링하고 있습니다.

어 앞서서 말씀드렸다시피 저희는 디자인 토큰과 컴포넌트가 잘 사용되는지를 확인하려고 하는데요.

먼저 디자인 토큰은 다음과 같은 항목들을 확인했습니다.

피그마 REST API의 응답 중에서 노드 정보를 활용해서 컬러의 필 스타일은 노드의 스타일스와 필을, 레이아웃의 스페이싱은 노드의 패딩과 아이템 스페이싱을, 타이포그래피의 텍스트 스타일은 노드의 스타일즈의 텍스트를, 셰이프의 레디어스와 섀도우 스타일은 노드의 코너 레디어스와 이펙트 스타일을 확인했습니다.

그리고 컴포넌트를 사용하는지는 비교적 쉬웠는데요. 저희 디자인 직군에서 우아 공방 컴포넌트의 경우에만 이모지 또는 특수 문자로 시작하도록 약속이 되어 있기 때문에 노드의 네임이 이모지 또는 특수 문자로 시작하는지를 확인하면 됐습니다.

저희는 이 분석을 바탕으로 피그마에서 우아한 공방 컴포넌트가 아닌 것들을 쉽게 볼 수 있게 하기 위해 피그마 플러그인도 개발했습니다.

피그마 플러그인은 간단하게 얘기하자면 피그마 내부에서 실행되는 JS 기반 확장 프로그램입니다.

오른쪽 플러그인 화면과 같이 UI와 로직을 자유롭게 구성할 수 있고 그 안에서 피그마 데이터를 가공하고 피그마 UI를 변경하실 수 있습니다.

그래서 앞서 분석된 JSON에서 노드들의 아이디를 가져와서 해당 노드들을 하이라이팅하는 피그마 플러그인을 개발하게 됐습니다.

왼쪽 예시 피그마를 보시면 전체 선택과 선택 삭제 버튼이 하이라이팅된 모습을 보실 수 있습니다.

이번엔 코드 단의 시스템 흐름도를 공유드리겠습니다.

GitLab CI/CD에서 스케줄 트리거를 통해서 우아공방 패키지를 사용하는 저장소 리스트를 사내 서버에 요청해서 가져오고, 그 저장소들을 반복문을 돌면서 분석을 진행했습니다.

그리고 분석된 내용을 JSON으로 만들어 마찬가지로 S3에 업로드를 하고 해당 JSON을 대시보드 웹에서 가져와 렌더링하게 됩니다.

저희는 코드를 분석하기 위해서 아뜰리에 트래커라는 라이브러리를 만들게 되었습니다.

해당 라이브러리에서는 임포트 분석을 통해서 어떤 컴포넌트가 얼마나 사용되는지를 확인하고 디자인 토큰 사용 현황을 분석해서 디자인 토큰과 하드코딩을 정량적으로 측정했습니다.

코드 분석을 위해서는 추상 구문 트리인 AST가 필요했어요. 그래서 AST를 분석할 수 있는 Babel Parser와 Babel Traversal을 이용하게 되었습니다.

어, 이제는 추상 구문 트리의 간단한 예제를 보여드리려고 합니다. 왼쪽은 사용처에서 쉽게 볼 수 있는 우아 공방 코드를 사용하는 모습입니다.

그리고 오른쪽은 추상 구문 트리의 전체적인 구조입니다. 어, 오른쪽에서 바디 부분에 코드가 변환된 내용이 들어가게 됩니다.

먼저 첫 번째 줄인 우아 공방 컴포넌트를 임포트하는 코드를 추상 구문 트리로 변환된 모습을 보면 임포트 디클레어레이션이라는 타입으로 아뜰리에의 민트와 버튼 객체가 잘 추출된 것을 볼 수 있습니다.

다음으로 두 번째 줄인 우아 공방 디자인 토큰을 임포트하는 코드는 마찬가지로 임포트 디클레어레이션이라는 타입으로 임포트 경로와 임포트한 값이 버스가 잘 추출된 모습을 보실 수 있습니다.

마지막으로 직접 디자인 토큰을 사용하는 세 번째 라인을 보겠습니다.

오른쪽과 같이 베리어블 디클레어레이션 타입으로 각각의 항목들이 잘 추출된 모습을 보실 수 있습니다.

저희는 이 추상 구문 트리를 비지터 패턴으로 모든 노드를 방문하면서 분석을 진행했습니다.

비지터 패턴은 간단하게 말씀드리면 트리의 모든 노드를 방문하면서 특정 노드 타입을 만날 때마다 콜백 함수가 실행되는 것입니다.

그래서 바벨이 이 추상 구문 트리를 순회하면서 임포트 디클러레이션, 멤버 익스프레션, JSX 어트리뷰트라는 콜백 함수를 실행하게 되고 그 안에서 저희는 임포트 구문을 감지하고 디자인 토큰 사용을 감지하고 하드코딩된 스타일 값을 감지했습니다.

그 결과로 우아공방 디자인 토큰과 하드코딩된 스타일 값의 수치를 확인할 수 있었고 하드코딩된 스타일 코드 정보 즉 파일명, 코드라인 값과 같은 정보를 수집할 수 있었습니다.

저희는 이렇게 분석에 그치지 않고 직접 수정까지 진행을 하려고 했어요.

올해 우아공방에서 마이그레이션을 쉽게 해 주는 자동화 도구인 코드 모드를 개발을 했었는데요.

이 도구를 사용하면 대화형으로 마이그레이션을 진행하면서 다양한 트랜스폼으로 코드를 변환하고 변환한 코드를 커밋까지 실행해 주는 도구를 개발했습니다.

이 코드 모드는 오른쪽과 같이 MPX 명령어로 쉽게 실행할 수 있습니다.

그래서 트래커를 통해 코드를 분석하고 분석한 정보를 코드 모드에게 넘겨서 수집한 코드를 변환까지 실행하게 됩니다.

해당 코드 모드를 터미널에서 실행하게 되면 명령어로 넘겨준 경로를 탐색하면서 하드코딩된 컬러가 있는지를 검사하고 직접 수정을 한 후에 커밋 메시지까지 작성해 주는 모습을 보실 수 있습니다.

그래서 이 결과 화면과 같이 하드코딩된 스타일들이 디자인 토큰으로 잘 변경되는 모습을 보실 수 있습니다.

그리고 이렇게 분석된 내용을 한 눈에 확인할 수 있게 대시보드 웹에서 차트로 시각화하고 있습니다.

이런 일련의 분석 과정을 통해서 저희는 세 가지를 이루어내게 됐습니다.

피그마 데이터와 AST 기반의 코드 분석으로 정량적 측정이 가능하게 되었고, GitLab CI/CD와 배치 프로세스로 수동 작업 없이 정기적인 분석을 가능하게 했고, 연결이 끊어진 코드를 우아한 공방 표준으로 다시 되돌리는 계기를 만들었습니다.

이렇게 문제를 해결해 나가는 과정에서 이 문제를 다른 관점으로 상황을 바라보고 해결 방안을 제시해 주신 팀원이 계십니다.

그분을 무대로 모시겠습니다. >> 저는 앞에서 현아님이 이제 다양한 방법으로 현재의 문제점을 어떻게 해결할지에 대해서 설명을 해 주셨다면은 저는 애초에 조금 다른 방법으로 처리를 해 보면 어떨까라고 생각을 해서 이후의 세션을 진행하게 되었습니다.

그래서 제가 생각했던 것들은 애초에 질문이 없으면 안 될까?

답변을 자동화할 순 없을까라고 생각을 하게 되었어요.

그래서 문제를 한번 다시 정의해 보려고 합니다.

첫 번째는 우아 공방에 문의가 많이 들어온다는 점이고요.

두 번째는 우아한 공방과 연결이 끊어진 컴포넌트가 늘어난다는 점입니다.

첫 번째, 우아 공방에 문의가 많이 들어온다는 것은 어떤 문의가 들어오는지 확인을 해보니 대부분은 버그 혹은 사용성 문의였습니다.

사용성 문의를 한번 확인해 보도록 할게요. 우아 공방에는 90개가 넘는 컴포넌트가 있고 각각의 컴포넌트마다 타입스크립트와 스토리북, 마크다운으로 세 가지 종류의 가이드라인이 있습니다.

당연해진 디자인시스템, 그다음 이야기: AST와 MCP로 여는 미래 #우아콘2025 #우아한형제들

우아한형제들의 기술조직 이야기를 전하는 우아한테크입니다.

우아한형제들 https://www.woowahan.com/
우아한테크 Facebook https://www.facebook.com/woowahanTech
우아한형제들 기술블로그 https://techblog.woowahan.com

우아한테크

우아한형제들의 디자인 시스템 '우아 공방'은 코어, 클레이(블루/민트), 몰드 세 계층으로 이루어져 있으며, 3년간의 운영을 통해 누적된 대량의 서포트 문의와 끊어진 컴포넌트 연결 문제가 발생했습니다.

AST(추상 구문 트리) 기반의 코드 분석 도구인 '우아공방 애널리틱스'와 '코드 모드'를 개발하여, 피그마와 코드에서 디자인 토큰 및 컴포넌트 사용 현황을 정량적으로 측정하고, 하드코딩된 스타일을 디자인 토큰으로 자동 변환하여 끊어진 연결 문제를 해결했습니다.

MCP(모델 컨텍스트 프로토콜)를 활용하여 우아 공방의 흩어진 정보(공식 문서, 피그마, 스토리북)를 통합하고, AI 에이전트가 해당 맥락을 기반으로 사용성 문의에 자동 응답하며, 컴포넌트 코드 자동 생성 및 변환을 지원하여 개발자의 편의성을 높였습니다.

우아한 공방 소개: 디자인 시스템의 역사와 구조

본 발표에서는 **우아한 공방의 역사와 그 과정에서 발생한 문제점들을 AST와 MCP를 통해 해결해 나간 경험**을 공유하고, 우아한 공방의 미래를 그려보고자 합니다. 우아한 공방은 우아한형제들의 디자인 시스템으로, 비즈니스 성장에 맞춰 유연하고 확장 가능한 구조를 갖추기 위해 코어, 클레이, 몰드 세 계층으로 이루어져 있습니다.

**코어는 디자인 토큰(컬러, 타이포그래피)과 UX 라이팅 지침을 포함한 최소한의 규칙**을 담고 있으며, 클레이는 서비스별 브랜드 아이덴티티와 사용성을 반영합니다. 클레이는 사장님 서비스를 위한 '블루'와 배달의민족 앱을 포함한 고객형 서비스를 위한 '민트'로 나뉘며, 각 팀이나 프로덕트에서 필요한 패턴을 관리하는 '몰드'가 이를 기반으로 존재합니다.

우아한 공방은 2022년부터 구축되어 2023년에 정식 버전 1이 배포되었으며, 2024년에는 클레이 민트와 블루 운영을 포함하여 **각 프로덕트별 몰드를 구성하고, 특히 백오피스 제작에 필요한 컴포넌트들을 모아둔 몰드 어드민 가이드를 제공**하기 시작했습니다. 현재는 공식 문서, 스토리북, 서포트 채널, 피그마 가이드와 함께 피그마 플러그인, 크롬 익스텐션 등의 도구를 제공하고 있습니다.

우아한 공방 운영의 어려움과 문제점

우아한 공방 런칭 이후 3년간 서포트 채널에는 **엄청난 양의 문의가 접수**되었습니다. 작년에만 1,300개, 올해 9월까지 1,000개에 달하는 문의가 있었으나, 이를 처리하는 웹 개발자는 최대 네 명에 불과하여 운영 개선에 항상 시간이 부족했습니다.

다양한 문의는 주로 수정, 위치 확인, 사용 방법, 추가 요청 등으로 구성되며, **우선순위에 따라 특정 문의가 제때 처리되지 못하는 경우**가 발생합니다. 서비스 개발 시 일정에 맞춰 꼭 적용해야 하는 상황이 많기 때문에, 이는 심각한 문제로 이어집니다.

예를 들어, 디자이너는 우아한 공방 컴포넌트에 필요한 설명 영역이 일정 내에 추가되지 않으면 **기존 컴포넌트를 디태치(연결 끊기)하고 새로운 커스텀 컴포넌트를 추가**하게 됩니다. 이는 서비스 개발자에게 그대로 전달되어 `<div>`와 같은 커스텀 태그나 스타일로 이어집니다.

결과적으로 우아한 공방에서 디자인 업데이트나 버그 픽스를 진행해도 **사용처에서는 해당 변경 사항이 반영되지 않는 문제**가 발생합니다. 이는 디자인 시스템의 일관성을 해치고 유지보수를 어렵게 만듭니다.

문제 해결을 위한 AST 기반 분석 및 자동화

저희의 목표는 **다시 우아한 공방이 활발하게 사용되도록 하는 것**이었습니다. 이를 위해 우아한 공방 사용 현황을 분석하고, 분석된 내용을 바탕으로 변화를 이끌어 나가기 위해 '우아한 공방 애널리틱스'를 개발했습니다. 이는 우아한 공방의 사용 현황을 한눈에 보고 수정 가이드를 제공하는 분석 도구입니다.

사용 현황 분석은 디자인과 코드 단으로 나누어 진행했습니다. **디자인은 피그마에서 디자인 토큰과 컴포넌트 사용을, 개발은 코드에서 디자인 토큰과 컴포넌트 사용을 분석**했습니다. 피그마 분석은 REST API를 통해 데이터를 가져와 JSON으로 생성하고 S3에 업로드한 뒤, 리액트 대시보드 웹에서 렌더링하는 방식으로 이루어졌습니다.

디자인 토큰 사용은 피그마 REST API 응답 중 노드 정보를 활용하여 컬러, 레이아웃, 타이포그래피, 셰이프 스타일 등을 확인했습니다. 컴포넌트 사용 여부는 **디자인 직군에서 우아한 공방 컴포넌트에만 이모지 또는 특수 문자로 시작하도록 약속했기 때문에, 노드 이름으로 쉽게 확인**할 수 있었습니다.

이 분석을 바탕으로 **피그마에서 우아한 공방 컴포넌트가 아닌 요소를 쉽게 볼 수 있도록 피그마 플러그인을 개발**했습니다. 이 플러그인은 피그마 내부에서 실행되는 JS 기반 확장 프로그램으로, 분석된 JSON에서 노드 ID를 가져와 해당 노드를 하이라이팅합니다.

코드 단 분석을 위해 GitLab CI/CD의 스케줄 트리거를 활용, 우아한 공방 패키지를 사용하는 저장소들을 반복 분석하고 JSON으로 S3에 업로드한 뒤 대시보드 웹에서 렌더링합니다. 이를 위해 **`아뜰리에 트래커` 라이브러리를 개발하여 임포트 분석, 디자인 토큰 사용 현황, 하드코딩 정량적 측정** 등을 수행했습니다.

코드 분석의 핵심은 **추상 구문 트리(AST)를 활용하는 것**이었습니다. Babel Parser와 Babel Traversal을 이용하여 AST를 분석하고, 비지터 패턴으로 모든 노드를 방문하며 임포트 구문, 디자인 토큰 사용, 하드코딩된 스타일 값을 감지했습니다.

그 결과, **우아한 공방 디자인 토큰과 하드코딩된 스타일 값의 수치를 확인**하고, 하드코딩된 스타일 코드(파일명, 코드 라인 등) 정보를 수집할 수 있었습니다. 또한, 분석에 그치지 않고 직접 수정을 위해 **`코드 모드`라는 자동화 도구를 개발**했습니다. 이 도구는 대화형으로 마이그레이션을 진행하며 코드를 변환하고 커밋까지 실행합니다.

이러한 과정을 통해 피그마 데이터와 AST 기반의 코드 분석으로 정량적 측정이 가능해졌고, GitLab CI/CD와 배치 프로세스로 수동 작업 없이 정기적인 분석이 가능해졌으며, **연결이 끊어졌던 코드를 우아한 공방 표준으로 되돌리는 계기**를 마련했습니다.

MCP를 활용한 정보 통합 및 코드 자동 생성

기존 문제점들을 해결하기 위한 다른 접근 방식으로 **"애초에 질문이 없거나 답변을 자동화할 수는 없을까?"** 라는 고민에서 시작되었습니다. 우아한 공방에 문의가 많고 연결이 끊어진 컴포넌트가 늘어나는 두 가지 주요 문제를 다시 정의했습니다.

대부분의 문의는 버그나 사용성 문의였는데, **90개가 넘는 컴포넌트와 각각 세 종류의 가이드라인(타입스크립트, 스토리북, 마크다운), 그리고 다양한 컴포넌트 형태와 콤보 가이드라인으로 인해 사용성 혼란**이 발생했습니다. 따라서 '흩어진 정보를 통합하면 어떨까'라는 결론에 도달했습니다.

연결이 끊어진 컴포넌트 문제의 근원은 **수많은 가이드를 지키는 컴포넌트 작성에 많은 시간과 관심이 소요**되기 때문입니다. 서비스 개발자는 기획서에 맞는 컴포넌트를 찾지 못하거나 없다고 판단하면 우아한 공방 컴포넌트를 확장하게 되고, 결국 원래 컴포넌트가 존재했음을 뒤늦게 알게 되는 상황이 반복됩니다. 이는 검색의 어려움과 정보 과다로 인한 문제였습니다. 따라서 '해당 맥락에 맞는 코드를 자동 생성해 주면 어떨까'라고 생각하게 되었습니다.

**정보 통합과 코드 자동 생성을 위해 모델 컨텍스트 프로토콜(MCP)**이라는 개념을 도입했습니다. AI 에이전트가 우아한 공방에 대한 개발을 할 때, 내부 시스템의 맥락을 정확히 파악할 수 있도록 MCP를 통해 리소스, 툴, 프롬프트라는 개념을 제공하여 우아한 공방의 맥락을 부여하고 자동으로 코드를 생성하는 것이 핵심입니다.

MCP는 **공식 문서, 피그마 디자인 가이드, 스토리북의 예제 및 사용법 등 흩어진 우아한 공방의 모든 정보들을 통합**했습니다. 웹사이트 파싱의 어려움을 해결하기 위해 Microsoft의 오픈소스인 `Markitdown`을 활용하여 HTML, PDF, 이미지 등을 마크다운 문서로 추출했습니다. 스토리북의 예제들은 모든 컴포넌트의 타입 명세로 존재했기에, 모노레포 구조를 활용하여 도메인별 빌드 결과를 MCP로 묶었습니다.

MCP 하위에 **다양한 디클레어 파일과 마크다운 파일, 체인지 로그와 같은 정적 데이터들을 에셋으로 모았습니다.** 이는 우아한 공방을 만들면서 발생했던 3년간의 수많은 양질의 자산으로, MCP 구축에 큰 도움이 되었습니다.

MCP 서버 인스턴스를 구축하고 리소스를 연결하여 `URI` 스킴을 통해 우아한 공방 공통 규칙 등의 정보를 제공합니다. 이를 통해 **AI 에이전트는 `URI` 스킴으로 파일을 읽어 우아한 공방의 디자인 시스템 사용 규칙을 설명**해 줄 수 있게 되어 흩어진 정보 통합 문제를 해결했습니다.

하지만 리소스 연결만으로는 검색이 잘 안 되는 문제점이 있어, **AI가 MCP에 직접 요청하도록 `툴스` 개념을 추가**했습니다. 툴스는 함수나 API처럼 행동을 수행하며, AI 에이전트가 이를 실행하여 값을 응답합니다. `겟 룰스`와 같은 툴을 통해 AI 에이전트가 MCP의 공통 규칙 리소스를 명확하게 호출하고 정보를 받을 수 있게 되었습니다.

더 나아가 **키워드 매칭을 강화하기 위해 레벤슈타인 거리 알고리즘, 약어 매칭, 한영 매칭 등을 활용**하여 `서치 시밀러 컴포넌트` 툴을 개발했습니다. 이 툴은 오타나 약어에도 불구하고 유사한 컴포넌트를 찾아 AI 에이전트가 정확한 정보를 제공하도록 돕습니다.

정보 통합 후에는 자동 코드 생성을 목표로 했습니다. AI 에이전트가 우아한 공방의 맥락을 이해하도록 **MCP 하위에 각 도메인에 맞는 상세한 `룰(가이드라인)`을 작성**했습니다. 대시보드형 페이지 가이드, UX 라이팅, 특정 HTML 컴포넌트 대신 우아한 공방 컴포넌트 사용 지침 등을 추가하여 AI 에이전트가 우리의 디자인 규칙에 맞춰 코드를 생성하도록 유도했습니다.

결과적으로 **AI 에이전트는 가이드라인에 맞춰 `1만 포인트`를 한글 숫자 표기 지향으로 수정하거나, 피그마 디자인을 민트 컴포넌트로 구현할 때 우아한 공방의 디자인 시스템 규칙을 따라 코드를 생성**하게 되었습니다. 이는 일관된 규칙 적용, 무작위 디버깅 회피, 디자인 토큰의 적극적 활용을 통해 피그마 디자인과 우아한 공방 컴포넌트를 일대일로 매핑하여 정확하게 만들 수 있게 했습니다.

마지막으로 **`프롬프트` 기능을 활용하여 AI 에이전트에게 명확한 지침서를 제공**했습니다. 툴스가 단건 호출이라면 프롬프트는 특정 맥락과 동작 패턴을 미리 설정하는 것으로, AI 에이전트가 코드 모드와 같은 변환 도구를 사용할 때 **명세서를 정확히 몰라도 자동으로 필요한 트랜스폼 옵션을 추론하여 실행**하도록 했습니다. 이를 통해 서비스 개발자들은 훨씬 더 쉽고 추상적으로 코드를 작성할 수 있게 되었습니다.

결론: AST와 MCP로 여는 우아한 공방의 미래

우아한 공방은 AST와 코드 모드를 통해 **사용처와 컴포넌트가 끊어진 문제를 해결**하고, MCP를 통해 자연스러운 답변과 코드 변환 자동화로 **문의 발생 문제를 효과적으로 해결**할 수 있었습니다.

저희는 '세상 모든 것이 식지 않도록'이라는 우아한형제들의 미션처럼, **모든 서비스가 우아한 공방이 되도록 노력**하고 있으며, 그 여정을 AST와 MCP로 앞으로도 이어나갈 것입니다.

우아한형제들의 디자인 시스템인 '우아 공방'이 런칭 3년 만에 겪게 된 주요 문제점들은 무엇인가요?

우아 공방의 'AST(추상 구문 트리) 기반 코드 분석'이 디자인 시스템의 사용 현황을 분석하고 개선하는 데 어떻게 활용되었는지 설명해주세요.

발표에서 언급된 'MCP(모델 컨텍스트 프로토콜)'가 흩어진 정보를 통합하고 코드를 자동 생성하는 데 어떤 역할을 하는지 구체적인 예시와 함께 설명해주세요.

MCP의 세 가지 주요 구성 요소(리소스, 툴, 프롬프트)는 각각 어떤 역할을 하며, 이들이 결합되어 디자인 시스템 활용도를 높이는 방식은 무엇인가요?

AST와 MCP를 통한 우아 공방의 개선 노력은 서비스 개발자들에게 어떤 이점을 제공하며, 궁극적으로 '우아한형제들의 모든 것이 우아한 공방이 되도록'이라는 목표 달성에 어떻게 기여하나요?

발표는 우아공방의 역사와 문제점, AST 및 MCP 적용 경험, 미래 계획 순으로 진행될 예정입니다.

우아공방은 우아한형제들의 디자인 시스템으로, 코어, 클레이, 몰드 세 개의 계층으로 이루어져 있습니다.

코어는 디자인 토큰 및 UX 라이팅 지침과 최소한의 코어 컴포넌트를 포함합니다.

클레이는 서비스별 브랜드 아이덴티티와 사용성 기준을 가지며(블루: 사장님 서비스, 민트: 고객 서비스), 몰드는 각 팀/프로덕트의 패턴을 관리합니다.

우아공방은 2022년부터 구축되어 2023년 정식 버전 1이 배포되었고, 2024년에는 몰드 어드민 가이드, 공식 문서, 스토리북, 피그마 플러그인 등 다양한 도구를 제공하고 있습니다.

우아공방 런칭 3년 후 서포트 채널(슬랙, 지라 티켓)을 되돌아보니 엄청난 양의 문의(작년 1,300개, 올해 9월까지 1,000개)가 접수되었습니다.

소수의 개발자가 많은 문의를 처리해야 했기에 운영 개선에 어려움이 있었고, 우아공방의 활용도에 의문이 생겼습니다.

주요 문의는 컴포넌트 수정, 위치, 사용법, 추가 요청 등이며, 일정 조율의 어려움으로 특정 문의는 지연될 수밖에 없었습니다.

서비스 디자이너는 필요한 컴포넌트가 일정 내에 추가되지 않으면 우아공방 컴포넌트를 '디테치'하여 커스텀 컴포넌트를 추가하게 됩니다.

서비스 개발자는 커스텀 태그(예: div)나 인라인 스타일링, CSS 추가 등으로 우아공방 가이드에서 벗어난 커스텀 개발을 진행합니다.

이로 인해 우아공방에서 컴포넌트가 업데이트되거나 디자인 토큰이 변경되어도, 사용자 측에서는 하드코딩된 스타일이 그대로 유지되어 반영되지 않는 문제가 발생합니다.

문제 해결 목표 및 애널리틱스 구축

목표는 '다시 우아공방이 쓰이도록' 하는 것이며, 이를 위해 사용 현황을 분석하고 변화를 이끌어내고자 했습니다.

우아공방 애널리틱스('아뜰리에'로 명명)를 구축하여 우아공방 사용 현황을 한눈에 파악하고 수정 가이드를 제공하는 것이 목표입니다.

사용 현황 분석은 디자인(피그마)과 코드(개발) 단으로 나누어 진행되었습니다.

피그마 REST API를 통해 데이터를 가져와 분석하고 JSON으로 S3에 업로드, React 대시보드 웹에서 렌더링하는 시스템 흐름입니다.

디자인 토큰(컬러, 레이아웃, 타이포그래피, 셰이프) 사용 여부를 피그마 노드 정보를 활용하여 확인했습니다.

컴포넌트 사용 여부는 우아공방 컴포넌트가 이모지/특수문자로 시작한다는 약속을 활용하여 노드 이름으로 확인했습니다.

분석 결과를 바탕으로 우아공방 컴포넌트가 아닌 것을 쉽게 식별하도록 피그마 플러그인을 개발했습니다.

AST 기반 코드 사용 현황 분석 및 자동 수정

GitLab CI/CD 스케줄 트리거를 통해 우아공방 패키지 사용 저장소들을 분석하고 JSON으로 S3에 업로드 후 대시보드 웹에서 렌더링합니다.

아뜰리에 트래커 라이브러리를 개발하여 임포트 분석으로 컴포넌트 사용량, 디자인 토큰 사용 현황, 하드코딩 정량적 측정, 하드코딩 코드 정보 수집을 진행했습니다.

코드 분석을 위해 Babel Parser와 Babel Traversal을 이용하여 추상 구문 트리(AST)를 분석했습니다.

AST 변환 예시를 통해 임포트 구문, 디자인 토큰 사용, 하드코딩된 스타일 값 감지 원리를 설명했습니다.

비지터 패턴을 활용하여 AST의 모든 노드를 방문하며 임포트, 디자인 토큰 사용, 하드코딩 스타일 값을 감지했습니다.

분석에 그치지 않고 코드 모드(자동화 도구)를 개발하여 하드코딩된 스타일을 디자인 토큰으로 변환하는 자동 수정 기능을 구현했습니다.

분석된 내용은 대시보드 웹에서 차트로 시각화하여 한눈에 확인할 수 있도록 했습니다.

이러한 분석 과정을 통해 정량적 측정, 정기적 분석, 그리고 연결이 끊어진 코드를 우아공방 표준으로 되돌리는 계기를 마련했습니다.

MCP를 활용한 문제 해결 및 자동화

다른 관점으로 접근하여 '애초에 질문이 없으면 안 될까?', '답변을 자동화할 순 없을까?'라는 질문에서 시작했습니다.

두 가지 문제점은 우아공방 문의량 과다(버그, 사용성 문의)와 연결 끊어진 컴포넌트 증가였습니다.

많은 컴포넌트와 다양한 가이드라인(타입스크립트, 스토리북, 마크다운, 콤보 가이드라인)으로 인해 개발자들이 사용성 혼란을 겪고 있습니다.

첫 번째 문제는 흩어진 정보를 통합하는 것으로 해결하고자 합니다.

두 번째 문제는 컴포넌트 작성의 어려움과 검색의 비효율성으로 인해 '연결이 끊어진 컴포넌트'가 발생합니다.

두 번째 문제는 맥락에 맞는 코드를 자동 생성하여 해결하고자 합니다.

MCP(Model Context Protocol)는 AI 앱에 우아공방의 맥락을 제공하여 자동 생성을 가능하게 하는 개념입니다.

MCP를 통해 AI에게 우아공방 맥락을 제공하고 자동으로 코드를 생성하는 것이 핵심입니다.

피그마 링크를 기반으로 MCP를 호출하여 디자인 확인, 우아공방 컴포넌트 확인 및 조합, 코드 생성을 통해 피그마 디자인을 우아공방 컴포넌트로 구현하는 예시를 제시했습니다.

우아공방 정보 통합 (MCP 리소스)

우아공방의 정보는 공식 문서, 피그마 디자인 가이드, 스토리북 예제 및 사용법에 흩어져 있었습니다.

웹사이트 파싱의 어려움(HTML 구조 변경)을 해결하기 위해 마이크로소프트의 오픈소스 'Markitdown'을 활용하여 PDF, HTML, 이미지를 마크다운 문서로 추출했습니다.

피그마 또한 PDF 추출 후 마크다운 파일로 변환했으며, 스토리북 예제는 타입 명세(모노레포 빌드 결과)를 활용했습니다.

MCP 하위 에셋으로 다양한 선언 파일, 마크다운 파일, 변경 로그 등 정적 데이터들을 모아 통합했습니다.

MCP 서버 인스턴스를 구축하고 리소스를 연결하여 URI 스킴으로 파일 시스템의 데이터를 읽어 응답하는 방식을 설명했습니다.

AI 에이전트가 MCP의 리소스를 검색하여 우아공방 공통 규칙을 설명해 줄 수 있게 되었습니다.

MCP 툴스를 통한 검색 강화 및 코드 자동 생성

리소스 연결만으로는 검색이 잘 안 되는 문제점이 발견되어, AI가 정보를 MCP에 직접 요청하도록 툴스 개념을 도입했습니다.

툴스는 함수나 API처럼 행동을 수행하며, AI 에이전트가 툴을 실행하고 그 값을 응답으로 받습니다.

툴스에 예상 질문과 행동을 작성하고 그 값을 정보로 리소스를 넘겨줌으로써 AI의 정보 요청을 명확하게 만들었습니다.

이제 '우아공방 MCP의 공통 규칙을 알려줘'라고 질의하면 AI는 리소스 참조 대신 '겟 룰스' 툴을 명확하게 호출합니다.

'우항공방 텍스트 인풋 컴포넌트에 대해 설명해 줘'와 같은 질문에도 '서치 컴포넌트' 툴을 호출하여 맥락 있는 설명을 제공할 수 있습니다.

키워드 매칭 강화를 위해 레벤슈타인 거리 알고리즘, 약어 매칭, 한영 매칭을 활용하여 유사 컴포넌트를 검색하는 '퍼지 서치'를 구현했습니다.

데이터 피커 오타 등 유사한 컴포넌트 질의 시, AI 에이전트가 시밀러 툴을 활용하여 스스로 올바른 컴포넌트를 추론하고 응답합니다.

연결이 끊어진 컴포넌트 자동 생성을 위해 통합된 데이터를 기반으로 AI 에이전트가 자동으로 코드를 생성하도록 했습니다.

AI 에이전트가 우아공방 맥락을 잘 활용하도록 MCP 하위에 룰과 도메인별 가이드라인, UX 라이팅 등 지침서를 추가했습니다.

프라이스 컴포넌트의 금액 표기법 수정 요청 시, 툴과 가이드라인을 통해 AI 에이전트가 '1만 포인트'가 아닌 한글 숫자 표기를 지향하도록 수정할 수 있습니다.

피그마 디자인을 민트 컴포넌트로 구현하는 과정에서, MCP가 피그마 MCP 호출, 우아공방 컴포넌트 리스트업, 사용 예제 및 가이드 확인, 코드 생성 순으로 진행되어 우아공방 디자인 시스템 규칙을 따르는 코드를 생성합니다.

이를 통해 디자인 시스템 일관된 규칙 적용, 무작위 디버깅 회피, 디자인 토큰 적극 활용, 적절한 컴포넌트 조합이 가능해졌습니다.