/figma:analyze — 피그마 디자인을 코드로 옮겨주는 분석가#

디자이너가 그린 피그마 화면을 읽어서, 무엇을 만들어야 하는지 정리하고 실제 기능 개발로 이어주는 전문 에이전트입니다.

한마디로#

디자이너가 그린 피그마 화면을 보고 "이걸 앱으로 만들려면 무엇이 필요한지"를 대신 정리해 주는 분석가입니다. 설계 도면을 보고 필요한 자재와 작업 목록을 뽑아주는 현장 반장과 비슷해요.

누가·언제 쓰나요#

• 피그마 디자인은 나왔는데, 이걸 실제 화면(앱)으로 옮기는 작업을 시작하려는 경우
• 디자인을 보고 "어떤 데이터가 필요하고, 어떤 화면 요소가 있는지" 요구사항을 정리하고 싶을 때

👉 사용하려면 피그마와 연결된 도구(figma MCP)가 켜져 있어야 합니다.

무엇을 해주나요#

분석이 끝나면 .claude/docs/{기능이름}/ 폴더 아래에 다음 결과물이 만들어집니다.

• figma_analysis.md — 피그마 화면을 분석한 결과
• requirements.md — "무엇을 만들어야 하는지" 정리한 요구사항 문서
• screenshots/ — 분석에 사용한 화면 캡처 이미지

여기에 더해, 분석 결과를 바탕으로 실제 기능 개발(/feature:create)과 ZenHub 작업 이슈(Epic/Story) 생성까지 이어줄 수 있습니다.

어떻게 쓰나요#

# 피그마에서 직접 선택한 화면을 분석 (기본)
/figma:analyze --use-selection

# 특정 노드(화면 요소) ID를 지정해서 분석
/figma:analyze --node-ids  " 1:23,4:56 " 

 # 이름으로 화면 요소를 검색해서 분석
/figma:analyze --search-query  " 로그인 카드 " 

 # 분석 후 곧바로 기능 개발까지 자동으로 이어가기
/figma:analyze --use-selection --auto-create

• --page-name: 특정 피그마 페이지를 지정하고 싶을 때 덧붙입니다.
• 기능 이름은 직접 적어줄 수도 있고, 비워두면 자동으로 추론합니다.

안에서 무슨 일이 벌어지나요#

크게 다섯 단계를 차례로 진행합니다.

1. 화면 가져오기 — 피그마에서 선택한 화면과 요소를 읽고, 스크린샷을 찍습니다.
2. 화면 뜯어보기 — 어떤 구성 요소(카드, 입력칸 등)가 있는지 식별하고, 글자·색상·간격 같은 디자인 정보를 추출합니다.
3. 요구사항 정리 — 디자인을 보고 필요한 데이터 항목과 화면 위젯, 그리고 동작(추가·조회·수정·삭제)을 정의합니다.
4. 기능 생성 — 요구사항 문서를 만들고, 실제 기능 개발(/feature:create)을 호출합니다.
5. 작업 이슈 생성 — ZenHub에 Epic/Story를 만들고 피그마 링크를 첨부합니다.

Phase 1: 피그마 노드 수집
  - get_selection / get_node_info
  - export_node_as_image (스크린샷)
    ↓
Phase 2: UI 분석
  - 컴포넌트 식별 (FRAME/TEXT/COMPONENT)
  - CoUI 매핑 (get_by_coui)
  - 텍스트 노드 스캔 (scan_text_nodes)
  - Design tokens 추출 (extract_design_tokens)
    ↓
Phase 3: 요구사항 정의
  - Figma → Entity 필드 매핑
  - UI → Flutter 위젯 변환
  - CRUD 메서드 식별
    ↓
Phase 4: Feature 생성
  - Requirements document 생성
  - /feature:create 호출
    ↓
Phase 5: ZenHub Story 생성
  - Epic/Story 생성
  - Figma 링크 첨부

.claude/docs/{feature_name}/
├── figma_analysis.md       # Figma analysis result
├── requirements.md         # Requirements document
└── screenshots/            # Captured screenshots