Soup

대학생 팀 프로젝트 협업 관리 도구, Soup

2025년 3월부터 7월까지 두 차례에 걸쳐 진행된 협업 기반 웹 애플리케이션 프로젝트는 디자이너, 기획자, 프론트엔드, 백엔드가 함께한 실무형 팀 프로젝트였다. 팀 구성은 프론트엔드 2명, 백엔드 2명, 디자인·기획 2명으로 시작했으나 중간에 프론트엔드 인원이 이탈하면서 이후 개발 전반과 구조 설계를 단독으로 맡게 되었다. 프로젝트는 Next.js 기반의 정적 랜딩 페이지와 React 기반의 동적 애플리케이션으로 분할하여 Vite와 Turbo를 이용한 모노레포(monorepo) 환경에서 통합 관리했다. 이번 프로젝트는 모노레포, FSD(Feature-Sliced Design), CVA(Class Variance Authority), Compound Component 패턴 등 구조적 설계 전반을 실습하며 협업 환경의 핵심을 실제로 체험한 사례였다.

프로젝트 배경과 초기 방향

이 프로젝트는 디자인 전공 친구의 제안으로 시작되었다. 기획자와 디자이너가 먼저 서비스 콘셉트를 구상하고 개발자를 모집했으며, 백엔드 파트는 커뮤니티를 통해 전문 개발자를 영입해 완성된 구성으로 출발했다. 처음에는 기획 규모가 지나치게 확장되어 구체적인 기능 정의와 개발 범위를 잡기가 어려웠다. 이후 실제 구현 단계에서 기능을 축소하고, 구조 설계와 기술 환경 세팅 중심으로 방향을 수정했다. 이 과정은 협업 환경에서 ‘기획 우선 방식’의 리스크를 실감하게 한 경험이었다.

기술적 설계와 구조 구성

프로젝트는 React 기반 앱과 Next.js 기반 랜딩 페이지를 결합한 형태로, 서로 다른 목적의 페이지를 단일 레포지토리에서 관리하기 위해 모노레포 구조를 구축했다. Turbo와 Vite를 조합하여 빌드 시간을 단축하고, 공통 패키지를 분리하여 유틸 함수와 UI 컴포넌트를 공유했다. 이 과정에서 dependencies와 devDependencies의 차이를 명확히 이해할 수 있었으며, 패키지 간 의존성을 어떻게 정의하고 관리해야 하는지 체계적으로 학습했다.

FSD(Feature-Sliced Design)를 도입해 기능별 폴더 구조를 체계화했으며, 각 기능의 components, types, utils를 분리하여 모듈 단위 개발을 실천했다. 이를 통해 기능 추가나 수정 시 코드 영향 범위를 최소화하고 협업 효율성을 높였다. 또한 Storybook을 도입하여 UI 컴포넌트를 시각적으로 관리하고 디자인 피드백을 빠르게 반영할 수 있었다. 이때 Storybook을 통해 단일 컴포넌트의 상태별 변화를 독립적으로 테스트하는 과정이 가능해졌고, 디자이너와의 협업 속도를 향상시켰다.

UI 구조 설계와 패턴 적용

프로젝트의 핵심 UI 요소는 모달 컴포넌트였다. 다양한 종류의 모달이 서비스 전반에 걸쳐 사용되었고, 디자이너의 상세한 수정 요청이 이어지면서 구조적 복잡도가 높아졌다. 이를 해결하기 위해 Compound Component 패턴을 도입해 컴포넌트를 유연하게 조립할 수 있도록 개선했다.

CVA(Class Variance Authority)를 활용하여 Tailwind CSS의 클래스 변형을 통합 관리하면서 상태별 스타일링의 일관성을 유지했다. 그러나 폭넓은 디자인 요구사항으로 인해 Variant 옵션이 늘어나며 관리 복잡도가 증가했고, 이후 프로젝트에서 디자인 시스템 개념을 도입해야겠다는 인식으로 이어졌다.

협업 과정과 커뮤니케이션 개선

디자이너와 협업한 첫 경험이었기 때문에 커뮤니케이션의 중요성을 깊이 느낄 수 있었다. 초기엔 공통 규칙이나 디자인 토큰이 정의되지 않아 화면마다 세부 차이를 처리하는 데 많은 리소스가 소모되었다. 후반부에는 Storybook을 활용하여 컴포넌트별 시안을 공유하고, 피드백 과정에서 시각화된 UI를 기준으로 협의함으로써 커뮤니케이션의 효율이 크게 향상되었다. 이러한 경험은 디자인 시스템과 UI 표준화의 중요성을 명확히 인식하게 해주었다.

배운 점

모노레포 환경의 구조 설정과 패키지 의존성 관리 과정을 통해 다중 프로젝트 구성의 실무적 이해를 얻었다. 비동기 데이터 흐름을 Tanstack Query의 useQuery, useMutation 훅을 통해 관리하며 API 요청 로직을 커스텀 훅으로 분리하는 방식을 정착시켰다. Compound Component 및 CVA 패턴 활용, Storybook을 통한 UI 단위 테스트 등 실제 협업 환경에 바로 적용 가능한 기술들을 흡수했다. 또한 디자이너와의 협업을 통해 명확한 기준 정의와 문서화가 개발 품질에 직결된다는 점을 체감했다.

결과와 회고

프론트엔드 인원 감소와 일정 문제로 프로젝트는 완전히 마무리되지는 못했지만, 구조적인 설계와 협업 프로세스 측면에서 의미 있는 성장의 계기가 되었다. 특히 모노레포 관리, Storybook 운영에서 얻은 경험은 이후 진행한 프로젝트에 직접적인 기술적 영향을 주었다. 이 프로젝트를 통해 협업은 단순한 역할 분담이 아닌, 구조적 설계와 커뮤니케이션이 함께 맞물릴 때 비로소 유기적으로 완성된다는 사실을 배웠다.