kdyweb - 웹 프로그램 페이지 구조 관리 (인셉션 스킬)

웹 프로젝트의 페이지 구조를 계약 기반으로 관리합니다. 모든 페이지는 생성과 동시에 네비게이션에 연결되어 "죽은 페이지"가 발생하지 않습니다.

핵심 원칙

1. 페이지 생성 = 연결 필수 — 파일만 만들고 끝내지 않음
2. 단일 진실의 원천 — docs/references/_WEB_CONTRACT.md가 모든 페이지 상태를 관리
3. 연쇄 검증 — 초기화/마이그레이션 완료 시 자동으로 연결성 검증 실행
4. 3단계 심각도 — 검증 이슈를 Critical / Important / Minor로 분류
5. 풀뿌리 검증 — 2단계 프로세스(기계적 탐색 → 필요성 검증)로 사장된 코드 제로 보장

용어 주의 — "계약"의 의미 이 문서에서 말하는 **"계약"은 docs/references/_WEB_CONTRACT.md(웹 구조 계약)**을 의미합니다. 병렬 개발(07-parallel-dev)의 **src/contracts/(코드 계약)**과는 별개의 개념입니다. 두 계약의 상세 구분은 01-dev-rules-system/07-parallel-dev/parallel-dev-coding-conventions.md Section 9를 참조하세요.

스킬 디렉토리 (5레벨)

03-skills/kdyweb/
├── SKILL.md                         ← Level 1: 진입점 (현재 파일)
├── phases/                          ← Level 2: 모드별 워크플로우
│   ├── init.md                      ← 초기화 모드 (9단계)
│   ├── page.md                      ← 페이지 추가 모드 (7단계)
│   ├── verify.md                    ← 검증 모드 (7단계, 10가지 이슈유형, 풀뿌리 검증)
│   ├── audit.md                     ← 완성도 감사 모드 (6단계)
│   ├── migrate.md                   ← 마이그레이션 모드 (6단계)
│   ├── component.md                 ← 컴포넌트 모드 (6단계)
│   └── evolve.md                    ← 계약 진화 모드 (5단계)
├── references/                      ← Level 3: 참조 데이터
│   ├── common-pages.md              ← 공통 페이지 정의 (7종 분류)
│   ├── shared-variables.md          ← 스택별 패턴 + 리다이렉트 템플릿
│   ├── connection-patterns.md       ← 연결 패턴 + 조건부 네비게이션
│   ├── page-companions.md           ← 동반 파일 패턴 (API/loading/error)
│   ├── seo-metadata.md              ← 프레임워크별 메타데이터 패턴
│   └── component-registry.md        ← 페이지 유형→컴포넌트 매핑
├── contract/                        ← Level 4: 계약 템플릿
│   ├── _WEB_CONTRACT_TEMPLATE.md    ← 계약 v2 (버전+컴포넌트 매핑)
│   └── _MIGRATION_CHECKLIST.md      ← migrate 모드용 체크리스트
└── strategies/                      ← Level 5: 전략 가이드
    └── large-project.md             ← 50+ 페이지 성능 최적화

Phase 0: 컨텍스트 탐지 및 모드 분기

스킬 발동 시 아래 순서로 컨텍스트를 파악하고 적절한 모드로 분기합니다.

Step 0-1: 프로젝트 루트 확인

# 프로젝트 루트 감지
pwd
ls -la package.json pyproject.toml next.config.* vite.config.* nuxt.config.* 2>/dev/null

Step 0-2: 계약 파일 존재 여부 확인

ls -la docs/references/_WEB_CONTRACT.md 2>/dev/null

Step 0-3: 사용자 의도 분석 (7모드)

사용자 메시지와 계약 파일 유무를 조합하여 모드를 결정합니다.

강제 모드 지정: --init, --page, --verify, --verify grassroots, --audit, --migrate, --component, --evolve, --resume

--resume: verify 모드에서 _CHECKPOINT_KDYWEB.md가 존재할 경우 중단된 라우트 그룹부터 검증을 재개합니다.

Step 0-4: 모드 분기 실행

분기 1 — 초기화 (계약 없음, 새 프로젝트)

계약 파일이 없습니다. 웹 프로젝트를 초기화합니다.

→ 스킬 내부 파일 로드: Read phases/init.md → init.md의 지시에 따라 실행

분기 2 — 마이그레이션 (계약 없음, 기존 코드 있음)

기존 프로젝트가 감지되었습니다. 코드를 분석하여 계약을 역생성합니다.

→ 스킬 내부 파일 로드: Read phases/migrate.md → migrate.md의 지시에 따라 실행

분기 3 — 페이지 추가

기존 계약을 확인하고 새 페이지를 추가합니다.

→ 스킬 내부 파일 로드: Read phases/page.md → page.md의 지시에 따라 실행

분기 4 — 검증

현재 프로젝트의 페이지 연결성을 검증합니다. (풀뿌리 요청 시 10가지 이슈유형 + 2단계 프로세스)

→ 스킬 내부 파일 로드: Read phases/verify.md → verify.md의 지시에 따라 실행

분기 5 — 완성도 감사

계약에 등록된 모든 페이지의 실제 구현 상태를 스캔하고, 미존재/미완성 페이지를 탐지합니다.

