# popdocs 사용 규칙

> **AI 에이전트 필독**: 이 문서는 popdocs 폴더 사용법입니다.
> 사용자가 "@popdocs"와 함께 요청하면 이 규칙을 참조하세요.

---

## 요청 유형 인식

### 키워드로 요청 유형 판별

| 유형 | 키워드 예시 | 행동 |
|------|------------|------|
| **저장** | 저장해줘, 기록해줘, 정리해줘, 추가해줘 | → 저장 규칙 따르기 |
| **조회** | 찾아줘, 검색해줘, 뭐 있어?, 어디있어? | → 조회 규칙 따르기 |
| **분석** | 분석해줘, 비교해줘, 어떻게 달라? | → 분석 규칙 따르기 |
| **수정** | 수정해줘, 업데이트해줘, 고쳐줘 | → 수정 규칙 따르기 |
| **요약** | 요약해줘, 정리해서 보여줘, 보고서 | → 요약 규칙 따르기 |
| **작업시작** | 시작하자, 이어서 하자, 뭐 해야 해? | → 작업 시작 규칙 |

### 요청 유형별 행동

```
[저장 요청]
"@popdocs 오늘 작업 저장해줘"
→ SAVE_RULES.md 저장 섹션 → 적절한 파일에 저장 → 동기화

[조회 요청]
"@popdocs 이전에 DnD 문제 어떻게 해결했어?"
→ PROBLEMS.md 검색 → 관련 내용만 반환

[분석 요청]  
"@popdocs v4랑 v5 뭐가 달라?"
→ decisions/ 또는 CHANGELOG 검색 → 비교표 생성

[수정 요청]
"@popdocs STATUS 업데이트해줘"
→ STATUS.md 수정 → README.md 동기화

[요약 요청]
"@popdocs 이번 주 작업 요약해줘"
→ sessions/ 해당 기간 검색 → 요약 생성

[작업 시작]
"@popdocs 오늘 작업 시작하자"
→ README → STATUS → 중단점 확인 → 작업 시작
```

---

## 컨텍스트 효율화 원칙

### Progressive Disclosure (점진적 공개)

**핵심**: 모든 문서를 한 번에 읽지 마세요. 필요한 것만 단계적으로.

```
Layer 1 (진입점)  → README.md, STATUS.md (먼저 읽기, ~100줄)
Layer 2 (상세)    → 필요한 문서만 선택적으로
Layer 3 (심화)    → 코드 파일, archive/ (필요시만)
```

### Token as Currency (토큰은 자원)

| 원칙 | 설명 |
|------|------|
| **관련성 > 최신성** | 모든 히스토리 대신 관련 있는 것만 |
| **요약 > 전문** | 긴 내용 대신 요약 먼저 확인 |
| **링크 > 복사** | 내용 복사 대신 파일 경로 참조 |
| **테이블 > 산문** | 긴 설명 대신 표로 압축 |
| **검색 > 전체읽기** | Ctrl+F 키워드 검색 활용 |

### Context Bloat 방지

```
❌ 잘못된 방법:
"모든 문서를 읽고 파악한 후 작업하겠습니다"
→ 1,300줄 이상 낭비

✅ 올바른 방법:
"README → STATUS → 필요한 섹션만" 
→ 평균 50~100줄로 작업 가능
```

---

## 문서 구조 (3계층)

```
popdocs/
│
├── [Layer 1: 진입점] ─────────────────────────
│   ├── README.md        ← 시작점 (현재 상태 요약)
│   ├── STATUS.md        ← 진행 상태, 다음 작업
│   └── SAVE_RULES.md    ← 사용 규칙 (지금 읽는 문서)
│
├── [Layer 2: 상세 문서] ─────────────────────────
│   ├── CHANGELOG.md     ← 변경 이력 (날짜별)
│   ├── PROBLEMS.md      ← 문제-해결 색인
│   ├── INDEX.md         ← 기능별 색인
│   ├── ARCHITECTURE.md  ← 코드 구조
│   ├── FILES.md         ← 파일 목록
│   ├── SPEC.md          ← 기술 스펙
│   └── PLAN.md          ← 계획
│
├── [Layer 3: 심화/기록] ─────────────────────────
│   ├── decisions/       ← ADR (결정 기록)
│   ├── sessions/        ← 날짜별 작업 기록
│   └── archive/         ← 보관 (레거시)
│
└── [외부 참조] ─────────────────────────
    └── 실제 코드 → frontend/components/pop/designer/
```

