대규모 프론트엔드 프로젝트에서 폴더 구조와 컴포넌트 기준 세우는 법

요약: 여러 명이 동시에 개발하는 프론트엔드 프로젝트에서는 폴더 구조와 컴포넌트 설계 기준이 생산성과 유지보수성에 직접 연결됩니다. 이 글은 실제 협업 과정에서 자주 발생하는 중복, 네이밍 혼란, 수정 영향도 문제를 바탕으로 기능·도메인 중심 구조를 판단하는 기준과 공통 컴포넌트 분리 원칙을 정리합니다.

왜 대규모 프론트엔드에서 구조 기준이 먼저 필요한가

여러 명이 동시에 개발하는 프로젝트에서는 같은 기능도 사람마다 다른 방식으로 구현되기 쉽습니다. 초기에는 화면이 빠르게 늘어나기 때문에 이 문제가 잘 드러나지 않을 수 있습니다. 하지만 공통 규칙 없이 개발이 이어지면 다음 문제가 반복됩니다.

기준이 없을 때 자주 생기는 문제

• 비슷한 역할의 컴포넌트가 여러 위치에 중복 생성됨
• 버튼, 모달, 테이블처럼 자주 쓰는 UI가 페이지별로 따로 만들어짐
• 스타일과 동작이 조금씩 달라져 일관성이 깨짐
• 정책 변경 시 여러 파일을 각각 수정해야 함
• QA 단계에서 동일 기능의 동작 차이가 발견됨
• 코드 리뷰가 구조 논쟁에 머물고 품질 논의가 줄어듦

실제 프로젝트에서도 화면 수는 빠르게 늘어났지만 공통 기준이 없어 비슷한 컴포넌트가 여러 개 생기고 수정 범위가 계속 커졌습니다. 이때 구조와 설계 기준을 먼저 세우는 일이 개발 속도보다 더 중요한 준비 작업이라는 점을 체감할 수 있습니다.

폴더 구조를 정할 때 먼저 봐야 할 기준

폴더 구조는 유행하는 방식보다 프로젝트 운영 방식에 맞게 정하는 편이 실용적입니다. 먼저 확인할 질문은 하나입니다.

이 프로젝트는 무엇을 중심으로 커지는가

• 기능 확장 중심인가
• 화면 단위 운영 중심인가
• 도메인이 명확한 서비스인가

규모가 커지고 도메인이 분명한 서비스라면 페이지 기준보다 기능 또는 도메인 기준으로 나누는 편이 유지보수에 유리할 수 있습니다. 이유는 단순합니다.

• 관련 로직과 컴포넌트를 가까이 둘 수 있음
• 변경이 일어날 때 영향 범위를 파악하기 쉬움
• 도메인 단위 책임이 분명해짐
• 신규 인력이 구조를 읽기 쉬워짐

페이지 중심 구조가 맞는 경우

다음 조건이 강하면 페이지 중심도 현실적인 선택이 될 수 있습니다.

• 초기 서비스라 빠른 구현이 더 중요함
• 화면 수는 적지만 기능 복잡도는 낮음
• 도메인 분리가 아직 명확하지 않음

기능 또는 도메인 중심 구조가 맞는 경우

다음 조건이 많아질수록 기능 또는 도메인 중심 구조가 유리합니다.

• 운영 중인 화면과 기능이 지속적으로 늘어남
• 주문, 결제, 회원처럼 비즈니스 영역이 분명함
• 여러 개발자가 동시에 같은 영역을 수정함
• 공통 UI와 도메인 전용 UI를 구분할 필요가 큼

공통 컴포넌트와 도메인 전용 컴포넌트 구분 기준

컴포넌트 설계에서 가장 많이 흔들리는 부분이 이 구분입니다. 판단 기준은 복잡하게 잡지 않는 편이 좋습니다.

공통 컴포넌트로 분리할 조건

다음 조건을 만족하면 공통 컴포넌트로 둘 수 있습니다.

• 여러 화면에서 같은 형태로 반복됨
• 특정 도메인 규칙에 묶이지 않음
• 표현 방식이 중심이고 비즈니스 맥락이 약함

예시:

• 기본 버튼
• 공통 모달 레이아웃
• 범용 테이블 UI
• 입력 필드 레이아웃

도메인 전용 컴포넌트로 둘 조건

다음 조건이 강하면 도메인 안에서 관리하는 편이 적합합니다.

• 주문, 결제, 회원 등 특정 비즈니스 맥락이 강함
• 도메인 규칙이나 정책이 포함됨
• 다른 화면으로 재사용해도 같은 도메인 안에서만 의미가 있음

