hooks, utils, components 구조에서 Feature 기반 구조로 개선하기

역할 기반 구조에서 발생한 코드 탐색 문제를 해결하기 위해
Feature 단위 구조(FSD 일부)를 도입한 경험을 정리한 글입니다.

 

📦 기존 프로젝트 구조

이전 프로젝트에서는 역할 기반(hooks, utils, components)으로
폴더를 분리하는 구조로 진행했었다.

📦src 
┣ 📂components 
┣ 📂hooks 
┣ 📂utils 
┣ 📂types 
┣ 📂lib
...

이전까지는 기초, 중급 프로젝트였기에 파일 수도 많지 않았고,
역할 기반으로 나누는 방식이 직관적이고 익숙해서 팀원 모두 사용하고 있었다.

 

🤔 프로젝트를 진행하며 느낀 점

개인 프로젝트나 팀 프로젝트를 여러번 경험해보면서
역할 기반 구조에 불편함을 느끼기 시작했다.

 

하나의 기능을 수정하려고 할 때
UI는 components 폴더에서 상태와 로직은 hooks, 타입은 types 폴더에서 수정해야 했고
관련 코드가 여러 폴더에 흩어져 있어서 하나의 기능을 이해하기 위해 여러 위치를 계속 탐색해야 했다.

 

결과적으로 코드 흐름 파악이 어려워지고
수정 시 영향 범위를 한 번에 파악하기 힘들어서
리팩토링을 할 때 코드를 확인하는데 많은 시간이 걸렸다.

 

🏃 불편한 폴더 구조 탈출하기

그래서 이번 프로젝트를 진행할 때는
역할 기반이 아닌 기능 단위로 코드를 묶는 구조를 고민하게 되었고
그 과정에서 FSD(Feature-Sliced Design)를 참고하게 되었다.

https://feature-sliced.design/kr/docs/get-started/overview

다만 이번 프로젝트는 약 5주간 진행되는 단기 프로젝트였기 때문에
FSD를 전체적으로 도입하기에는 구조가 다소 무겁고
팀원 모두가 이해해서 적용하기에는 시간이 촉박하다고 판단했다.

 

그래서 FSD 개념에서 우리 프로젝트에 도입하면 좋을 부분만 뽑아서
선택적으로 프로젝트에 적용했다.

 

💡 프로젝트에 적용하기

1. pages 레이어 → app 디렉토리

📦src
┣ 📂app
┃ ┣ 📂(protected)
┃ ┣ 📂(public)
...

Next.js의 App Router를 사용하고 있었기 때문에
FSD의 pages 레이어는 별도로 구성하지 않고
app 디렉토리로 대체했다.

 

2. 구조 단순화하기

구조는 shared / features로 단순화했다.

📦src
┣ 📂features  # 기능 단위 코드
┣ 📂shared    # 공통으로 사용하는 코드

복잡한 레이어를 모두 도입하기보다는
팀이 빠르게 이해하고 적용할 수 있도록 단순화하는 데 집중했다.

 

3. shared 기준 정의

구조를 나누는 과정에서 가장 고민이 많았던 부분은
어디까지를 shared로 관리할 것인가였다.

 

그래서 두 곳 이상에서 사용되거나 재사용 가능성이 있는 경우에만
shared로 분리하기로 기준을 세웠다.

기준을 적용하면서 불필요한 추상화를 줄일 수 있었고,
shared 레이어가 과도하게 커지는 것도 방지할 수 있었다.

 

4. features 구조 설계

features 폴더는 하나의 기능에 필요한 모든 코드를
한 곳에 모으는 것을 중점으로 했다.

📦features 
┣ 📂activity-detail
┃ ┣ 📂components
┃ ┣ 📂hooks
┃ ┣ 📂queries
┃ ┣ 📂utils
┃ ┗ 📂constants
┣ 📂activity-form 
┣ 📂auth
┣ 📂main
┣ 📂mypage
┗ 📂notification

features는 페이지 단위로 구성했고,
feature 내부에는 관련 코드를 기능 단위로 나누었다.

 

🔍 구조 개선 결과 및 회고

Before vs After

Before (역할 기반 구조)	After (Feature 기반 구조)
기능 하나 수정 시 여러 폴더 이동 필요	관련 코드가 하나의 feature 내부에 모여 있음
코드 흐름 파악 어려움	기능 단위로 코드 이해 가능
탐색 비용 증가	리팩토링 시 영향 범위 파악 용이

 

회고

이번 경험을 통해 구조 설계에는 정답이 있는 것이 아니라는 점을 느꼈다.

 

FSD를 그대로 적용하는 것보다 프로젝트의 규모, 기간, 팀의 상황을 고려해서
필요한 부분 만큼만 적용하는 것이 더 중요하다고 생각하게 되었다.

 

그리고 단순히 기능을 구현하는 것을 넘어 코드 구조를 설계하는 과정이
개발 생산성과 유지보수성에 큰 영향을 준다는 것을 체감할 수 있었다!