---

## 조회 규칙 (읽기)

### 작업 시작 시

```
1. README.md 읽기 (~60줄)
   └→ 현재 상태, 다음 작업 확인

2. STATUS.md 읽기 (~40줄)
   └→ 상세 진행 상황, 중단점 확인

3. 필요한 문서만 선택적으로
```

### 요청별 조회 경로

| 사용자 요청 | 조회 경로 |
|-------------|----------|
| "지금 뭐 해야 해?" | README → STATUS |
| "어제 뭐 했어?" | sessions/어제날짜.md |
| "이전에 비슷한 문제?" | PROBLEMS.md (키워드 검색) |
| "이 기능 어디있어?" | INDEX.md 또는 FILES.md |
| "왜 이렇게 결정했어?" | decisions/ |
| "전체 히스토리" | CHANGELOG.md (기간 한정) |
| "코드 구조 알려줘" | ARCHITECTURE.md |
| "v4랑 v5 뭐가 달라?" | decisions/003 또는 CHANGELOG |

### 효율적 검색

```
# 전체 파일 읽지 말고 키워드 검색
PROBLEMS.md에서 "DnD" 검색 → 관련 행만
CHANGELOG.md에서 "2026-02-05" 검색 → 해당 날짜만
FILES.md에서 "렌더러" 검색 → 관련 파일만
```

---

## 저장 규칙 (쓰기)

### 저장 유형별 위치

| 요청 패턴 | 저장 위치 | 형식 |
|----------|----------|------|
| "오늘 작업 저장/정리해줘" | sessions/YYYY-MM-DD.md | 세션 템플릿 |
| "이 결정 기록해줘" | decisions/NNN-제목.md | ADR 템플릿 |
| "이 문제 해결 기록해줘" | PROBLEMS.md | 행 추가 |
| "작업 내용 추가해줘" | CHANGELOG.md | 섹션 추가 |
| "현재 상태 업데이트" | STATUS.md | 상태 수정 |
| "기능 색인 추가해줘" | INDEX.md | 행 추가 |

### 저장 후 필수 동기화

```
저장 완료 후 항상:
1. STATUS.md 업데이트 (진행 상태, 다음 작업)
2. README.md "마지막 대화 요약" 업데이트 (1-2줄)
```

---

## 분석/비교 규칙

### 비교 요청 시

```
사용자: "@popdocs v4랑 v5 뭐가 달라?"

AI 행동:
1. decisions/003-v5-grid-system.md 확인 (있으면)
2. 없으면 CHANGELOG에서 관련 날짜 검색
3. 비교표 형식으로 응답

응답 형식:
| 항목 | v4 | v5 |
|------|----|----|
| 배치 | Flexbox | CSS Grid |
| ... | ... | ... |
```

### 분석 요청 시

```
사용자: "@popdocs 이번 달 작업 분석해줘"

AI 행동:
1. sessions/ 폴더에서 해당 기간 파일 목록
2. 각 파일의 "요약" 섹션만 추출
3. 종합 분석 제공
```

---

## 수정 규칙

### 문서 수정 요청 시

```
사용자: "@popdocs STATUS 업데이트해줘"

AI 행동:
1. STATUS.md 읽기
2. 변경 내용 적용
3. README.md 동기화 (마지막 대화 요약)
4. 변경 내용 사용자에게 확인
```

### 여러 문서 수정 시

```
수정 순서: 
상세 문서 먼저 → STATUS.md → README.md
(역방향: 진입점이 항상 최신 상태 유지)
```

---

## 요약/보고서 규칙

