kdyspike — 사전 연구 자동 강제

기술적으로 어려운 기능 구현 전 사전 연구(스파이크)를 자동 강제하는 스킬. 난이도 5단계 자동 판별 → 마이크로/풀 스파이크 2트랙 → 검증 게이트 → 의사결정 기록.

기본 경로

GENERAL_PRO 결정 순서:
1. 환경변수 GENERAL_PRO_PATH
2. CWD가 00-general-pro* 내부이면 해당 루트
3. ~/{develop,dev}/00-general-pro-web 존재 탐색
4. 실패 시 AskUserQuestion: "00-general-pro-web 경로를 입력해주세요"

GENERAL_PRO = {결정된 경로}
SKILLS_DIR  = $GENERAL_PRO/03-skills
PHASES_DIR  = $GENERAL_PRO/03-skills/kdyspike/phases
REFS_DIR    = $GENERAL_PRO/03-skills/kdyspike/references
TECH_RD     = $GENERAL_PRO/01-dev-rules-system/06-tech-rd

인수 처리

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

Phase 흐름

Step 0-0: 체크포인트 확인
  → --resume 시 _CHECKPOINT_KDYSPIKE.md에서 재개
    |
Phase 0: 컨텍스트 탐지
  → 프로젝트 스택 파악, 기존 spikes/ 확인, 레퍼런스 로드
    |
Phase 1: 난이도 판별    ← phases/difficulty-assessment.md
  → 점수 기반 5단계 자동 판별 + 사용자 확인 [게이트1]
    |
    ├── Level 1 → 스킬 종료 (즉시 코딩)
    ├── Level 2~3 → Phase 2A
    └── Level 4~5 → Phase 2B
    |
Phase 2A: 마이크로 스파이크   ← phases/micro-spike.md
  → 웹검색 3회 + 문서 1개 + 마이크로 문서 생성
    |
Phase 2B: 풀 스파이크         ← phases/full-spike.md
  → 웹검색 5~10회 + spikes/ 폴더 + 실험코드
    |
Phase 3: 검증 게이트          ← phases/verification-gate.md
  → 산출물 완전성 자동 확인 + Go/No-Go [게이트2]
    |
Phase 4: 의사결정 기록
  → ADR 생성 + _SPIKE_CLEARANCE.md 코딩 허가 엔트리

Step 0-0: 체크포인트 확인

--resume 인수이거나 _CHECKPOINT_KDYSPIKE.md가 존재하면:

1. 체크포인트 파일 Read
2. 마지막 완료 Phase 확인
3. 다음 Phase부터 재개

체크포인트가 없고 --resume이면:

• "체크포인트가 없습니다. Phase 0부터 시작합니다." 안내

Phase 0: 컨텍스트 탐지

Step 0-1. 프로젝트 스택 파악

