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 구현 계획 저장해줘"
→ PLAN.md "현재 구현 계획" 섹션 교체 → STATUS.md 동기화
[작업 시작]
"@popdocs 오늘 작업 시작하자"
→ README → STATUS → PLAN.md "현재 구현 계획" → 중단점 확인 → 작업 시작
컨텍스트 효율화 원칙
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 |
| "구현 계획 보여줘" |
PLAN.md "현재 구현 계획" 섹션 |
| "어제 뭐 했어?" |
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 |
행 추가 |
| "구현 계획 저장해줘" |
PLAN.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 (마지막 요약) |
| PLAN.md 구현 계획 수정 |
STATUS.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)
# YYYY-MM-DD 작업 기록
## 요약
(한 줄 요약 - 50자 이내)
## 완료
- [x] 작업1
- [x] 작업2
## 미완료
- [ ] 작업3 (이유: ...)
## 중단점
> (내일 이어서 할 때 바로 시작할 수 있는 정보)
## 대화 핵심
- 키워드1: 설명
- 키워드2: 설명
## 관련 링크
- CHANGELOG: #YYYY-MM-DD
- ADR: decisions/NNN (있으면)
문제-해결 (PROBLEMS.md 행 추가)
| 문제 | 해결 | 날짜 | 키워드 |
|------|------|------|--------|
| (에러/문제 설명) | (해결 방법) | YYYY-MM-DD | 검색용 |
ADR (decisions/NNN-제목.md)
# ADR-NNN: 제목
**날짜**: YYYY-MM-DD
**상태**: 채택됨
## 배경 (왜)
(2-3문장)
## 결정 (무엇)
(핵심 결정 사항)
## 대안
| 옵션 | 장점 | 단점 | 결과 |
|------|------|------|------|
## 교훈
- (배운 점)
구현 계획 (PLAN.md "현재 구현 계획" 교체)
### 대상: [기능명]
#### 구현 순서 (의존성 기반)
1. [ ] 파일명 - 변경 내용 요약
2. [ ] 파일명 - 변경 내용 요약
#### 파일별 변경 사항
| # | 파일 (경로) | 작업 | 핵심 변경 | 주의사항 |
|---|------------|------|----------|---------|
| 1 | path/file.tsx (신규) | 생성 | 설명 | 주의 |
| 2 | path/file.tsx (수정) | 수정 | 설명 | 주의 |
#### 함정 경고
- (빠뜨리면 에러나는 것들)
#### 참조
- 관련 문서/파일 경로
라이프사이클:
- 계획 수립 시: "현재 구현 계획" 섹션을 새 계획으로 교체
- 코딩 중: 완료 항목
[ ] → [x]
- 기능 완료 시: 다음 기능 계획으로 교체 (이전 계획은 CHANGELOG에 기록됨)
- 항상 1개만 존재
CHANGELOG 섹션
## [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