540 lines
13 KiB
Markdown
540 lines
13 KiB
Markdown
# 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*
|