---

name: figma-spec-sync description: > Figma 기획 파일을 기계 추출 스냅샷(md + 선택 PNG)으로 받아 이전 판본과의 구조 delta(섹션·화면·기획 설명)를 뽑고, 그 변경을 구현 실물과 대조해 기존 정합 plan(대조표)의 작업 항목으로 라우팅하는 워크플로 skill. Figma REST API를 직접 부르므로 MCP 없이 반복 pull이 되고, 파일 version 게이트로 "plan이 아직 반영하지 않은 pull"을 판정한다. "figma 동기화", "figma 스냅샷 받아", "figma 뭐 바뀌었나", "figma diff", "기획 변경 확인", "figma 변경으로 계획 세워줘", "figma 정합 plan", "디자인 대조표 만들어", "figma sync", "figma spec snapshot", "figma delta", "what changed in figma", "align implementation with figma", "figma-spec-sync" 등에서 트리거. 디자인→코드 생성이나 Figma 파일 편집은 다루지 않는다.

figma-spec-sync

Figma 기획 변경 → 작업 계획. 목적은 diff를 보여주는 게 아니라 변경을 행선지가 있는 작업 항목으로 바꾸는 것이다.

기본은 읽기 전용이다. plan에 쓰는 것은 사용자가 항목을 승인한 뒤이고, 유일한 예외는 §Sync 상태 표 갱신이다(판단이 아니라 기록).

전제

• Node 18+, git, Figma 토큰. 토큰은 env FIGMA_TOKEN 또는 ~/.config/figma/token(scope file_content:read) — 발급은 references/config.md.
• 대상 repo의 설정 파일 figma-spec-sync.json — 스키마는 references/config.md. 첫 사용이면 §1에서 만든다.
• 정합 plan(대조표) — 없으면 references/alignment-plan-template.md로 만든다. §Sync 상태 표의 Figma file version 행이 게이트의 기준이다.
• SKILL_DIR은 이 SKILL.md가 있는 디렉토리다 — 스킬을 로드한 절대 경로에서 SKILL_DIR="$(dirname <SKILL.md 절대 경로>)"로 잡는다. 셸 상태는 호출 간에 유지되지 않으므로 명령마다 인라인으로 앞에 붙이거나 스크립트 절대 경로를 직접 쓴다.

실행 순서

1. Setup

설정 탐색 순서는 --config → ./figma-spec-sync.json → ./docs/figma-spec-sync.json. 없으면 사용자에게 Figma URL(file key·node-id)과 스냅샷 md·plan 경로를 물어 설정을 만들고, plan이 없으면 템플릿으로 뼈대를 만든다. 토큰이 없으면 스크립트가 발급 절차를 출력하고 멈춘다.

설정이 있으면 두 가지만 본다: plan이 가리키는 파일이 실재하는가, 그리고 git status --short <out> <plan>. out이 dirty면 이전 pull이 아직 triage되지 않은 채 working tree에 있는 것이고, plan이 dirty면 triage가 진행 중이다 — §3 게이트(base 판본 plan vs working tree md)를 읽을 때 이 상태를 알아야 한다.

2. Pull

node "${SKILL_DIR}/scripts/figma-sync.mjs" --config figma-spec-sync.json

version 게이트라 무변경이면 API 왕복 한 번(수 초)으로 끝난다. 기준은 이미지 캐시 state가 있으면 그것, 없으면 기존 md 서두의 version 줄 — clone만 한 머신에서도 같은 판정이다. 둘 다 없으면(첫 실행·구 포맷 md) 항상 받는다. 스냅샷 md는 손으로 고치지 않는다.

"변경 없음"은 Figma↔md 판정이고 plan 반영 여부는 §3 게이트가 판정한다 — 항상 §3까지 돈다. md가 최신인데 plan이 뒤처진 상태("변경 없음" + 게이트 미반영 + delta 큼)가 이 skill이 제일 자주 만나는 시작점이다.

3. 구조 delta

raw git diff는 섹션 개명을 거대한 삭제+추가로 보여 읽을 수 없다. 헬퍼가 섹션·화면·기획 설명 단위로 접는다.

node "${SKILL_DIR}/scripts/snapshot-delta.mjs" --config figma-spec-sync.json

기본은 --base <deltaBase> --head :worktree. 출력 서두의 두 블록을 먼저 읽는다:

• [게이트] — plan(base 판본) §Sync 상태의 version과 md(head)의 version을 대조한다. 다르면 plan이 아직 반영하지 않은 pull이 있고, 이 skill의 나머지 단계가 그 작업이다. 같으면 아래 delta가 비어 있어야 정상이고, 비어 있지 않으면 §6의 표 갱신을 빠뜨린 것이다.
• [검증] — md 서두의 "추출 결과: 섹션 N개, 기획 설명 M건"과 파싱 결과를 대조한다. ⚠가 뜨면 렌더 포맷이 바뀌어 파서가 낡은 것이다. delta를 믿지 말고 snapshot-delta.mjs의 parse를 먼저 고친다.