### 요약 요청 시

```
사용자: "@popdocs 이번 주 요약해줘"

AI 행동:
1. sessions/ 해당 기간 파일 확인
2. 각 파일의 "요약" + "완료" 섹션 추출
3. 압축된 형식으로 응답

응답 형식:
## 이번 주 요약 (02-01 ~ 02-05)
| 날짜 | 주요 작업 |
|------|----------|
| 02-05 | v5 통합 완료 |
| 02-04 | ... |
```

### 보고서 생성 요청 시

```
사용자: "@popdocs 진행 보고서 만들어줘"

AI 행동:
1. STATUS.md (현재 상태)
2. CHANGELOG.md (최근 작업)
3. sessions/ (상세 기록)
4. 보고서 형식으로 조합

→ 새 파일 생성하지 말고 응답으로 제공
→ 필요시 사용자가 저장 요청
```

---

## 예외 처리

### 분류 불가 시

```
사용자: "@popdocs 이거 저장해줘" (유형 불명확)

AI 행동:
→ 사용자에게 질문: "어떤 유형으로 저장할까요?"
   - 오늘 작업 기록 (sessions/)
   - 문제-해결 기록 (PROBLEMS.md)
   - 결정 사항 (decisions/)
   - 변경 이력 (CHANGELOG.md)
```

### 복합 요청 시

```
사용자: "@popdocs 문제 해결했고 결정도 내렸어. 저장해줘"

AI 행동 (순서):
1. PROBLEMS.md에 문제-해결 추가
2. decisions/에 ADR 생성 (필요시)
3. CHANGELOG.md에 섹션 추가
4. STATUS.md 업데이트
5. README.md 동기화
```

### 전체 조회 요청 시

```
사용자: "@popdocs 전체 히스토리 보여줘"

AI 행동:
→ "기간을 지정해주시면 더 정확히 찾아드릴게요."
   - 예: "최근 1주일", "2월 작업", "v5 관련"

→ 기간 없이 강행 시: CHANGELOG.md 최근 5개 항목만
```

### 파일 없음 시

```
사용자: "@popdocs 어제 작업 보여줘" (sessions/어제.md 없음)

AI 행동:
→ "어제 작업 기록이 없습니다. CHANGELOG.md에서 찾아볼까요?"
```

### 키워드 검색 실패 시

```
사용자: "@popdocs DnD 문제 찾아줘" (PROBLEMS.md에 없음)

AI 행동:
→ "PROBLEMS.md에서 못 찾았습니다. 다른 곳도 검색할까요?"
   - CHANGELOG.md
   - INDEX.md
   - sessions/
```

---

## 동기화 규칙

### 항상 동기화해야 하는 쌍

| 변경 문서 | 동기화 대상 |
|----------|-----------|
| sessions/ 생성 | STATUS.md (최근 세션) |
| PROBLEMS.md 추가 | - |
| decisions/ 생성 | STATUS.md (관련 결정), CHANGELOG.md |
| CHANGELOG.md 추가 | STATUS.md (진행 상태) |
| STATUS.md 수정 | README.md (마지막 요약) |

### 불일치 발견 시

```
README.md와 STATUS.md 내용이 다르면:
→ STATUS.md를 정본(正本)으로
→ README.md를 STATUS.md 기준으로 업데이트
```

---

## 정리 규칙

### 주기적 정리 (수동 요청 시)

| 대상 | 조건 | 조치 |
|------|------|------|
| sessions/ | 30일 이상 | archive/sessions/로 이동 |
| PROBLEMS.md | 100행 초과 | 카테고리별 분리 검토 |
| CHANGELOG.md | 연도 변경 | 이전 연도 archive/로 |

### 정리 요청 패턴

```
사용자: "@popdocs 오래된 파일 정리해줘"

AI 행동:
1. sessions/ 30일 이상 파일 목록 제시
2. 사용자 확인 후 archive/로 이동
3. 강제 삭제하지 않음
```

---

## 템플릿

### 세션 기록 (sessions/YYYY-MM-DD.md)

