Figma 퍼블리싱 파이프라인 12. publish vs publish-v4 비교 분석
기존 publish 파이프라인은 "처음부터 새로 만드는" 상황에 맞춰져 있었다. 그런데 실무에서 내가 마주한 대부분의 작업은 이미 구현된 페이지에 시안 변경분만 반영하는 경우였다. 그래서 publish-v4를 새로 설계했고, 이번에 두 파이프라인을 나란히 놓고 어떤 차이가 있는지, 왜 v4로 전환했는지를 한번 정리해봤다.
1. 핵심 철학 차이
두 파이프라인은 같은 "Figma → 코드" 작업을 다루지만 접근 방식 자체가 다르다. publish는 전면 재구현(Fresh Publish)이고, publish-v4는 "지금 코드와 Figma가 뭐가 다른가"를 비교한 뒤 그 차이만 패치하는(Compare & Patch) 방식이다.
| 항목 | publish | publish-v4 |
|---|---|---|
| 모드 | Fresh Publish (전면 재구현) | Compare & Patch (비교 후 수정) |
| 입력 | Figma Design IR만 | Design IR + Code IR |
| 출력 | 전체 구현 지시 | Diff HIGH/MED/LOW 항목만 |
| 용도 | 새 페이지 첫 구현 | 기존 페이지 + 시안 변경분 반영 |
여기서 IR(Intermediate Representation, 중간 표현)은 Figma 디자인이나 소스 코드를 파이프라인이 다루기 쉬운 구조화된 형태로 변환한 데이터다. Design IR은 Figma 노드 트리를, Code IR은 실제 소스 코드를 추상화한 결과물이다.
2. 파이프라인 Phase 차이
Phase 번호는 그대로 유지하면서 v4에서는 비교·진단을 담당하는 단계가 추가됐다.
publish (fresh):
0 → 1 → 2 → 3 → 4 → 4.5 → 4.7 → [fresh diff] → 6 → 6.5 → 10 → 11 → 12
publish-v4:
0 → 1 → 2 → 3 → 4 → 4.5 → 5 → 6 → 6.5 → 7 → 8 → 9 → 10 → 11 → 12- v4 추가: Phase 5 (Code IR) · Phase 7 (7-tier 매칭) · Phase 8 (Diff Engine) · Phase 9 (비교 리포트)
- v4 제거: Phase 4.7 (Figma 스크린샷)
Phase 5는 현재 구현된 코드를 IR로 파싱하는 단계이고, Phase 7은 Design IR 노드와 Code IR 노드를 7단계 기준(텍스트, 역할, 위치 등)으로 매칭한다. Phase 8의 Diff Engine이 매칭된 짝을 비교해 차이를 HIGH/MED/LOW로 등급화하고, Phase 9에서 사람이 읽는 비교 리포트를 만든다.
3. 주요 변경점 요약
구조뿐 아니라 내부 옵션값과 검증 방식도 꽤 많이 바꿨다.
| 항목 | 기존(publish) | v4 |
|---|---|---|
| Design IR snippet max_chars | 30,000 | 10,000 |
| IR snippet container noise | 미필터 | 빈 container 필터 |
| Phase 4.7 (Figma 스크린샷) | 포함 | 제거 |
| Phase 5-9 비교 분석 | 없음 / 옵션 | 필수 (v4 핵심) |
| Phase 6.5 체크리스트 | 0개 섹션 포함 | 0개 섹션 스킵 |
| Phase 6.5 검증 방식 | Claude가 수백 행 1:1 대조 | Python 자동 검증 → mismatch만 Claude 전달 |
IR snippet의 max_chars를 30K → 10K로 줄인 건 그만큼 snippet에 들어가는 정보를 추렸다는 뜻이다. 빈 container(자식이 없거나 의미 없는 레이아웃 래퍼)를 필터링하면서 같은 페이지를 더 작은 토큰으로 표현할 수 있었다.
4. v4 개선 포인트 (전환 이유)
4-1. 토큰 대폭 절감 (~40%)
실제로 측정했을 때 입력·출력 토큰이 40% 가까이 줄었다.
| publish | publish-v4 | |
|---|---|---|
| 입력 | 70~90K | 40~55K |
| 출력 | 15~20K | 12~16K |
절감 요인을 정리하면 이렇다.
- IR snippet 30K → 10K (container noise 필터링)
- Phase 4.7 제거 (불안정한 추가 API 호출 제거)
- Phase 6.5 0개 섹션 스킵
- Phase 6.5 Python 자동 검증 → Claude는 mismatch만 읽음
Phase 4.7의 Figma 스크린샷은 원래 검증용으로 붙였지만, 추가 API 호출이 불안정했고(실패 시 전체 파이프라인이 막혔다) 토큰도 크게 먹었다. v4에서는 과감하게 잘라냈다.
4-2. 노이즈 제거 (진짜 문제만 전달)
Fresh 모드는 "전체 = missing_in_code HIGH"로 간주한다. 즉 이미 맞게 구현된 부분까지도 "빠졌으니 다시 만들어라"로 취급돼서 재작성을 유도했다. 이게 회귀(regression, 원래 잘 동작하던 코드가 수정 과정에서 망가지는 현상)의 원인이 됐다.
v4는 Diff Engine이 실제로 다른 항목만 HIGH/MED/LOW로 등급화한다. 결과적으로 Claude가 받는 지시가 "이 부분만 바꿔라"로 좁혀져서 불필요한 변경이 확 줄었다.
4-3. 기계 검증 도입 (Phase 6.5 Auto-Check)
기존에는 Claude가 사람처럼 체크리스트를 쭉 읽으면서 "이 항목이 코드에 반영됐는지"를 1:1 대조했다. 수백 행이 넘어가면 실수가 섞이고, 토큰도 많이 먹고, 느렸다. v4에서는 이 단계를 phase6_5_auto_check.py 스크립트로 옮겼다.
Python이 체크리스트 항목을 파싱해서 실제 코드와 비교한 뒤, mismatch(불일치 항목)만 markdown으로 내보낸다. Claude는 그 요약만 읽으면 되니까 정확도는 올라가고 토큰은 내려간다.
4-4. 섹션 선택 버그 수정
v1에는 non-TTY 환경(Claude Code 서브프로세스처럼 터미널이 아닌 환경)에서 섹션 선택 프롬프트가 스킵되면서 전체 섹션이 자동 선택되는 버그가 있었다. 사용자가 "이 섹션만 바꿔줘"라고 해도 전체가 돌아가 버리는 셈이었다.
v4에서는 non-TTY일 때 exit code 10을 반환하도록 바꿨다. 이렇게 하면 Claude Code가 에러를 감지해서 반드시 사용자에게 어떤 섹션을 고를지 묻게 된다.
4-5. 페이지 경로 자동 추출
--page-path /my/setting/user-info 같은 옵션을 받으면 Code IR 범위를 정확한 _source/components 하위 폴더로 제한한다. 이렇게 하면 다음이 좋아진다.
- Diff 노이즈가 줄어든다(관련 없는 컴포넌트가 비교 대상에서 빠진다)
- 하드코딩된 folder_map 의존이 사라진다(예전엔 경로 → 폴더 매핑 테이블을 수동으로 관리했다)
5. 전환 이유 요약
publish(fresh)는 "처음 만드는 페이지"에는 최적이다. 하지만 내가 실제로 맡는 작업의 대부분은 기존 페이지 + 시안 변경분 반영 케이스였다. 이 케이스에 fresh 모드를 쓰면 다음 문제가 발생했다.
- 이미 올바른 부분까지 재작성 지시 → 회귀 위험
- 토큰 70~90K 소모 → 비용 부담
- Claude가 수백 행 체크리스트를 1:1로 대조 → 느리고 실수 많음
v4는 "현재 코드가 Figma와 뭐가 다른가"를 Python이 기계적으로 판정한 다음 HIGH 항목만 Claude에게 넘기는 구조다. 결과적으로 토큰·정확도·속도가 모두 개선됐다. Diff 엔진과 Auto-Check 도입이 v4 전환의 핵심이었다.
6. 결론
- 신규 페이지 첫 구현:
publish(Fresh) - 기존 페이지 시안 변경분 반영 / 정밀 diff 수정:
publish-v4(Compare & Patch) ← 실무 기본값
publish를 버린 게 아니라, 용도를 분리했다는 쪽이 정확하다. 첫 구현에는 여전히 fresh가 유리하고, 그 이후의 반복적인 유지보수는 v4가 훨씬 효율적이었다.