Figma 퍼블리싱 파이프라인 02. 스킬 시스템 설계와 엣지케이스 처리

Python과 REST API로 기초는 잡아뒀는데, 실행할 때마다 절차를 손으로 챙기고 있었다. 절차 자체를 Claude Code 스킬로 코드화해서 강제하기로 했다.

매번 같은 자리에서 틀렸다

Figma 퍼블리싱은 반복적이면서 실수가 잦다. 토큰 매핑을 추측하면 grey.6과 grey.7을 반드시 틀린다. 아이콘을 수동으로 받으면 currentColor 치환을 빼먹는다. 대형 시안을 한 번에 처리하면 컨텍스트가 넘쳐서 뒤쪽 섹션을 추측으로 채운다. QA를 건너뛰면 strokeDashes 같은 세부가 누락된다.

전부 사람이 조심해서 막을 종류가 아니라, 절차에서 빠질 수 없게 만들어야 하는 것들이었다.

스킬을 세 계층으로 나눴다

돌려보니 엣지케이스가 쏟아졌다

처음 만든 스킬은 단순했다. Figma URL 받아서 스펙 저장하고 에이전트 돌리는 정도. 실제로 쓰기 시작하니 다섯 번에 걸쳐 고쳐야 했다.

첫 번째로 기본 안전장치가 없었다. 이전 세션의 Figma fileKey가 임시 파일에 남아 있으면 새 URL을 넣어도 옛날 파일을 조회했다. Figma API에서 데이터를 받아오긴 했는데 레이아웃이나 색상, 자산 목록 같은 필수 섹션이 빠져 있어도 다음 단계로 넘어갔다. 병렬 에이전트 여러 개가 같은 shared.md에 동시에 쓰다가 내용이 뒤섞이기도 했다.

fileKey는 URL에서 직접 파싱해 즉시 검증하게 하고, 스펙은 필수 섹션이 다 있는지 확인하는 단계를 넣었다. 병렬 쓰기는 에이전트마다 개별 결과 파일을 쓰게 하고 오케스트레이터가 순차 병합하는 방식으로 바꿨다.

두 번째로 URL 형태가 하나가 아니었다. figma.com/design/:fileKey/...만 있는 줄 알았는데 브랜치 URL과 Make URL이 따로 있었다.

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

패턴별로 분기해서 파싱하게 고쳤다. 같이 걸린 게 타입 체크 명령어였는데, 프로젝트마다 달라서 package.json의 scripts를 읽어 자동으로 감지하게 했다.

세 번째로 단계 사이에서 값이 사라졌다. 사용자가 넣은 --page src/app/dashboard 옵션을 PRE 단계에서 파싱했는데 PHASE 3에서 읽으려니 없었다. 중간 단계를 거치며 전달이 끊긴 것이다. 파싱한 값을 임시 파일에 저장해서 어느 단계에서든 직접 읽게 했다.

네 번째는 템플릿 치환이었다. 섹션별 스펙 파일을 순회하는데 파일이 하나도 없으면 와일드카드 패턴 *.md이 그대로 문자열로 처리됐다. 그리고 공유 문서에 넣어둔 [여기에 페이지 경로] 같은 플레이스홀더가 실제 값으로 안 바뀐 채 에이전트에게 전달됐다. 순회 전에 파일 존재를 확인하고, 플레이스홀더를 남기는 대신 실제 값을 주입한 뒤 문서를 만들게 했다.

다섯 번째는 마지막 조립이었다. PHASE 3에서 page.tsx를 만들 때 "모든 섹션 컴포넌트를 import하라"고만 지시했는데, 정작 어떤 컴포넌트가 존재하는지 목록이 없었다. PHASE 2가 끝나면 실제로 생성된 파일 목록을 수집해서 그걸 기준으로 조립하게 했다.

시안 크기에 따라 에이전트 수를 조절했다

섹션 간 import 의존성도 같이 봤다. CardGrid가 Card를 쓴다면 Card가 먼저 만들어져야 한다. 독립적인 섹션은 병렬로, 의존 관계가 있으면 순차로 돌린다.

메인 에이전트가 코드를 쓰지 않게 했다

메인 에이전트는 서브에이전트에 위임만 하고 직접 코드를 쓰지 않는다. 이렇게 하면 컨텍스트가 격리된다. 대형 페이지를 한 에이전트가 처리하면 앞부분 분석을 뒷부분에서 잊어버리는데, 섹션별로 나누면 각자 자기 스펙만 본다.

에이전트 사이의 데이터 전달은 변수가 아니라 임시 파일로 한다. 파일이라서 에이전트가 교체돼도 상태가 남는다.

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

잘못된 입력은 첫 단계에서 끊는다. fileKey가 없거나 nodeId 형식이 틀리거나 스펙이 불완전하면 PHASE 0 이전에 에러를 낸다. 뒤에서 발견하면 이미 API를 호출하고 에이전트를 돌린 뒤라 비용이 날아간다.

막힌 지점과 원인

다섯 번 고치는 동안 새로 추가한 기능은 거의 없다. 전부 이미 있던 절차가 조용히 어긋나던 자리를 막은 것이었다.