kdywave — 범용 Wave 리서치+설계 오케스트레이션

프로젝트의 기술 리서치부터 아키텍처 설계, 로드맵 산출까지를 Wave 단위로 체계적으로 수행하는 스킬입니다. Plan D Visual 프로젝트에서 Wave 1-4(109개 문서)를 통해 실증된 방법론을 범용화했습니다.

핵심 원칙

인수 처리

사용자가 제공한 인수: $ARGUMENTS

Phase 흐름

Phase 0: 프로젝트 탐색     → 프로젝트 프로필 수집, 규모 감지, 디렉토리 초기화
Phase 1: Wave 계획 수립     → 카테고리 매핑, Wave 구성, 의사결정 질문, 사용자 승인
Phase 2: Wave 실행 루프     → Wave 1-5 순차, 각 Wave 내 에이전트 병렬 발사
Phase 3: Wave 검증          → 산출물 완전성, 스코어링 검증, 일관성 확인
Phase 4: 완료 & 인계        → 최종 패키징, kdygenesis 연계 제안, 피드백 등록

Phase 0: 프로젝트 탐색

상세: phases/phase-0-discovery.md 참조

Read: phases/phase-0-discovery.md

1. 체크포인트 확인: --resume 또는 기존 _CHECKPOINT_KDYWAVE.md 감지
2. --status 처리: 마스터 인덱스 로드 → 대시보드 출력 → 종료
3. --from-idea 처리: kdyidea 계획서에서 프로젝트 프로필 자동 추출
4. 프로젝트 프로필 수집: 유형, 플랫폼, 규모, 확정 기술, 특수 요구
5. 스코어링 항목 결정: references/scoring-frameworks.md 로드 → 도메인 프리셋 선택
6. 연구자료 교차 참조: GP_AVAILABLE이면 $GENERAL_PRO/08-research-vault/*/ 스캔 → 프로젝트 도메인과 매칭되는 주제 폴더의 기존 분석 카드/종합 문서를 Wave 1 입력 컨텍스트로 활용
7. 산출물 디렉토리 생성: docs/{project-name}/ 구조 초기화
8. 체크포인트 생성: _CHECKPOINT_KDYWAVE.md 초기화

Phase 1: Wave 계획 수립

상세: phases/phase-1-wave-planning.md 참조

Read: phases/phase-1-wave-planning.md
Read: references/scale-wave-matrix.md
Read: references/category-catalog.md

1. 규모 결정: --scale 또는 프로젝트 복잡도 기반 자동 감지 → S/M/L/XL
2. 카테고리 매핑: 프로젝트 유형별 리서치 카테고리 결정 (references/category-catalog.md)
3. Wave 구성: 규모별 Wave 파라미터 적용 (references/scale-wave-matrix.md)
4. 의사결정 질문 등록: DQ-1.x ~ DQ-5.x 초기 질문 등록 (references/decision-tracking.md)
5. Wave별 문서 목록 생성: 카테고리 × Wave 타입 → 문서 ID/제목/템플릿 매핑
6. 에이전트 수 결정: 규모별 최적 에이전트 수 (references/scale-wave-matrix.md)
7. 마스터 인덱스 초안: templates/master-index.md 기반 README.md 생성
8. 사용자 승인: Wave 계획, 카테고리, 문서 목록, 에이전트 수 확인 (AskUserQuestion)
   • --dry-run → 계획만 출력하고 종료

Phase 2: Wave 실행 루프

상세: phases/phase-2-wave-execution.md 참조

Read: phases/phase-2-wave-execution.md
Read: references/agent-prompt-templates.md
Read: references/quality-gates.md

Wave 구조 (기본 5 Wave, 규모에 따라 조정)

Wave 1: 기초 리서치 (Deep Dive)
  → 각 카테고리의 핵심 후보 기술을 개별 심층 분석
  → 템플릿: templates/research-deep-dive.md
  → 에이전트당 1-2개 문서, 최소 500줄/문서

Wave 2: 비교 리서치 (Comparison + Matrix)
  → 카테고리 내 기술 간 1:1 비교 + 카테고리별 매트릭스
  → 템플릿: templates/research-comparison.md, templates/research-matrix.md
  → 비교 문서 최소 300줄, 매트릭스 문서에 정량 비교표 필수

Wave 3: 심층 분석 (Vision + Requirements + Deep Analysis)
  → 비전, 사용자 스토리, 요구사항(FR+NFR+CON+ASM) + 추가 심층
  → 템플릿: templates/vision-suite.md
  → 의사결정 질문 답변 확정

Wave 4: 아키텍처 설계 (Architecture + UI/UX + Integration)
  → 시스템 아키텍처, 컴포넌트 설계, 통합 설계, UI/UX 사양
  → 템플릿: templates/architecture-suite.md
  → Wave 1-3 결론 기반 설계 결정

Wave 5: 로드맵 + 스파이크 (Roadmap + Prototyping)
  → 릴리스 계획, 마일스톤, 기술부채 관리, 스파이크 사양
  → 템플릿: templates/roadmap-suite.md
  → kdygenesis 연계 가능한 프로젝트 청사진

실행 루프

FOR wave_n IN [1..configured_waves]:
  1. 품질 게이트 확인 (references/quality-gates.md)
     → 이전 Wave 완료 조건 충족 확인
  2. 에이전트 프롬프트 구성 (references/agent-prompt-templates.md)
     → L1(표준) + L2(Wave 공통) + L3(개별 미션) + L4(계약)
  3. 에이전트 병렬 발사 (Agent tool × N)
     → 각 에이전트가 1-3개 문서 담당
     → isolation 불필요 (문서 작성은 파일 충돌 없음)
     → run_in_background: true
  4. 결과 수집 + 품질 확인
     → 산출물 완전성 확인, 스코어링 앵커 준수 확인
  5. 마스터 인덱스(README.md) 갱신
     → 문서 목록 + 상태 + 점수 업데이트
  6. 의사결정 질문 업데이트
     → 이 Wave에서 답변된 DQ 항목 갱신
  7. 역방향 피드백 확인 (references/feedback-protocol.md)
     → 이전 Wave 결론과 충돌 발견 시 역방향 업데이트 트리거
  8. 체크포인트 갱신
  9. cs 세션 종료 권장 (대규모 Wave 완료 시)

안전 장치

• 에이전트 실패 복구: 1회 자동 재시도, 2회 실패 시 건너뜀
• 3연속 실패: AskUserQuestion → 계속/중단
• 스파이크 트리거: Wave 1/3에서 복잡 기술 발견 시 kdyspike 위임 가능

Phase 3: Wave 검증

상세: phases/phase-3-wave-validation.md 참조

Read: phases/phase-3-wave-validation.md

1. 산출물 완전성: 계획된 문서 vs 실제 생성 문서 비교
2. 스코어링 검증: 모든 매트릭스 문서의 점수 앵커 준수 확인 (references/scoring-anchoring.md)
3. 의사결정 답변 확인: 모든 DQ 항목에 답변 존재 여부
4. Wave 간 일관성: 후속 Wave가 이전 Wave 결론과 모순되지 않는지 확인
5. 역방향 피드백 실행: 모순 발견 시 이전 문서 업데이트

Phase 4: 완료 & 인계

상세: phases/phase-4-completion.md 참조

Read: phases/phase-4-completion.md

1. 최종 패키징: 마스터 인덱스 완성, GLOSSARY 생성, 전체 문서 링크 검증
2. kdygenesis 연계 제안: 리서치 산출물 → 프로젝트 생성으로 이어가는 경로 안내
3. 연구자료 아카이빙 판단 및 저장:

   if GP_AVAILABLE:
     RESEARCH_VAULT = $GENERAL_PRO/08-research-vault
   
     # ── 아카이빙 가치 판단 ──
     archive_score = 0
     if Wave 1 심층 분석에서 기술 비교/평가 매트릭스 생성됨: +2
     if 기존 vault 주제와 연속성 있음 (시계열 추적 가치): +2
     if Wave 3~4에서 아키텍처 의사결정(ADR급) 도출됨: +2
     if 특정 프로젝트에만 한정되지 않는 범용 기술 리서치: +1
     if 3개+ 외부 소스 비교 분석 포함: +1
   
     if archive_score >= 3:
       topic_slug = 프로젝트 도메인의 kebab-case
       if $RESEARCH_VAULT/{topic_slug}/ 미존재:
         AskUserQuestion: "'{도메인}' Wave 리서치를 research-vault에 아카이빙할까요?"
         → 승인 시: mkdir -p + _TOPIC_TEMPLATE.md 복사 → _INDEX.md 초기화
       Write: $RESEARCH_VAULT/{topic_slug}/analyses/YYYY-MM-DD-wave-{project}.md
         → Wave 1~5 핵심 발견·의사결정을 분석 카드로 요약
       Edit: $RESEARCH_VAULT/{topic_slug}/_INDEX.md → 분석 이력 1행 추가
     else:
       → 아카이빙 건너뜀 (로컬 Wave 산출물만 유지)
   

4. 역방향 피드백 트리거 등록: --feedback 모드 안내 (향후 재실행 시)
5. 체크포인트 완료 표시: _CHECKPOINT_KDYWAVE.md 최종 상태 기록
6. 최종 보고서 출력: 산출물 요약, 핵심 결정 사항, 다음 권장 작업

예외사항

다음은 kdywave의 문제가 아닌 것입니다:

• 프로젝트 초기 구조 생성: kdygenesis 사용
• 코드 구현: kdyswarm 사용
• 단일 기술의 빠른 검증: kdyspike 사용 (마이크로 스파이크)
• 아이디어 발굴: kdyidea 사용
• 뉴스/트렌드 수집: kdyintel 사용

스킬 연동

kdyidea (아이디어) ──→ kdywave (리서치+설계) ──→ kdygenesis (프로젝트 생성)
                          │                           │
                          ├── kdyswarm (병렬 엔진)      ├── kdyswarm (병렬 개발)
                          ├── kdyspike (기술 검증)      └── kdynext (건강 진단)
                          └── cs (세션 종료)

참조 파일 구조

kdywave/
├── SKILL.md                          ← 지금 이 파일 (진입점)
├── phases/
│   ├── phase-0-discovery.md          # 프로젝트 탐색
│   ├── phase-1-wave-planning.md      # Wave 계획 수립
│   ├── phase-2-wave-execution.md     # Wave 실행 루프
│   ├── phase-3-wave-validation.md    # Wave 검증
│   └── phase-4-completion.md         # 완료 & 인계
├── references/
│   ├── scale-wave-matrix.md          # 규모별 Wave 구성 매트릭스
│   ├── scoring-frameworks.md         # 프로젝트 유형별 스코어링 프리셋
│   ├── scoring-anchoring.md          # 점수 앵커링 기준서
│   ├── category-catalog.md           # 프로젝트 유형별 리서치 카테고리
│   ├── agent-prompt-templates.md     # Wave별 에이전트 프롬프트 템플릿
│   ├── decision-tracking.md          # 의사결정 추적 시스템
│   ├── quality-gates.md              # 품질 게이트 (Wave 진입/완료 조건)
│   └── feedback-protocol.md          # 역방향 피드백 프로토콜
├── templates/
│   ├── research-deep-dive.md         # Wave 1 심층 분석 문서 템플릿
│   ├── research-comparison.md        # Wave 2 비교 분석 문서 템플릿
│   ├── research-matrix.md            # Wave 2 카테고리 비교 매트릭스 템플릿
│   ├── vision-suite.md               # 비전+스토리+요구사항 통합 템플릿
│   ├── architecture-suite.md         # 아키텍처+컴포넌트+통합+UI/UX 통합 템플릿
│   ├── roadmap-suite.md              # 로드맵+스파이크 통합 템플릿
│   └── master-index.md               # 마스터 인덱스 (진행 대시보드) 템플릿
└── examples/
    └── scale-examples.md             # S/M/L 규모별 실행 예시

사용 예시

# 기본 실행 — 프로젝트 탐색부터 전체 Wave
/kdywave 실시간 협업 문서 에디터 프로젝트

# kdyidea 결과에서 이어받기
/kdywave --from-idea docs/idea-plan.md

# 계획만 확인 (실행 안 함)
/kdywave 데스크톱 앱 --dry-run

# 규모 강제 지정
/kdywave --scale L 대규모 SaaS 플랫폼

# 특정 Wave부터 시작
/kdywave --wave 3 --resume

# 진행 상황 확인
/kdywave --status

# 기존 산출물에 역방향 피드백
/kdywave --feedback

# 소규모 CLI 도구 리서치
/kdywave --scale S REST API 서버

주의사항

• 컨텍스트 비용: 대규모(L/XL)에서 100+ 문서를 생성하므로 에이전트 비용이 발생합니다. --dry-run으로 먼저 확인 권장
• Wave 순서: Wave는 반드시 순차 실행. 이전 Wave 결과가 다음 Wave의 입력
• 체크포인트: 중단 시 _CHECKPOINT_KDYWAVE.md에 진행 상태가 저장됩니다
• 역방향 피드백: --feedback 모드는 기존 산출물을 수정하므로, git commit 후 실행 권장
• 세션 종료: 각 Wave 완료 시 /cs로 세션 종료하여 기록을 남기는 것을 권장합니다

관련 스킬/에이전트