kdyextract v2 - 범용 재사용 코드·디자인 추출 및 패키징

프로젝트 또는 웹사이트에서 범용으로 재사용 가능한 코드·디자인 자산을 분석, 추출하여 체계적으로 정리한다.

인수 처리

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

--dry-run은 분석(Phase 2~4)은 정상 실행. 분석 비용을 줄이려면 --category나 --focus를 함께 사용.

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

--resume 인수 또는 기존 체크포인트 파일 존재 시 중단 지점에서 재개합니다.

if --resume:
  Read: docs/references/_CHECKPOINT_KDYEXTRACT.md
  → 마지막 완료 Phase 확인
  → "수집 데이터 요약" 로드 (분석 결과, 승인 목록 등)
  → Phase 5 이후부터 재개 (Phase 6 정제 또는 Phase 7 파일 생성)
elif _CHECKPOINT_KDYEXTRACT.md 파일이 이미 존재하고 상태가 미완료:
  AskUserQuestion: "이전 세션의 체크포인트가 있습니다. 재개/새로 시작?"
else:
  Phase 0부터 정상 진행

Phase 0: 컨텍스트 탐지

0-1. 실행 환경 확인

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

• TS 저장소: $GENERAL_PRO/02-reusable-code/
• Python 저장소: $GENERAL_PRO/02-reusable-code-python/
• 페이지 저장소: $GENERAL_PRO/02-reusable-page/
• 디자인 저장소: $GENERAL_PRO/02-reusable-design/
• 컨벤션: docs/rules/reusable-code.md

0-2. 모드 판단

0-3. 플래그 파싱

/kdyextract https://linear.app --pages 3 --focus design --dry-run
→ mode = "web-scan", url = "https://linear.app"
→ pages = 3, focus = "design", dry_run = true

Phase 1: 대상 확인

Mode A: 프로젝트 경로 확인

경로 미제공 시 질문:

## 코드 추출 대상 확인

1. **프로젝트 경로**: (예: {DEV_DIR}/my-project)
2. **프로젝트 설명**: (간단히)
3. **옵션**: [전체 / 특정 카테고리 / 드라이런]

Mode B/C: 웹사이트 타겟 확인

URL 미제공 시 질문. 상세 질문 항목: references/mode-b-web-scan.md Phase W-1 참조.

## 웹사이트 추출 대상 확인