예시:

• 결제 실패 사유를 보여주는 모달
• 주문 상태 변경 이력을 표현하는 패널
• 회원 등급 조건에 따라 동작이 달라지는 UI

핵심은 재사용 빈도만 보지 않는 것입니다. 여러 군데에서 쓰여도 도메인 규칙이 강하면 무리하게 공통으로 올리지 않는 편이 유지보수에 유리합니다.

컴포넌트 책임 분리 원칙

대규모 프로젝트에서는 UI와 비즈니스 로직의 책임을 나누는 기준이 필요합니다. 기준이 없으면 테스트 범위가 커지고 재사용성도 낮아집니다.

기본 원칙

• UI만 담당하는 컴포넌트와 비즈니스 로직 컴포넌트를 최대한 분리함
• 상태는 실제로 그 값을 사용하는 가장 가까운 공통 상위에서 관리함
• 하위 컴포넌트는 필요한 데이터와 이벤트만 props로 받게 함

이렇게 나누는 이유

• 테스트 대상이 명확해짐
• 하위 컴포넌트 재사용성이 높아짐
• 상태 변경 흐름을 추적하기 쉬워짐
• 리뷰할 때 로직과 표현을 분리해서 볼 수 있음

체크포인트

props 설계

• 하위 컴포넌트가 꼭 필요한 값만 받는가
• 의미가 겹치는 props가 많은가
• 도메인 로직이 props 이름에 과하게 섞여 있는가

상태 설계

• 상태가 너무 상위에 있어 불필요한 전달이 생기지 않는가
• 반대로 너무 하위에 있어 여러 컴포넌트에서 재사용이 어려운가
• 공통 상위에서 관리하는 편이 변경 흐름 파악에 유리한가

이벤트 책임

• 이벤트 발생과 비즈니스 처리 책임이 분리되어 있는가
• 하위 컴포넌트는 사용자 액션 전달에 집중하는가
• 상위 컴포넌트가 정책 판단과 상태 변경을 담당하는가

문서화는 짧게, 예시는 구체적으로

기준은 말로만 공유하면 오래 유지되기 어렵습니다. 실제로 효과적이었던 방식은 문서와 예시 코드를 함께 관리하는 방법입니다.

문서에 최소한 포함할 항목

• 폴더 구조 원칙
• 네이밍 규칙
• 공통 컴포넌트 등록 기준
• 도메인 폴더 분리 기준
• 예외를 허용하는 조건

예시 코드가 중요한 이유

짧은 문서만으로는 해석이 달라질 수 있습니다. 반면 대표 기능 하나를 모범 사례처럼 만들어 두면 새로 합류한 개발자가 빠르게 기준을 이해할 수 있습니다.

효과는 다음과 같습니다.

• 온보딩 속도 개선
• 구조 관련 질문 감소
• 코드 리뷰 기준 통일
• 팀 내부 해석 차이 축소

기준을 세운 뒤 기대할 수 있는 변화

구조 기준을 정하면 가장 먼저 체감되는 변화는 코드 리뷰 방식입니다.

실제로 달라지는 점

• 어디에 무엇을 넣어야 하는지 공통 이해가 생김
• 구조 자체를 두고 논쟁하는 시간이 줄어듦
• 로직 품질과 예외 처리에 더 집중할 수 있음
• 기존 자산을 먼저 찾는 문화가 자리 잡음
• 비슷한 컴포넌트를 새로 만드는 일이 줄어듦
• 개발 속도가 급격한 편차 없이 안정화됨

여기서 중요한 점은 속도가 무조건 빨라진다고 단정하지 않는 것입니다. 다만 반복되는 구조 혼란과 중복 구현이 줄어들면, 전체 작업 흐름은 더 예측 가능해지는 경향이 있습니다.

기준이 너무 엄격할 때 생기는 부작용

기준이 많을수록 좋은 것은 아닙니다. 실제로 구조 규칙이 지나치게 세세하면 기능 추가보다 규칙 해석에 더 많은 시간이 들어갈 수 있습니다.

자주 생기는 부작용

• 작은 작업도 구조 판단에 시간이 오래 걸림
• 신규 인력이 규칙 자체를 부담으로 느낌
• 예외 상황에서 팀이 멈춤
• 개발보다 형식 준수에 집중하게 됨

조정 방법

핵심은 규칙의 계층을 나누는 것입니다.

꼭 지켜야 하는 핵심 원칙

• 공통 컴포넌트 기준
• 도메인 폴더 기준
• 네이밍 규칙
• 상태 책임 분리 원칙

