[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -1,115 +1,198 @@
|
||||
---
|
||||
id: wiki-2026-0508-feature-driven-architecture
|
||||
title: Feature Driven Architecture
|
||||
title: Feature-Driven Architecture
|
||||
category: 10_Wiki/Topics
|
||||
status: needs_review
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: []
|
||||
aliases: [FDD, Feature Slices, Vertical Slice Architecture]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.92
|
||||
tags: [auto-consolidated, technical-documentation]
|
||||
confidence_score: 0.9
|
||||
verification_status: applied
|
||||
tags: [architecture, feature-slices, modularity, frontend]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-05-08
|
||||
last_reinforced: 2026-05-10
|
||||
github_commit: pending
|
||||
inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
|
||||
tech_stack:
|
||||
language: unspecified
|
||||
framework: unspecified
|
||||
language: typescript
|
||||
framework: nextjs
|
||||
---
|
||||
|
||||
# [[Feature-Driven Architecture|Feature-Driven Architecture]]
|
||||
# Feature-Driven Architecture
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
Feature-Driven [[Architecture|Architecture]](또는 기능 주도 아키텍처, [[Feature-Sliced Design|Feature-Sliced Design]])는 파일 유형이 아닌 실제 비즈니스 기능이나 도메인을 기준으로 프론트엔드 프로젝트 코드를 그룹화하는 구조 설계 방식입니다 [1-3]. 특정 기능에 필요한 UI 컴포넌트, 비즈니스 로직, 스타일(CSS)을 독립적인 기능 폴더(예: `features/`) 내에 함께 캡슐화하여 관리합니다 [4, 5]. 이를 통해 결합도를 낮추고 모듈 경계를 명확히 하여 대규모 애플리케이션에서의 유지보수성, 확장성 및 팀 간 병렬 협업을 획기적으로 개선합니다 [1, 3].
|
||||
## 매 한 줄
|
||||
> **"매 layer-by-type 의 feature-by-vertical-slice 의 invert"**. Feature-Driven Architecture 매 codebase 의 organization unit 매 feature/use-case — 매 each feature 매 own UI + state + API + tests 의 own. Frontend 매 FSD (Feature-Sliced Design), Backend 매 vertical slice / modular monolith 의 manifest.
|
||||
|
||||
---
|
||||
## 매 핵심
|
||||
|
||||
기능 중심 아키텍처(Feature-Driven [[Architecture|Architecture]])는 프로젝트를 파일의 유형(컴포넌트, 훅, 스타일 등)이 아닌 비즈니스 기능(Feature)이나 도메인을 기준으로 코드를 그룹화하는 프론트엔드 구조 설계 방식이다 [1-3]. 이 방식에서는 특정 기능과 관련된 컴포넌트, 비즈니스 로직, 스타일시트가 하나의 기능별 디렉터리 내에 함께 병치(co-located)된다 [1, 4]. 이를 통해 코드의 모듈성과 캡슐화를 높이고, 대규모 애플리케이션이 확장됨에 따라 발생할 수 있는 복잡성을 제어하여 유지보수성을 극대화한다 [1, 2, 5].
|
||||
### 매 Why
|
||||
- **Layer-by-type problem**: 매 `controllers/`, `services/`, `models/` 매 small project 의 fine, 매 100+ features 시 매 cross-cutting changes 의 5 directories 의 touch.
|
||||
- **Feature 의 lifecycle**: 매 feature 의 add/remove/own 의 single folder 의 happen.
|
||||
- **Team scaling**: 매 vertical squad 의 own 매 single feature folder, 매 conflicts 의 minimize.
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
* **기능 기반의 코드 분리와 캡슐화**
|
||||
초기 웹 개발이나 소규모 프로젝트에서 흔히 쓰이는 컴포넌트(components), 훅(hooks), 유틸(utils) 등 파일 유형별 폴더 그룹화 대신 비즈니스 기능이나 도메인을 기준으로 구조를 구성합니다 [3, 6]. 예를 들어, [[Next.js|Next.js]] 환경에서는 라우터 기능을 담당하는 폴더(`app/`)는 라우팅과 레이아웃 용도로만 최소화하여 사용하고, 실제 비즈니스 로직과 복잡한 상태 관리는 `features/` 디렉토리(예: `market-data`, `user-profile`, `auth`) 내부로 이동시킵니다 [4, 6]. 이러한 캡슐화는 버그 발생 시 개발자가 방대한 전역 폴더를 탐색할 필요 없이 해당 기능 폴더만 확인하게 해주어 문제 해결을 직관적으로 만듭니다 [4].
|
||||
### 매 FSD layers (frontend)
|
||||
1. `app/` — global setup, routing, providers.
|
||||
2. `pages/` — route compositions.
|
||||
3. `widgets/` — composite UI blocks.
|
||||
4. `features/` — user actions (login, addToCart).
|
||||
5. `entities/` — business objects (User, Product).
|
||||
6. `shared/` — UI kit, utils, API client.
|
||||
- 매 import rule: 매 upper layer → lower layer only.
|
||||
|
||||
* **유지보수성 및 확장성 향상**
|
||||
관심사의 분리([[_뇌와 팔다리의 분리_ - 관심사의 분리 (Separation of Concerns)|Separation of Concerns]])를 실현하는 이 구조는 대규모 프로젝트 확장에 매우 유리합니다 [2-4]. 기능 단위로 코드가 분리되어 있어 코드 소유권이 명확해지고, 여러 팀이 병렬로 작업하기 쉬워지며 리팩토링이 안전해집니다 [3]. 또한, 네트워크 호출 등 API 연동 로직도 기능 폴더 내의 전용 서비스로 묶어 두어 프론트엔드 요소와 백엔드 API 간의 의존성을 깔끔하게 분리할 수 있습니다 [4, 6].
|
||||
### 매 응용
|
||||
1. Next.js / Remix apps with FSD.
|
||||
2. Modular monolith — Java/.NET vertical slices.
|
||||
3. Mobile (RN/Flutter) feature modules.
|
||||
4. Microfrontend per-feature deployment.
|
||||
|
||||
* **CSS 구조 설계와의 강력한 시너지 (스타일 모듈화)**
|
||||
기능 주도 아키텍처는 스타일 시스템의 확장성을 설계하는 데 필수적입니다 [7]. 비즈니스 관련 컴포넌트와 그에 연결된 [[CSS Modules|CSS Modules]], [[SCSS|SCSS]] 파일을 같은 기능 디렉토리 내에 함께 위치시킵니다(co-location) [5]. 이러한 모듈화는 애플리케이션에서 특정 기능을 삭제할 때 해당 기능의 스타일 코드 역시 자동으로 폐기될 수 있게 보장하여, 레거시 프로젝트에 쌓이기 쉬운 사용되지 않는 '유령 스타일(ghost styles)'이나 데드 코드의 축적을 방지합니다 [5].
|
||||
전반적인 프로젝트 구조를 Feature-Sliced Design(FSD) 같은 기능 기반으로 구성하고, 개별 CSS 구조는 BEM 같은 방법론을 통해 관리하면 기술 부채를 크게 줄일 수 있는 강력한 아키텍처가 형성됩니다 [1, 8].
|
||||
## 💻 패턴
|
||||
|
||||
---
|
||||
|
||||
- **구조적 특징 및 모듈성:** 기능 중심 아키텍처에서는 코드를 앱의 실제 도메인(예: `market-data`, `user-profile`, `auth` 등)을 기반으로 `features/` 디렉터리에 분리하여 관리한다 [6]. 이러한 모듈성 덕분에 애플리케이션에서 특정 기능이 제거될 때 관련된 스타일과 코드도 자동으로 정리되므로, 레거시 코드베이스에 사용되지 않는 유령 스타일(ghost styles)이 축적되는 것을 방지할 수 있다 [4].
|
||||
- **관심사의 분리와 캡슐화:** 라우트 파일(예: [[Next.js|Next.js]]의 `app/` 디렉터리)은 라우팅과 레이아웃 생성 등 최소한의 역할만 수행하도록 유지하고, 실제 비즈니스 로직과 상태 관리는 기능 폴더로 이동시킨다 [1, 6]. 이를 통해 버그가 발생했을 때 거대한 전역 컴포넌트 폴더를 뒤질 필요 없이 특정 기능 폴더 내부만 확인하면 되는 캡슐화(Encapsulation) 이점을 얻을 수 있다 [6].
|
||||
- **[[Feature-Sliced Design|Feature-Sliced Design]] (FSD) 연계:** 전반적인 프론트엔드 아키텍처를 다루는 Feature-Sliced Design (FSD) 방법론은 애플리케이션을 여러 계층(layer)으로 구성하고 각 계층의 엄격한 의존성 규칙과 명확한 모듈 경계를 정의한다 [7]. FSD를 통해 프로젝트 구조를 관리하고 그 내부에서 BEM 또는 [[CSS Modules|CSS Modules]]를 활용하여 CSS 구조를 캡슐화하면 기술 부채를 크게 줄이는 강력하고 유지보수하기 쉬운 아키텍처가 형성된다 [7, 8].
|
||||
- **확장성 및 팀 협업:** 코드가 비즈니스 기능별로 그룹화되어 있으므로 여러 팀이 동시에 작업하는 병렬 워크플로우(Parallel team workflows)가 가능해진다 [3]. 또한, 각 기능에 대한 코드 소유권(Ownership)이 명확해져 장기적인 유지보수와 리팩토링을 훨씬 안전하게 수행할 수 있다 [3].
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
|
||||
No trade-offs available.
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
- **Related Topics:** [[Feature-Sliced Design (FSD)|Feature-Sliced Design (FSD]], CSS Modules, [[BEM|BEM]]
|
||||
- **Projects/Contexts:** [[Next.js Modular and Scalable Project Structure|Next.js Modular and Scalable Project Structure]], Large Frontend Projects
|
||||
- **Contradictions/Notes:** 소스에 따르면 애플리케이션 초기에는 파일 유형별 구성이 빠르고 편할 수 있으나, 데이터 대시보드나 복잡한 사용자 흐름을 다루게 될수록 관리 불능 상태에 빠지게 됩니다. 따라서 프로젝트 장기 스케일링을 위해 일찍부터 Feature-Driven Architecture 멘탈 모델을 채택하는 것이 거대한 리팩토링의 두통을 막는 방법으로 강력하게 권장됩니다 [2, 6, 9].
|
||||
|
||||
---
|
||||
*Last updated: 2026-04-26*
|
||||
|
||||
---
|
||||
|
||||
- **Related Topics:** [[Feature-Sliced Design (FSD)|Feature-Sliced Design (FSD]], Domain-Driven Architecture, BEM (Block Element Modifier), [[CSS Modules|CSS Modules]]
|
||||
- **Projects/Contexts:** 대규모 프론트엔드 프로젝트의 아키텍처 설계, 대형 엔터프라이즈 환경의 유지보수 가능한 스타일 시스템 엔지니어링, 확장 가능한 Next.js 프로젝트 구조 수립 [2, 4, 5].
|
||||
- **Contradictions/Notes:** 많은 개발자들이 컴포넌트, 훅, 로직 등을 같은 파일 유형끼리 묶는 전역 폴더 방식을 사용하지만, 애플리케이션이 성장하여 대시보드나 복잡한 사용자 흐름을 다루게 되면 이 방식은 관리가 불가능(unmanageable)해지므로 대규모 프로젝트에서는 기능 중심 아키텍처가 전역 스타일 디렉터리보다 우수하다고 평가받는다 [2, 5, 9].
|
||||
|
||||
---
|
||||
*Last updated: 2026-04-26*
|
||||
|
||||
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
|
||||
|
||||
**언제 이 지식을 쓰는가:**
|
||||
- *(TODO)*
|
||||
|
||||
**언제 쓰면 안 되는가:**
|
||||
- *(TODO)*
|
||||
|
||||
## 🧪 검증 상태 (Validation)
|
||||
|
||||
- **정보 상태:** needs_review
|
||||
- **출처 신뢰도:** A
|
||||
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
|
||||
|
||||
## 🧬 중복 검사 (Duplicate Check)
|
||||
|
||||
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
|
||||
- **처리 방식:** UPDATE (자동 정규화)
|
||||
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
|
||||
|
||||
## 🕓 변경 이력 (Changelog)
|
||||
|
||||
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
|
||||
|
||||
## 💻 코드 패턴 (Code Patterns)
|
||||
|
||||
**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
|
||||
|
||||
```text
|
||||
# TODO
|
||||
### FSD folder layout
|
||||
```
|
||||
src/
|
||||
├── app/ # providers, router, global styles
|
||||
├── pages/
|
||||
│ └── checkout/
|
||||
│ └── ui/Checkout.tsx
|
||||
├── widgets/
|
||||
│ └── header/ui/Header.tsx
|
||||
├── features/
|
||||
│ ├── auth-login/
|
||||
│ │ ├── ui/LoginForm.tsx
|
||||
│ │ ├── model/store.ts
|
||||
│ │ ├── api/login.ts
|
||||
│ │ └── index.ts # public api
|
||||
│ └── cart-add-item/
|
||||
├── entities/
|
||||
│ ├── user/{ui, model, api}/
|
||||
│ └── product/{ui, model, api}/
|
||||
└── shared/
|
||||
├── ui/Button.tsx
|
||||
└── api/baseQuery.ts
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준 (Decision Criteria)
|
||||
### Public API (index.ts barrel)
|
||||
```typescript
|
||||
// features/auth-login/index.ts
|
||||
export { LoginForm } from './ui/LoginForm';
|
||||
export { useLoginMutation } from './api/login';
|
||||
// 매 internal model/store 의 not exported — encapsulation
|
||||
```
|
||||
|
||||
**선택 A를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
### ESLint 의 enforce layer rules
|
||||
```javascript
|
||||
// .eslintrc — eslint-plugin-boundaries
|
||||
module.exports = {
|
||||
plugins: ['boundaries'],
|
||||
settings: {
|
||||
'boundaries/elements': [
|
||||
{ type: 'app', pattern: 'src/app/*' },
|
||||
{ type: 'pages', pattern: 'src/pages/*' },
|
||||
{ type: 'features', pattern: 'src/features/*' },
|
||||
{ type: 'entities', pattern: 'src/entities/*' },
|
||||
{ type: 'shared', pattern: 'src/shared/*' },
|
||||
],
|
||||
},
|
||||
rules: {
|
||||
'boundaries/element-types': ['error', {
|
||||
default: 'disallow',
|
||||
rules: [
|
||||
{ from: 'pages', allow: ['features', 'entities', 'shared'] },
|
||||
{ from: 'features', allow: ['entities', 'shared'] },
|
||||
{ from: 'entities', allow: ['shared'] },
|
||||
],
|
||||
}],
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
**선택 B를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
### Vertical slice (.NET / Node)
|
||||
```typescript
|
||||
// features/place-order/handler.ts
|
||||
export class PlaceOrderCommand {
|
||||
constructor(public userId: string, public items: Item[]) {}
|
||||
}
|
||||
|
||||
**기본값:**
|
||||
> *(TODO)*
|
||||
export async function placeOrder(cmd: PlaceOrderCommand, deps: Deps) {
|
||||
const user = await deps.users.findById(cmd.userId);
|
||||
if (!user) throw new NotFoundError();
|
||||
const order = Order.create(user, cmd.items);
|
||||
await deps.orders.save(order);
|
||||
await deps.bus.emit('order.placed', { orderId: order.id });
|
||||
return { orderId: order.id };
|
||||
}
|
||||
|
||||
## ❌ 안티패턴 (Anti-Patterns)
|
||||
// features/place-order/route.ts
|
||||
router.post('/orders', async (req, res) => {
|
||||
const result = await placeOrder(req.body, deps);
|
||||
res.json(result);
|
||||
});
|
||||
// 매 single folder 매 use-case 의 entire handle
|
||||
```
|
||||
|
||||
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
|
||||
### Cross-feature communication via events
|
||||
```typescript
|
||||
// features/cart-checkout — 매 features/inventory-update 의 NOT 매 import
|
||||
// 매 instead: emit event, 매 inventory feature 의 subscribe
|
||||
import { bus } from '@/shared/event-bus';
|
||||
|
||||
async function checkout(cart: Cart) {
|
||||
await bus.emit('checkout.completed', { items: cart.items });
|
||||
}
|
||||
|
||||
// features/inventory-update/index.ts
|
||||
bus.on('checkout.completed', async ({ items }) => {
|
||||
await decrementStock(items);
|
||||
});
|
||||
```
|
||||
|
||||
### Feature flag boundary
|
||||
```typescript
|
||||
// features/new-search-v2/index.ts
|
||||
import { useFlag } from '@/shared/feature-flags';
|
||||
import { SearchV1 } from '@/features/search-v1';
|
||||
import { SearchV2 } from './ui/SearchV2';
|
||||
|
||||
export function Search() {
|
||||
const v2 = useFlag('search-v2');
|
||||
return v2 ? <SearchV2 /> : <SearchV1 />;
|
||||
}
|
||||
// Removal 의 single folder delete
|
||||
```
|
||||
|
||||
## 매 결정 기준
|
||||
| 상황 | Approach |
|
||||
|---|---|
|
||||
| Solo / < 10 features | 매 layer-by-type 매 fine |
|
||||
| Frontend, growing team | 매 FSD |
|
||||
| Backend, modular monolith | 매 vertical slice (CQRS-style) |
|
||||
| Microservices | 매 service-per-feature 매 already |
|
||||
| Strict isolation 의 needed | 매 ESLint boundaries + barrel exports |
|
||||
|
||||
**기본값**: 매 frontend 매 FSD, 매 backend 매 vertical slice — 매 cross-feature 의 events.
|
||||
|
||||
## 🔗 Graph
|
||||
- 부모: [[Software-Architecture]] · [[Modular-Monolith]]
|
||||
- 변형: [[Feature-Sliced-Design]] · [[Vertical-Slice-Architecture]] · [[Hexagonal-Architecture]]
|
||||
- 응용: [[Microfrontends]] · [[CQRS]] · [[Bounded-Context]]
|
||||
- Adjacent: [[Domain-Driven-Design]] · [[Clean-Architecture]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: 매 10+ features, 매 multi-team. Frontend 매 page-driven 의 outgrow. Modular monolith 매 service split 의 prepare.
|
||||
**언제 X**: 매 small app (<10 screens). 매 prototype phase — 매 over-structure cost > benefit.
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **Cross-feature direct import**: 매 `features/cart` 매 `features/checkout/internal` 의 import — 매 coupling 의 reintroduce. Public API 만 의 use.
|
||||
- **God shared/**: 매 모든 utility 의 `shared/utils/` 의 dump — 매 entities/features 의 leak 의 should.
|
||||
- **Premature feature split**: 매 single-screen app 의 7 features 의 carve — 매 navigation cost.
|
||||
- **Layer skipping**: 매 `entities` 매 `features` 의 import — 매 dependency rule violation.
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (feature-sliced.design official; Jimmy Bogard "Vertical Slice Architecture").
|
||||
- 신뢰도 A.
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-10 | Manual cleanup — FSD layout + ESLint boundaries + vertical slice patterns |
|
||||
|
||||
Reference in New Issue
Block a user