FSD 아키텍처 적용기: "이 코드는 어디에 넣어야 할까?"라는 질문에 답한 코드 위치의 명확성

카카오페이의 ceo-plus 레포는 기능이 늘면서 components, apis, pages, helpers가 뒤섞인 구조로 복잡해졌고, 코드가 어디에 있어야 하는지 판단하는 비용이 커졌다. 그 결과 탐색 시간은 늘고, 작업자마다 구조 해석이 달라지는 비일관성과 사이드 이펙트에 대한 불안이 함께 커졌다.

이를 해결하기 위해 FSD(Feature-Sliced Design) 를 도입했다. FSD는 코드를 Layers > Slices > Segments 로 나눠 재사용 범위와 의존성을 통제하는 아키텍처로, 상위 레이어가 하위 레이어만 참조하는 단방향 구조를 전제로 한다.

핵심 레이어는 app, pages, widgets, features, entities, shared이며, 이 프로젝트에서는 widgets 레이어를 쓰지 않기로 했다. 독립적인 대형 UI 컴포넌트의 비중이 낮아 기능 단위는 주로 features 안에서 관리하는 편이 더 맞았기 때문이다.

또한 pages는 같은 도메인끼리 slice grouping 을 허용해 과도한 slice 생성을 줄였다. 혜택, 쿠폰처럼 동일 도메인에서 여러 페이지가 생기는 서비스 특성상, 페이지마다 slice를 쪼개면 구조가 다시 복잡해질 수 있어서다.

API 위치도 재정의했다.

• pages/[slice]/api: 해당 페이지에서만 쓰는 API
• features/[slice]/api: 같은 페이지 그룹 안에서 재사용하는 기능 API
• entities/[domain]/api: 여러 페이지 그룹에서 공통으로 쓰는 도메인 API

마이그레이션은 한 번에 뒤집는 방식이 아니라 bottom-up 으로 진행했다. 먼저 pages에 두고, 여러 페이지에서 재사용되면 features, 더 넓게 재사용되면 entities, 전역 공통은 shared로 올리는 규칙을 세워 팀이 자연스럽게 레이어 감각을 익히도록 했다.

적용 후에는 코드의 위치를 보고 역할을 바로 파악할 수 있게 됐다. 재사용 범위가 분명해지면서 잘못된 의존성을 줄였고, 기능 단위의 응집도가 높아져 리팩토링과 테스트도 쉬워졌다. 결국 FSD는 코드가 있어야 할 자리를 명확히 정의해 주는, 실무형 구조 해법으로 작동했다.