From f67ae4e2f3285269664f75f2d2e573104f3629d6 Mon Sep 17 00:00:00 2001
From: happybell80 <happybell80@naver.com>
Date: Sat, 29 Nov 2025 17:23:14 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20React=20=EA=B5=AC=EC=A1=B0=20=EC=9B=90?=
 =?UTF-8?q?=EC=B9=99=20=EB=AC=B8=EC=84=9C=20=EC=B6=94=EA=B0=80=20=EB=B0=8F?=
 =?UTF-8?q?=20README=20=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 book/300_architecture/300_README.md           |   4 +
 .../313_React_구조_원칙.md                | 133 ++++++++++++++++++
 2 files changed, 137 insertions(+)
 create mode 100644 book/300_architecture/313_React_구조_원칙.md

diff --git a/book/300_architecture/300_README.md b/book/300_architecture/300_README.md
index fa04a8e..d92c78a 100644
--- a/book/300_architecture/300_README.md
+++ b/book/300_architecture/300_README.md
@@ -10,6 +10,9 @@ Part 2에서 우리는 게임 메커니즘을 활용한 설계를 소개했습
 
 ## 목차
 - 310_전체_시스템_구조_컨테이너와_마이크로서비스.md
+- 311_FastAPI_구조_원칙.md
+- 312_문서_작성_원칙.md
+- 313_React_구조_원칙.md
 - 320_Slack_기반_인터페이스_설계.md
 - 330_백엔드_PostgreSQL_ChromaDB_Vector_Memory.md
 - 340_GUI_공유_아키텍처_레벨기반_권한.md
@@ -22,6 +25,7 @@ Part 2에서 우리는 게임 메커니즘을 활용한 설계를 소개했습
 
 ## 대상 독자
 - 백엔드 개발자
+- 프론트엔드 개발자
 - DevOps 엔지니어
 - 시스템 아키텍트
 