1. Read: CLAUDE.md → 스택 정보 추출 ($STACK)
2. Glob: package.json, requirements.txt, go.mod 등 → 의존성 목록 ($DEPS)
3. Glob: spikes/ → 기존 스파이크 목록 ($EXISTING_SPIKES)
4. Glob: docs/research/ → 기존 마이크로 스파이크, ADR 목록
5. if GP_AVAILABLE:
     RESEARCH_VAULT = $GENERAL_PRO/08-research-vault
     Glob: $RESEARCH_VAULT/*/analyses/*spike*.md, *검증*.md
     → vault에 동일 기술/도메인의 기존 스파이크 분석 카드가 있으면 표시
     → "기존 연구자료 {N}건 발견 ({topic})" → Phase 1 난이도 판별 시 참고

Step 0-2. 기능 설명 수집

• 인수에 <기능 설명>이 있으면 $FEATURE에 할당
• 없으면 AskUserQuestion:

  어떤 기능을 구현하려고 하시나요?
  (기술적 세부사항을 포함해주세요. 예: "WebRTC 기반 실시간 화상 회의 기능")
  

Step 0-3. --status 처리

--status 인수인 경우:

1. Glob: spikes/spike-* → 폴더 목록
2. Glob: docs/research/micro-spike-* → 마이크로 목록
3. Read: docs/research/_SPIKE_CLEARANCE.md (있으면)
4. 결과 테이블 출력:

--- Spike 현황 ---

| # | 유형 | 주제 | 상태 | 판정 |
|---|------|------|------|------|
| 1 | Full | spike-001-webrtc | 완료 | Go |
| 2 | Micro | zustand-상태관리 | 완료 | Go |
| 3 | Full | spike-002-canvas | 진행중 | - |

--status 후 스킬 종료.

Step 0-4. 체크포인트 초기화

_CHECKPOINT_KDYSPIKE.md 생성:

# kdyspike 체크포인트

- 시작: {날짜시간}
- 기능: {$FEATURE}
- 프로젝트 스택: {$STACK}
- 기존 스파이크: {$EXISTING_SPIKES 수}

## Phase 0 완료

Phase 1: 난이도 판별

상세: phases/difficulty-assessment.md 참조

1. references/difficulty-criteria.md 로드
2. $FEATURE에서 기술 키워드 추출
3. 항목별 점수 합산 → Level 산출
4. [게이트1] 사용자 확인 (AskUserQuestion)
   • Y: 해당 트랙으로 진행
   • N: 수동 조정
   • skip: 스킬 종료 (Level 4~5 skip 시 경고)
5. 체크포인트 갱신

--assess 처리

Phase 1까지만 실행하고 결과 출력 후 스킬 종료:

--- 난이도 판별 결과 ---

기능: {$FEATURE}
총점: {N}점 → Level {N} ({명칭})
권장: {트랙}

스파이크를 시작하려면: /kdyspike {$FEATURE}

Phase 2A: 마이크로 스파이크

상세: phases/micro-spike.md 참조

Level 2~3 또는 --micro 인수 시 실행:

1. WebSearch (최대 3회) — 핵심 질문 조사
2. WebFetch (선택 1회) — 핵심 문서 정독
3. docs/research/micro-spike-{YYYYMMDD}-{주제}.md 생성 (references/spike-templates.md 섹션 A)
4. 결과 요약 출력
5. 체크포인트 갱신
6. → Phase 3

Phase 2B: 풀 스파이크

상세: phases/full-spike.md 참조

Level 4~5 또는 --full 인수 시 실행:

1. 스파이크 넘버링 (기존 spikes/ 스캔)
2. spikes/spike-{NNN}-{주제}/ 폴더 구조 생성 (references/spike-templates.md 섹션 B)
3. WebSearch + WebFetch (5~10회) — 심층 조사 → findings.md
4. experiments/ 실험 코드 작성
5. README.md 결론 업데이트
6. 결과 요약 출력
7. 체크포인트 갱신
8. → Phase 3

Level 5 추가 안내:

• "이 기능은 Level 5 (Research)입니다. 풀 스파이크 후 POC가 필요할 수 있습니다."
• 06-tech-rd/ Stage 2 (POC) 프로세스 안내

Phase 3: 검증 게이트

상세: phases/verification-gate.md 참조

1. 트랙에 따른 산출물 완전성 검사
2. Go/No-Go 자동 판정
3. [게이트2]
   • Go: Phase 4로 진행
   • No-Go: 보완 안내 → 보완 후 재검증 또는 중단
4. 체크포인트 갱신

Phase 4: 의사결정 기록

Step 4-1. ADR 생성

1. 기존 ADR 넘버링 확인: docs/research/decisions/ADR-*.md 스캔
2. references/decision-record-template.md 템플릿으로 ADR 생성:
   • 파일: docs/research/decisions/ADR-{NNN}-{주제slug}.md
   • 컨텍스트: 스파이크 배경
   • 검토 옵션: 스파이크에서 비교한 접근법
   • 결정: 선택한 접근법
   • 이유: 선택 근거

필요한 디렉토리가 없으면 자동 생성:

mkdir -p docs/research/decisions

Step 4-2. _SPIKE_CLEARANCE.md 엔트리 추가

1. docs/research/_SPIKE_CLEARANCE.md 없으면 references/spike-templates.md 섹션 C 헤더로 생성
2. 엔트리 1행 추가:

| {날짜} | {주제} | L{N} | {Micro/Full} | Go | {산출물 경로} | ADR-{NNN} |

Step 4-2b. 연구자료 아카이빙 판단 및 저장

if GP_AVAILABLE:
  RESEARCH_VAULT = $GENERAL_PRO/08-research-vault

  # ── 아카이빙 가치 판단 ──
  archive_score = 0
  if 스파이크 난이도 Level 3 이상 (풀 스파이크 수행됨): +3
  if 기존 vault 주제와 연속성 있음 (같은 기술 도메인 추적): +2
  if POC 코드/실험 결과가 다른 프로젝트에도 재사용 가능: +1
  if ADR에 기술 선택 근거가 범용적: +1

  if archive_score >= 3:
    topic_slug = 기술 도메인의 kebab-case 변환

    if $RESEARCH_VAULT/{topic_slug}/ 미존재:
      AskUserQuestion: "'{기술}' 스파이크 결과를 research-vault에 아카이빙할까요?"
      → 승인 시: mkdir -p + _TOPIC_TEMPLATE.md 복사 → _INDEX.md 초기화
    else:
      → 기존 주제 폴더에 추가

    Write: $RESEARCH_VAULT/{topic_slug}/analyses/YYYY-MM-DD-spike-{주제}.md
      → _ANALYSIS_TEMPLATE.md 기반, 스파이크 결과(난이도/판정/핵심발견/ADR) 분석 카드 작성
    Edit: $RESEARCH_VAULT/{topic_slug}/_INDEX.md
      → 분석 이력 테이블에 1행 추가
  else:
    → 아카이빙 건너뜀 (로컬 스파이크 결과만 유지)

Step 4-3. 체크포인트 정리

스킬 완료이므로 _CHECKPOINT_KDYSPIKE.md에 최종 상태 기록:

## Phase 4 완료 (스킬 완료)
- ADR: docs/research/decisions/ADR-{NNN}-{주제}.md
- Clearance: docs/research/_SPIKE_CLEARANCE.md에 등록
- 완료 시각: {날짜시간}

Step 4-4. 최종 결과 보고

--- kdyspike 완료 ---

기능: {$FEATURE}
Level: {N} ({명칭})
트랙: {마이크로/풀}

산출물:
- {스파이크 문서/폴더 경로}
- ADR: docs/research/decisions/ADR-{NNN}-{주제}.md
- Clearance: docs/research/_SPIKE_CLEARANCE.md

파일 변경 목록:
- [생성] {파일1}
- [생성] {파일2}
- [수정] {파일3} (있는 경우)

코딩 허가가 부여되었습니다. 구현을 시작하세요.

다음 권장 작업:
- 기능 구현 시작
- Level 5인 경우: POC 진행 검토 (06-tech-rd Stage 2 참조)

Superpowers 연계

이 스킬 실행 중 아래 superpowers 원칙을 적용한다.

예외사항

다음은 이 스킬이 해결하는 문제가 아닌 것:

• 이미 잘 아는 기술의 단순 적용: Level 1 판별 → 즉시 코딩 허가
• POC 전체 프로세스: Level 5에서 안내만, 직접 수행은 06-tech-rd/ Stage 2
• 프로덕션 코드 작성: 스파이크는 실험 코드만, 프로덕션은 별도
• 기존 스파이크 재실행: --status로 확인 후 판단

관련 스킬/에이전트

사용 예시

# 전체 플로우 (기능 설명 포함)
/kdyspike WebRTC 기반 실시간 화상 회의 기능

# 난이도 판별만
/kdyspike --assess 실시간 협업 에디터

# 마이크로 스파이크 직행
/kdyspike --micro Zustand 상태관리 패턴

# 풀 스파이크 직행
/kdyspike --full WebSocket 실시간 동기화

# 현황 조회
/kdyspike --status

# 중단 작업 재개
/kdyspike --resume

주의사항

• hooks (spike-guard)는 선택적 opt-in: 반복 실패하는 프로젝트에만 활성화. 스킬 자체는 hooks 없이 독립 동작
• 마이크로 스파이크에서 실험 코드 작성 금지: 조사+의사결정만. 코드가 필요하면 풀 스파이크
• 기존 spikes/ 구조 존중: 이미 06-tech-rd/ 방식으로 spikes/가 있으면 동일 넘버링 체계 사용
• Level 4~5 skip 경고: 사용자가 skip해도 작동하지만, 리스크 경고를 반드시 출력