From 116da944ad31cfaacac042263ac14757912cdeba Mon Sep 17 00:00:00 2001 From: SeongHyun Kim Date: Mon, 9 Feb 2026 09:33:54 +0900 Subject: [PATCH] =?UTF-8?q?docs(popdocs):=20=EC=9B=8C=ED=81=AC=ED=94=8C?= =?UTF-8?q?=EB=A1=9C=EC=9A=B0=20=ED=94=84=EB=A1=AC=ED=94=84=ED=8A=B8=20?= =?UTF-8?q?=EB=B0=8F=20=EA=B5=AC=ED=98=84=20=EA=B3=84=ED=9A=8D=20=ED=85=9C?= =?UTF-8?q?=ED=94=8C=EB=A6=BF=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - WORKFLOW_PROMPTS.md 신규 생성 (작업 단계별 표준 프롬프트) - PLAN.md에 "현재 구현 계획" 섹션 템플릿 추가 - SAVE_RULES.md에 구현 계획 저장/조회/동기화 규칙 추가 - README.md에 구현 계획 및 워크플로우 프롬프트 링크 추가 Co-authored-by: Cursor --- popdocs/PLAN.md | 30 ++++++ popdocs/README.md | 2 + popdocs/SAVE_RULES.md | 37 ++++++- popdocs/WORKFLOW_PROMPTS.md | 205 ++++++++++++++++++++++++++++++++++++ 4 files changed, 273 insertions(+), 1 deletion(-) create mode 100644 popdocs/WORKFLOW_PROMPTS.md diff --git a/popdocs/PLAN.md b/popdocs/PLAN.md index 95e18ac3..f1c9e17c 100644 --- a/popdocs/PLAN.md +++ b/popdocs/PLAN.md @@ -94,6 +94,36 @@ v4 관련 파일은 모두 삭제되었습니다. --- +## 현재 구현 계획 + +> **용도**: 이 섹션은 "지금 바로 실행할 구체적 계획"입니다. +> 새 세션에서 이 섹션만 읽으면 코딩을 시작할 수 있어야 합니다. +> 완료되면 다음 기능의 계획으로 **교체**합니다. + +### 대상: (계획 수립 전) + +현재 구현 계획이 없습니다. 계획 수립 세션에서 다음 형식으로 작성해주세요: + +``` +### 대상: [기능명] + +#### 구현 순서 (의존성 기반) +1. [ ] 파일명 - 변경 내용 요약 +2. [ ] 파일명 - 변경 내용 요약 + +#### 파일별 변경 사항 +| # | 파일 (경로) | 작업 | 핵심 변경 | 주의사항 | +|---|------------|------|----------|---------| + +#### 함정 경고 +- (빠뜨리면 에러나는 것들) + +#### 참조 +- 관련 문서/파일 경로 +``` + +--- + ## 브레이크포인트 (v5.2 현재) | 모드 | 화면 너비 | 칸 수 | 대상 기기 | diff --git a/popdocs/README.md b/popdocs/README.md index 88a478e2..aa2db7e0 100644 --- a/popdocs/README.md +++ b/popdocs/README.md @@ -39,6 +39,8 @@ | 브레이크포인트 재설계 | [decisions/005-breakpoint-redesign.md](./decisions/005-breakpoint-redesign.md) | | 자동 줄바꿈 시스템 | [decisions/006-auto-wrap-review-system.md](./decisions/006-auto-wrap-review-system.md) | | 개발 계획/로드맵 | [PLAN.md](./PLAN.md) | +| 지금 바로 코딩할 계획 | [PLAN.md "현재 구현 계획"](./PLAN.md#현재-구현-계획) | +| 작업 프롬프트 | [WORKFLOW_PROMPTS.md](./WORKFLOW_PROMPTS.md) | | 컴포넌트 상세 설계 | [components-spec.md](./components-spec.md) | | 이전 문제 해결 | [PROBLEMS.md](./PROBLEMS.md) | | 코드 어디 있어? | [FILES.md](./FILES.md) | diff --git a/popdocs/SAVE_RULES.md b/popdocs/SAVE_RULES.md index 4d2bff9b..fc445170 100644 --- a/popdocs/SAVE_RULES.md +++ b/popdocs/SAVE_RULES.md @@ -41,9 +41,13 @@ "@popdocs 이번 주 작업 요약해줘" → sessions/ 해당 기간 검색 → 요약 생성 +[계획 저장] +"@popdocs 구현 계획 저장해줘" +→ PLAN.md "현재 구현 계획" 섹션 교체 → STATUS.md 동기화 + [작업 시작] "@popdocs 오늘 작업 시작하자" -→ README → STATUS → 중단점 확인 → 작업 시작 +→ README → STATUS → PLAN.md "현재 구현 계획" → 중단점 확인 → 작업 시작 ``` --- @@ -133,6 +137,7 @@ popdocs/ | 사용자 요청 | 조회 경로 | |-------------|----------| | "지금 뭐 해야 해?" | README → STATUS | +| "구현 계획 보여줘" | PLAN.md "현재 구현 계획" 섹션 | | "어제 뭐 했어?" | sessions/어제날짜.md | | "이전에 비슷한 문제?" | PROBLEMS.md (키워드 검색) | | "이 기능 어디있어?" | INDEX.md 또는 FILES.md | @@ -164,6 +169,7 @@ FILES.md에서 "렌더러" 검색 → 관련 파일만 | "작업 내용 추가해줘" | CHANGELOG.md | 섹션 추가 | | "현재 상태 업데이트" | STATUS.md | 상태 수정 | | "기능 색인 추가해줘" | INDEX.md | 행 추가 | +| "구현 계획 저장해줘" | PLAN.md "현재 구현 계획" | 섹션 교체 | ### 저장 후 필수 동기화 @@ -342,6 +348,7 @@ AI 행동: | decisions/ 생성 | STATUS.md (관련 결정), CHANGELOG.md | | CHANGELOG.md 추가 | STATUS.md (진행 상태) | | STATUS.md 수정 | README.md (마지막 요약) | +| PLAN.md 구현 계획 수정 | STATUS.md (다음 작업) | ### 불일치 발견 시 @@ -435,6 +442,34 @@ AI 행동: - (배운 점) ``` +### 구현 계획 (PLAN.md "현재 구현 계획" 교체) + +```markdown +### 대상: [기능명] + +#### 구현 순서 (의존성 기반) +1. [ ] 파일명 - 변경 내용 요약 +2. [ ] 파일명 - 변경 내용 요약 + +#### 파일별 변경 사항 +| # | 파일 (경로) | 작업 | 핵심 변경 | 주의사항 | +|---|------------|------|----------|---------| +| 1 | path/file.tsx (신규) | 생성 | 설명 | 주의 | +| 2 | path/file.tsx (수정) | 수정 | 설명 | 주의 | + +#### 함정 경고 +- (빠뜨리면 에러나는 것들) + +#### 참조 +- 관련 문서/파일 경로 +``` + +**라이프사이클**: +- 계획 수립 시: "현재 구현 계획" 섹션을 새 계획으로 **교체** +- 코딩 중: 완료 항목 `[ ]` → `[x]` +- 기능 완료 시: 다음 기능 계획으로 **교체** (이전 계획은 CHANGELOG에 기록됨) +- 항상 1개만 존재 + ### CHANGELOG 섹션 ```markdown diff --git a/popdocs/WORKFLOW_PROMPTS.md b/popdocs/WORKFLOW_PROMPTS.md new file mode 100644 index 00000000..2d4a08b7 --- /dev/null +++ b/popdocs/WORKFLOW_PROMPTS.md @@ -0,0 +1,205 @@ +# 워크플로우 프롬프트 + +> 각 작업 단계에서 AI에게 내리는 표준 프롬프트입니다. +> 상황에 맞는 프롬프트를 복사해서 사용하세요. +> `[괄호]` 안은 상황에 맞게 수정하세요. + +--- + +## 한 번에 복사용 + +``` +===== 토의 중 개념 학습 ===== +지금 설명한 [개념명]을 우리 프로젝트 코드에서 실제 사용되는 예시로 보여줘. +해당 코드가 없으면 어떤 문제가 생기는지 한 문장으로. + +===== 계획 ===== +구현 계획서를 작성해줘. + +포함할 것: +1. 파일별 변경 사항 (추가/수정/삭제할 코드) +2. 구현 순서 (의존성 기반) + +사전 검증 (코딩 전에 반드시): +1. 새로 추가할 변수/함수/타입 각각에 대해 해당 파일에서 Grep으로 동일 이름 검색 +2. 충돌 발견 시 "충돌: [이름] - [파일명] 라인 [X]에 기존 정의 있음" 보고 +3. 충돌 있으면 해결 방안 제시 (이름 변경 or 기존 코드 재사용) +4. 계획서에 명시된 모든 함수/변수/타입을 리스트업하고 "어디서 정의, 어디서 사용" 매핑 +5. 사용처는 있는데 정의가 누락된 항목이 있으면 보고 + +주의사항: +- 이 대화를 못 본 사람도 실행할 수 있을 정도로 구체적으로 +- 빠뜨리면 에러날 만한 함정을 명시적으로 경고해줘 + +문서 정리: +- PLAN.md "현재 구현 계획" 섹션을 이 계획으로 교체해줘 +- STATUS.md "다음 작업"도 동기화해줘 + +===== 계획 이해 (선택) ===== +이 계획에서 가장 복잡한 변경 1개를 골라서, +왜 이렇게 해야 하는지 한 문장으로 설명해줘. + +===== 코딩 ===== +위 계획대로 코딩 진행해줘. + +규칙: +1. 각 파일 수정 전에 해당 파일을 먼저 전체 읽어 +2. 새로 추가할 변수명이 파일에 이미 존재하는지 Grep으로 확인 +3. 기존 코드에 동일 이름이 있으면 재사용하거나 명시적으로 삭제 후 새로 정의해 +4. 한 파일 완료할 때마다 린트 확인 + +각 파일 수정이 끝나면 이것만 알려줘: +- 충돌 검사 결과 +- 추가한 import +- 정의한 함수/변수 +- 이 파일에서 가장 핵심적인 변경 1개와 그 이유 (한 문장) + +코딩 완료 후 자체 검증: +- 새로 추가한 모든 변수/함수가 정의되어 있는가? +- 동일 이름의 변수/함수가 파일 내에 2개 이상 존재하지 않는가? +- import한 모든 것이 실제로 사용되는가? +- 사용하는 모든 것이 import되어 있는가? +- interface의 모든 props가 실제로 전달되는가? +이상 없으면 완료 보고, 이상 있으면 수정 후 보고. + +문서 정리: +- PLAN.md "현재 구현 계획"에서 완료된 항목은 [ ] → [x]로 체크해줘 + +===== 새 세션 코딩 (다른 모델) ===== +@popdocs/ 의 README → STATUS → PLAN.md "현재 구현 계획" 순서로 읽고, +계획대로 코딩을 진행해줘. + +규칙: +1. 각 파일 수정 전에 해당 파일을 먼저 전체 읽어 +2. 새로 추가할 변수명이 파일에 이미 존재하는지 Grep으로 확인 +3. 기존 코드에 동일 이름이 있으면 재사용하거나 명시적으로 삭제 후 새로 정의해 +4. 한 파일 완료할 때마다 린트 확인 + +각 파일 수정이 끝나면 이것만 알려줘: +- 충돌 검사 결과 +- 추가한 import +- 정의한 함수/변수 +- 이 파일에서 가장 핵심적인 변경 1개와 그 이유 (한 문장) + +코딩 완료 후 자체 검증: +- 새로 추가한 모든 변수/함수가 정의되어 있는가? +- 동일 이름의 변수/함수가 파일 내에 2개 이상 존재하지 않는가? +- import한 모든 것이 실제로 사용되는가? +- 사용하는 모든 것이 import되어 있는가? +- interface의 모든 props가 실제로 전달되는가? +이상 없으면 완료 보고, 이상 있으면 수정 후 보고. + +문서 정리: +- PLAN.md "현재 구현 계획"에서 완료된 항목은 [ ] → [x]로 체크해줘 + +===== 검수 ===== +수정한 파일들을 검수해줘. + +검증 항목: +1. 린트 에러 +2. 새로 추가한 변수/함수가 중복 정의되지 않았는지 Grep 확인 +3. import한 것 중 사용 안 하는 것, 사용하는데 import 안 한 것 +4. interface에 정의된 props와 실제 전달되는 props 일치 여부 + +문제 발견 시: +- 고치기 전에 해당 코드를 보여주고 어디가 잘못됐는지 표시해줘 +- 내가 확인한 다음에 고쳐줘 + +문서 정리: +- 발견된 문제가 있으면 PROBLEMS.md에 추가할 내용을 미리 정리해둬 + +===== 수정 ===== +발견된 문제를 수정해줘. + +수정 전에 먼저: +1. 이 문제가 왜 발생했는지 원인 한 문장 +2. 다음에 같은 실수를 방지하려면 코딩할 때 뭘 확인했어야 하는지 한 문장 +그다음 수정 진행해. + +문서 정리: +- 수정한 내용을 PROBLEMS.md 형식(문제 | 해결 | 날짜 | 키워드)으로 정리해둬 + +===== 기록 ===== +작업 내용을 popdocs에 기록해줘. + +업데이트 대상: +- sessions/오늘날짜.md 생성 +- CHANGELOG.md 섹션 추가 +- STATUS.md 진행상태 업데이트 +- PLAN.md "현재 구현 계획"에서 완료 항목 최종 확인 +- README.md "마지막 대화 요약" 동기화 +- PROBLEMS.md에 발생한 문제-해결 추가 (있으면) +- INDEX.md에 새로 추가된 기능/함수 색인 추가 (있으면) + +추가로 "이번 작업에서 배운 것" 섹션을 포함해줘: +- 새로 알게 된 기술 개념 (있으면) +- 발생했던 에러와 원인 패턴 (있으면) +- 다음에 비슷한 작업할 때 주의할 점 (있으면) +없으면 생략. + +===== 동기화 확인 ===== +popdocs 문서 간 동기화 상태를 확인해줘. + +확인 항목: +1. README.md "마지막 대화 요약"이 STATUS.md와 일치하는지 +2. STATUS.md "다음 작업"이 PLAN.md "현재 구현 계획"과 일치하는지 +3. PLAN.md 체크박스 상태가 실제 코드 변경과 일치하는지 +4. sessions/오늘날짜.md의 "완료" 항목이 CHANGELOG.md와 일치하는지 + +불일치 발견 시: +- 어떤 문서의 어떤 부분이 다른지 보여줘 +- STATUS.md를 정본으로 맞춰줘 + +===== 주간 복습 (금요일) ===== +이번 주 작업 기록을 보고: +1. 내가 "쉽게 설명해줘"라고 요청했던 개념 중 가장 중요한 3개 +2. 발생했던 에러 중 다시 만날 가능성이 높은 패턴 2개 +3. 각각을 한 문장 정의 + 우리 프로젝트에서 어디에 해당하는지 +정리해줘. + +참조할 문서: +- sessions/ 이번 주 파일들 +- PROBLEMS.md 이번 주 항목들 +- CHANGELOG.md 이번 주 섹션들 +``` + +--- + +## popdocs 업데이트 시점 요약 + +| 단계 | 업데이트 대상 | 시점 | +|------|-------------|------| +| 계획 수립 | PLAN.md "현재 구현 계획", STATUS.md | 계획 확정 시 | +| 코딩 중 | PLAN.md 완료 체크 `[x]` | 각 파일 완료 시 | +| 검수 | PROBLEMS.md 내용 준비 | 문제 발견 시 | +| 수정 | PROBLEMS.md 내용 준비 | 수정 완료 시 | +| 기록 | sessions/, CHANGELOG, STATUS, README, PROBLEMS, INDEX | 작업 완료 시 | +| 동기화 확인 | 전체 문서 간 불일치 점검 | 기록 직후 | +| 주간 복습 | (응답으로 제공, 파일 저장은 선택) | 금요일 | + +--- + +## 세션 분리 가이드 + +``` +[Opus 세션] 토의 + 계획 + → popdocs 업데이트 (PLAN.md, STATUS.md) + → 세션 종료 + +[새 세션 - Sonnet/Opus] 코딩 + 검수 + 수정 + → "@popdocs/ 읽고 PLAN.md 계획대로 진행해" + → 15건 이내로 완료 + → 세션 종료 + +[새 세션 - 아무 모델] 기록 + 동기화 확인 + → "기록" 프롬프트 → "동기화 확인" 프롬프트 +``` + +**세션을 끊는 기준**: +- 작업이 15건 이내로 끝나면 한 세션에서 끝까지 (끊을 필요 없음) +- 대화가 15건을 넘어갈 것 같으면 세션 분리 +- 완전히 다른 작업으로 전환할 때 + +--- + +*최종 업데이트: 2026-02-06*