읽는 법:

• ~ A → B (화면 겹침 N%) — 개명·재편. 100%면 이름만 바뀐 것이라 작업 항목이 아니다. 단 ✅ 류 접두사가 붙은 개명은 디자이너의 확정 신호라 버리지 않고 Gotchas대로 사용자 확인 대상에 올린다.
• - 사라짐 + + 신규가 같이 뜨면 개명이 아니라 실제 재편이다. 헬퍼는 화면 이름 겹침 30% 미만을 짝지어주지 않으므로 화면 단위로 사람이 이어붙이지 말고 신규 섹션으로 읽는다. 중첩 섹션(depth 2)이 depth 1로 승격되면 이렇게 보이고, 실제로도 재편이 맞다. 이건 화면 lineage 얘기이고 도메인 소속은 §6에서 따로 판정한다 — 사라진 섹션과 같은 도메인의 plan이 있으면 신규 섹션은 그 plan으로 간다.
• + 신규: X (화면 N, 설명 M) 아래에 화면 이름이 나열되고, 신규 섹션의 기획 설명은 [기획 설명]에 전문이 출력된다. 여기가 작업 항목의 원재료다.
• + 신규: X (화면 0, 설명 0) — 빈 섹션은 기획이 없는 게 아니라 추출 한계(작은 프레임·짧은 메모·낱개 목업)로 비어 보이는 것이다. §Figma 직접 보기로 실물을 확인하고 §6의 "담지 않는 축"으로 라우팅한다.

이미 publish된 구간을 다시 보려면 --base <이전 commit> --head <rev>. 옵션은 --help.

4. 기존 결정과 충돌하는지 확인하고 최신 원본으로 재판정

최신 Figma가 기준이다. 기획은 계속 바뀌므로 이전 결정이 있어도 원본이 바뀌면 최신본으로 다시 판단한다. 이 단계의 목적은 결정을 지키는 게 아니라 무엇이 되돌아가는지 드러내는 것이다 — 신규 내용을 spec으로 취급하기 전에 그 영역에 이미 내려진 판단이 있는지 plan의 결정 로그·확인 필요·해당 화면 절에서 찾고, 충돌하면 사용자에게 유효성을 되묻지 않고 재판정한 뒤 되돌린 결정을 결정 로그와 보고에 명시한다. 재판정은 자동 채택이 아니다 — Figma가 준 것과 사용자가 직접 말한 것을 구분해 적는다.

5. 구현 실물과 대조

기획 설명은 가설이고 현재 동작은 source가 권위다. 각 delta마다 실제로 뭐가 있는지 확인하고 file:line으로 근거를 남긴다. 근거 출처는 스킬이 아니라 대상 repo에서 도출한다 — AGENTS.md·README·디렉토리 구조에서 라우트 정의, 기능 게이팅(feature flag·registry), DB schema, API 계약(OpenAPI·controller)의 위치를 찾아 표로 정리하고 그 표를 이번 세션의 기준으로 쓴다.

6. 라우팅 — 새 plan을 만들지 않는다

행선지가 이미 있다. 없을 때만 새로 만든다.

| delta 성격 | 행선지 | |---|---| | 매 pull의 규모·version | plan §Sync 상태 표 + "pull에서 반영된 변화" 문단. delta가 비어도 갱신한다 — 이 표의 version이 §3 게이트의 기준이라 빠뜨리면 다음에 이미 본 delta가 다시 미반영으로 판정된다 | | 기존 화면 절의 기획 변경 | plan의 해당 화면 절 | | 소유 plan이 있는 신규 도메인의 기획 도착 | 그 도메인 plan. 대기 그룹에서 진행 그룹으로 올릴지는 사용자 판단 | | 소유 plan이 없는 신규 영역 | plan에 새 절 + 대상 repo의 roadmap 문서(있으면) | | 기획 내부 불일치·해석 불가 | plan §확인 필요 | | 추출 한계로 안 보이는 것 | plan §Sync 상태의 "담지 않는 축" 목록 |

새 plan이 필요하면 대상 repo의 plan 규약(위치·untracked 인큐베이션 여부)을 따른다.

7. 출력

작업 항목은 제안으로 내고 승인 전에 plan에 쓰지 않는다. 항목마다: 무엇이 바뀌었나(Figma 근거) · 현재 구현은 어떤가(file:line) · 무엇을 해야 하나 · 행선지. §Sync 상태 표만 바로 갱신한다.

스냅샷 md와 plan 갱신은 같은 브랜치·같은 PR에 묶는다. 갈라놓으면 main이 md는 받고 plan version은 옛것인 상태가 생겨, 게이트는 "미반영"이라 하고 delta는 "변화 없음"이라 하는 모순이 난다. commit·PR·merge 절차는 대상 repo 규약을 따른다.