→ 스킬 내부 파일 로드: Read phases/audit.md → audit.md의 지시에 따라 실행

분기 6 — 컴포넌트

페이지 유형에 맞는 컴포넌트를 스캐폴딩합니다.

→ 스킬 내부 파일 로드: Read phases/component.md → component.md의 지시에 따라 실행

분기 7 — 계약 진화

계약을 업데이트하고 변경 사항을 추적합니다.

→ 스킬 내부 파일 로드: Read phases/evolve.md → evolve.md의 지시에 따라 실행

의도 불명확 시 — 사용자에게 질문:

## kdyweb 모드 선택

현재 프로젝트에 웹 계약이 존재합니다.

어떤 작업을 수행할까요?
1. **페이지 추가** — 새 페이지를 만들고 네비게이션에 연결
2. **연결성 검증** — 6가지 이슈유형 (전체) / 10가지 + 2단계 프로세스 (풀뿌리)
3. **완성도 감사** — 페이지 구현 상태 스캔 + 미완성/미존재 자동 구현
4. **컴포넌트 생성** — 페이지 유형에 맞는 컴포넌트 스캐폴딩
5. **계약 진화** — 계약 업데이트 + 변경 이력 관리
6. **초기화 재실행** — 계약을 초기화하고 처음부터 다시 설정

공유 규칙 (모든 Phase 공통)

계약 파일 경로

• 계약 위치: docs/references/_WEB_CONTRACT.md
• 계약 템플릿: contract/_WEB_CONTRACT_TEMPLATE.md
• 공통 변수: references/shared-variables.md
• 마이그레이션 체크리스트: contract/_MIGRATION_CHECKLIST.md

계약 통신 규칙

1. 작업 전: 반드시 docs/references/_WEB_CONTRACT.md를 읽고 현재 상태 파악
2. 작업 후: 반드시 계약 파일을 갱신 (라우트 추가/수정/삭제 반영)
3. 검증 후: 검증 결과를 계약의 연결성 검증 결과 섹션에 기록

연쇄 발동 규칙

병렬 개발 연동 (Stage 7)

병렬 개발 환경에서는 01-dev-rules-system/07-parallel-dev/parallel-dev-coding-conventions.md (Stage 7)과 연동됩니다.

계약 파일 잠금 규칙 (병렬 개발 시):

• _WEB_CONTRACT.md는 동시에 하나의 터미널만 수정 가능
• 계약 수정 시 작업 시작/완료를 docs/status/current.md에 기록
• 충돌 발생 시 최신 타임스탬프의 변경을 우선

모드 연쇄 체인

                              kdyweb
                                │
                       [Phase 0: 컨텍스트 탐지]
                                │
        ┌───────┬───────┬───┬───┴───┬───────┬───────┐
        │       │       │   │       │       │       │
      init    page   verify audit migrate component evolve
      (9)     (7)     (7)   (6)    (6)     (6)      (5)
        │       │       │     │      │       │       │
   Phase0-A  +연결   10가지  5가지  코드→   Stage7   버전
   딥스캔    계획    이슈유형 휴리    계약생성  네이밍   스냅샷
                    2단계   스틱
                    풀뿌리  스캔
        │    미니    3단계     │      │   kdypick    │
        │    verify  심각도    │      │    연동       │
        └──┬──┘    │         │      │              │
           │       │     미니verify  │              │
    자동→verify  수정제안     │       ▼              ▼
           │              kdypick  자동→verify  범위→verify
           ▼               추천
    → kdypick 추천

사용 예시

# 새 웹 프로젝트 초기화 (계약 생성 + 페이지 세트 + 검증)
/kdyweb

# 기존 프로젝트에 계약 도입
/kdyweb --migrate

# 페이지 추가
/kdyweb 대시보드 페이지 추가해줘

# 여러 페이지 한번에
/kdyweb 프로필, 설정, 알림 페이지 만들어줘

# 연결성 검증 (6가지 이슈유형)
/kdyweb 연결 검증해줘

# 풀뿌리 검증 (10가지 이슈유형 + 2단계 프로세스)
/kdyweb 풀뿌리 검증해줘
/kdyweb --verify grassroots

# 완성도 감사 (스텁/미완성 탐지 + 자동 구현)
/kdyweb 페이지 완성도 검사해줘
/kdyweb 스텁 페이지 찾아줘
/kdyweb --audit
/kdyweb 미완성 페이지 구현해줘
/kdyweb 빈 페이지 감사
/kdyweb 페이지 감사하고 자동 구현

# 컴포넌트 스캐폴딩
/kdyweb 알림 목록 컴포넌트 만들어줘

# 계약 진화
/kdyweb 계약 업데이트 — 인증 페이지 제거

# 특정 모드 강제
/kdyweb --init
/kdyweb --page 결제 페이지
/kdyweb --verify
/kdyweb --audit
/kdyweb --migrate
/kdyweb --component 대시보드 위젯
/kdyweb --evolve

Superpowers 연계

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

kdyswarm 위임 조건

다음 조건이 모두 충족될 때 /kdyswarm으로 위임을 권장한다:

• init 모드에서 10개 이상 페이지를 동시 생성
• 각 페이지가 독립적 (공유 컴포넌트 없음)

관련 스킬

기존 시스템과 연동