ADR-0001: 모듈 분할 방법론으로 Feature-Sliced Design v2.1 채택
상태
Accepted
날짜
2026-08-10
맥락
본 표준의 1순위 품질 목표는 예측 가능성이며, "규칙만으로 코드의 배치 위치가 일의적으로 결정된다"로 정의되어 있습니다. 주된 독자가 AI 코딩 에이전트이므로 배치 판정이 실행마다 달라지면 같은 요구사항이 매번 다른 위치에 구현됩니다.
Angular 자체는 폴더 구조를 규정하지 않습니다. 스타일 가이드가 파일명과 클래스명을 다루지만, 어떤 코드가 어느 폴더로 가는지는 정의하지 않습니다. 방법론 없이 시작하면 "이 조회 함수를 서비스로 뺄지 컴포넌트에 둘지"를 매번 판단하게 되고, 판단 기준이 문서화되지 않아 사람과 에이전트가 서로 다른 결론에 도달합니다.
결정
Feature-Sliced Design v2.1을 모듈 분할 방법론으로 채택합니다.
- 계층은
app·pages·shared세 개로 시작합니다.features와entities는 동일 코드가 두 곳 이상에서 실제로 사용되는 것이 확인된 시점에 생성합니다. - 계층 간 임포트는 하위 방향으로만 허용하고, 슬라이스 외부 접근은
index.ts공개 API를 경유합니다. - Angular의
src/app디렉터리를 FSDapp계층으로 그대로 사용합니다.
강제 수단은 Steiger입니다. forbidden-imports, no-higher-level-imports, public-api, no-public-api-sidestep, no-cross-imports, insignificant-slice, excessive-slicing이 빌드를 실패시킵니다.
세부 규칙은 패키지 배치와 참조 규칙이 원본입니다.
검토한 대안
Angular 관례 기반 구조 (core / shared / features)
| 구분 | 내용 |
|---|---|
| 장점 | 프레임워크 문서·스키매틱·생태계와 마찰이 없습니다. 별도 학습이 필요 없습니다 |
| 단점 | features 내부에서 무엇이 어디로 가는지에 대한 결정론이 없습니다. 공유 로직이 shared로 흘러 비대해지는 것을 막을 규칙과 그 강제 수단을 직접 설계해야 합니다 |
| 기각 사유 | 1순위 목표인 예측 가능성을 달성하려면 배치 규칙을 직접 정의하고 린트도 직접 만들어야 합니다. FSD는 그 둘을 이미 갖고 있습니다 |
백엔드 바운디드 컨텍스트 미러링
| 구분 | 내용 |
|---|---|
| 장점 | 서버 API 경계와 1:1로 대응하며 백엔드 문서와 상호 참조가 쉽습니다 |
| 단점 | 화면은 여러 컨텍스트를 가로지르는 것이 정상이므로 미러링이 곧 깨집니다. 서버 리팩터링이 프론트엔드 구조 변경을 유발합니다 |
| 기각 사유 | 화면 단위와 서버 도메인 단위가 일치하지 않는 것이 예외가 아니라 기본입니다 |
결과
배치 규칙과 그 강제 수단을 재발명하지 않게 됩니다. 문서는 판정 트리와 Angular 교차 규칙만 정의하면 되고, 나머지는 FSD 공식 문서를 참조합니다. 에이전트가 이미 학습한 규범이므로 지시 문장이 짧아집니다.
감수하는 사항은 다음과 같습니다.
- FSD 공식 프레임워크 통합 가이드에 Angular가 없습니다. Next.js · Nuxt · Vite · Astro만 존재하며, Angular 교차 규칙은 본 표준이 직접 정의해야 합니다. 대규모 적용 사후 보고를 확인하지 못했으므로 선례 부족 상태에서 진행합니다.
- Steiger가 0.6.0 베타입니다. README에 API 변경 가능성이 명시되어 있고 0.5.0에서 설정 형식이 변경된 전례가 있습니다. 규칙 본문을 문서에 옮겨 적지 않고
steiger.config.ts를 원본으로 두어 갱신 비용을 낮춥니다. pages슬라이스의 배럴 파일이 Angular 지연 로딩과 간섭합니다.loadComponent가index.ts를 경유하면 같은 배럴이 내보내는 리졸버가 초기 번들로 끌려옵니다. 화면 컴포넌트 자체는 지연 청크로 분리되므로 청크 분리가 무뎌지지는 않습니다.