1. **URL**: (예: https://linear.app)
2. **소스코드 경로** (있으면, Mode C):
3. **관심 영역**: [전체 / 디자인만 / 코드 패턴만 / 특정 페이지]
4. **추출 목적**: (예: "네비게이션 패턴과 색상 체계 참고")

윤리 고지 (Mode B/C에서 반드시 출력):

코드 패턴과 스타일 구조만 참고용으로 추출합니다. 이미지/로고/폰트 파일은 직접 복사하지 않으며 참조 URL만 기록합니다. robots.txt를 확인하고 허용 경로만 스캔합니다.

Step 2-0: Mode C 부하 제어 분기

Mode C (Hybrid)일 경우 최대 12개 서브에이전트가 동시 실행될 수 있어 컨텍스트 소비가 높습니다. 사용자에게 실행 전략을 확인합니다.

if Mode == C (Hybrid):
  AskUserQuestion:
    question: "Mode C: 최대 12개 서브에이전트 동시 발사. 실행 전략을 선택하세요."
    options:
      - "순차 실행 (권장)" → Mode A 에이전트 1~5 완료 후 Mode B 에이전트 W-1~W-4 실행
      - "병렬 실행 (빠름, 컨텍스트 소비 높음)" → 전체 동시 발사
      - "Mode A/B 별도 세션 분리" → Mode A만 실행, Mode B는 별도 세션 안내

Phase 2: 분석

2-1. 동적 카테고리 맵 생성 (공통)

4개 저장소의 실제 폴더를 Glob으로 동적 스캔 → CATEGORY_MAP 구성:

Glob("02-reusable-code/*"), Glob("02-reusable-code-python/*")
Glob("02-reusable-page/*"), Glob("02-reusable-design/*")

Mode B Only: 이 스캔은 Phase 3 비교용으로만 실행. 웹 스캔 자체는 Phase 2-3에서 수행.

2-2. Mode A: 프로젝트 병렬 탐색

--category 필터 시 해당 에이전트만, 없으면 전체 실행.

에이전트 1: 구조 + 기술스택 + 라이선스 (package.json, tsconfig 등)
에이전트 2: 재사용 컴포넌트 (components/ui/, 훅)
에이전트 3: API/서비스 (lib/, utils/, services/)
에이전트 4: 테스트 코드 (--skip-tests가 아닌 경우)
에이전트 5: Python (pyproject.toml 존재 시)

2-3. Mode B: 웹사이트 스캔

--focus 필터에 따라 해당 에이전트만 실행. robots.txt를 먼저 확인.

에이전트 W-1: Playwright 페이지 크롤링 (DOM, computed CSS, 네트워크 로그)
에이전트 W-2: CSS/스타일 분석 (스타일시트, CSS 변수, 미디어쿼리, 키프레임)
에이전트 W-3: 에셋 수집 (SVG, 이미지 URL 참조, 폰트 설정)
에이전트 W-4: 인터랙션 관찰 (hover, scroll, 클릭, 반응형)

상세 에이전트 스펙: references/mode-b-web-scan.md Phase W-2 참조.

2-4. Mode C: 하이브리드 (Mode A + Mode B 병렬)

Mode A 에이전트 15 (코드 정적 분석) + Mode B 에이전트 W-1W-4 (라이브 웹 스캔) + Mode C 전용 에이전트 C-1~C-3 (정적 설정 분석 + 렌더링 검증). 이후 Phase 2-W → Phase 3+ 합류. 상세: references/mode-b-web-scan.md Mode C 에이전트 참조.

Phase 2-W: 웹 추출물 분류 + 재구성 (Mode B/C 전용)

Mode A는 이 Phase를 건너뛴다.

2-W-1. 추출 분류

스캔 결과를 7가지 카테고리로 자동 분류:

분류 규칙 상세: references/mode-b-web-scan.md Phase W-3 참조.

2-W-2. 코드 재구성

raw 웹 자산을 재사용 가능한 형태로 변환:

변환 규칙 상세 + 코드 예시: references/mode-b-web-scan.md Phase W-4 참조.

→ 이후 Mode A/B/C 모두 Phase 3~8 동일 흐름 (기존 패키징 확인 → 비교 → 승인 → 정제 → 생성 → 보고).

Phase 3: 기존 패키징 확인

CATEGORY_MAP 기반으로 4개 저장소의 기존 파일 목록 수집:

Glob("02-reusable-code/**/*.{ts,tsx}")
Glob("02-reusable-code-python/**/*.py")
Glob("02-reusable-page/**/*.{ts,tsx}")
Glob("02-reusable-design/**/*.{css,ts,svg}")

결과로 EXISTING_FILES 구성 → Phase 4 비교에 사용.

Phase 4: 중복/유사 비교

유사도 판단 기준 (Mode A: 코드)

유사도 판단 기준 (Mode B: 디자인)

판단 분류 (공통)

카테고리 배치 모호 시 → references/category-placement-rules.md 적용.

Phase 4-A: 품질 검증

docs/rules/reusable-code.md + 04-agents/code-reviewer.md 기준.

등급: A (통과) / B (Phase 6 정제) / C (거부 권장)

Phase 4-B: 구문 검증

TS: npx tsc --noEmit --pretty <파일> (실패 시 Grep 기반 패턴 스캔) Python: python -c "import ast, sys; ast.parse(open(sys.argv[1], encoding='utf-8').read())" "<경로>" CSS: 기본 구문 확인 (닫히지 않은 {}, 잘못된 속성명). Mode B 토큰은 :root 선언 또는 @import만 있으면 통과.

실패 → B등급 강등 (Phase 6), 수정 불가 → C등급 + 보고.

Step 4-C: 체크포인트 갱신 (Phase 2~4 완료)

분석 완료 시 체크포인트 파일을 갱신하여 재개 시 Phase 2~4 재실행을 방지합니다.

Write/Edit: docs/references/_CHECKPOINT_KDYEXTRACT.md

갱신 내용:
  - Phase 4 상태: ✅ 완료
  - 분석 결과 요약 (신규/업데이트/스킵/제외 목록)
  - 품질 등급 요약 (A/B/C 분포)
  - Mode, 대상 경로/URL

Phase 5: 사용자 판단 요청

반드시 사용자에게 확인:

## 추출 계획 [Mode A/B/C]

### 코드 (X개)
| 파일 | 카테고리 | 등급 | 설명 |

### 디자인 자산 (X개) — Mode B/C
| 파일 | 카테고리 | 설명 |

### 업데이트 (X개)
| 파일 | 변경 | 권장 |

### 스킵 / 제외 / 거부

진행 방식:
1. 전체 승인
2. 코드만 / 디자인만
3. 개별 선택

--dry-run: 위 보고 출력 후 종료.

Phase 6: 정제

Mode에 따라 정제 규칙 적용:

• Mode A 정제: references/refinement-rules.md (6.1~6.6)
• Mode B 정제: references/mode-b-web-scan.md Mode B 정제 규칙 (W-6.1~W-6.3)
  • DOM 정제: 불필요 wrapper 제거, 시맨틱 태그, aria 보존
  • 스타일 정제: 사이트 색상 → CSS 변수, px → rem, 미디어쿼리 → Tailwind
  • 에셋 정제: SVG 최적화, currentColor 변환, kebab-case 명명

정제 체크리스트:

• 프로젝트/사이트 특화 값 제거
• 하드코딩 → 변수/파라미터/props
• 메타데이터 헤더 (@source, @extracted, @version)
• 컨벤션 준수 확인
• (Mode B) 저작권 침해 없음 확인

Phase 7: 파일 생성/업데이트 (트랜잭션)

트랜잭션 방식 — 실패 시 이번 세션 생성 파일만 역순 삭제.

7-1. 신규 파일 생성

카테고리 폴더 생성 (필요 시) → Write.

7-2. 충돌 해결

기존 파일 존재 시 질문: 덮어쓰기 / 병합(diff) / 스킵 / 백업 후 덮어쓰기. 다수 충돌 시 일괄 옵션.

7-3. README 업데이트

각 카테고리 README에 새 파일 문서화. 02-reusable-design/README.md 추출 이력 테이블에도 추가.

Phase 8: 결과 보고 + 후속

8-1. 결과 요약

## 추출 완료 [Mode A/B/C]

### 코드 추가 (X개) | 디자인 자산 추가 (X개)
| 파일 | 카테고리 | 라인 수/크기 |

### 업데이트 (X개) | 스킵 (X개)

### 출처: {프로젝트명 또는 URL} ({날짜})

8-2. CLAUDE.md 이력 추가

코드 추출 이력 테이블에 항목 추가.

8-3. 카탈로그 동기화 안내

새 카테고리 추가 시 /kdyupdate 실행 권장.

Superpowers 연계

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

예외사항

• 빈 결과: 추출 대상 0개 → "추출 가능한 자산이 없습니다" 안내 후 종료
• 모든 파일 C등급: "추출 적합한 자산이 없습니다" 안내
• Phase 7 실패: 부분 기록 자동 정리 + 원인 보고
• robots.txt 차단 (Mode B): 차단된 경로 스킵, 전체 차단 시 종료 + 안내
• Playwright 미설치 (Mode B): 설치 안내 (npx playwright install chromium)

관련 스킬/에이전트

사용 예시

# Mode A: 프로젝트에서 코드 추출
/kdyextract {프로젝트 경로}/my-project
/kdyextract {프로젝트 경로}/my-project --category hooks
/kdyextract {프로젝트 경로}/my-project --skip-tests --dry-run

# Mode B: 웹사이트에서 프론트엔드 자산 추출
/kdyextract https://linear.app
/kdyextract https://vercel.com --pages 3 --focus design
/kdyextract https://stripe.com/docs --focus code --dry-run

# Mode C: 소스코드 + 라이브 스캔 하이브리드
/kdyextract {프로젝트 경로}/clone-project https://original-site.com

# 이전 세션에서 중단된 지점부터 재개
/kdyextract --resume

주의사항

1. 원본 보존 - 원본 프로젝트/웹사이트는 수정하지 않음
2. 저작권 - 이미지/로고/폰트 직접 복사 금지 (URL 참조만)
3. robots.txt - Mode B에서 반드시 확인, 차단 경로 스킵
4. 라이선스 - 오픈소스 직접 복사 금지 (Phase 4-A 검출)
5. 트랜잭션 - Phase 7 실패 시 부분 기록 자동 정리
6. 동적 스캔 - 하드코딩 카테고리 목록 의존 금지
7. Rate limiting - Mode B 요청 간 1초 이상 간격

참조 문서