diff --git a/book/300_architecture/313_React_구조_원칙.md b/book/300_architecture/313_React_구조_원칙.md
new file mode 100644
index 0000000..4b8bea2
--- /dev/null
+++ b/book/300_architecture/313_React_구조_원칙.md
@@ -0,0 +1,133 @@
+# React 프론트엔드 구조 원칙
+
+**작성일**: 2025-11-29
+**수정일**: 2025-11-29
+**참고**: 311_FastAPI_구조_원칙.md, 312_문서_작성_원칙.md
+
+## 1. 컴포넌트 설계 원칙
+
+### Single Responsibility Principle (SRP)
+- 각 컴포넌트는 하나의 책임만 수행
+- 큰 컴포넌트는 작은 서브 컴포넌트나 훅으로 분리
+- UI 렌더링과 비즈니스 로직 분리
+
+### 컴포넌트 분리 기준
+- 300줄 이상: 서브 컴포넌트 또는 커스텀 훅으로 분리 검토
+- 1000줄 이상: Monolithic Component로 간주, 리팩토링 필수
+- UI + API + State + Events 모두 혼재: 계층 분리 필요
+
+## 2. 비즈니스 로직 분리
+
+### Custom Hooks 패턴
+- 데이터 fetching 로직: `useFetch`, `useQuery` 등 커스텀 훅으로 추출
+- 상태 관리 로직: `useState` 복잡도가 높으면 커스텀 훅으로 분리
+- UI 컴포넌트는 렌더링과 이벤트 핸들링만 담당
+
+### 계층 분리
+```
+UI Components (렌더링)
+    ↓
+Custom Hooks (비즈니스 로직)
+    ↓
+API Services (통신)
+    ↓
+State Management (전역 상태)
+```
+
+## 3. 상태 관리 원칙
+
+### Immutability
+- 상태 직접 변경 금지: 항상 새로운 객체/배열 생성
+- 예측 가능한 상태 업데이트 보장
+- React 리렌더링 최적화
+
+### 상태 관리 전략
+- 컴포넌트 내부 상태: `useState` (로컬 UI 상태)
+- 전역 상태: Context API 또는 상태 관리 라이브러리 (Zustand/Recoil)
+- 서버 상태: React Query, SWR 등 전용 라이브러리
+
+### Prop Drilling 회피
+- 3단계 이상 props 전달 시 Context API 또는 상태 관리 도입
+- 불필요한 중간 컴포넌트 통과 제거
+
+## 4. 파일 및 폴더 구조
+
+### 권장 구조
+```
+src/
+├── components/          # 재사용 가능한 UI 컴포넌트
+│   ├── ui/             # 기본 UI 컴포넌트 (버튼, 입력 등)
+│   └── features/       # 기능별 컴포넌트
+├── hooks/              # 커스텀 훅
+├── services/           # API 통신 로직
+├── stores/             # 전역 상태 관리 (선택)
+├── utils/              # 유틸리티 함수
+├── types/              # TypeScript 타입 정의
+└── pages/              # 페이지 컴포넌트
+```
+
+### 파일 명명 규칙
+- 컴포넌트: `PascalCase.tsx` (예: `ChatInterface.tsx`)
+- 훅: `use` 접두사 + `PascalCase.ts` (예: `useChat.ts`)
+- 유틸: `camelCase.ts` (예: `formatDate.ts`)
+- 타입: `PascalCase.ts` (예: `Message.ts`)
+
+## 5. 네이밍 규칙
+
+### 명확한 네이밍
+- 구체적이고 설명적인 이름 사용
+- 축약어 지양, 의도가 명확한 이름
+- 예: `handleSendMessage` > `handleSend`, `chatHistory` > `data`
+
+### 변수/함수 네이밍
+- 컴포넌트: `PascalCase`
+- 함수: `camelCase`, 동사로 시작 (`handle`, `fetch`, `update`)
+- 상수: `UPPER_SNAKE_CASE`
+- boolean: `is`, `has`, `should` 접두사
+
+## 6. 코드 품질 원칙
+
+### useEffect 의존성 관리
+- 의존성 배열 정확히 명시
+- 중복 호출 및 무한 루프 방지
+- cleanup 함수 적절히 사용
+
+### 성능 최적화
+- 불필요한 리렌더링 방지: `React.memo`, `useMemo`, `useCallback` 적절히 활용
+- 대용량 리스트: 가상화 (virtualization) 고려
+- 이미지/리소스: lazy loading 적용
+
+### 타입 안전성
+- TypeScript 타입 정의 명확히
+- `any` 타입 최소화
+- 인터페이스/타입 재사용
+
+## 7. 금지 사항
+
+- ❌ 하드코딩된 값: 상수, 설정값은 환경변수 또는 설정 파일로 관리
+- ❌ Monolithic Component: 1000줄 이상 컴포넌트
+- ❌ 컴포넌트 내 비즈니스 로직: 커스텀 훅으로 분리
+- ❌ 상태 직접 변경: Immutability 원칙 위반
+- ❌ console.log 디버그 코드: 프로덕션 코드에 남기지 않음
+- ❌ 순환 import
+- ❌ Prop Drilling: 3단계 이상 전달 시 상태 관리 도입
+
+## 8. 체크리스트
+
+코드 작성 전/후 확인:
+- [ ] 각 컴포넌트가 단일 책임을 수행하는가?
+- [ ] 비즈니스 로직이 커스텀 훅으로 분리되었는가?
+- [ ] 상태 변경이 Immutability 원칙을 따르는가?
+- [ ] 파일 크기가 300줄 이하인가? (예외: 핵심 컴포넌트는 가급적 유지)
+- [ ] 하드코딩된 값이 없는가?
+- [ ] Prop Drilling이 3단계 이상인가? (상태 관리 필요)
+- [ ] TypeScript 타입이 명확히 정의되었는가?
+- [ ] useEffect 의존성이 정확한가?
+
+## 9. 참고
+
+- 상위 원칙: 이 문서는 일반적인 React 프로젝트 원칙을 다룹니다.
+- 프로젝트별 특화 규칙: 각 프로젝트의 README나 문서에 추가 규칙 명시
+- 백엔드 원칙: `311_FastAPI_구조_원칙.md` 참고
+- 문서 작성 원칙: `312_문서_작성_원칙.md` 참고
+