Figma → 코드 자동화 스킬 개발기: 엣지케이스와의 전쟁

사용자 입력: Figma URL + 옵션(페이지 경로, 컴포넌트 이름)
                    │
                    ▼
 ┌─ PRE ──────────────────────────────┐
 │  URL에서 fileKey, nodeId 파싱      │
 │  형식 검증 (잘못된 입력 즉시 차단) │
 └────────────────────────────────────┘
                    │
                    ▼
 ┌─ PHASE 0 ─────────────────────────────┐
 │  Figma REST API로 디자인 스펙 수집    │
 │  레이아웃, 색상, 자산, 컴포넌트 트리  │
 └───────────────────────────────────────┘
                    │
                    ▼
 ┌─ PHASE 1 ──────────────────────┐
 │  아이콘 SVG 추출 + 최적화     │
 │  이미지 다운로드 + 경로 생성  │
 └────────────────────────────────┘
                    │
                    ▼
 ┌─ PHASE 1.5 ────────────────────────────────┐
 │  디자인을 섹션으로 분할                    │
 │  섹션 간 의존성 분석 → 병렬/순차 결정     │
 └────────────────────────────────────────────┘
                    │
          ┌────────┼────────┐
          ▼        ▼        ▼
 ┌──────────┐┌──────────┐┌──────────┐
 │ Agent 1  ││ Agent 2  ││ Agent 3  │  ← PHASE 2: 섹션별 병렬 구현
 │ Header   ││ Hero     ││ Footer   │
 └──────────┘└──────────┘└──────────┘
          │        │        │
          └────────┼────────┘
                   ▼
 ┌─ PHASE 3 ──────────────────────────┐
 │  섹션 결과물 병합                  │
 │  page.tsx 조립 + 타입 체크        │
 └────────────────────────────────────┘
                   │
                   ▼
 ┌─ POST ─────────────────┐
 │  임시 파일 정리        │
 └────────────────────────┘

// 오케스트레이터 = 컨테이너 컴포넌트
function Orchestrator({ figmaUrl, pagePath }) {
  // 직접 UI를 그리지 않고, 하위 컴포넌트에 위임
  const spec = useFigmaSpec(figmaUrl)       // PHASE 0
  const assets = useAssetExtract(spec)       // PHASE 1
  const sections = useSectionSplit(spec)     // PHASE 1.5
 
  return sections.map(section =>
    <SectionAgent key={section.id} spec={section} />  // PHASE 2
  )
}

// 독립적인 섹션 → 병렬 실행
const [header, hero, footer] = await Promise.all([
  buildSection('Header', headerSpec),
  buildSection('HeroSection', heroSpec),
  buildSection('Footer', footerSpec),
])
 
// 의존 관계 있는 섹션 → 순차 실행
const card = await buildSection('Card', cardSpec)
const cardGrid = await buildSection('CardGrid', cardGridSpec) // Card에 의존

// 1) fileKey 검증 — URL에서 직접 파싱하고 즉시 검증
function parseAndValidate(url: string) {
  const fileKey = extractFileKey(url)
  if (!fileKey) throw new Error('fileKey 파싱 실패')
 
  const nodeId = extractNodeId(url)
  if (!/^\d+:\d+$/.test(nodeId)) throw new Error(`nodeId 형식 오류: ${nodeId}`)
 
  return { fileKey, nodeId }
}
 
// 2) 스펙 완전성 검증 — 필수 섹션이 모두 있는지 체크
const requiredSections = ['레이아웃 스펙', '색상 스펙', '자산 목록', '컴포넌트 트리']
const missing = requiredSections.filter(s => !specContent.includes(s))
if (missing.length > 0) throw new Error(`스펙 누락: ${missing.join(', ')}`)

// 변경 전 (위험): 모든 에이전트가 같은 파일에 동시 쓰기
Agent 1 ──write──▶ shared.md ◀──write── Agent 2   ← 내용 충돌!
 
// 변경 후 (안전): 각자 독립 파일 → 오케스트레이터가 순차 병합
Agent 1 ──write──▶ result-1.md
Agent 2 ──write──▶ result-2.md
Agent 3 ──write──▶ result-3.md
                         │
Orchestrator ◀───── 검증 후 병합 (빈 파일이나 내용 부실하면 에러)

일반:   figma.com/design/abc123/MyPage?node-id=10-20
                         ^^^^^^ fileKey
 
브랜치: figma.com/design/abc123/branch/xyz789/MyPage
                                      ^^^^^^ 이게 진짜 fileKey
 
Make:   figma.com/make/def456/MyPrototype
                       ^^^^^^ fileKey

function extractFileKey(url: string): string {
  if (url.includes('/make/')) {
    return url.match(/figma\.com\/make\/([^/?]+)/)?.[1]
  }
  if (url.includes('/branch/')) {
    // branch URL에서는 branchKey가 실제 fileKey
    return url.match(/\/branch\/([^/?]+)/)?.[1]
  }
  // 기본 design URL
  return url.match(/figma\.com\/design\/([^/?]+)/)?.[1]
}

PRE (파싱) ──── pageePath = "src/app/dashboard"
    │
PHASE 0~2 ──── (여러 단계를 거치면서...)
    │
PHASE 3 ──── pagePath = ???  ← 어디로 갔지?

// Context처럼 동작하는 임시 파일
PRE에서 저장 → /tmp/.current-page = "src/app/dashboard"
PHASE 3에서 읽기 → const pagePath = readFile('/tmp/.current-page')
POST에서 삭제 → cleanup()  // 다음 실행에 영향 안 주도록

// page.tsx를 조립해야 하는데...
import { Header } from './components/Header'
import { HeroSection } from './components/HeroSection'
import { CardGrid } from './components/CardGrid'  // 이 컴포넌트가 진짜 있나?
// Footer는 빠뜨림 — 있는지 몰랐으니까

// 구현된 컴포넌트 목록을 수집
const implementedFiles = [
  'src/components/dashboard/Header.tsx',
  'src/components/dashboard/HeroSection.tsx',
  'src/components/dashboard/CardGrid.tsx',
  'src/components/dashboard/Footer.tsx',
]
 
// 이 목록을 기준으로 page.tsx 조립
// → import 누락이나 존재하지 않는 컴포넌트 참조 방지

입력: Figma URL + --page src/app/dashboard --name DashboardPage

/tmp/.current-filekey         ← Figma 파일 식별자
/tmp/.current-page            ← 출력 경로
/tmp/figma-spec-cache.md      ← 전체 디자인 스펙
/tmp/figma-result-section-N.md ← 각 에이전트의 구현 결과