# 워크플로우 프롬프트

> 각 작업 단계에서 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 이번 주 섹션들

===== 병합 준비 (merge 전) =====
[source-branch]를 [target-branch]에 병합하려고 해.

병합 전 점검해줘:
1. 양쪽 브랜치의 최근 커밋 히스토리 비교 (git log --oneline --left-right [target]...[source])
2. 충돌 예상 파일 목록 (git merge --no-commit --no-ff [source] 후 git diff --name-only --diff-filter=U)
3. 충돌 예상 파일 중 규모가 큰 파일(500줄 이상) 식별 - 이 파일들은 특별 주의 대상
4. 양쪽에서 동시에 수정한 파일 목록 (git diff --name-only [target]...[source])
5. 삭제 vs 수정 충돌 가능성 (한쪽에서 삭제하고 다른 쪽에서 수정한 파일)

점검 후 위험도를 알려줘:
- 높음: 같은 함수/컴포넌트를 양쪽에서 구조적으로 변경한 경우
- 중간: 같은 파일이지만 다른 부분을 수정한 경우
- 낮음: 서로 다른 파일만 수정한 경우

충돌 예상 파일이 있으면 각 파일별로:
- 양쪽에서 무엇을 변경했는지 한 줄 요약
- 어떤 쪽을 기준으로 병합해야 하는지 판단 근거

===== 병합 실행 (merge 중) =====
병합을 진행해줘.

규칙:
1. diff3 형식으로 충돌 표시 (git config merge.conflictstyle diff3)
2. 충돌 파일 하나씩 순서대로 해결 - 의존성 낮은 파일부터
3. 각 충돌 파일 해결 전에 반드시:
   - 공통 조상(base)을 확인하여 양쪽이 원래 코드에서 무엇을 변경했는지 파악
   - 양쪽 변경의 의도를 모두 보존할 수 있는지 판단
   - 한쪽만 선택해야 하면 그 이유를 명시
4. 충돌 마커(<<<<<<, ======, >>>>>>)가 모두 제거되었는지 확인

각 충돌 파일 해결 후 보고:
- 충돌 위치 (함수명/컴포넌트명)
- 해결 방식: "양쪽 통합" / "ours 선택" / "theirs 선택" / "새로 작성"
- 선택 이유 한 문장

===== 병합 후 시맨틱 검증 (merge 후 - 가장 중요) =====
텍스트 충돌은 해결했지만, Git이 감지 못하는 시맨틱 충돌을 점검해줘.

검증 항목:
1. 함수/변수 이름 변경 충돌: 한쪽에서 rename한 함수를 다른 쪽에서 기존 이름으로 호출하고 있지 않은지
2. 타입/인터페이스 변경 충돌: 타입 필드가 변경/삭제되었는데 다른 쪽에서 해당 필드를 사용하는 코드가 추가되지 않았는지
3. import 정합성: 병합 후 중복 import, 누락 import, 사용하지 않는 import 확인
4. 함수 시그니처 충돌: 매개변수가 변경되었는데 호출부가 기존 시그니처를 사용하지 않는지
5. 삭제된 코드 의존성: 한쪽에서 삭제한 함수/변수를 다른 쪽 새 코드가 참조하지 않는지
6. 전역 상태/설정 변경: 설정값이 바뀌었는데 기존 값 기반 로직이 추가되지 않았는지

검증 방법:
- TypeScript 타입 체크: npx tsc --noEmit
- 빌드 확인: npm run build
- 남은 충돌 마커: git diff --check
- 병합으로 변경된 전체 diff: git diff HEAD~1..HEAD

문제 발견 시:
- 파일명, 라인, 구체적인 문제를 보여줘
- 수정 방안을 제시하되, 내 확인 후에 수정해줘

===== 병합 후 빌드/테스트 검증 =====
병합 후 프로젝트가 정상 작동하는지 확인해줘.

