diff --git a/README.md b/README.md
index aaff1ee..042c7b9 100644
--- a/README.md
+++ b/README.md
@@ -1,169 +1,236 @@
-# Project
+# 프로젝트 잼 (Project Jam)
-프로젝트 잼 - 함께 만들어가는 사이드 프로젝트
+함께 만들어가는 사이드 프로젝트 매칭 플랫폼 🚀
+
+> **"아이디어는 있지만 팀원이 없다?"** 프로젝트 잼에서 완벽한 팀원을 찾아보세요!
## 📋 목차
+- [프로젝트 소개](#-프로젝트-소개)
+- [주요 기능](#-주요-기능)
- [기술 스택](#-기술-스택)
- [프로젝트 구조](#-프로젝트-구조)
- [FSD 아키텍처](#-fsd-아키텍처)
-- [코드 품질 관리](#-코드-품질-관리)
- [개발 환경 설정](#-개발-환경-설정)
- [브랜치 전략 & CI/CD](#-브랜치-전략--cicd)
- [커밋 컨벤션](#-커밋-컨벤션)
- [개발 가이드라인](#-개발-가이드라인)
-## 🛠 기술 스택
+## 🎯 프로젝트 소개
+
+프로젝트 잼은 **사이드 프로젝트를 함께 진행할 팀원을 찾는 플랫폼**입니다.
+
+### 💡 핵심 가치
+- **매칭**: 기술 스택과 관심사가 맞는 개발자 연결
+- **협업**: 체계적인 프로젝트 관리와 소통 지원
+- **성장**: 실무 경험을 통한 개발 역량 향상
+
+### 🎯 타겟 사용자
+- 사이드 프로젝트 아이디어는 있지만 팀원이 필요한 개발자
+- 새로운 기술을 배우며 실무 경험을 쌓고 싶은 개발자
+- 포트폴리오 프로젝트를 함께 만들고 싶은 개발자
+
+## ✨ 주요 기능
+
+### 🔍 프로젝트 탐색
+- **스마트 검색**: 기술 스택, 포지션, 카테고리별 필터링
+- **실시간 검색**: 즉석 결과 표시 및 검색 기록 관리
+- **페이지네이션**: 부드러운 스크롤과 함께하는 페이지 이동
-### Core
-- **React 19** - UI 라이브러리
-- **TypeScript 5** - 타입 시스템
-- **Vite** - 빌드 도구
+### 📝 프로젝트 관리
+- **4단계 등록**: 직관적인 프로젝트 생성 프로세스
+- **상세 정보**: 기술 스택, 일정, 팀 구성, 요구사항 등
+- **실시간 수정**: 프로젝트 정보 동적 업데이트
-### Code Quality
-- **ESLint** - 코드 품질 검사
-- **Prettier** - 코드 포매팅
-- **Husky** - Git Hooks 관리
-- **lint-staged** - 스테이지된 파일만 검사
-- **Commitlint** - 커밋 메시지 컨벤션
+### 👥 팀원 매칭
+- **지원 시스템**: 원클릭 프로젝트 지원 및 관리
+- **이메일 연동**: EmailJS를 통한 직접 소통 지원
+- **프로필 시스템**: 개발자 경력 및 관심사 표시
-### Architecture
-- **FSD (Feature-Sliced Design)** - 프로젝트 아키텍처
-- **Path Alias** - 절대 경로 import
+### 🎨 사용자 경험
+- **반응형 디자인**: 모바일부터 데스크톱까지 완벽 지원
+- **다크/라이트 테마**: 사용자 선호에 따른 테마 전환
+- **접근성**: ARIA 표준 준수 및 키보드 네비게이션
+
+## 🛠 기술 스택
+
+### Frontend Core
+- **React 19** - 최신 UI 라이브러리 + Concurrent Features
+- **TypeScript 5** - 강타입 시스템으로 안정성 확보
+- **Vite** - 초고속 빌드 및 HMR 지원
+- **Material-UI (MUI)** - 일관된 디자인 시스템
+
+### State Management & Data Fetching
+- **Zustand** - 가볍고 직관적인 상태 관리
+- **TanStack Query (React Query)** - 서버 상태 관리 및 캐싱
+- **React Hook Form** - 고성능 폼 상태 관리
+
+### Backend & Infrastructure
+- **Firebase** - 실시간 데이터베이스 및 인증
+ - Authentication (Google, GitHub)
+ - Firestore Database
+ - Storage
+- **EmailJS** - 클라이언트 사이드 이메일 발송
+- **Vercel** - 자동 배포 및 호스팅
+
+### Code Quality & DX
+- **ESLint + Prettier** - 코드 품질 및 스타일 일관성
+- **Husky + lint-staged** - Git Hooks를 통한 자동 검증
+- **Commitlint** - 커밋 메시지 컨벤션 강제
+- **TypeScript Strict Mode** - 엄격한 타입 검사
+
+### Architecture & Patterns
+- **FSD (Feature-Sliced Design)** - 확장 가능한 프로젝트 구조
+- **Compound Component Pattern** - 재사용 가능한 UI 컴포넌트
+- **Custom Hooks Pattern** - 비즈니스 로직 분리
## 📁 프로젝트 구조
```
src/
-├── app/ # 앱 전체 설정 및 진입점
-│ ├── configs/ # 환경 설정
-│ ├── entry/ # 앱 진입점
-│ ├── routes/ # 라우팅 설정
-│ └── styles/ # 글로벌 스타일
-├── entities/ # 도메인 엔티티 (Read 로직)
-├── features/ # 기능 단위 (CUD 로직)
-├── pages/ # 페이지 컴포넌트
-├── shared/ # 공통 유틸리티
-└── widgets/ # 복합 컴포넌트
+├── app/ # 🏛️ 앱 전체 설정 및 진입점
+│ ├── configs/ # 환경 설정 (Vite, Firebase)
+│ ├── entry/ # 앱 진입점 (main.tsx)
+│ ├── routes/ # 라우팅 설정 (Auth, Layout)
+│ └── styles/ # 글로벌 스타일 & 테마
+├── widgets/ # 🧩 복합 UI 컴포넌트
+│ ├── Header/ # 네비게이션 헤더
+│ ├── Footer/ # 푸터
+│ ├── hero/ # 메인 히어로 섹션
+│ └── BackToHome/ # 홈 이동 버튼
+├── pages/ # 📄 페이지 컴포넌트 (8개)
+│ ├── home/ # 메인 홈페이지
+│ ├── project-list/ # 프로젝트 목록 & 검색
+│ ├── project-detail/ # 프로젝트 상세보기
+│ ├── project-insert/ # 프로젝트 등록 (4단계)
+│ ├── user-profile/ # 사용자 프로필
+│ ├── login/ # 로그인
+│ ├── signup/ # 회원가입
+│ └── not-found/ # 404 페이지
+├── features/ # ⚡ 비즈니스 기능 (CUD 로직)
+│ ├── auth/ # 소셜 로그인 & 로그아웃
+│ ├── projects/ # 프로젝트 CRUD & 좋아요
+│ └── email/ # 이메일 발송 시스템
+├── entities/ # 📊 도메인 엔티티 (Read 로직)
+│ ├── projects/ # 프로젝트 조회 & 표시
+│ ├── search/ # 검색 & 필터링
+│ └── user/ # 사용자 정보 표시
+└── shared/ # 🔧 공통 유틸리티
+ ├── api/ # API 클라이언트
+ ├── hooks/ # 공통 커스텀 훅
+ ├── stores/ # Zustand 스토어
+ ├── types/ # 공통 타입 정의
+ ├── ui/ # 재사용 UI 컴포넌트
+ └── libs/ # 유틸리티 함수
```
-### 폴더별 표준 구조
+### 📊 주요 도메인 모델
-각 도메인 폴더(`entities`, `features`)는 다음과 같은 표준 구조를 따릅니다:
-
-```
-domain-name/
-├── api/ # API 요청 로직
-├── hooks/ # 커스텀 훅
-├── queries/ # React Query 설정
-├── types/ # TypeScript 타입 정의
-├── ui/ # UI 컴포넌트
-├── libs/ # 유틸리티 함수
-└── index.ts # 외부 노출 인터페이스
-```
+- **프로젝트 도메인**: 제목, 설명, 기술스택, 카테고리, 포지션, 일정 등
+- **사용자 도메인**: 이름, 이메일, 역할, 경험, 좋아요/지원 프로젝트 등
+- **검색 도메인**: 카테고리, 상태, 워크플로우, 포지션, 정렬 기준 등
## 🏗 FSD 아키텍처
-### 계층별 역할
+### 계층별 역할 및 실제 구현
1. **App Layer** (`src/app/`)
- - 앱 전체 설정 및 초기화
- - 글로벌 프로바이더, 라우터 설정
+ - 🔧 **설정**: Firebase, React Query, MUI Theme
+ - 🛣️ **라우팅**: Private Routes, Auth Guards
+ - 🎨 **글로벌 스타일**: CSS Variables, 폰트 설정
2. **Pages Layer** (`src/pages/`)
- - 각 페이지별 컴포넌트
- - 라우팅과 연결되는 최상위 페이지
+ - 📄 **페이지 조합**: 8개 주요 페이지
+ - 🔗 **라우팅 연결**: URL 파라미터 처리
+ - 📱 **레이아웃**: 페이지별 고유 레이아웃
3. **Widgets Layer** (`src/widgets/`)
- - 여러 features를 조합한 복합 컴포넌트
- - 페이지의 큰 섹션 단위
+ - 🧩 **복합 컴포넌트**: Header, Footer, Hero
+ - 📦 **재사용 섹션**: 여러 페이지에서 공통 사용
4. **Features Layer** (`src/features/`)
- - **CUD 로직** (Create, Update, Delete)
- - 사용자 인터랙션이 포함된 기능
- - 상태 변경을 담당
+ - ⚡ **CUD 로직**: 프로젝트 생성/수정/삭제, 좋아요
+ - 🔐 **인증**: 소셜 로그인, 로그아웃
+ - 📧 **이메일**: EmailJS 연동 메시지 발송
5. **Entities Layer** (`src/entities/`)
- - **Read 로직** (조회, 표시)
- - 도메인 모델과 읽기 전용 로직
- - 비즈니스 엔티티 표현
+ - 📊 **Read 로직**: 프로젝트 조회, 검색, 사용자 표시
+ - 🎨 **UI 컴포넌트**: 카드, 리스트, 상세 정보
+ - 🔍 **검색 시스템**: 필터링, 페이지네이션
6. **Shared Layer** (`src/shared/`)
- - 공통 유틸리티, UI 컴포넌트
- - 모든 계층에서 사용 가능
+ - 🔧 **공통 도구**: API 클라이언트, 유틸리티
+ - 💾 **상태 관리**: Zustand 스토어
+ - 🎨 **UI 킷**: 버튼, 모달, 스피너 등
-### 의존성 규칙
+### 의존성 규칙 시각화
```
-App ← Pages ← Widgets ← Features ← Entities ← Shared
-```
-
-- 하위 계층은 상위 계층을 참조할 수 없습니다
-- 같은 계층 내 다른 모듈 간 직접 참조는 금지됩니다
-- 같은 모듈 내에서는 자유롭게 참조 가능합니다
-
-## 🔍 코드 품질 관리
-
-### ESLint 규칙
-
-- **FSD 아키텍처 강제**: 계층별 참조 제한
-- **TypeScript 엄격 모드**: 명시적 함수 반환 타입 필수
-- **React 모범 사례**: Hooks 규칙, JSX 접근성
-- **Import 정리**: 절대/상대 경로 규칙
-
-### Prettier 설정
-
-- **세미콜론**: 필수
-- **따옴표**: 큰따옴표 사용
-- **Trailing Comma**: 항상 추가
-- **들여쓰기**: 2칸 스페이스
-
-### Path Alias
-
-```typescript
-// tsconfig.app.json, vite.config.ts, eslint.config.mjs에 설정
-"@app/*": ["./src/app/*"]
-"@pages/*": ["./src/pages/*"]
-"@widgets/*": ["./src/widgets/*"]
-"@features/*": ["./src/features/*"]
-"@entities/*": ["./src/entities/*"]
-"@shared/*": ["./src/shared/*"]
+┌─────────────────────────────────────────┐
+│ App Layer (설정, 라우팅, 글로벌 스타일) │
+└─────────────────┬───────────────────────┘
+ │ ✅ 참조 가능
+┌─────────────────▼───────────────────────┐
+│ Pages (홈, 프로젝트, 프로필, 로그인 등) │
+└─────────────────┬───────────────────────┘
+ │ ✅ 참조 가능
+┌─────────────────▼───────────────────────┐
+│ Widgets (헤더, 푸터, 히어로 섹션) │
+└─────────────────┬───────────────────────┘
+ │ ✅ 참조 가능
+┌─────────────────▼───────────────────────┐
+│ Features (인증, 프로젝트 CUD, 이메일) │
+└─────────────────┬───────────────────────┘
+ │ ✅ 참조 가능
+┌─────────────────▼───────────────────────┐
+│ Entities (프로젝트 조회, 검색, 사용자) │
+└─────────────────┬───────────────────────┘
+ │ ✅ 참조 가능
+┌─────────────────▼───────────────────────┐
+│ Shared (API, 훅, 스토어, UI 컴포넌트) │
+└─────────────────────────────────────────┘
```
## 🚀 개발 환경 설정
-### 설치
+### 필수 요구사항
+- **Node.js** 18+
+- **pnpm** (패키지 매니저)
+- **Firebase** 프로젝트 설정
+- **EmailJS** 계정 설정
+
+### 설치 및 실행
```bash
+# 의존성 설치
pnpm install
-```
### 개발 서버 실행
-```bash
+# 개발 서버 실행 (http://localhost:5173)
pnpm dev
-```
-
-### 빌드
-```bash
+# 빌드
pnpm build
-```
-### 미리보기
-
-```bash
+# 빌드 미리보기
pnpm preview
```
-### 코드 검사
+### 코드 품질 관리
```bash
-# ESLint 검사
+# ESLint 검사 (FSD 아키텍처 규칙 포함)
pnpm lint
# Prettier 포매팅
pnpm format
+
+# TypeScript 타입 검사
+pnpm type-check
+
+# 전체 품질 검사
+pnpm lint && pnpm type-check
```
## 🔀 브랜치 전략 & CI/CD
@@ -171,34 +238,32 @@ pnpm format
### 브랜치 구조
```
-main (Production)
-├── develop (Staging)
-│ ├── feat/auth/tkyoun0421
-│ ├── feat/user-profile/developer2
-│ └── fix/login-bug/tkyoun0421
+main (🚀 Production)
+├── develop (🚧 Staging)
+│ ├── feat/search
+│ ├── feat/user
+│ ├── fix/email
+│ └── refactor/auth
```
### 워크플로우
-1. **기능 개발**: `feat/기능명/깃허브아이디` 브랜치에서 개발
-2. **스테이징**: `develop` 브랜치로 PR → Vercel Preview 자동 배포
-3. **프로덕션**: `develop` → `main` PR → Vercel Production 자동 배포
+1. **기능 개발**: `feat/기능명` 브랜치
+2. **Staging**: `develop` 브랜치 → Vercel Preview 자동 배포
+3. **Production**: `main` 브랜치 → Vercel Production 자동 배포
### CI/CD 파이프라인
-- **CI**: 타입체크, 린트, 포맷, 빌드, 보안 검사
-- **CD**: Vercel 자동 배포 (develop: Preview, main: Production)
-
-### 관련 문서
-
-- [브랜치 전략 상세 가이드](./docs/BRANCH_STRATEGY.md)
-- [GitHub Actions CI/CD 설정](./.github/workflows/README.md)
+- 📋 타입체크, 린트, 포맷팅 검사
+- 🏗️ 프로덕션 빌드 테스트
+- 🔒 보안 취약점 스캔
+- 🚀 Vercel 자동 배포
## 📝 커밋 컨벤션
-[Conventional Commits](https://www.conventionalcommits.org/) 규칙을 따릅니다.
+[Conventional Commits](https://www.conventionalcommits.org/) 규칙을 엄격히 준수합니다.
-### 허용되는 타입
+### 커밋 타입
- `feat`: 새로운 기능
- `fix`: 버그 수정
@@ -214,7 +279,7 @@ main (Production)
### 커밋 메시지 형식
-```
+```bash
type(scope): subject
body
@@ -222,71 +287,95 @@ body
footer
```
-### 예시
+## 🎯 개발 가이드라인
-```bash
-git commit -m "feat(user): 사용자 프로필 조회 기능 추가"
-git commit -m "fix(auth): 로그인 실패 시 에러 처리 개선"
-git commit -m "docs: README에 FSD 아키텍처 설명 추가"
-```
+### React 컴포넌트 작성 규칙
-## 🎯 개발 가이드라인
+- **명시적 반환 타입**: 모든 컴포넌트는 `JSX.Element` 반환 타입 명시
+- **React.FC 금지**: 함수형 컴포넌트 직접 선언 방식 사용
+- **단일 책임 원칙**: 하나의 컴포넌트는 하나의 역할만 담당
-### 컴포넌트 작성 규칙
+### Features vs Entities 구분 기준
-1. **명시적 반환 타입**: 모든 컴포넌트는 `JSX.Element` 반환 타입을 명시
-2. **React.FC 금지**: 함수형 컴포넌트 직접 선언 방식 사용
-3. **단일 책임 원칙**: 하나의 컴포넌트는 하나의 역할만 담당
+| 구분 | Features | Entities |
+|------|----------|----------|
+| **역할** | 사용자 액션 처리 | 데이터 표시 |
+| **예시** | 로그인 폼, 프로젝트 생성 | 프로젝트 카드, 사용자 정보 |
+| **상태** | 변경 가능 (CUD) | 읽기 전용 (Read) |
+| **의존성** | Entities 참조 가능 | Features 참조 불가 |
-```typescript
-// ✅ 올바른 예시
-const UserProfile = (): JSX.Element => {
- return
;
-};
-```
+- **kebab-case 사용**: `project-list/`, `user-profile/`, `email-modal/`
+- **다른 케이스 금지**: `ProjectList/`, `userProfile/`, `Email_Modal/`
-### Features vs Entities 구분
+### Import 순서 규칙
-- **Features**: 사용자 액션, 폼 제출, 데이터 변경
-- **Entities**: 데이터 표시, 읽기 전용 컴포넌트
+1. 외부 라이브러리 (React, MUI 등)
+2. 내부 모듈 (절대 경로)
+3. 상대 경로
-### 모듈 구조 예시
+## 🛡️ 코드 품질 자동화
-```typescript
-// src/entities/user/index.ts
-export { UserCard } from './ui/UserCard';
-export { useUserQuery } from './queries/useUserQuery';
-export type { User } from './types/User';
+### Pre-commit Hooks
-// src/features/auth/index.ts
-export { LoginForm } from './ui/LoginForm';
-export { useLoginMutation } from './hooks/useLoginMutation';
-```
+1. TypeScript 타입 체크
+2. ESLint 자동 수정
+3. Prettier 포매팅
+4. 커밋 메시지 검증
+
+### VSCode 설정 권장사항
-## 🔧 Git Hooks
+- 저장 시 자동 포맷팅
+- Prettier 기본 포맷터 설정
+- 절대 경로 import 선호
+- ESLint 검증 활성화
-### Pre-commit
+## 🚀 배포 및 성능
-- ESLint 자동 수정
-- Prettier 포매팅
-- 타입 체크
+### 빌드 최적화
+- **Tree Shaking**: 사용하지 않는 코드 제거
+- **Code Splitting**: 페이지별 청크 분할
+- **Dynamic Import**: 지연 로딩 구현
-### Commit-msg
+### 성능 모니터링
+- **Core Web Vitals**: LCP, FID, CLS 추적
+- **Bundle Analyzer**: 번들 크기 분석
+- **Lighthouse**: 성능 점수 측정
-- 커밋 메시지 컨벤션 검사
-- 제목 길이 제한 (50자)
-- 헤더 길이 제한 (72자)
+### 배포 환경
+- **Production**: `main` 브랜치 → `project-jam.vercel.app`
+- **Staging**: `develop` 브랜치 → `project-jam-dev.vercel.app`
+- **Preview**: PR 브랜치 → 고유 미리보기 URL
+
+## 📚 관련 문서
+
+- 📖 [FSD 아키텍처 상세 가이드](./docs/FSD_ARCHITECTURE.md)
+- 🌿 [브랜치 전략 가이드](./docs/BRANCH_STRATEGY.md)
+- 🏗️ [각 계층별 상세 문서](./src/)
+ - [App Layer](./src/app/README.md)
+ - [Pages Layer](./src/pages/README.md)
+ - [Widgets Layer](./src/widgets/README.md)
+ - [Features Layer](./src/features/README.md)
+ - [Entities Layer](./src/entities/README.md)
+ - [Shared Layer](./src/shared/README.md)
+
+## 🤝 기여하기
+
+1. **이슈 등록**: 버그 리포트나 기능 제안
+2. **브랜치 생성**: `feat/기능명`
+3. **개발**: FSD 규칙 준수하여 개발
+4. **품질 검사**: `pnpm lint && pnpm type-check`
+5. **PR 생성**: `develop` 브랜치로 Pull Request
+
+---
-## 📚 추가 문서
+## 📞 문의 및 지원
-- [FSD 아키텍처 상세 가이드](./docs/FSD_ARCHITECTURE.md)
-- [각 계층별 README](./src/)
+- **GitHub Issues**: 버그 리포트 및 기능 제안
+- **Discussion**: 질문 및 아이디어 공유
+- **Email**: project-jam@example.com
---
-💡 **개발 시 주의사항**: FSD 아키텍처 규칙을 위반하면 ESLint 에러가 발생합니다. 의존성 규칙을 준수하여 개발해 주세요!
+💡 **개발 팁**: FSD 아키텍처를 준수하면 ESLint가 실시간으로 도와드립니다. 의존성 규칙을 위반하면 빨간 밑줄로 알려드려요! 🔴
diff --git a/src/app/README.md b/src/app/README.md
index 5d8d911..3f3ae6d 100644
--- a/src/app/README.md
+++ b/src/app/README.md
@@ -1,215 +1,146 @@
-# 🚀 App Layer
+# App Layer
-**앱 전체 설정 및 초기화를 담당하는 레이어**
+> 🏛️ **애플리케이션의 최상위 계층** - 전체 앱의 설정과 초기화를 담당
-App 레이어는 애플리케이션의 진입점과 전역 설정을 관리합니다.
+## 📖 개요
-## 📁 폴더 구조
+App Layer는 **FSD 아키텍처의 최상위 계층**으로, 애플리케이션 전체의 설정과 초기화를 담당합니다. 다른 모든 계층들이 올바르게 작동할 수 있는 환경을 제공합니다.
-```
-app/
-├── entry/ # 앱 진입점
-│ └── main.tsx # React 애플리케이션 마운트
-├── routes/ # 라우팅 설정
-│ └── App.tsx # 메인 앱 컴포넌트, 라우터 설정
-├── styles/ # 전역 스타일
-│ └── App.css # 글로벌 CSS
-├── configs/ # 앱 설정
-│ └── vite-env.d.ts # Vite 환경 타입 정의
-├── index.html # HTML 템플릿
-└── README.md # 이 파일
-```
+## 📁 디렉토리 구조
-## 🛣️ 라우터 설정 (React Router v7)
-
-### 레이지 로딩 구현
-
-성능 최적화를 위해 모든 페이지 컴포넌트에 레이지 로딩을 적용했습니다:
-
-```typescript
-// app/routes/App.tsx
-import { Suspense, lazy } from "react";
-import { LoadingSpinner } from "@shared/ui";
-
-// 동적 임포트로 번들 분할
-const HomePage = lazy(() => import("@pages/home/ui/HomePage"));
-const ProjectDetailPage = lazy(() => import("@pages/project-detail/ui/ProjectDetailPage"));
-const NotFoundPage = lazy(() => import("@pages/not-found/ui/NotFoundPage"));
-
-function App(): JSX.Element {
- return (
-
- }>
-
- } />
- } />
- } />
-
-
-
- );
-}
```
-
-### 📈 레이지 로딩의 장점
-
-1. **초기 번들 크기 감소**: 첫 페이지 로드 시 필요한 코드만 다운로드
-2. **빠른 초기 로딩**: 사용자가 접근하지 않는 페이지는 로드하지 않음
-3. **자동 코드 스플리팅**: Vite가 자동으로 청크를 분할
-4. **네트워크 효율성**: 필요할 때만 리소스 다운로드
-
-### 🔧 라우트 설정 규칙
-
-#### 1. 페이지 컴포넌트 요구사항
-```typescript
-// ✅ 올바른 방법 - default export 사용
-const HomePage = (): JSX.Element => {
- return
홈 페이지
;
-};
-
-export default HomePage;
-
-// ❌ 잘못된 방법 - named export는 레이지 로딩에서 사용 불가
-export { HomePage };
+src/app/
+├── configs/ # 🔧 앱 전체 설정
+│ └── vite-env.d.ts # Vite 환경 변수 타입 정의
+├── entry/ # 🚀 앱 진입점
+│ └── main.tsx # React 앱 최초 마운트
+├── routes/ # 🛣️ 라우팅 설정
+│ ├── App.tsx # 최상위 앱 컴포넌트
+│ ├── AuthLayout.tsx # 인증 관련 레이아웃
+│ ├── MainLayout.tsx # 메인 앱 레이아웃
+│ └── PrivateRoute.tsx # 인증 가드
+└── styles/ # 🎨 글로벌 스타일
+ ├── fonts/ # 웹폰트 (Pretendard)
+ ├── global.css # CSS 리셋 & 전역 스타일
+ └── theme.ts # MUI 테마 설정
```
-#### 2. 라우트 패턴
-```typescript
-// 기본 라우트
-} />
-
-// 동적 라우트
-} />
+## 🎯 주요 책임
-// 중첩 라우트
-} />
-
-// 404 페이지 (반드시 마지막에 위치)
-} />
-```
-
-#### 3. 네비게이션 가드
-```typescript
-// 인증이 필요한 페이지의 경우
-const ProtectedRoute = ({ children }: { children: React.ReactNode }) => {
- const isAuthenticated = useAuth();
- return isAuthenticated ? children : ;
-};
-
-
-
-
- }
-/>
-```
-
-## 🎨 로딩 상태 관리
-
-### LoadingSpinner 컴포넌트
-레이지 로딩 중 표시되는 로딩 스피너:
-
-```typescript
-// shared/ui/LoadingSpinner.tsx
-const LoadingSpinner = (): JSX.Element => {
- return (
-
-
- 페이지를 로딩 중입니다...
-
- );
-};
-```
-
-### 에러 바운더리
-추후 추가 예정:
-```typescript
-// app/components/ErrorBoundary.tsx
-class ErrorBoundary extends Component {
- // 레이지 로딩 실패 시 에러 처리
-}
-```
+### 1. 앱 진입점 관리 (`entry/`)
+- **React 앱 초기화**: DOM 마운트 및 최초 렌더링
+- **StrictMode 설정**: 개발 환경에서 잠재적 문제 감지
+- **Global Provider 설정**: React Query, Router, Theme Provider
+
+### 2. 라우팅 시스템 (`routes/`)
+- **라우트 정의**: 8개 주요 페이지 라우팅
+- **인증 가드**: 로그인 필요 페이지 보호
+- **레이아웃 관리**: 인증/비인증 사용자별 레이아웃
+- **중첩 라우팅**: 계층적 URL 구조
+
+### 3. 글로벌 스타일 (`styles/`)
+- **CSS 변수**: 색상, 폰트, 간격 등 디자인 토큰
+- **웹폰트 관리**: Pretendard 폰트 최적화 로딩
+- **MUI 테마**: Material-UI 커스텀 테마 정의
+- **반응형 브레이크포인트**: 모바일 퍼스트 디자인
+
+### 4. 환경 설정 (`configs/`)
+- **환경 변수**: Firebase, EmailJS 등 외부 서비스 설정
+- **타입 정의**: Vite 관련 환경 변수 타입 안전성
+- **빌드 설정**: 배포 환경별 설정 분리
+
+## 🏗 아키텍처 역할
+
+### 계층 의존성 관리
+App Layer는 **모든 하위 계층을 통합**하여 완전한 애플리케이션을 구성합니다.
+
+- **Pages** → UI 라우팅 연결
+- **Widgets** → 공통 레이아웃 컴포넌트 배치
+- **Features** → 전역 기능 초기화
+- **Entities** → 데이터 계층 설정
+- **Shared** → 공통 설정 및 유틸리티
+
+### 전역 상태 관리
+- **React Query**: 서버 상태 관리 및 캐싱 설정
+- **Zustand**: 클라이언트 상태 관리 초기화
+- **Firebase**: 인증 및 데이터베이스 연결 설정
+
+### 라우팅 전략
+- **React Router v6**: 선언적 라우팅
+- **Lazy Loading**: 페이지별 코드 스플리팅
+- **Protected Routes**: 인증 기반 접근 제어
+- **Error Boundaries**: 라우트 레벨 에러 처리
+
+## ⚡ 성능 최적화
+
+### 초기 로딩 최적화
+- **폰트 preload**: 중요 폰트 우선 로딩
+- **Critical CSS**: 중요 스타일 인라인 처리
+- **Resource Hints**: DNS prefetch, preconnect 설정
+
+### 번들 최적화
+- **Tree Shaking**: 사용하지 않는 코드 제거
+- **Code Splitting**: 라우트별 청크 분할
+- **Dynamic Import**: 필요 시점 모듈 로딩
+
+## 🔒 보안 고려사항
+
+### 환경 변수 관리
+- **민감 정보 보호**: API 키 등 환경 변수 분리
+- **런타임 검증**: 필수 환경 변수 존재 여부 확인
+- **타입 안전성**: 환경 변수 타입 정의 및 검증
+
+### 인증 보안
+- **토큰 관리**: Firebase Auth 토큰 자동 갱신
+- **세션 보안**: 안전한 세션 관리
+- **CSRF 보호**: 크로스 사이트 요청 위조 방지
+
+## 📊 성능 모니터링
+
+### Core Web Vitals
+- **LCP (Largest Contentful Paint)**: 최대 콘텐츠 렌더링 시간
+- **FID (First Input Delay)**: 첫 번째 입력 지연 시간
+- **CLS (Cumulative Layout Shift)**: 누적 레이아웃 이동
+
+### 사용자 경험 메트릭
+- **TTFB (Time to First Byte)**: 첫 바이트까지의 시간
+- **FCP (First Contentful Paint)**: 첫 콘텐츠 렌더링 시간
+- **TTI (Time to Interactive)**: 상호작용 가능 시점
+
+## 🚀 배포 설정
+
+### Vercel 최적화
+- **Build Settings**: 빌드 명령어 및 출력 디렉토리
+- **Environment Variables**: 배포 환경별 변수 설정
+- **Headers Configuration**: 보안 헤더 및 캐싱 정책
+
+### 환경별 배포
+- **Production**: `main` 브랜치 → 프로덕션 도메인
+- **Staging**: `develop` 브랜치 → 스테이징 도메인
+- **Preview**: PR 브랜치 → 미리보기 URL
+
+## 🎯 개발 가이드라인
+
+### App Layer 수정 시 주의사항
+1. **전역 영향도**: 모든 페이지에 영향을 미침
+2. **성능 고려**: 초기 로딩 성능에 직접 영향
+3. **의존성 순환**: 하위 계층 참조 금지
+4. **브레이킹 체인지**: 다른 개발자와 사전 논의 필요
+
+### 새로운 글로벌 설정 추가 시
+1. **configs/** 디렉토리에 설정 파일 생성
+2. **main.tsx**에서 Provider 래핑
+3. **타입 정의** 추가 (vite-env.d.ts)
+4. **문서화** 및 팀 공유
-## 🔗 의존성 규칙
-
-App 레이어는 **모든 레이어**를 참조할 수 있습니다:
-
-```typescript
-// ✅ 허용 - 모든 레이어 참조 가능
-import { HomePage } from '@pages/home'; // Pages
-import { Navigation } from '@widgets/navigation'; // Widgets
-import { LoginForm } from '@features/auth'; // Features
-import { UserCard } from '@entities/user'; // Entities
-import { Button } from '@shared/ui'; // Shared
-```
-
-## 📝 진입점 설정
-
-### main.tsx
-React 애플리케이션의 진입점:
-
-```typescript
-// app/entry/main.tsx
-import { StrictMode } from 'react';
-import { createRoot } from 'react-dom/client';
-import App from '@app/routes/App';
-
-createRoot(document.getElementById('root')!).render(
-
-
-
-);
-```
-
-### 전역 프로바이더 설정
-추후 추가될 프로바이더들:
-
-```typescript
-// React Query, 테마, 다국어 등
-function App(): JSX.Element {
- return (
-
-
-
- {/* 라우터 설정 */}
-
-
-
- );
-}
-```
-
-## 🚀 성능 최적화
-
-### 1. 프리로딩
-중요한 페이지는 미리 로드:
-```typescript
-// 마우스 오버 시 프리로드
-const handleMouseEnter = () => {
- import('@pages/about/ui/AboutPage');
-};
-```
+---
-### 2. 번들 분석
-빌드 후 번들 크기 확인:
-```bash
-pnpm build
-pnpm preview
-```
+## 📚 관련 문서
-### 3. 라우트 우선순위
-자주 사용되는 라우트를 먼저 정의:
-```typescript
-
- } /> {/* 가장 많이 사용 */}
- } /> {/* 두 번째로 많이 사용 */}
- } /> {/* 가끔 사용 */}
- } /> {/* 404는 항상 마지막 */}
-
-```
+- [🏗 FSD 아키텍처 가이드](../../docs/FSD_ARCHITECTURE.md)
+- [🎨 디자인 시스템](./styles/README.md)
+- [🛣️ 라우팅 가이드](./routes/README.md)
---
-💡 **참고**: 새로운 페이지를 추가할 때는 반드시 레이지 로딩을 적용하고 default export를 사용해 주세요!
\ No newline at end of file
+💡 **개발 팁**: App Layer는 **앱의 뼈대**입니다. 변경 시 모든 하위 계층에 영향을 미치므로 신중하게 접근하세요!
\ No newline at end of file
diff --git a/src/entities/README.md b/src/entities/README.md
index 725b96c..079a653 100644
--- a/src/entities/README.md
+++ b/src/entities/README.md
@@ -1,253 +1,271 @@
-# 📊 Entities Layer
+# Entities Layer
-**데이터 조회와 표시를 담당하는 레이어**
+> 📊 **도메인 엔티티 계층** - 비즈니스 도메인 데이터의 조회와 표시를 담당
-Entities 레이어는 **Read 로직**에 특화된 계층으로, 데이터를 조회하고 표시하는 역할을 담당합니다.
+## 📖 개요
-## 🎯 역할과 책임
+Entities Layer는 **비즈니스 도메인의 핵심 데이터를 관리**하는 계층입니다. 주로 Read 작업을 담당하며, 데이터를 조회하고 사용자에게 표시하는 UI 컴포넌트와 로직을 포함합니다.
-### 주요 기능
-- 📋 **데이터 조회**: API로부터 데이터 패칭
-- 🎨 **데이터 표시**: UI 컴포넌트로 데이터 렌더링
-- 🔄 **데이터 캐싱**: React Query를 통한 효율적인 캐싱
-- 📊 **상태 관리**: 읽기 전용 상태 관리
+## 📁 디렉토리 구조
-### Features vs Entities 구분
-| **Features (CUD)** | **Entities (Read)** |
-|-------------------|---------------------|
-| 데이터 변경 | 데이터 표시 |
-| `useMutation` | `useQuery` |
-| 폼 제출, 버튼 클릭 | 데이터 조회, 렌더링 |
-| LoginForm, DeleteButton | UserCard, PostList |
+```
+src/entities/
+├── projects/ # 📋 프로젝트 도메인
+│ ├── api/ # 프로젝트 조회 API
+│ │ ├── getProjectApplicationsApi.ts
+│ │ ├── getProjectLikeApi.ts
+│ │ └── projectsApi.ts
+│ ├── hooks/ # 프로젝트 관련 훅
+│ │ ├── useDeleteProjectsMutation.ts
+│ │ ├── useGetProjects.ts
+│ │ └── useProjectsByIds.ts
+│ ├── queries/ # React Query 쿼리
+│ │ ├── useGetProjectApplications.ts
+│ │ ├── useGetProjectLike.ts
+│ │ ├── useProjectList.ts
+│ │ ├── useProjectsItem.ts
+│ │ └── useProjectsTotalCount.ts
+│ ├── types/ # 프로젝트 타입 정의
+│ │ └── firebase.ts
+│ └── ui/ # 프로젝트 표시 UI
+│ ├── liked-projects/
+│ ├── post-info/
+│ ├── profile-page-projects-card/
+│ ├── project-collection-tab/
+│ ├── project-insert/
+│ ├── projects-card/
+│ ├── projects-detail/
+│ └── projects-stats/
+├── search/ # 🔍 검색 도메인
+│ ├── api/ # 검색 API
+│ │ └── projectSearchApi.ts
+│ ├── hooks/ # 검색 관련 훅
+│ │ ├── useFilteredProjects.ts
+│ │ ├── useProjectSearch.ts
+│ │ ├── useSearchHistory.ts
+│ │ └── useSearchInput.ts
+│ ├── model/ # 검색 비즈니스 로직
+│ │ ├── searchConstants.ts
+│ │ ├── searchFormConfig.ts
+│ │ └── searchQueryBuilder.ts
+│ ├── queries/ # 검색 쿼리
+│ │ └── useProjectSearchQueries.ts
+│ └── ui/ # 검색 UI 컴포넌트
+│ ├── SearchActions.tsx
+│ ├── SearchFilters.tsx
+│ ├── SearchForm.tsx
+│ ├── SearchInput.tsx
+│ ├── SearchInputHistory.tsx
+│ ├── SearchInputHistoryToggle.tsx
+│ ├── SearchLabels.tsx
+│ ├── SearchListResultHandler.tsx
+│ ├── SearchLoadingSpinner.tsx
+│ ├── SearchPagination.tsx
+│ ├── SearchSelectBox.tsx
+│ ├── SearchStatusField.tsx
+│ └── SelectBox.tsx
+└── user/ # 👤 사용자 도메인
+ ├── hooks/ # 사용자 관련 훅
+ │ ├── useSignUp.ts
+ │ ├── useSignUpForm.ts
+ │ ├── useUpdateUser.ts
+ │ └── useUpdateUserForm.ts
+ └── ui/ # 사용자 표시 UI
+ ├── SubmitButton.tsx
+ ├── UpdateUserForm.tsx
+ ├── user-profile/
+ │ ├── TapWithBadge.tsx
+ │ ├── UserProfileCard.tsx
+ │ └── UserProfileHeader.tsx
+ └── UserInfoForm.tsx
+```
-## 📁 폴더 구조
+## 🎯 도메인별 상세 기능
-각 도메인 엔티티는 다음 구조를 따릅니다:
+### 1. Projects Entity (`projects/`)
+**역할**: 프로젝트 정보의 조회와 표시
-```
-entities/
-├── user/ # 사용자 도메인
-│ ├── api/ # API 요청 로직
-│ │ └── userApi.ts
-│ ├── hooks/ # 커스텀 훅
-│ │ └── useUser.ts
-│ ├── queries/ # React Query 설정
-│ │ └── userQueries.ts
-│ ├── types/ # TypeScript 타입
-│ │ └── User.ts
-│ ├── ui/ # UI 컴포넌트
-│ │ ├── UserCard.tsx
-│ │ ├── UserProfile.tsx
-│ │ └── UserList.tsx
-│ ├── libs/ # 유틸리티 함수
-│ │ └── userUtils.ts
-│ └── index.ts # 외부 노출 인터페이스
-├── post/ # 게시물 도메인
-│ ├── api/
-│ ├── hooks/
-│ ├── queries/
-│ ├── types/
-│ ├── ui/
-│ ├── libs/
-│ └── index.ts
-└── README.md # 이 파일
-```
+#### 주요 컴포넌트 그룹
+- **liked-projects/**: 좋아요한 프로젝트 목록 및 빈 상태
+- **post-info/**: 프로젝트 상세 정보 (지원, 리더 정보, 메타데이터)
+- **project-collection-tab/**: 프로젝트 컬렉션 탭 네비게이션
+- **project-insert/**: 프로젝트 등록 폼의 각 카드 컴포넌트들
+- **projects-card/**: 프로젝트 목록용 카드 및 빈 상태
+- **projects-detail/**: 프로젝트 상세 페이지 섹션들
+- **projects-stats/**: 프로젝트 통계 및 안내 정보
-## 🔧 개발 가이드
+#### 데이터 관리
+- **조회 최적화**: React Query를 통한 데이터 캐싱
+- **상태 동기화**: 실시간 프로젝트 상태 반영
+- **페이지네이션**: 대용량 프로젝트 목록 처리
-### 1. API 요청 로직 (`api/`)
+### 2. Search Entity (`search/`)
+**역할**: 프로젝트 검색 및 필터링 시스템
-```typescript
-// entities/user/api/userApi.ts
-import { apiClient } from '@shared/api';
-import type { User } from '../types/User';
+#### 핵심 기능
+- **다중 필터**: 카테고리, 기술스택, 포지션, 상태별 필터링
+- **검색 기록**: 사용자별 검색 이력 관리
+- **실시간 검색**: 타이핑과 동시에 결과 업데이트
+- **고급 검색**: 복합 조건을 통한 정확한 매칭
-export const userApi = {
- getUser: async (id: string): Promise => {
- const response = await apiClient.get(`/users/${id}`);
- return response.data;
- },
+#### 검색 엔진 구조
+- **Query Builder**: 동적 검색 쿼리 생성
+- **Filter Chain**: 연쇄적 필터 적용
+- **Result Ranking**: 관련도 기반 결과 정렬
- getUsers: async (): Promise => {
- const response = await apiClient.get('/users');
- return response.data;
- },
-};
-```
+### 3. User Entity (`user/`)
+**역할**: 사용자 정보 표시 및 프로필 관리
-### 2. React Query 설정 (`queries/`)
-
-```typescript
-// entities/user/queries/userQueries.ts
-import { useQuery, UseQueryResult } from '@tanstack/react-query';
-import { userApi } from '../api/userApi';
-import type { User } from '../types/User';
-
-export const useUser = (id: string): UseQueryResult => {
- return useQuery({
- queryKey: ['user', id],
- queryFn: () => userApi.getUser(id),
- enabled: !!id,
- });
-};
-
-export const useUsers = (): UseQueryResult => {
- return useQuery({
- queryKey: ['users'],
- queryFn: userApi.getUsers,
- });
-};
-```
+#### 사용자 표시 컴포넌트
+- **ProfileCard**: 사용자 기본 정보 카드
+- **ProfileHeader**: 프로필 페이지 헤더
+- **TapWithBadge**: 배지가 있는 탭 컴포넌트
-### 3. 커스텀 훅 (`hooks/`)
-
-```typescript
-// entities/user/hooks/useUser.ts
-import { useUser as useUserQuery } from '../queries/userQueries';
-import type { User } from '../types/User';
-
-export const useUser = (id: string) => {
- const query = useUserQuery(id);
-
- return {
- user: query.data,
- isLoading: query.isLoading,
- isError: query.isError,
- error: query.error,
- refetch: query.refetch,
- };
-};
-```
+#### 사용자 정보 관리
+- **회원가입**: 새 사용자 등록 폼
+- **프로필 수정**: 기존 사용자 정보 업데이트
+- **표시 최적화**: 사용자 데이터 효율적 렌더링
-### 4. UI 컴포넌트 (`ui/`)
+## 🏗 아키텍처 패턴
-```typescript
-// entities/user/ui/UserCard.tsx
-import { useUser } from '../hooks/useUser';
-import type { User } from '../types/User';
+### 1. Repository Pattern
+API 호출을 추상화하여 데이터 접근 로직과 UI를 분리
-interface UserCardProps {
- userId: string;
-}
+### 2. Query Object Pattern
+복잡한 검색 조건을 객체로 캡슐화하여 관리
-const UserCard = ({ userId }: UserCardProps): JSX.Element => {
- const { user, isLoading, isError } = useUser(userId);
+### 3. Observer Pattern
+데이터 변경 시 관련 컴포넌트들에게 자동 알림
- if (isLoading) return
로딩 중...
;
- if (isError) return
에러가 발생했습니다
;
- if (!user) return
사용자를 찾을 수 없습니다
;
+## 🎨 UI 컴포넌트 설계 원칙
- return (
-
-
{user.name}
-
{user.email}
-
- );
-};
+### 1. 단일 책임 원칙
+각 컴포넌트는 하나의 명확한 데이터 표시 역할만 담당
-export { UserCard };
-```
+### 2. 조합 가능성
+작은 컴포넌트들을 조합하여 복잡한 UI 구성
-### 5. 타입 정의 (`types/`)
-
-```typescript
-// entities/user/types/User.ts
-export interface User {
- id: string;
- name: string;
- email: string;
- avatar?: string;
- createdAt: string;
- updatedAt: string;
-}
-
-export interface UserPreview {
- id: string;
- name: string;
- avatar?: string;
-}
-```
+### 3. 재사용성
+다양한 맥락에서 사용 가능한 유연한 컴포넌트 설계
-### 6. 외부 노출 인터페이스 (`index.ts`)
+## 📊 데이터 흐름 관리
-```typescript
-// entities/user/index.ts
-// UI 컴포넌트
-export { UserCard } from './ui/UserCard';
-export { UserProfile } from './ui/UserProfile';
-export { UserList } from './ui/UserList';
+### 1. 서버 상태 캐싱
+- **React Query**: 서버 데이터 자동 캐싱 및 무효화
+- **Stale-While-Revalidate**: 캐시된 데이터 우선 표시 후 백그라운드 업데이트
+- **옵티미스틱 업데이트**: 사용자 액션 즉시 반영
+
+### 2. 클라이언트 상태 관리
+- **지역 상태**: 컴포넌트 내부 UI 상태
+- **전역 상태**: 여러 컴포넌트가 공유하는 상태
+- **동기화**: 서버 상태와 클라이언트 상태 일치
-// 훅
-export { useUser } from './hooks/useUser';
+### 3. 에러 상태 처리
+- **로딩 상태**: 데이터 fetching 중 로딩 표시
+- **에러 상태**: 네트워크 에러 시 친화적 메시지
+- **빈 상태**: 데이터가 없을 때 적절한 안내
-// 타입
-export type { User, UserPreview } from './types/User';
+## ⚡ 성능 최적화
-// API (필요한 경우에만)
-export { userApi } from './api/userApi';
-```
+### 1. 렌더링 최적화
+- **React.memo**: 불필요한 리렌더링 방지
+- **가상화**: 대용량 리스트 가상 스크롤
+- **지연 로딩**: 뷰포트 진입 시 컴포넌트 로딩
-## 🎯 베스트 프랙티스
+### 2. 데이터 최적화
+- **선택적 필드**: 필요한 데이터만 요청
+- **페이지네이션**: 대용량 데이터 청크 단위 로딩
+- **프리페칭**: 사용자 행동 예측하여 미리 데이터 로딩
-### 1. 데이터 조회 최적화
-- React Query의 캐싱 활용
-- 적절한 `staleTime` 설정
-- 데이터 의존성 관리 (`enabled` 옵션)
+### 3. 번들 최적화
+- **트리 쉐이킹**: 사용하지 않는 코드 제거
+- **코드 스플리팅**: 라우트/컴포넌트별 청크 분할
+- **동적 임포트**: 조건부 컴포넌트 로딩
+
+## 🔍 검색 시스템 고도화
+
+### 1. 검색 알고리즘
+- **풀텍스트 검색**: 제목, 설명 내 키워드 매칭
+- **가중치 기반 스코어링**: 필드별 중요도 차등 적용
+- **퍼지 매칭**: 오타 허용 검색
+
+### 2. 사용자 경험 개선
+- **자동완성**: 입력 중 검색어 제안
+- **검색 하이라이트**: 결과에서 검색어 강조
+- **최근 검색어**: 사용자별 검색 이력
-### 2. 컴포넌트 설계
-- 단일 책임 원칙 준수
-- 로딩/에러 상태 처리
-- 명시적 반환 타입 ([JSX.Element 사용][[memory:7559751984028653409]])
+### 3. 고급 필터링
+- **다중 선택**: 여러 카테고리 동시 선택
+- **범위 필터**: 날짜, 팀 크기 등 범위 조건
+- **정렬 옵션**: 최신순, 인기순, 관련도순
-### 3. 타입 안전성
-- 모든 API 응답에 타입 정의
-- 선택적 프로퍼티 명시
-- 유니온 타입 활용
+## 🎯 사용자 경험 (UX) 고려사항
-### 4. 성능 고려사항
-- 불필요한 리렌더링 방지
-- 메모이제이션 적절히 활용
-- 지연 로딩 고려
+### 1. 로딩 상태 관리
+- **스켈레톤 UI**: 데이터 로딩 중 레이아웃 미리보기
+- **프로그레시브 로딩**: 중요한 내용부터 우선 표시
+- **백그라운드 업데이트**: 사용자 인터랙션 방해 없이 데이터 갱신
-## 🔗 의존성 규칙
+### 2. 반응형 디자인
+- **모바일 최적화**: 터치 친화적 인터페이스
+- **적응형 레이아웃**: 화면 크기별 최적 배치
+- **성능 고려**: 모바일 환경에서의 빠른 로딩
-Entities는 **Shared 레이어만** 참조할 수 있습니다:
+### 3. 접근성 (Accessibility)
+- **키보드 네비게이션**: 마우스 없이도 완전한 사용
+- **스크린 리더**: 시각 장애인을 위한 음성 지원
+- **색상 대비**: WCAG 가이드라인 준수
-```typescript
-// ✅ 허용
-import { Button } from '@shared/ui';
-import { formatDate } from '@shared/libs';
-import { apiClient } from '@shared/api';
+## 🧪 테스트 전략
-// ❌ 금지 - 상위 레이어 참조
-import { LoginForm } from '@features/auth'; // Features
-import { Header } from '@widgets/header'; // Widgets
-import { HomePage } from '@pages/home'; // Pages
+### 1. 컴포넌트 테스트
+- **렌더링 테스트**: 다양한 props에 대한 올바른 렌더링
+- **상호작용 테스트**: 사용자 클릭, 입력에 대한 반응
+- **상태 변경 테스트**: 데이터 변경 시 UI 업데이트
-// ❌ 금지 - 같은 레이어 다른 모듈 참조
-import { PostCard } from '@entities/post'; // 다른 Entity
-```
+### 2. 통합 테스트
+- **API 연동 테스트**: 실제 API와의 데이터 흐름
+- **검색 시나리오**: 복합 검색 조건의 정확한 결과
+- **페이지네이션 테스트**: 대용량 데이터 처리
-## 📝 명명 규칙
+### 3. 성능 테스트
+- **렌더링 성능**: 컴포넌트 렌더링 시간 측정
+- **메모리 사용량**: 메모리 누수 검사
+- **번들 크기**: 최적화 효과 측정
-- **폴더명**: kebab-case (`user-profile`, `product-list`)
-- **파일명**: PascalCase (`UserCard.tsx`, `ProductList.tsx`)
-- **컴포넌트명**: PascalCase + 명시적 반환 타입
-- **훅명**: `use` 접두사 + camelCase (`useUser`, `useProductList`)
-- **타입명**: PascalCase (`User`, `Product`)
+## 🎯 개발 가이드라인
+
+### Entities vs Features 구분 기준
+- **Entities**: 사용자가 **보는** 데이터 (프로젝트 카드, 사용자 프로필)
+- **Features**: 사용자가 **하는** 액션 (프로젝트 생성, 로그인)
+
+### 새로운 Entity 생성 시
+1. **도메인 분석**: 비즈니스 도메인의 명확한 경계 정의
+2. **API 설계**: RESTful한 읽기 전용 엔드포인트
+3. **타입 정의**: TypeScript 인터페이스로 데이터 구조 명시
+4. **컴포넌트 분리**: 작은 단위로 재사용 가능한 컴포넌트
+5. **쿼리 최적화**: React Query 캐싱 전략 수립
+
+### 기존 Entity 수정 시
+1. **영향도 분석**: 해당 Entity를 사용하는 모든 위치 파악
+2. **하위 호환성**: 기존 인터페이스 유지 또는 점진적 마이그레이션
+3. **성능 영향**: 변경으로 인한 성능 저하 여부 확인
+4. **테스트 업데이트**: 변경된 로직에 맞는 테스트 케이스
+
+### 성능 고려사항
+1. **리렌더링 최소화**: 불필요한 상태 변경 방지
+2. **메모리 효율**: 대용량 데이터 처리 시 가상화 고려
+3. **네트워크 최적화**: 필요한 데이터만 선택적으로 로딩
+4. **캐싱 전략**: 적절한 캐시 TTL 설정
-## 🚀 시작하기
+---
-새로운 엔티티를 추가할 때:
+## 📚 관련 문서
-1. **도메인 폴더 생성**: `entities/domain-name/`
-2. **기본 구조 설정**: `api/`, `hooks/`, `queries/`, `types/`, `ui/`, `index.ts`
-3. **타입 정의**: 먼저 타입부터 정의
-4. **API 레이어**: API 요청 함수 작성
-5. **Query 레이어**: React Query 훅 작성
-6. **UI 컴포넌트**: 데이터 표시 컴포넌트 작성
-7. **Public API**: `index.ts`에서 외부 노출 인터페이스 정의
+- [🏗 FSD 아키텍처 가이드](../../docs/FSD_ARCHITECTURE.md)
+- [⚡ Features Layer](../features/README.md)
+- [🔧 Shared Layer](../shared/README.md)
---
-💡 **참고**: Entities는 **읽기 전용**입니다. 데이터 변경이 필요한 경우 Features 레이어를 사용해 주세요!
\ No newline at end of file
+💡 **개발 팁**: Entities는 **데이터의 표현**에 집중하세요. 사용자가 정보를 쉽게 이해하고 탐색할 수 있는 직관적인 UI를 만드는 것이 핵심입니다!
\ No newline at end of file
diff --git a/src/entities/projects/ui/project-insert/ProjectCategoryCard.tsx b/src/entities/projects/ui/project-insert/ProjectCategoryCard.tsx
index e9f71ed..c986952 100644
--- a/src/entities/projects/ui/project-insert/ProjectCategoryCard.tsx
+++ b/src/entities/projects/ui/project-insert/ProjectCategoryCard.tsx
@@ -32,22 +32,42 @@ const ProjectCategoryCard = ({