# POP 저장/조회 규칙

**AI가 POP 관련 저장/조회 요청을 처리할 때 참고하는 규칙**

---

## 1. 저장 요청 처리

사용자가 저장/기록/정리/업데이트 등을 요청하면:

### 1.1 파일 관련

| 요청 유형 | 처리 방법 |
|----------|----------|
| 새 파일 추가됨 | `FILES.md`에 파일 정보 추가 |
| 구조 변경됨 | `ARCHITECTURE.md` 업데이트 |
| 작업 완료 | `CHANGELOG.md`에 기록 |
| 중요 결정 | `decisions/` 폴더에 ADR 추가 |

### 1.2 rangraph 동기화

| 요청 유형 | rangraph 처리 |
|----------|--------------|
| 중요 결정 | `save_decision` 호출 |
| 교훈/규칙 | `save_lesson` 호출 |
| 새 키워드 | `add_keyword` 호출 |
| 작업 흐름 | `workflow_submit` 호출 |

### 1.3 예시

```
사용자: "오늘 작업 정리해줘"
AI:
1. CHANGELOG.md에 오늘 날짜로 Added/Changed/Fixed 기록
2. rangraph save_decision 또는 save_lesson 호출
3. 필요시 FILES.md, ARCHITECTURE.md 업데이트
```

---

## 2. 조회 요청 처리

사용자가 조회/검색/찾기 등을 요청하면:

### 2.1 popdocs 우선순위

| 필요한 정보 | 참조 문서 | 토큰 비용 |
|------------|----------|----------|
| 빠른 참조 | `README.md` | 낮음 (151줄) |
| 전체 구조 | `ARCHITECTURE.md` | 중간 (530줄) |
| 파일 위치 | `FILES.md` | 높음 (900줄) |
| 기술 스펙 | `SPEC.md` | 중간 |
| 컴포넌트 | `components-spec.md` | 중간 |
| 진행 상황 | `PLAN.md` | 낮음 |
| 변경 이력 | `CHANGELOG.md` | 낮음 |

### 2.2 조회 전략

```
1단계: rangraph search_memory로 빠르게 확인
2단계: 관련 popdocs 문서 참조
3단계: 필요시 실제 소스 파일 Read
```

### 2.3 예시

```
사용자: "v4 렌더러 어디있어?"
AI:
1. rangraph search_memory "v4 렌더러" (캐시된 정보)
2. FILES.md에서 확인: PopFlexRenderer.tsx (498줄)
3. 필요시 실제 파일 Read
```

---

## 3. 토큰 효율화 전략

### 3.1 문서 읽기 우선순위

```
최소 토큰: README.md (빠른 참조)
     ↓
중간 토큰: ARCHITECTURE.md (구조 이해)
     ↓
필요시: FILES.md (파일 상세)
     ↓
마지막: 실제 소스 파일
```

### 3.2 효율적 패턴

| 상황 | 효율적 방법 | 비효율적 방법 |
|------|------------|--------------|
| 파일 위치 찾기 | FILES.md 검색 | 전체 폴더 탐색 |
| 구조 이해 | ARCHITECTURE.md | 모든 파일 읽기 |
| 빠른 확인 | rangraph 검색 | 문서 전체 읽기 |
| 특정 코드 | FILES.md → Read | Glob + 전체 Read |

### 3.3 캐싱 활용

rangraph에 저장된 정보:
- POP 문서 구조 (save_decision)
- 저장/조회 규칙 (save_lesson)
- 핵심 파일 위치 (save_lesson)
- 키워드: popdocs, ARCHITECTURE.md, FILES.md

---

## 4. 문서별 용도

| 문서 | 읽을 때 | 수정할 때 |
|------|--------|----------|
| README.md | 빠른 참조 필요 시 | 문서 구조 변경 시 |
| ARCHITECTURE.md | 구조 이해 필요 시 | 폴더/모듈 변경 시 |
| FILES.md | 파일 찾을 때 | 파일 추가/삭제 시 |
| SPEC.md | 기술 스펙 확인 시 | 스펙 변경 시 |
| PLAN.md | 진행 상황 확인 시 | 계획 변경 시 |
| CHANGELOG.md | 이력 확인 시 | 작업 완료 시 |

---

## 5. 실제 처리 예시

### 5.1 저장 요청

```
사용자: "PopButton 컴포넌트 만들었어"

AI 처리:
1. FILES.md에 파일 정보 추가
2. CHANGELOG.md에 Added 기록
3. components-spec.md에 스펙 추가 (필요시)
4. rangraph save_decision 호출
```

### 5.2 조회 요청

```
사용자: "v4 캔버스 어떻게 동작해?"

AI 처리:
1. rangraph search_memory "v4 캔버스"
2. FILES.md에서 PopCanvasV4.tsx 확인
3. ARCHITECTURE.md에서 캔버스 섹션 확인
4. 필요시 PopCanvasV4.tsx 직접 Read
```

### 5.3 업데이트 요청

```
사용자: "PLAN.md 업데이트해줘"

AI 처리:
1. 현재 PLAN.md 읽기
2. 완료된 항목 체크, 새 항목 추가
3. rangraph에 진행 상황 저장 (필요시)
```

---

## 6. 키워드 체계

rangraph 키워드 카테고리:

| 카테고리 | 키워드 예시 |
|----------|-----------|
| pop | popdocs, ARCHITECTURE.md, FILES.md |
| v4 | PopFlexRenderer, PopCanvasV4, 제약조건 |
| designer | PopDesigner, PopPanel |

---

## 7. 이 문서의 용도

- AI가 POP 관련 요청을 받으면 이 규칙을 참고
- 저장 시: popdocs 문서 + rangraph 동기화
- 조회 시: 토큰 효율적인 순서로 확인
- 사용자가 규칙 변경을 요청하면 이 문서 수정

---

*최종 업데이트: 2026-02-04*