Fe spec

FE Spec 작성 스킬

사용자의 기능 설명을 받아 실행 가능한 프론트엔드 스펙으로 변환합니다.

When to Use

• 새로운 페이지나 컴포넌트 개발 시작 전
• 기획 내용을 구체적인 개발 태스크로 나눠야 할 때
• feature.md가 없거나 내용이 불충분할 때

Instructions

Phase 0 — 에이전트 분석 (선택적 위임)

요구사항이 복잡하거나 디자인 시안이 있는 경우, 스펙 작성 전 아래 에이전트에 위임한다:

상황	위임 에이전트
요구사항이 모호하거나 갭이 있을 때	fe-analyst — 6갭 분석 후 명확화 질문 도출
PPT/기획서·화면설계서가 있을 때	fe-deck-reader — 다중 슬라이드를 [정책·화면·흐름]으로 분해 (→ 화면은 fe-vision, 정책 갭은 fe-analyst 로 이어짐)
Figma·스크린샷·디자인 시안(개별 화면)이 있을 때	fe-vision — 레이아웃·컴포넌트·색상 정밀 추출
특정 라이브러리·API 조사가 필요할 때	fe-researcher — 공식 문서 기반 조사
RSC 경계·아키텍처·스타일링 전략(Tailwind/shadcn) 결정이 필요할 때	fe-architect — 구조 자문

PPT 입력 처리: .pptx 는 직접 읽을 수 없다. PDF 로 변환(파워포인트/Keynote 의 PDF 내보내기) 해 전달받는 것을 기본으로 한다 — 정책 텍스트와 화면 목업이 모두 보존된다. 슬라이드별 PNG 묶음도 가능하나 텍스트가 OCR 한계를 받는다. 변환된 기획서는 fe-deck-reader 가 분해한 뒤, 그 산출물을 fe-vision·fe-analyst 가 이어받는다. (OneDrive/SharePoint 의 기획서는 Microsoft 365 커넥터로 가져올 수 있으나, 슬라이드를 시각적으로 렌더해 주지 않을 수 있어 화면 분석에는 PDF 변환이 더 안전하다.)

Phase 1 — 목적 명확화

사용자에게 반드시 확인:

1. 누가 쓰는가? (사용자 페르소나)
2. 무엇을 해결하는가? (핵심 문제)
3. 완료의 기준은? (Acceptance Criteria)
4. 비정상·엣지 동작은? (로딩 / 빈 상태 / 에러·네트워크 실패 / 권한 없음 — happy 경로만 정의하지 않는다)

Phase 2 — 스펙 문서 생성

feature.md 파일을 프로젝트 루트에 생성합니다:

# [기능명]

## 목적


## 화면 흐름
> PPT/기획서 기반이면 `fe-deck-reader` 분해 결과(화면 인벤토리·흐름)를 옮긴다. 각 화면의 충실도 등급(고증 시안/와이어프레임/스케치)을 함께 적어 구현 정밀도 기준을 명확히 한다.
- 화면 목록: (화면ID — 화면명 — 충실도 등급) ※ 화면ID 있으면 라우트·네이밍 근거
- 레퍼런스 (고증 시안 한정): 화면ID → Figma 노드 URL / 시안·슬라이드 이미지 경로. fe-start Phase 4.5 시각 충실도 게이트(`fe-vision` 대조 모드)의 비교 기준이 된다. 고증 아니면 비움.
- 전환: (화면 A —[트리거]→ 화면 B, 유형: 페이지/모달/토스트)

## 컴포넌트 구조

- 신규: 
- 수정: 

## 기술 상세
- 관련 페이지/라우트: 
- API 엔드포인트: 
- 상태관리: (예: Zustand·Pinia·NgRx | TanStack Query | 로컬 state)
- 스타일링: (Tailwind 클래스 / shadcn/ui 컴포넌트 / 커스텀 CSS)
- 의존 컴포넌트: 

## 정책/규칙
> 기획서에 **명시된** 비즈니스 규칙을 옮긴다 — 규칙마다 **대상(화면ID·요소)**과 출처 슬라이드를 유지한다. `fe-deck-reader` 의 정책 표가 1차 입력. 미명시(행간) 규칙은 여기 적지 말고 `fe-analyst` 갭으로 분리한다.
- 조건부 동작: (예: 재고 0이면 담기 비활성)
- 권한 분기: (역할별 노출/동작 차이)
- 검증 규칙: (필수·형식·길이·범위)
- 상태 전이: (상태 흐름·되돌림 제약)
- 인터랙션: (저장→토스트→목록 갱신 등 액션 결과)
- 계산·로직: (금액·할인 등 산식)