순서:
1. 남은 충돌 마커 검색: 프로젝트 전체에서 <<<<<<, ======, >>>>>> 검색
2. TypeScript 컴파일: npx tsc --noEmit → 타입 에러 목록
3. 프론트엔드 빌드: npm run build → 빌드 에러 목록
4. 백엔드 빌드: npm run build (backend-node) → 빌드 에러 목록
5. 린트 체크: 변경된 파일들에 대해 린트 확인

에러 발견 시 각각에 대해:
- 에러 메시지 전문
- 원인이 병합 때문인지, 기존 코드 문제인지 구분
- 병합 때문이면 어떤 충돌 해결이 잘못되었는지 추적

===== 병합 완료 정리 =====
병합이 완료되었어. 정리해줘.

정리 항목:
1. 병합 요약: 어떤 브랜치에서 어떤 브랜치로, 총 충돌 파일 수, 해결 방식 통계
2. 주의가 필요한 변경사항: 시맨틱 충돌 위험이 있었던 부분 목록
3. 테스트가 필요한 기능: 병합으로 영향받은 기능 목록 (수동 테스트 대상)
4. 커밋 메시지 작성: 병합 내용을 요약한 적절한 커밋 메시지 제안

문서 정리:
- PROBLEMS.md에 병합 중 발견된 문제-해결 추가 (있으면)
- CHANGELOG.md에 병합 내용 기록
```

---

## popdocs 업데이트 시점 요약

| 단계 | 업데이트 대상 | 시점 |
|------|-------------|------|
| 계획 수립 | PLAN.md "현재 구현 계획", STATUS.md | 계획 확정 시 |
| 코딩 중 | PLAN.md 완료 체크 `[x]` | 각 파일 완료 시 |
| 검수 | PROBLEMS.md 내용 준비 | 문제 발견 시 |
| 수정 | PROBLEMS.md 내용 준비 | 수정 완료 시 |
| 병합 준비 | (응답으로 제공) | merge 시작 전 |
| 병합 실행 | (충돌 해결 중) | merge 진행 중 |
| 병합 시맨틱 검증 | (응답으로 제공) | 텍스트 충돌 해결 직후 |
| 병합 빌드 검증 | (응답으로 제공) | 시맨틱 검증 후 |
| 병합 완료 정리 | PROBLEMS.md, CHANGELOG.md | 병합 최종 완료 시 |
| 기록 | sessions/, CHANGELOG, STATUS, README, PROBLEMS, INDEX | 작업 완료 시 |
| 동기화 확인 | 전체 문서 간 불일치 점검 | 기록 직후 |
| 주간 복습 | (응답으로 제공, 파일 저장은 선택) | 금요일 |

---

## 세션 분리 가이드

```
[Opus 세션] 토의 + 계획
  → popdocs 업데이트 (PLAN.md, STATUS.md)
  → 세션 종료

[새 세션 - Sonnet/Opus] 코딩 + 검수 + 수정
  → "@popdocs/ 읽고 PLAN.md 계획대로 진행해"
  → 15건 이내로 완료
  → 세션 종료

[새 세션 - 아무 모델] 기록 + 동기화 확인
  → "기록" 프롬프트 → "동기화 확인" 프롬프트

[병합 세션 - Opus 권장] 브랜치 병합
  → "병합 준비" 프롬프트 → 위험도 파악
  → "병합 실행" 프롬프트 → 텍스트 충돌 해결
  → "병합 후 시맨틱 검증" 프롬프트 → 숨은 버그 점검
  → "병합 후 빌드/테스트 검증" 프롬프트 → 빌드 확인
  → "병합 완료 정리" 프롬프트 → 기록 및 커밋
```

**세션을 끊는 기준**:
- 작업이 15건 이내로 끝나면 한 세션에서 끝까지 (끊을 필요 없음)
- 대화가 15건을 넘어갈 것 같으면 세션 분리
- 완전히 다른 작업으로 전환할 때

---

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