상황에 따라 유연하게 적용할 권장 규칙

• 세부 하위 폴더 구성
• 예외적인 파일 배치 방식
• 특정 기능에서만 필요한 구조 보조 규칙

이 방식은 팀이 공통 기준을 잃지 않으면서도 불필요한 경직성을 줄이는 데 도움이 됩니다.

초기 스타트업과 대규모 운영 서비스의 판단 기준

같은 원칙을 모든 조직에 동일하게 적용하는 것은 비효율적일 수 있습니다.

초기 서비스에서의 기준

• 속도를 우선함
• 처음부터 지나치게 복잡한 구조는 피함
• 다만 확장 가능성이 높은 핵심 도메인에는 최소한의 분리 기준을 둠

적합한 접근:

• 폴더 구조를 단순하게 시작함
• 공통 컴포넌트 기준만 우선 정함
• 도메인 분리는 자주 변경되는 핵심 영역부터 적용함

운영 규모가 큰 서비스에서의 기준

• 역할과 책임을 더 명확히 나눔
• 도메인 기준 구조를 우선 검토함
• 공통 자산과 도메인 자산의 경계를 분명히 함
• 문서와 예시 코드를 함께 관리함

운영 서비스는 변경 비용이 빠르게 커지기 때문에 초기에 정리한 기준이 장기 유지보수 비용에 직접 영향을 줍니다.

바로 적용할 수 있는 실천 체크리스트

처음부터 완벽한 구조를 만들 필요는 없습니다. 우선 현재 팀이 자주 부딪히는 문제부터 정리하는 편이 현실적입니다.

1단계. 현재 혼란 사례 수집

• 중복 생성된 컴포넌트 목록 정리
• 폴더 위치 때문에 찾기 어려운 파일 사례 수집
• 네이밍이 제각각인 컴포넌트 확인
• 정책 변경 시 여러 파일을 수정했던 사례 기록

2단계. 세 가지 기준만 먼저 합의

• 공통 컴포넌트 기준
• 도메인 폴더 기준
• 네이밍 규칙

3단계. 대표 예시 코드 만들기

• 한 기능을 기준 구조로 구현
• 문서와 함께 저장
• 신규 작업은 이 예시를 우선 참고

4단계. 리뷰 기준에 반영

• 구조 적합성 확인
• 공통 자산 재사용 여부 확인
• 상태와 이벤트 책임 위치 확인

5단계. 분기별 또는 기능 단위로 조정

• 지나치게 복잡한 규칙 제거
• 예외가 잦은 규칙은 문서 수정
• 실제 사용성이 낮은 공통 컴포넌트는 재검토

결론

대규모 프론트엔드 프로젝트에서 폴더 구조와 컴포넌트 설계 기준은 선택 사항이 아니라 협업 비용을 줄이기 위한 운영 기준에 가깝습니다. 핵심은 복잡한 규칙을 많이 만드는 것이 아닙니다. 현재 프로젝트에서 반복되는 중복, 네이밍 혼란, 수정 영향도 문제를 먼저 확인하고, 공통 컴포넌트 기준과 도메인 구조 기준, 네이밍 규칙부터 팀 단위로 합의하는 것이 우선입니다. 이후 문서와 예시 코드를 함께 관리하면 기준은 더 오래 유지됩니다.

자주 묻는 질문

폴더 구조는 페이지 기준보다 도메인 기준이 항상 더 좋은가요?

항상 그렇지는 않습니다. 초기 서비스처럼 속도가 중요한 경우에는 페이지 기준이 더 단순하고 효율적일 수 있습니다. 다만 서비스 규모가 커지고 도메인이 명확해질수록 기능 또는 도메인 기준이 유지보수에 유리해지는 경우가 많습니다.

공통 컴포넌트는 많이 만들수록 좋은가요?

그렇지 않습니다. 여러 곳에서 사용된다는 이유만으로 공통으로 올리면 도메인 규칙까지 섞여 오히려 복잡해질 수 있습니다. 특정 비즈니스 맥락이 강한 컴포넌트는 도메인 안에서 관리하는 편이 적합합니다.

문서화는 어느 수준까지 해야 하나요?

길고 자세한 문서보다 짧은 원칙 문서와 대표 예시 코드 조합이 실용적입니다. 폴더 구조 원칙, 네이밍 규칙, 공통 컴포넌트 기준 정도를 먼저 정리하고, 실제 구현 예시 하나를 함께 두는 방식이 이해와 적용 속도 측면에서 효과적입니다.