19 KiB
19 KiB
워크플로우 프롬프트
각 작업 단계에서 AI에게 내리는 표준 프롬프트입니다. 상황에 맞는 프롬프트를 복사해서 사용하세요.
[괄호]안은 상황에 맞게 수정하세요.
한 번에 복사용
===== 토의 중 개념 학습 =====
지금 설명한 [개념명]을 우리 프로젝트 코드에서 실제 사용되는 예시로 보여줘.
해당 코드가 없으면 어떤 문제가 생기는지 한 문장으로.
===== 토의 시작 =====
[주제/아이디어]에 대해 토의하자.
사전 준비 (토의 시작 전에 반드시):
1. @popdocs/ 의 README → STATUS → PLAN.md 순서로 현재 상태 파악
2. 관련 기존 문서 확인 (POPUPDATE_2.md, ARCHITECTURE.md 등 해당되는 것만)
3. 현재 계획과 충돌하거나 영향받는 부분이 있으면 먼저 알려줘
===== 토의 마무리 =====
토의 내용을 정리하고 popdocs에 반영해줘.
정리할 것:
1. 이번 토의에서 결정된 사항 전체를 테이블로 요약
2. 보류/미결 사항이 있으면 별도로 정리
3. PLAN.md 반영 방식 제안: "새 계획 생성" / "기존 계획 수정" / "계획 변경 불필요"
4. 설계 문서(POPUPDATE_2.md 등) 업데이트 필요 여부 제안
내 확인 후 문서 반영:
- PLAN.md: 새 계획이면 "현재 구현 계획" 교체, 수정이면 해당 부분 갱신
- STATUS.md: 진행상태/다음 작업 업데이트
- README.md: "마지막 대화 요약" 동기화
- sessions/오늘날짜.md: 생성 (결정 사항, 보류/미결, 다음 토의 주제 중심)
- CHANGELOG.md: 설계 결정 섹션 추가
- decisions/: 중요한 아키텍처 결정이 있으면 ADR 생성 (없으면 생략)
제외 대상 (토의 세션에서는 불필요):
- PROBLEMS.md (코드 에러 없음)
- INDEX.md (새 함수 없음)
===== 아이디어/설계 토의 (이어서) =====
@popdocs/ 의 README → STATUS 읽고, 이전 토의 이어서 하자.
확인할 것:
1. sessions/최근날짜.md에서 "보류/미결" 항목 확인
2. 지난번 결정 사항 요약해서 보여줘
3. 이어서 논의할 주제 제시
이후 진행은 "토의 마무리"와 동일한 규칙으로.
===== 계획 =====
구현 계획서를 작성해줘.
포함할 것:
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 일치 여부
문제 발견 시:
- 고치기 전에 해당 코드를 보여주고 어디가 잘못됐는지 표시해줘
- 내가 확인한 다음에 고쳐줘
- 발견된 각 문제의 크기를 판단하고 다음 단계를 추천해줘:
소형 (1개 파일, 10줄 이내): "바로 수정 가능합니다" → "수정" 프롬프트
중형 (2-3개 파일, 수십 줄): "미니 계획이 필요합니다" → "미니 계획" 프롬프트
대형 (4개+ 파일, 구조 변경): "계획부터 다시 세워야 합니다" → "계획" 프롬프트
문서 정리:
- 발견된 문제가 있으면 PROBLEMS.md에 추가할 내용을 미리 정리해둬
===== 미니 계획 (중형 문제용) =====
검수에서 발견된 중형 문제를 해결할 미니 계획을 세워줘.
발견된 문제:
[문제 설명 - 또는 위 검수에서 보고된 내용 참조]
미니 계획에 포함할 것:
1. 원인 분석: 왜 이 문제가 발생했는지 한 문장
2. 영향 범위: 수정해야 할 파일과 함수 목록
3. 수정 순서: 의존성 기반
4. 각 파일별 변경 내용 (구체적으로)
5. 사전 검증: 수정할 변수/함수가 다른 곳에서 사용되는지 Grep 확인
6. 함정 경고: 이 수정으로 깨질 수 있는 다른 부분
미니 계획은 PLAN.md에 반영하지 않아 (너무 작으니까).
대신 수정 완료 후 PROBLEMS.md에 "문제 | 해결 | 날짜 | 키워드"로 기록해줘.
계획이 확인되면 바로 수정 진행해줘.
수정 규칙:
1. 각 파일 수정 전에 해당 파일을 먼저 읽어
2. 수정할 변수/함수가 파일에 이미 존재하는지 Grep 확인
3. 한 파일 완료할 때마다 린트 확인
수정 완료 후:
- 자체 검증 (import 정합성, 중복 정의, props 일치)
- 이상 없으면 "재검수 필요 없음" / 이상 있으면 "재검수 필요 - 검수 프롬프트를 다시 사용해주세요" 보고
===== 수정 =====
발견된 문제를 수정해줘.
수정 전에 먼저:
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에 병합 내용 기록
프롬프트 목록 (총 21개)
| # | 프롬프트 | 언제 사용 |
|---|---|---|
| 1 | 토의 중 개념 학습 | 토의 중 모르는 개념이 나왔을 때 |
| 2 | 토의 시작 | 새 주제로 설계/아이디어 토의 시작 |
| 3 | 토의 마무리 | 토의 끝, 결정사항 문서화 |
| 4 | 아이디어/설계 토의 (이어서) | 이전 토의 이어서 할 때 |
| 5 | 계획 | 구현 계획서 작성 |
| 6 | 계획 이해 (선택) | 계획에서 복잡한 부분 이해 |
| 7 | 코딩 | 계획대로 코딩 실행 |
| 8 | 새 세션 코딩 | 다른 모델/세션에서 코딩 이어서 |
| 9 | 검수 | 수정한 파일 검증 (크기 자동 판단 포함) |
| 10 | 미니 계획 | 검수에서 중형 문제 발견 시 |
| 11 | 수정 | 소형 문제 바로 수정 |
| 12 | 기록 | 작업 내용 popdocs 기록 |
| 13 | 동기화 확인 | 문서 간 일치 여부 점검 |
| 14 | 주간 복습 | 금요일 복습 |
| 15 | 병합 준비 | merge 전 위험도 파악 |
| 16 | 병합 실행 | merge 충돌 해결 |
| 17 | 병합 후 시맨틱 검증 | 숨은 논리 충돌 점검 |
| 18 | 병합 후 빌드/테스트 검증 | 빌드 확인 |
| 19 | 병합 완료 정리 | 병합 기록 및 커밋 |
워크플로우 흐름도
[토의 흐름]
토의 시작 → (자유 토의) → 토의 마무리
또는: 아이디어/설계 토의 (이어서) → (자유 토의) → 토의 마무리
[코딩 흐름]
계획 → (계획 이해) → 코딩 → 검수 → AI가 크기 판단
│
┌──────────────┼──────────────┐
[소형] [중형] [대형]
수정 →완료 미니 계획 계획부터
→ 수정+자체검증 새 사이클
→ (재검수 필요 시 검수 다시)
[기록 흐름]
기록 → 동기화 확인
[병합 흐름]
병합 준비 → 병합 실행 → 시맨틱 검증 → 빌드/테스트 검증 → 병합 완료 정리
popdocs 업데이트 시점 요약
| 단계 | 업데이트 대상 | 시점 |
|---|---|---|
| 토의 시작 | 현재 상태 파악, 관련 문서 확인 | 토의 세션 시작 시 |
| 토의 마무리 | PLAN, STATUS, README, sessions/, CHANGELOG, decisions/ | 토의 세션 종료 시 |
| 계획 수립 | PLAN.md "현재 구현 계획", STATUS.md | 계획 확정 시 |
| 코딩 중 | PLAN.md 완료 체크 [x] |
각 파일 완료 시 |
| 검수 | PROBLEMS.md 내용 준비 + 크기 자동 판단 | 문제 발견 시 |
| 미니 계획 (중형) | PROBLEMS.md (수정 완료 후) | 검수에서 중형 문제 발견 시 |
| 수정 (소형) | PROBLEMS.md 내용 준비 | 수정 완료 시 |
| 병합 준비 | (응답으로 제공) | merge 시작 전 |
| 병합 실행 | (충돌 해결 중) | merge 진행 중 |
| 병합 시맨틱 검증 | (응답으로 제공) | 텍스트 충돌 해결 직후 |
| 병합 빌드 검증 | (응답으로 제공) | 시맨틱 검증 후 |
| 병합 완료 정리 | PROBLEMS.md, CHANGELOG.md | 병합 최종 완료 시 |
| 기록 | sessions/, CHANGELOG, STATUS, README, PROBLEMS, INDEX | 코딩 작업 완료 시 |
| 동기화 확인 | 전체 문서 간 불일치 점검 | 기록 직후 |
| 주간 복습 | (응답으로 제공, 파일 저장은 선택) | 금요일 |
세션 분리 가이드
[Opus 세션] 토의 + 계획
→ "토의 시작" 프롬프트 → 자유롭게 토의
→ "토의 마무리" 프롬프트 → 문서 반영 + 동기화
→ 세션 종료
[새 세션 - Sonnet/Opus] 코딩 + 검수 + 수정
→ "@popdocs/ 읽고 PLAN.md 계획대로 진행해"
→ 15건 이내로 완료
→ 세션 종료
검수에서 새 문제 발견 시 (AI가 크기 자동 판단 후 추천):
소형 → "수정" 프롬프트 → 완료
중형 → "미니 계획" 프롬프트 → 수정+자체검증 → 재검수 필요 시 "검수" 다시
대형 → "계획" 프롬프트부터 새 사이클 시작
[새 세션 - 아무 모델] 기록 + 동기화 확인
→ "기록" 프롬프트 → "동기화 확인" 프롬프트
[병합 세션 - Opus 권장] 브랜치 병합
→ "병합 준비" 프롬프트 → 위험도 파악
→ "병합 실행" 프롬프트 → 텍스트 충돌 해결
→ "병합 후 시맨틱 검증" 프롬프트 → 숨은 버그 점검
→ "병합 후 빌드/테스트 검증" 프롬프트 → 빌드 확인
→ "병합 완료 정리" 프롬프트 → 기록 및 커밋
마무리 프롬프트 선택 기준:
- 토의 마무리: 코드 변경 없이 설계/계획/아이디어를 논의한 세션
- 기록: 실제 코드를 작성/수정/삭제한 세션
- 한 세션에서 토의 + 코딩을 모두 했으면 기록을 사용 (상위 호환)
세션을 끊는 기준:
- 작업이 15건 이내로 끝나면 한 세션에서 끝까지 (끊을 필요 없음)
- 대화가 15건을 넘어갈 것 같으면 세션 분리
- 완전히 다른 작업으로 전환할 때
최종 업데이트: 2026-02-10