```markdown
# YYYY-MM-DD 작업 기록

## 요약
(한 줄 요약 - 50자 이내)

## 완료
- [x] 작업1
- [x] 작업2

## 미완료
- [ ] 작업3 (이유: ...)

## 중단점
> (내일 이어서 할 때 바로 시작할 수 있는 정보)

## 대화 핵심
- 키워드1: 설명
- 키워드2: 설명

## 관련 링크
- CHANGELOG: #YYYY-MM-DD
- ADR: decisions/NNN (있으면)
```

### 문제-해결 (PROBLEMS.md 행 추가)

```markdown
| 문제 | 해결 | 날짜 | 키워드 |
|------|------|------|--------|
| (에러/문제 설명) | (해결 방법) | YYYY-MM-DD | 검색용 |
```

### ADR (decisions/NNN-제목.md)

```markdown
# ADR-NNN: 제목

**날짜**: YYYY-MM-DD
**상태**: 채택됨

## 배경 (왜)
(2-3문장)

## 결정 (무엇)
(핵심 결정 사항)

## 대안
| 옵션 | 장점 | 단점 | 결과 |
|------|------|------|------|

## 교훈
- (배운 점)
```

### CHANGELOG 섹션

```markdown
## [YYYY-MM-DD] 제목

### 배경
(왜 - 2-3문장)

### 작업
- [x] 완료1
- [ ] 미완료 → STATUS.md로

### 다음
→ STATUS.md 참조
```

---

## 토큰 비용 가이드

| 문서 | 평균 줄 수 | 언제 읽나 |
|------|-----------|----------|
| README.md | ~60 | 항상 (진입점) |
| STATUS.md | ~40 | 항상 (진입점) |
| SAVE_RULES.md | ~350 | 저장/조회 요청 시 |
| sessions/날짜.md | ~30 | 해당 날짜만 |
| PROBLEMS.md | ~100 | 키워드 검색 |
| INDEX.md | ~80 | 키워드 검색 |
| CHANGELOG.md | ~600 | 날짜/키워드 검색 |
| ARCHITECTURE.md | ~300 | 구조 파악 시 |
| FILES.md | ~200 | 파일 찾을 때 |

**권장**: README + STATUS = ~100줄로 작업 시작

---

## 예시 워크플로우

### 1. 작업 시작

```
사용자: "@popdocs 오늘 작업 시작하자"

AI:
1. README.md 읽기 (60줄)
2. STATUS.md 읽기 (40줄)
3. 중단점 확인
4. "중단점: PopCanvas.tsx line 76 타입 오류. 여기서 시작할까요?"
```

### 2. 자료 검색

```
사용자: "@popdocs DnD 관련 자료 찾아줘"

AI:
1. PROBLEMS.md에서 "DnD" 검색
2. INDEX.md에서 "DnD" 검색  
3. 관련 내용 종합해서 응답
4. 전체 파일 읽지 않음
```

### 3. 비교 요청

```
사용자: "@popdocs v4랑 v5 비교해줘"

AI:
1. decisions/003-v5-grid-system.md 확인
2. "대안 검토" 섹션에서 비교표 추출
3. 필요시 CHANGELOG 보충
```

### 4. 작업 저장

```
사용자: "@popdocs 오늘 작업 저장해줘"

AI:
1. sessions/2026-02-05.md 생성
2. STATUS.md 업데이트
3. README.md "마지막 대화 요약" 업데이트
4. "저장 완료. 내일 이어서 할 중단점도 기록했습니다."
```

### 5. 불명확한 요청

```
사용자: "@popdocs 이거 저장해줘"

AI:
"어떤 유형으로 저장할까요?
1. 오늘 작업 기록 (sessions/)
2. 문제-해결 (PROBLEMS.md)
3. 결정 사항 (decisions/)
4. 변경 이력 (CHANGELOG.md)"
```

---

*2025-2026 AI 컨텍스트 엔지니어링 기반*
*Progressive Disclosure, Agentic Context Engineering, Token as Currency*