[Storybook] Claude Code를 활용해 Storybook을 만들어보자

이 트러블슈팅은 롤페 프로젝트에서 수행되었습니다.

GitHub - Team-Exiters/Roll-Pe_FE

 

문제 상황 개요

❓ 문제 상황
'롤페' 프로젝트 전역에서 사용되는 공통 레이아웃 컴포넌트들의 바리에이션이 많아 명확한 파악이 어려움

 

이전 LCP 개선(포스팅 링크)에 이어 계속해서 사이드 프로젝트 '롤페'의 리팩토링을 이어나가고 있다.

롤페에는 버튼, 모달 등 서비스 전역에서 쓰이는 공통 레이아웃 컴포넌트들이 그렇게 많지는 않다. 하지만, 그들의 바리에이션이 많다.

버튼의 경우를 예로 들면, onClickHandler가 필요한 <button> 요소로 감싸진 버튼, 단순 페이지 이동에 사용되는, <Link>로 감싸진 버튼, 그리고 Form 제출에 활용되는 <input type="submit">인 버튼.

 

하지만 이 녀석들을 갖다 쓰는 데에 있어서, 과거의 내가 작성했지만서도 정확히 어떤 녀석인지 파악하기 위해 코드를 읽으러 가기 번거롭다는 느낌을 받았다.

 

그래서, 모든 컴포넌트까지는 아니어도 우선적으로 기본으로 사용되는 UI 관련 컴포넌트들에 대해서 Storybook으로 명세화를 하면 어떨까 하는 생각이 들었다. 이전에 알뜰폰 & 인터넷 요금제 통신 판매 서비스를 외주 개발 할 때에 처음 사용해본 도구인데 컴포넌트에 주어지는 값들에 따른 변화를 파악할 수 있어서 컴포넌트 관리가 너무 편리하다고 느꼈기 때문이다.

 

더불어서, 컴포넌트 주도 개발이 무엇인지 직접 체험해보면 좋겠다는 생각이 들었다.

컴포넌트 주도 개발, CDD에 대한 개념은 직전에 Atomic Design 개념과 함께 정리해서 포스팅 해두었다.

 

 

[FE] CDD (컴포넌트 주도 개발) feat. Atomic Design

 

이걸 염두에 두면서 이번 트러블슈팅과 함께 CDD와 Atomic Design을 조금 더 깊이 이해해보려고 노력해보았다.

 

문제 해결 목표

📈 문제 해결 목표
1. Claude Code를 이용해 '롤페' 프로젝트의 기본 공용 컴포넌트 (button, input, modal)을 Storybook으로 문서화한다.

 

문제 해결 과정

Storybook?

Storybook은 React, Vue, Angular 등의 웹 프론트엔드 프레임워크에서 UI 컴포넌트를 애플리케이션과 분리된 화면에서 개발·테스트·문서화할 수 있게 도와주는 도구이다.

 

컴포넌트별로 '스토리'라고 부르는 다양한 상태를 정의하고, 프로젝트를 수행하는 다른 직군의 팀원들과 함께 시각적으로 확인 및 공유하면서 CDD를 실천할 수 있도록 도와준다.

 

위에 기술했듯, 외주 프로젝트를 진행하며 이 Storybook을 통한 UI 컴포넌트 명세를 한 번 수행해 본 적이 있다.

헌데, 이 과정이 꽤나 반복되는 코드 작성이 많아 번거롭다. 따라서 이 과정을 Claude Code를 이용해 자동화 하고자 하는 것이다.

 

1. Claude Code 시작하기

이 포스팅은 트러블슈팅에 대해서만 다루고 있으므로, Claude Code 초기 설정을 하는 방법에 대해서는 기회가 생긴다면 별도 포스팅으로 분리를 해보겠다. 이 포스팅에서는 내가 어떤 방법으로 Storybook 문서화를 자동화 했는지만 다룬다.

 

일단, 이전까진 Cursor AI를 사용해왔으며 Claude Code는 처음 다뤄보는 도구였기 때문에 아래의 유튜브 영상을 많이 참고했다.

 

1 - 1. Sub-Agent로 프론트엔드 전문가 만들기

서브에이전트?

서브에이전트 - Claude Code Docs

 

서브에이전트란 Claude Code가 작업을 위임할 수 있는 사전 구성된 AI 성격이다.