## 시나리오 (정상 + 비정상)
> 비정상(non-happy)을 반드시 함께 명시한다 — 누락 시 happy-only 테스트가 만들어진다. fe-test-author가 이 목록을 그대로 테스트로 옮긴다.
- 정상: (핵심 사용자 흐름)
- 로딩: (요청 진행 중 — 스켈레톤/스피너)
- 빈 상태: (결과 0건 — 안내 문구·CTA)
- 에러: (4xx/5xx·네트워크 실패 — 에러 UI·재시도)
- 엣지: (권한 없음·경계값·긴 텍스트 등 해당 시)

## 완료 기준 (Acceptance Criteria)
- [ ] 타입 에러 0개 (프로젝트 typecheck 스크립트 통과)
- [ ] 린터(ESLint/Biome) 경고 0개
- [ ] 테스트 통과 — 정상 흐름 + **비정상 경로(로딩·빈 상태·에러)** 커버 (happy-only 금지)
- [ ] (E2E/Playwright 존재 시) 비정상 경로를 네트워크 모킹(`page.route()`)으로 검증
- [ ] 빌드 성공
- [ ] 반응형: 모바일(375px) / 태블릿(768px) / 데스크탑(1280px)
- [ ] 접근성: 키보드 네비게이션, aria-label, 본문 대비 ≥ 4.5:1
- [ ] (다크 모드 지원 시) 라이트/다크 모두 정상 렌더
- [ ] (DESIGN.md 존재 시) DESIGN.md 의 Bans(anti-slop) 위반 없음
- [ ] (고증 시안 화면 한정) 시각 충실도 — 구현 스크린샷이 레퍼런스와 대조해 임계 이상 (fe-vision 대조 모드; PPT 슬라이드는 구조 일치 기준, 색·타이포 제외)


## 금지 사항
- [ ] any 타입 사용
- [ ] 컴포넌트 라이프사이클에서 서버 데이터 직접 fetch (useEffect fetch)
- [ ] 컴포넌트에 비즈니스 로직 직접 작성
- [ ] 하드코딩 색상 (디자인 토큰 사용)
- [ ] (env 모듈 존재 시) import.meta.env 직접 접근
- [ ] 외부 링크에 rel="noopener noreferrer" 누락 (target="_blank" 단독)

Phase 3 — 다음 단계 선택 (승인 요청)

스펙 작성 후 AskUserQuestion 으로 다음 단계를 묻는다 — "1·2·3 중 고르세요" 식 자유 텍스트 번호 메뉴가 아니라, 사용자가 선택지에서 고르는 라디오(단일 선택) 형태로 노출한다. 선택 전에는 절대 구현을 시작하지 않는다.

// AskUserQuestion 호출 — 단일 선택(라디오)
{
  "questions": [{
    "header": "다음 단계",
    "question": "위 스펙으로 어떻게 진행할까요?",
    "multiSelect": false,
    "options": [
      { "label": "풀 자동",    "description": "구현 → 리뷰 → 커밋·PR까지 자동 진행 (이후 '커밋할까요?'만 추가로 물음)" },
      { "label": "구현만",     "description": "코드만 작성하고 멈춤 (리뷰·PR 없음)" },
      { "label": "스펙 수정",  "description": "고칠 부분을 반영한 뒤 다시 확인" }
    ]
  }]
}

선택 결과에 따라 분기한다:

• 풀 자동 → 이 선택이 곧 "구현 시작" 승인이다. fe-start 파이프라인으로 이어가되, 방금 승인을 받았으므로 fe-start Phase 1(구현 시작 확인) STOP 은 생략하고 Phase 2 부터 진행한다. 남는 사람 개입은 Phase 5("커밋할까요?") 한 번뿐. (fe-spec 자신은 빌드·커밋을 직접 실행하지 못하므로 후속 스킬 호출[핸드오프]은 메인 세션이 수행한다.)
• 구현만 → fe-build 만 수행하고 멈춘다 (리뷰·커밋·PR 없음).
• 스펙 수정 → 무엇을 고칠지 확인한 뒤(사용자가 "Other" 로 바로 적어줄 수도 있음) feature.md 를 수정하고 이 Phase 를 다시 묻는다.

"Other" 는 AskUserQuestion 이 항상 자동 제공한다 — 위 3개 밖의 지시를 사용자가 직접 입력하면 그 의도대로 분기한다.

Anti-patterns (하지 말 것)

• 스펙 없이 바로 컴포넌트 코드 작성
• "대충 이런 느낌"으로 넘어가기
• 완료 기준 없이 시작하기