들어가며
1편에서는 토큰 구조와 foundation을 설계했고, 2편에서는 공통 컴포넌트의 경계를 세우고, 실제로 공통 컴포넌트를 구현하고 앱에 치환했었다. 그리고 이제 최종 마이그레이션까지 남은 작업은 styles 파일과 useTheme를 이용하는 기존 theme 의존성을 완전히 제거하는 것이었다.
이번 글에서는 이 남은 의존성을 덜어내는 작업과, 마이그레이션 과정에서 발견된 문제를 해결하는 과정, 그리고 이렇게 단 시간에 많은 작업을 혼자서 해낼 수 있었던 방법에 대해서 정리해보려고 한다.
theme 기반 스타일 코드 제거
코드 전반적으로 흩어져 있던 theme 기반 스타일 코드를 getToken, applyTypographyToken 같은 새로운 API를 사용하는 방식으로 수정해야 했다.
우선 기존 사용 패턴을 분석했다.
${({ theme }) => theme.color.semantic.text.strong} 같은 styled-components theme 접근, useTheme를 이용한 컴포넌트 코드에서의 theme 접근, getColorFromTheme이나 processStyle 같은 helper 함수까지. 이런 패턴들이 코드 전반에 흩어져 있었다.
치환 패턴이 명확한 것도 나름 많아서 규칙을 정리해 둔 다음에 자동화한 것도 좀 있었지만, 토큰 매핑이 애매한 경우라던가, 하드코딩하고 있었던 색깔 같은 것들도 꽤 많아서 생각보다 직접 변환해야 하는 것들도 많았다. 정말... 디자인 시스템 마이그레이션 작업 중 가장 재미없고 머리아픈 작업이었다.
ThemeProvider 제거 : 진짜 끝!?
레거시 theme 의존성을 모두 걷어냈으니 이제 비로소 Theme 객체와 ThemeProvider 자체를 제거할 수 있었다.
파일 하나와 코드 한두줄 정도를 제거하는 일이긴 했지만, 의미가 꽤 크다. 이 이후에는 모든 스타일이 새 token 기반 구조를 바라보고 있다는 것을 보장할 수 있게 된 것이기 때문이다.
ThemeProvider를 제거하고 앱이 정상적으로 동작하는 것을 확인한 순간, 도파민이 싹 돌았다. 이제 끝인가... 싶었는데, 마이그레이션 작업 중에 눈에 띄었던 문제들이 아직 남아 있었다.
아직 남았다 : 마이그레이션 작업 중에 보였던 문제 해결하기
디자인 시스템과는 좀 거리가 있긴 하지만, 마이그레이션 작업을 하다 보니 기존 구조의 문제가 눈에 띄기 시작했다. 마이그레이션 작업을 완료한 후에, 이 문제들을 수정했다.
페이지 배경색 불일치 문제 : 공통 PageLayout 도입
기존에는 각 페이지나 컴포넌트가 개별적으로 배경색을 설정하고 있었다. 이건 화면 구조가 개별적인 컴포넌트들이 배경을 갖고 화면 전체를 꽉 채우는 구조로 되어 있었기 때문인데, 이렇게 하다 보니 컴포넌트가 바뀌거나 화면 구성이 변경될 때 마다 배경의 의도치 않게 달라지는 상황이 반복되었다.
이런 문제를 공통 PageLayout 컴포넌트를 도입해서 페이지 배경색의 기준을 한 곳으로 모으는 방법으로 해결했다. 각 컴포넌트 단위로 배경을 일일이 지정해주는 것이 아닌 페이지 최상단의 레이아웃 단위로 페이지의 배경을 설정할 수 있는 구조로 변경한 것이다.
<PageLayout $bg="neutral" $hasBottomFixedAction>{/* page content */}</PageLayout>
SVG icon currentColor 전환
기존 아이콘들 중 일부는 SVG 파일 안에 fill="..." 형태로 하드코딩되어 있었다. 의도했던 것은 아니고 처음에 SVG 파일로 export할 때 신경쓰지 못했던 부분인데, 이렇게 되다 보니 아이콘의 색을 변경해야 하는 상황에 일일이 파일을 수정해야 하는 문제가 있었다.
사실 지금까지는 좀 흐린 눈...을 하고 넘어갔던 문제이긴 한데, 이번에 작업을 하다 보니 색 변경을 시도했는데 안되었고 알고보니 SVG에 색이 하드코딩되어있었음! 이 상황을 몇번 마주하고 나니 이 참에 CSS의 color 속성으로 아이콘 색상을 제어할 수 있도록 fill="currentColor"로 전환해야겠다는 생각을 했다.
/* 색상 제어가 CSS로 가능해짐 */.icon {color: ${getToken('fg.primary.normal')};}
AI와의 알콩달콩 작업
이 모든 작업을 나 혼자서 거의 2주만에 마무리했다. 정말... 서비스 코드 전체를 확인하고 변경하는 수준으로 변경 범위가 넓었는데, 이게 가능했던 이유는 조금 당연한 것 같기도 하지만 AI 덕분이었다.
단순히 "해줘" 라고 요구하기에는 변경해야 할 범위가 너무 많았고, 이미 잘 동작하고 있던 서비스이기 때문에 잘못 변경해서는 절대 안됐었다.
그래서 나름대로 체계를 잡고 작업 프로세스를 만들었었는데, 작업을 완료한 뒤에 생각해보니 개인적으로는 잘 동작하고 만족스러웠던 것 같아서 정리해보려고 한다.
공통 컴포넌트 작업 - claude skill을 활용하기
디자인 시스템을 기반으로 공통 컴포넌트를 구현하는데는 클로드 스킬을 활용해서 작업했다.
공통 컴포넌트는 새로운 디자인 시스템이 100%는 아니지만 잘 반영되어 있는 상태였고, 디자인 시스템의 토큰은 미리 정리해둔 상태였기 때문에 스킬을 활용하기 좋은 상황이라고 생각했다. 그래서 피그마 링크와 컴포넌트 이름을 입력으로 넣으면, 그 이름으로 컴포넌트를 구현하는 클로드 스킬을 만들었다.
우리 팀의 구현 규칙과, 이번에 반영해야 하는 디자인 시스템의 규칙을 전달하고, 무엇보다 임의로 판단해서 잘못 구현하면 안되기 때문에 임의 판단을 금지하는 중단 조건을 엄청 강조해두었다.
Flex, Text 컴포넌트 치환 작업 - claude skill을 활용하기
Flex, Text 컴포넌트는 프로젝트의 전반적으로 사용되던 레이아웃/폰트 컴포넌트이다. 비교적 치환 규칙이 단순하면서도 작업량이 너무 많아서, 이 역시도 스킬을 활용하기 좋은 상황이라고 생각했다.
각 컴포넌트 치환 작업에 들어가기 전에, 전반적으로 사용 현황을 분석했다. 그리고 해당 컴포넌트에서 사용되고 있는 토큰 같은 치환에 필요한 정보들을 스킬 파일에 명시해두었다.
정말 많은 곳에서 쓰이는 컴포넌트였기 때문에 곧바로 치환하기에는 리스크가 크다고 판단했다. 따라서 dry-run을 기본값으로 두고, 예상 결과를 내가 확인한 다음에 실제 치환을 수행하도록 했다. 그리고 공통 컴포넌트 작업과 동일하게 임의 판단을 금지하는 중단 조건 역시 추가해두었다.
Claude는 구현자, Codex는 설계자와 검토자
요즘 개발 작업에는 Claude와 Codex를 주로 쓰는데, 쓰다보니 이녀석들의 (개인적인 측면에서의)장단점이 확실히 느껴졌다.
Claude는 개발 스타일이 나와 잘 맞는다. 처음부터 너무 복잡하고 빡빡하게 짜기 보다는 적당한 추상화를 추구하는 느낌? 그래서 개인적으로는 Claude가 작성한 코드를 봤을 때 가장 손댈 부분이 없다고 느껴진다. 반면에 좀 조심성이 없는 느낌이다. 일단 표면에 드러난 문제들을 빠르게 해결하고, 다른 문제가 발견되면 이어서 덕지덕지 해결하려고 하는 느낌이라 처음 지시가 중요한 것 같다는 생각이 들었다.
Codex는 Claude와 완전히 정반대의 느낌을 받았는데, 일단 정말.. 생각이 많은 느낌이다. 어떤 설계를 주고, 피드백을 달라고 했을 때 살짝 부담스럽게 느껴질 정도로 피드백을 꼼꼼히 (그리고 많이...) 준다. 부담스럽긴 해도 내가 미처 확인하지 못한 빠뜨린 부분을 확인하는데 정말 많은 도움이 되었다. 반면에... 코드 스타일이 나와 정말 맞지 않는다. 일일이 추상화 함수를 만들고, 변수/함수 이름에 모든 맥락을 꽉꽉 눌러담은 userLoginTokenExpiryTimeInSeconds 같은 이름들을 자주 만들어내는 편인 것 같다. 내가 잘못 설정한 것인지는 몰라도 나름대로 규칙을 제공했는데도 계속 이런 식이라 너무 불만족스러워서 긴 분량의 코드 작성에는 활용하지 않는다.
아무튼 이렇게 느낀 각자의 장점만 골라서 활용하는 방법을 요즘 여러 환경에서 시도해보고 있고 이번 마이그레이션 작업에도 활용해봤는데 꽤 만족스러웠다.
토큰 설계와 디자인 시스템 컴포넌트 분리 기준 같은 설계 작업은 Codex와 의논했다. 이렇게 의논한 것을 바탕으로 정리한 규칙을 Claude Skill에 넣고, 실제 마이그레이션 작업은 Claude에게 맡겼다. 이 때 많은 분량을 한번에 작업하면 Claude가 실수할 확률이 높아지는 것 같아서, 컴포넌트 단위, 디렉토리 단위로 쪼개서 요청했다. 그리고 이렇게 작업한 결과를 Codex와 함께 점검했다.
이 Claude와 Codex의 세션은 굳이 연결되어있을 필요가 없어서 각자 다른 세션을 열어 두고 작업했다. 그래서 이번 마이그레이션 작업 동안 내 메인 모니터에서 가장 자주 봤던 화면은 아래의 4칸짜리 터미널 화면이었다.
시간을 보니 5월 5일 새벽 2시 17분에 찍은 스크린샷인데 뭔가 이렇게 작업을 하고 있는 모습이 문득 너무 웃겨서 찍었던 기억이 있다. 아무튼 이렇게 메인 모니터에 터미널 창을 켜두고, 서브 모니터에 코드 에디터를 켜두고 실제 변경사항을 코덱스와 함께 나도 꼼꼼히 살펴보았다.
좋았던 점과 아쉬운 점
무엇보다 좋았던 점은 skill 문서를 작성하면서 나도 매핑 규칙을 다시 확인해보고 점검할 수 있었다는 점이다. 마이그레이션 작업 특성상 기존 코드를 어떻게 새로운 코드로 바꿀 것인지를 확실히 정해두고, 일관되게 수정하는 것이 매우 중요했는데, skill문서 작성을 통해서 이 과정을 할 수 있었다는 점이 좋았다. 실제로 작업을 위한 문서기도 했지만, 다른 팀원에게 기존 코드를 어떻게 치환하는지 그 규칙을 설명하는 문서로도 좋은 역할을 했던 것 같다. 나도 PR에 따로 치환 규칙을 적으려다가 스킬 문서가 있는 것을 기억하고 해당 스킬 문서를 그대로 첨부하는 식으로 팀원에게 치환 규칙을 전달했다.
이렇게 스킬을 사용하지 않거나, 직접 하는 경우에 비해서는 확실히 휴먼 에러 없이 일관된 방식으로 마이그레이션 작업을 진행할 수 있었다는 장점도 있었을 것 같다. 동일한 작업은 아니지만 3년 전(...)에 기존 서비스 디자인을 리뉴얼하는 작업을 했었는데, 프론트엔드 공부 경력 3개월 개발자 4명이 거의 2달을 걸려서 작업했었던 경험이 있다.... 압도적인 생산성이다.
아쉬운 점인지 다행인 점인지는 모르겠지만, 그래도 확실히 인간 개발자의 확인이 필요하다는 점 또한 느꼈다. 그토록 임의 판단을 하지 말라는 규칙을 스킬 문서에 강조했음에도 불구하고 임의로 토큰 매핑 규칙을 판단해서 정정했던 적도 몇번 있었고, 기본적으로 텍스트를 작업할 때 맥락과 관계 없이 p 태그를 사용해서 몇번 고쳐준 적도 있었다.
그리고 claude, codex, 그리고 나 이렇게 3번의 확인 과정을 거쳤음에도 불구하고 미처 확인하지 못했던 figma 디자인 요소를 PR 리뷰에서 다른 팀원이 짚어주었다. 물론 내가 좀 더 스킬 문서를 제련했더라면, 좀 더 꼼꼼히 살폈더라면 이 아쉬운 점도 없었을 수도 있겠다.
끝! 후련하다
사실 디자인 시스템 작업은 내 숙원 사업 중 하나였다. 모처럼 디자이너분과 함께 하는 프로젝트이고, 디자이너분도 디자인 시스템 구축에 대한 니즈가 있으셨기 때문에 이건 진짜 절호의 기회라고 생각했었다. 하지만 공을 들여서 구축해둔 기존의 theme 방식이 너무 복잡했고, Flex 컴포넌트도 애매하게 일반화하는 바람에 너무 복잡해져서 자꾸 사이드 이펙트가 발생해서 속상한 마음이 컸다. 게다가 styled-components 의존을 버리지 못했다면 온전한 디자인 시스템이라고 말하기도 어렵다는 문제도 있었다.
아무튼 이렇게 아쉬움으로만 남아 있었던 디자인 시스템을 나름 만족스러운 설계로 잘 만들어내고, 마이그레이션 작업까지 나름 빠른 시간 안에 마무리해서 엄청 후련하다! 아직 "디자인 시스템" 적으로는 토큰을 추가한다거나 하는 변경사항이 있을 수 있겠지만 이렇게 설계부터 다시 뜯어고치는 작업은 당분간 없을 것 같다. (없어야만 한다 ㅠㅠ)
단순히 부채를 해결한 것 뿐 아니라 그 과정에도 내가 해보고 싶었던 범용적으로 사용할 수 있는 디자인 시스템에 대한 고민이라던가, AI를 활용한 마이그레이션 작업까지. 하고 싶었던 것들을 많이 해 볼 수 있었고, 뭔가 실무... 와 가까워진 느낌도 들어서 좋았다. (흑흑)
3년 전에는 시간이 엄청 걸려서 했던 일을 거의 2주만에 마무리하고, 좀 아쉽게 사용했던 storybook도 그 아쉬웠던 부분을 싹 해결하는 방향으로 썼다는 점도 약간 성장의 맛을 느낄 수 있어서 좋았다.
앞으로 여유가 되거나 욕심이 더 생긴다면, 이렇게 만들어둔 디자인 시스템을 모노레포로 만드는 작업까지 해보고 싶다! 그때는 더 성장한 내가 되어 있길....