# Folder Map — PROJECT_MAP.md 생성 및 유지 가이드

Claude Code가 세션 간 프로젝트 구조를 기억하기 위한 `PROJECT_MAP.md` 시스템.

---

## PROJECT_MAP.md 란

프로젝트 루트에 위치하는 **폴더 구조 메모리 파일**이다. 모든 에이전트가 작업 시작 시 이 파일을 먼저 읽어 "어떤 폴더에 무엇이 있는지" 파악한다.

**왜 필요한가:** Claude Code는 세션마다 새로 시작하므로, 프로젝트 구조를 매번 탐색하면 토큰 낭비가 크다. PROJECT_MAP.md 한 파일만 읽으면 전체 구조를 즉시 파악할 수 있다.

---

## 초기 생성 절차

프로젝트 루트에 PROJECT_MAP.md가 없을 때 실행한다:

1. 프로젝트 루트에서 최상위 폴더 목록 스캔
2. 각 폴더의 목적을 파악 (package.json, build.gradle, pubspec.yaml 등 메타파일 기준)
3. 아래 템플릿으로 PROJECT_MAP.md 생성

---

## PROJECT_MAP.md 템플릿 (React + Spring Boot + Mobile)

```markdown
# PROJECT_MAP

> 마지막 업데이트: {YYYY-MM-DD HH:MM}
> 스택: React {version} | Spring Boot {version} | {Mobile Framework} {version}
> 업데이트 방법: "PROJECT_MAP 업데이트해줘" 또는 zio-harness 실행 시 자동 갱신

## 프로젝트 구조

### 루트
| 파일/폴더 | 용도 |
|----------|------|
| `frontend/` | React 웹 프론트엔드 |
| `backend/` | Spring Boot 백엔드 API |
| `mobile/` | 모바일 앱 (React Native / Flutter) |
| `e2e/` | Playwright E2E 테스트 |
| `docs/` | 프로젝트 문서 |
| `docker-compose.yml` | 로컬 개발 환경 |
| `PROJECT_MAP.md` | 이 파일 — 폴더 구조 메모리 |

### frontend/ (React)
| 경로 | 용도 |
|------|------|
| `src/pages/` | 페이지 컴포넌트 (라우트 단위) |
| `src/components/` | 공유 UI 컴포넌트 |
| `src/hooks/` | 커스텀 훅 |
| `src/store/` | 상태 관리 (Zustand / Redux) |
| `src/api/` | API 호출 함수 (Axios / fetch) |
| `src/types/` | TypeScript 타입 정의 |
| `src/utils/` | 유틸리티 함수 |
| `public/` | 정적 에셋 |
| `package.json` | 의존성 |
| `.env.local` | 로컬 환경 변수 (VITE_API_URL 등) |

### backend/ (Spring Boot)
| 경로 | 용도 |
|------|------|
| `src/main/java/{package}/controller/` | REST API 컨트롤러 |
| `src/main/java/{package}/service/` | 비즈니스 로직 |
| `src/main/java/{package}/repository/` | JPA 리포지토리 |
| `src/main/java/{package}/domain/` | 엔티티 / 도메인 모델 |
| `src/main/java/{package}/dto/` | Request / Response DTO |
| `src/main/java/{package}/config/` | Spring 설정 (Security, CORS 등) |
| `src/main/java/{package}/exception/` | 예외 처리 |
| `src/main/resources/application.yml` | 앱 설정 |
| `src/main/resources/db/migration/` | Flyway DB 마이그레이션 |
| `src/test/` | 단위/통합 테스트 |
| `build.gradle` | 의존성 |

### mobile/ (React Native / Flutter)
| 경로 | 용도 |
|------|------|
| `src/screens/` | 화면 컴포넌트 |
| `src/navigation/` | 네비게이션 설정 |
| `src/components/` | 공유 UI 컴포넌트 |
| `src/api/` | API 클라이언트 |
| `src/store/` | 상태 관리 |
| `src/types/` | 타입 정의 |
| `android/` | Android 네이티브 코드 |
| `ios/` | iOS 네이티브 코드 |

### e2e/ (Playwright)
| 경로 | 용도 |
|------|------|
| `tests/` | 테스트 파일 |
| `pages/` | 페이지 오브젝트 |
| `fixtures/` | 테스트 픽스처 |
| `playwright.config.ts` | Playwright 설정 |

## 핵심 컨벤션
- **API URL 패턴**: `GET /api/v1/{resource}`, `POST /api/v1/{resource}`
- **컴포넌트 네이밍**: PascalCase (예: `UserProfile.tsx`)
- **훅 네이밍**: `use` 접두사 (예: `useAuth.ts`)
- **서비스 네이밍**: `{Resource}Service.java`
- **DTO 네이밍**: `{Action}{Resource}Request.java`, `{Resource}Response.java`

## 환경 변수
| 변수 | 위치 | 설명 |
|------|------|------|
| `VITE_API_URL` | frontend/.env.local | 백엔드 API 주소 |
| `DB_URL` | backend/application.yml | 데이터베이스 주소 |
| `JWT_SECRET` | backend/application.yml | JWT 서명 키 |

## 최근 변경 이력
| 날짜 | 변경 내용 | 담당 에이전트 |
|------|----------|--------------|
| {YYYY-MM-DD} | 초기 맵 생성 | analyst |
```

---

## 업데이트 규칙

다음 상황에서 PROJECT_MAP.md를 업데이트한다:

1. **새 폴더 생성** → 해당 폴더 행 추가
2. **새 컨벤션 발견** → 핵심 컨벤션 섹션에 추가
3. **새 환경 변수 추가** → 환경 변수 테이블 업데이트
4. **구조 변경** → 해당 섹션 수정

업데이트 시 `마지막 업데이트` 날짜와 최근 변경 이력을 항상 갱신한다.

---

## 빠른 파악 프로토콜

에이전트가 새 작업을 시작할 때:

```
1. PROJECT_MAP.md 읽기 (없으면 생성)
2. 작업과 관련된 폴더 파악
3. 해당 폴더만 탐색 (전체 탐색 금지)
4. 작업 완료 후 새 파일/폴더가 생겼으면 PROJECT_MAP.md 갱신
```

이 순서를 지키면 탐색 토큰을 70% 이상 절약할 수 있다.