CODE_ASSISTANT/docs/superpowers/specs/2026-07-27-hyperwaterfall-integration-design.md

하이퍼워터폴 접목 설계 — 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 파이프라인 안 태움 (폴더 + 문서 편집뿐이라 너무 작음).