Figma 직접 보기

스냅샷이 답하지 못하는 지점(빈 신규 섹션·짧은 메모·낱개 목업·작은 프레임)에서 "Figma를 연다"는 에이전트에게는 Figma MCP(mcp.figma.com) 호출이다. 스냅샷 md의 모든 화면·섹션·기획 설명 링크에 node-id가 있으므로 그 id로 바로 본다. 대량·반복 조회는 여기가 아니라 REST 스냅샷이다 — MCP는 특정 node 하나를 들여다보는 저빈도 조회에만 쓴다.

• get_screenshot — 노드 하나를 PNG로. 1000×600 미만 프레임(템플릿·컴포넌트 크기)과 낱개 목업의 실물 확인.
• use_figma 읽기 전용 스크립트 — 특정 섹션 아래를 findAll로 훑어 60자 미만 TEXT·프레임 밖 노드를 즉석 조회. 호출 전에 figma-use 스킬을 먼저 로드한다(호출마다 페이지 컨텍스트가 리셋되고, 쓰기 규칙이 같은 도구에 걸려 있다).

진입 조건: 첫 호출 전 whoami로 seat를 본다 — Starter 플랜과 유료 플랜의 View/Collab seat는 월 6콜이라 triage 도구로 못 쓴다. MCP가 없거나 제한이면 사용자에게 node-id 링크를 주고 브라우저 확인을 요청한다. 코멘트는 MCP에 도구가 없어 이 경로로도 못 본다.

Gotchas

• version은 내용이 아니다. Figma version은 본문이 한 글자도 안 바뀌어도 올라간다(실측: version 상이, md 본문 바이트 동일). 게이트 "미반영" + delta "변화 없음"은 정상이고 할 일은 §Sync 상태 version 갱신 하나다. 이걸 "delta 헬퍼가 놓쳤다"로 진단하지 않는다.
• 확정 디자인이 아니다. 화면마다 다른 버전이 섞여 있고 메뉴 구성은 계속 바뀐다. 정합 대상은 기획 의미이지 그런 표면이 아니다. ✅ 같은 접두사는 디자이너의 확정 표시로 읽되 근거로 삼기 전에 사용자에게 확인한다.
• 화면 수가 세 종류다. md 표는 이름 있는 프레임을 세되 Body·App처럼 이름만 있는 컨테이너도 섞여 있다. PNG와 pull 로그의 "화면 N개"는 크기 기준(FRAME 1000×600 이상)이라 이름 없는 안쪽 컨테이너까지 잡는다. 세 숫자를 같은 것으로 보고 "누락"을 진단하지 않는다.
• 스냅샷이 구조적으로 담지 않는 축 — 여기 없다고 기획에 없는 것이 아니다. 판단이 걸리면 §Figma 직접 보기. (1) 코멘트: 미결 논의가 코멘트에만 있는데 스크립트는 노드 트리만 받고 MCP에도 코멘트 도구가 없다 — REST /comments 수집을 스크립트에 추가하는 것이 유일한 경로다. (2) 60자 미만 메모: SPEC_MIN_LENGTH가 짧은 전이 지시·조각 메모를 떨어뜨린다. (3) 캔버스 낱개 목업: 프레임으로 묶이지 않은 노드는 표에도 PNG에도 없다. (4) 1000×600 미만 프레임: 템플릿·컴포넌트 크기는 렌더 대상이 아니다. (5) 중첩 섹션 라벨: depth 2 SECTION은 이름이 사라지고 화면만 평평하게 나열된다.
• 같은 images(=state)를 가리키는 실행은 한 곳에서만. 다른 checkout에서 같은 images로 돌리면 state만 앞서 나가고 원래 checkout의 md는 낡은 채 "변경 없음"으로 끝나 영구히 안 고쳐진다. 정기 실행(cron·launchd)을 두면 그 래퍼가 유일한 images 소유자다.
• 스냅샷을 승인 전에 commit하는 lane이면 deltaBase를 publish 지점(main 등)으로 준다. commit은 "확인했다"의 표시가 아니고, plan이 기록한 version만 triage 완료의 마커다.
• 파서는 렌더 포맷에 결합돼 있다. 두 스크립트는 한 디렉토리에서 같이 움직인다. [검증] ⚠가 뜨면 delta보다 파서를 먼저 본다.

관련

• 문서 repo ↔ 구현 repo 동기화의 evidence 규칙·쓰기 방향은 repo-prd-sync skill. 이 skill은 소스가 문서가 아니라 디자인 툴 API인 경우를 다룬다.
• 화면 PNG는 images 디렉토리의 index.html을 브라우저로 열어 훑는다. repo 밖이고 git 추적 대상이 아니다.