60 lines
3.1 KiB
Markdown
60 lines
3.1 KiB
Markdown
# 하이퍼워터폴 접목 설계 — spec-kit + superpowers 워크플로우 보강
|
|
|
|
- 날짜: 2026-07-27
|
|
- 출처: rhwp Hyper-Waterfall 방법론 정리 문서 (myVault topics/2026-07/0005)
|
|
- 결정 방식: brainstorming 스킬로 4문답 → 방안 A 승인
|
|
|
|
## 목적 (사용자 선택)
|
|
|
|
AI 페어프로그래밍의 두 약점을 문서로 막는다.
|
|
|
|
1. 세션 간 기억 유지 — 세션 끊겨도 "지금 뭐 하지 / 어디까지 / 왜 이렇게"가 0초에 복원
|
|
2. 방향 교정 게이트 — 틀린 방향으로 확신하며 달리는 걸 계획·완료 승인에서 잡음
|
|
3. 피드백·실패 자산화 — 사람 교정(feedback)과 실패 기록(troubleshootings) 영구 보존
|
|
4. 문서 체계 — 위 셋을 담는 최소 폴더 구조
|
|
|
|
## 결정 사항
|
|
|
|
| 항목 | 결정 |
|
|
|---|---|
|
|
| 앞단 | spec-kit 설치해서 결합 (하이퍼워터폴은 보강재, plan 집은 `specs/<feature>/` 하나 유지) |
|
|
| 승인 강도 | 계획(plan/tasks) + 완료(report)만 승인. 중간 단계는 보고서만 남기고 멈추지 않음 |
|
|
| 식별자 | spec-kit feature 이름. 이슈 번호·manifest 4필드는 스킵 (문서 늘어나 헷갈리면 그때) |
|
|
|
|
## 폴더 구조
|
|
|
|
```
|
|
specs/<feature>/ # spec-kit 표준 (spec.md, plan.md, tasks.md)
|
|
stage-N.md # [추가] 단계 보고: 한 일 / 검증 결과 / 다음
|
|
report.md # [추가] 완료 보고: 계획 vs 결과 + 달라진 점 + 남긴 것
|
|
|
|
docs/
|
|
orders/YYYYMMDD.md # [추가] 오늘 할 일 + 진행 중 feature 포인터 (ztodo.md 승격)
|
|
feedback/yyyy-mm-dd-<keyword>.md # [추가] 사람 교정 원문 + 왜 + 앞으로
|
|
tech/<topic>.md # [추가] 기술 사실 영구화 (topic 당 1파일, 갱신형)
|
|
troubleshootings/ # 기존 그대로
|
|
```
|
|
|
|
## 파이프라인 훅 5개
|
|
|
|
1. **세션 부트스트랩**: orders 최신 → 진행 중 feature 의 tasks.md + 최신 stage-N.md → 필요시 feedback/tech
|
|
2. **executing-plans 도중**: task 묶음 끝날 때마다 stage-N.md 기록, 승인 대기 없이 진행
|
|
3. **완료 시**: verification-before-completion → report.md → 사용자 최종 승인 → merge
|
|
4. **사용자 교정 시**: Claude 가 자발적으로 feedback/ 기록 (자동 트리거)
|
|
5. **기술 사실 발견 시**: tech/ 기록, plan 때 docs-lib 와 같이 참조
|
|
|
|
## 스킵한 것 (YAGNI)
|
|
|
|
- rhwp 이슈 번호 파일명 규칙 — 이슈·PR 안 쓰는 솔로 로컬 워크플로우
|
|
- manifest 4필드(kind/status/canonical/last_verified) — 문서 수십 개 넘어 캐논이 헷갈리면 도입
|
|
- PR 리뷰 라우팅·CI 게이트 — GitHub Actions 파이프라인 없음
|
|
|
|
## 도입 작업 (이 설계의 구현 범위)
|
|
|
|
1. spec-kit 설치 (`specify init --here --ai claude --script ps`)
|
|
2. `docs/orders`·`docs/feedback`·`docs/tech` 생성 + 각 README 양식
|
|
3. CLAUDE.md 갱신 (파이프라인 훅 + 부트스트랩 섹션)
|
|
4. ztodo.md 항목을 첫 orders 파일로 이사
|
|
|
|
도입 자체는 spec-kit 파이프라인 안 태움 (폴더 + 문서 편집뿐이라 너무 작음).
|