Antigravity Agent
5.7 KiB
id, category, confidence_score, tags, last_reinforced, github_commit
| id | category | confidence_score | tags | last_reinforced | github_commit | |
|---|---|---|---|---|---|---|
| P-REINFORCE-AUTO-71F406 | 10_Wiki/💡 Topics/Design & Experience | 0.90 |
|
2026-04-20 | [P-Reinforce] Continuous Worker - 대규모 프론트엔드 웹 프로젝트 폴더 구조화 |
대규모 프론트엔드 웹 프로젝트 폴더 구조화
📌 한 줄 통찰 (The Karpathy Summary)
대규모 프론트엔드 웹 프로젝트의 폴더 구조화는 프로젝트의 규모와 복잡성이 증가함에 따라 관심사를 효과적으로 분리하여 유지보수성과 확장성을 높이는 설계 과정이다 [1, 2]. 초기에는 개발의 속도를 높일 수 있는 역할 중심의 폴더 구조가 주로 사용되지만, 프로젝트가 성장함에 따라 관련 파일을 하나의 단위로 묶어 관리하는 기능 중심의 구조(예: Feature-Sliced Design 아키텍처)로 진화하게 된다 [1, 3, 4]. 이는 데이터와 화면 간의 의존성을 줄이고 컴포넌트 및 기능의 결합도를 낮추어 코드 관리를 용이하게 하기 위한 필수적인 원칙이다 [5, 6].
📖 구조화된 지식 (Synthesized Content)
-
역할 중심 폴더 구조와 한계: 현대의 프론트엔드 프로젝트는 주로
/api(백엔드 통신),/components(공통 컴포넌트),/hooks,/pages(라우팅),/store(상태 관리),/utils등 세부적인 역할을 기준으로 폴더를 분리하는 방식을 사용한다 [7, 8]. 이 방식은 규모가 작을 때는 매우 효율적이지만, 대규모 프로젝트가 될 경우 특정 관심사(기능)를 찾아 수정할 때 관련 파일들이 여러 역할 폴더에 흩어져(파편화) 파악이 어려워지고, 불필요한 코드까지 건드리게 되는 등 유지보수와 기능 확장의 명확한 한계를 맞이하게 된다 [3, 4, 9]. -
프로젝트 진화에 따른 폴더 구조의 변화: 프로젝트의 성장에 따라 관심사의 방향이 달라지므로 폴더 구조 또한 지속적으로 진화해야 한다 [4, 10].
- 초기 단계: 화면 구현에 초점을 맞추어 페이지(route)별로 화면을 나누고, 공통 컴포넌트는
/shared등에 보관하는 형태가 적합하다 [2]. - 성장기: 공통 로직을 제외하고, 각 페이지별로 독립적인 상태 관리와 API 호출을 묶어 페이지 폴더 안에 포함시킴으로써 책임 범위를 명확히 하는 방식이 효율적이다 [2, 6].
- 릴리즈 막바지 및 유지보수 시기: 데이터 처리와 비즈니스 로직 중심의 대화가 주를 이루기 시작한다 [6]. 이때 화면을 그리는 뷰(View) 컴포넌트와 데이터를 다루는 도메인 컴포넌트를 명확히 분리해야 하며, 신규 기능의 추가나 삭제 시 커밋 범위를 제한하기 위해 코드를 기능(Feature) 단위로 모아 관리해야 한다 [4, 6, 9].
- 초기 단계: 화면 구현에 초점을 맞추어 페이지(route)별로 화면을 나누고, 공통 컴포넌트는
-
기능 중심 아키텍처 (Feature-Sliced Design, FSD) 도입: 대규모 프로젝트에서 발생하는 기능 간 결합도 상승 및 관리의 어려움을 근본적으로 해결하기 위해 기능(Feature)을 기준으로 코드를 분리하는 FSD 아키텍처가 대두되었다 [1, 5]. 하나의 기능과 관련된 모든 파일을 같은 폴더에 묶어 독립적으로 관리하도록 설계함으로써 복잡성을 줄이고, 여러 개발자가 협업할 때 필요한 멘탈 모델을 일치시켜 확장성을 크게 향상시킨다 [1, 5, 11].
-
마이크로 프론트엔드 (Micro Frontends) 활용: 수백 개의 화면과 다양한 기능이 혼재된 아주 거대한 규모의 경우, 모놀리식 프론트엔드를 분해하여 마이크로 프론트엔드 아키텍처를 채택하기도 한다 [12-14]. 이 접근 방식은 장바구니, 상품 목록 등의 비즈니스 기능 단위를 별도의 개발 팀이 소유하게 하여, 프레임워크나 기술 스택에 구애받지 않고 독립적인 개발, 테스트, 배포가 가능하게 함으로써 팀의 자율성과 유지보수성을 극대화한다 [13, 15].
⚠️ 모순 및 업데이트 (Contradictions & RL Update)
- 과거 데이터와의 충돌: 자동화 엔진에 의해 매핑된 지식으로, 추후 정밀 검증 필요.
- 정책 변화: Design & Experience 분야의 자동 자산화 수행.
🔗 지식 연결 (Graph)
- Related Topics: 관심사의 분리 (Separation of Concerns), Feature-Sliced Design (FSD), 마이크로 프론트엔드 (Micro Frontends)
- Projects/Contexts: 항해 DEV LAB 미니 학술회 (FSD와 프론트엔드 관심사 분리에 관한 시각과 발표 내용이 논의된 맥락 [16]), 스포티파이 (Spotify) (자율적인 기능 단위 '스쿼드' 모델과 프론트엔드를 분리하는 마이크로 프론트엔드를 결합하여 대규모 웹 앱 개발의 확장성을 획기적으로 개선한 실제 기업 사례 [17, 18])
- Contradictions/Notes: 소스에 따르면 폴더 구조 설계에 있어서 절대적으로 "이것이 정답"이라고 할 수 있는 완벽한 구조는 존재하지 않는다. 프로젝트의 특성과 규모, 팀의 요구사항, 그리고 시기에 따라 기능 중심, 역할 중심, 혹은 도메인 중심 등으로 유연하게 폴더 구조를 진화시키고 균형을 맞추는 것이 핵심이라고 조언한다 [11, 19].
Last updated: 2026-04-18
- Raw Source: 00_Raw/2026-04-20/대규모 프론트엔드 웹 프로젝트 폴더 구조화.md