• 특정 목적과 전문 분야를 가지고 있음
• 주 대화와 분리된 자체 컨텍스트 윈도우 사용
• 사용할 수 있는 특정 도구로 구성
• 동작을 안내하는 커스텀 시스템 프롬프트 포함

약간 AI 에이전트로 팀을 꾸린다고 생각하면 편할 것 같다. 프론트엔드 전문가 성격을 갖는 것, 백엔드 전문가 성격을 갖는 것, 코드 리뷰에 특화된 성격을 갖는 것, 배포에 특화된 성격을 갖는 것... 이런 식으로 서브에이전트를 구성하면 혼자여도 충분히 간단한 애플리케이션 정도는 개발할 수 있을 것 같은 신기한 기능. Cursor AI에는 없는 기능이라 한 번 사용해보았다.

 

nice-fe-guy라는 이름의(...) 서브에이전트를 만들었다.

 

Sonnet 4.5 모델을 이용하도록 했고, 시스템 프롬프트는 Toss에서 공개한 프롬프트를 이용했다.

frontend-guidelines.md

 

이제 이 나이스한 프론트엔드 가이(...)는 내가 직접 작업을 지시하거나 관련된 컨텍스트가 나올 경우 나이스하게 일을 해줄 것이다.

 

2. Storybook 설정하기

기존 '롤페' 프로젝트에서는 Storybook을 사용하고 있지 않기 때문에, Storybook 10을 설치하고 환경을 구축하는 것부터 부탁했다.

 

스크린샷에서는 8을 설치하겠다고 했는데, 추후에 최신 버전인 10으로 잘 설치해주었다.

package.json

package.json 파일을 확인하니 Storybook을 위한 코어 패키지, 애드온 등을 잘 설치했다.

 

이후로도 main.ts, preview.ts와 같은 설정 파일부터 Storybook을 위한 vite 설정까지 아주 완벽하게 잘 해냈다.

특히 프로젝트 전체를 컨텍스트로 삼아서 그런지, preview.ts에서 COLORS 객체로 지정한 공용 색상까지 배경 색상으로 잘 가져다 쓴 모습이 인상적이었다.

  .storybook/preview.ts

import type { Preview } from '@storybook/nextjs-vite'
import { COLORS } from '../public/styles/colors'

const preview: Preview = {
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },

    a11y: {
      test: 'todo'
    },

    backgrounds: {
      default: 'white',
      values: [
        {
          name: 'white',
          value: COLORS.ROLLPE_PRIMARY,
        },
        {
          name: 'black',
          value: COLORS.ROLLPE_SECONDARY,
        },
        {
          name: 'gray',
          value: COLORS.ROLLPE_SECTION_BACKGROUND,
        },
        {
          name: 'main',
          value: COLORS.ROLLPE_MAIN,
        },
      ],
    },
  },
};

export default preview;

 

아래는 Claude가 정리해준 preview.ts의 설정 내용이다.

• controls: color/date 매처 설정
• a11y: test mode 'todo' 설정
• backgrounds: 4가지 배경색 옵션
  • white (ROLLPE_PRIMARY)
  • black (ROLLPE_SECONDARY)
  • gray (ROLLPE_SECTION_BACKGROUND)
  • main (ROLLPE_MAIN)
    
    

3. stories에 UI 공용 컴포넌트 추가하기

이제 설정이 끝났으니 앞서 이야기한 button, input, modal에 대한 문서화를 수행할 차례다.

 

Claude에게 app/_components 디렉토리에서 해당 컴포넌트들을 Storybook으로 문서화해달라고 요청을 했다.

혹시 몰라서 단계를 수행하기 전에 내게 진행 여부를 묻도록 하였다.

 

역시나여기서 두 가지 문제가 생기는데...

 

3 - 1. stories를 app/_components에 만들려고 하는 귀여운 claude code

내 지난 외주 프로젝트 경험에 따르면 stories는 상위에 별도 디렉토리로 관리되어야 한다.

 

Storybook은 프로젝트 전체에 관여하는 빌드 도구 중 하나인데 app/_components에 종속되게 되면 관심사가 분리되지 않아 유지보수에 어려움을 겪을 것 같았다.

 

어차피... 컴포넌트들만 모인 디렉토리이긴 해도 depth가 깊어지면 귀찮아질 것 같아서 바로...

꾸짖을 갈 시전

 

3 - 2. 계속 .stories.ts를 .tsx로 바꾸고 싶어하는 claude code

역시 지난 외주 프로젝트 경험에 따르면, .stories.ts 파일에서는 컴포넌트 함수를 import하여 args로 전달하는 방식을 취했다.

