purplemux: Skill for Claude Code

spec-detail — 스펙 상세 작성

스펙 초안 기반으로 상세 문서(ui/flow/api)를 작성합니다. 페이지 + 문서 종류 지정 가능. 미지정 시 전체 DRAFT 페이지 일괄 처리합니다. "v1 상세 스펙", "v1 order-management ui" 요청 시 사용합니다.

Instructions

다음 단계를 순서대로 수행하세요.

1. 버전 확인

• 사용자가 버전을 지정한 경우 해당 버전 사용 (예: v1, v2)
• 미지정 시 현재 진행 중인 버전 사용

2. 요구사항 맥락 파악

• .specs/v{N}/PRD.md를 읽어 요구사항 상세 맥락 파악

3. 프로젝트 가이드 파악

• CLAUDE.md의 "참고 문서" 섹션에서 docs/ 가이드 목록 파악

4. 대상 결정

• 페이지 + 문서 종류 지정 → 해당 문서만 생성 (예: v1 order-management ui)
• 페이지만 지정 → 해당 페이지의 ui.md + flow.md + api.md 일괄 생성
• 미지정 → 전체 DRAFT 상태 페이지의 상세 문서 일괄 생성

5. spec.md 기반 상세 문서 작성

• 대상 페이지의 spec.md를 읽어 개요 파악 후 상세 문서 작성

6. 문서별 작성 기준

ui.md — 화면 구성 상세

# 화면 구성

## 1. 목록 페이지

### 레이아웃

(ASCII art 또는 구조 설명)

### 테이블 컬럼 / 카드 구성

| 컬럼명 | 필드 | 타입 | 비고 |
| ------ | ---- | ---- | ---- |
| ...    | ...  | ...  | ...  |

## 2. 상세 페이지

### 폼 필드

| 필드명 | 컴포넌트 | 필수 | 검증 규칙 |
| ------ | -------- | ---- | --------- |
| ...    | ...      | ...  | ...       |

핵심 내용: 레이아웃, 테이블 컬럼, 폼 필드, 컴포넌트 매핑

flow.md — 사용자 흐름 / 상태 전이

# 사용자 흐름

## 1. 기본 흐름

1. (단계별 흐름 기술)

## 2. 상태 전이

```mermaid
stateDiagram-v2
    [*] --> 초기상태
    초기상태 --> 다음상태: 트리거
```

## 3. 엣지 케이스

- (예외 상황 및 처리 방법)

핵심 내용: 기본 흐름(단계별), 상태 전이(mermaid), 엣지 케이스

api.md — API 연동 스펙

# API 연동

## 조회 API

### {API명}

- 엔드포인트/쿼리: ...
- 파라미터: ...
- 캐시 전략: ...

## 변경 API

### {API명}

- 엔드포인트/뮤테이션: ...
- 부수 효과: ...

## 필터/정렬 매핑

| UI 필터 | API 조건 |
| ------- | -------- |
| ...     | ...      |

핵심 내용: 조회/변경 API 정의, 파라미터, 캐시 전략, 필터 매핑

7. 일관성 유지

• 관련 프로젝트 가이드(docs/)의 패턴 준수
• 기존에 작성된 페이지와 스타일 일관성 유지

8. 품질 기준 적용

각 상세 문서에 아래 품질 기준을 반드시 반영합니다:

ui.md — 토스급 완성도

• 모든 화면에 로딩 상태(스켈레톤/스피너), 빈 상태(안내 메시지+액션), 에러 상태(재시도 옵션)를 명세
• 인터랙션 피드백(버튼 클릭, 폼 제출, 삭제 등)과 전환 애니메이션 정의
• 반응형 레이아웃·접근성(키보드 내비게이션, 포커스 관리) 고려사항 포함

flow.md — 빠른 체감 속도

• Optimistic UI 적용 대상 액션을 식별하고 낙관적 업데이트 흐름과 롤백 시나리오를 명시
• 사용자가 대기하는 구간을 최소화하는 방향으로 흐름 설계 (prefetch, 백그라운드 동기화 등)
• 실패 시 사용자 경험이 끊기지 않는 에러 복구 흐름 포함