이렇게 하면 .stories.ts에서 중복해서 JSX 코드를 작성하는, 불필요한 코드 작성도 줄일 수 있기도 하고, 애초에 meta 객체에서 component는 ReactNode 그 자체를 넘겨도 되는 것이니

2단 꾸짖을 갈

 

 

그래서 내 이전 프로젝트에서의 예시와 공식문서의 예제 코드를 프롬프트로 전달하며 이 구조를 따르라고 꾸짖어주니 이 구조대로 잘 만들어주었다. (아니 인공지능한테 사람이 공식문서 퍼날라주는거 이거 맞나)

 

아무튼, 이렇게 발생한 두 개의 문제를 해결하여 Storybook 문서화를 완료했고, 완성된 구조는 다음과 같다.

stories/
  ├── mocks/
  │   └── data.ts                    // Mock 데이터
  └── ui/
      ├── button/
      │   └── Button.stories.ts      // 5가지 버튼 스토리
      ├── input/
      │   └── Input.stories.ts       // Input 컴포넌트 스토리
      ├── loading/
      │   └── Loading.stories.ts     // Loading 컴포넌트 스토리
      └── modal/
          └── Modal.stories.ts       // Modal 컴포넌트 스토리

 

mocks 하위의 Mock 데이터는 별도로 부탁하지 않았는데도 알아서 잘 딱 깔끔하고 센스있게 만들어주는건 또 좋네.

 

문제 해결 결과

‼️ Button, Input, Modal 컴포넌트에 대한 Storybook 문서화 성공
성공적으로 롤페의 공용 Button, Input, Modal 컴포넌트에 대한 명세를 작성했다.

 

1. Button 컴포넌트 명세

Claude가 똑똑하게도 긴 텍스트가 삽입되었을 때 등 다양한 테스트 케이스를 함께 구현해준 모습을 볼 수 있다.

 

2. Input 컴포넌트 명세

음..? 체크박스는 없는데

 

3. Modal 컴포넌트 명세

 

느낀점

그동안 GPT, Cursor AI, Gemini 등 다양한 AI 도구를 활용해봤고, 그 중에서 Cursor AI가 가장 쓰기 편하고 좋다는 생각을 가졌었다.

그런데 Claude Code를 처음 써보고나니 내가 우물 안 개구리였다는 생각이 문득 들었다.

 

별도의 IDE 설치 없이 CLI 환경에서 사용됨에도 프로젝트 전체의 맥락을 잘 이해했고, Claude Code의 작업 수행에 의문을 품는 경우의 대처가 너무 마음에 들었다.

 

기존 다른 에이전트들의 경우 작업 수행에 딴지를 걸 경우에 자꾸 빙빙 돌아가려는 경향이 없잖아 있었던 경험이 있는데, claude는 정말 알잘딱깔센이 잘 되는 느낌? 곧이 곧대로, 내 의도를 명확히 파악해주는 느낌이 들었다.

 

또한, 그동안은 AI 에이전트를 최대한 배제하는게 성장에 도움이 될 것이라고 생각이 되어 최소한으로 사용하고자 노력해왔는데, 이런 단순한 문서화와 같은 단순 작업의 경우 사용하지 않으면 바보가 되는 것 같다. 이렇게나 시간을 절약할 수 있는데. 내가 직접 이 작업을 수행했다면 아마 적잖은 시간이 걸렸을 것 같은데, claude를 익히고 적용하는데에 어림잡아 1시간 30분 내로 해결한 것 같다.

 

마지막으로, CDD와 함께 Atomic Design 개념에 대해서도 공부를 해봤는데, 대체로 이 트러블슈팅에서 해결한 문제에 사용된 컴포넌트들의 경우 Atom 단계의 녀석은 하나도 없다. 그야 당연하게도 Atom은 단순한 HTML 요소로서의 <button>, <input> 등등일테니 이것들을 이용해 만든 조금 더 복잡한 molecules에 해당한다고 생각된다.

 

추후 organism에 해당하는 더 복잡한 컴포넌트들도 차근차근 문서화해놓으면 좋을 것 같다.

 

자료 출처

storybook : https://storybook.js.org/

conponentdrive : https://www.componentdriven.org/

어라운드 허브 슈티디오 - 컴포넌트 주도 개발 (CDD) 이론편 : https://youtu.be/KnscSsHTggs?si=0hk-vTpdb5UrVUqv