pubuilder 05. 기본 publish 스킬과 Figma Design IR 토큰 최적화

이미 서버 코어와 UI로 이어진 퍼블리싱 파이프라인은 있었다. 이날은 거기에 방법론과 효율성을 채웠다. 사설 도구에 묶여 있던 퍼블리싱 흐름을 범용 스킬로 빼내고, Figma 원본 JSON이 프롬프트를 통째로 잡아먹던 문제를 서버 전처리로 줄이고, 그 기본 스킬을 설치 직후부터 보이도록 패키지에 심어 v0.8.0을 냈다.

사설 도구에 묶여 있던 퍼블리싱 흐름을 범용 스킬로 뺐다

/publish, /publish-v1에서 이미 검증한 흐름이 있었지만, 특정 프로젝트와 사설 도구 이름에 붙어 있어 다른 저장소로 옮기기 어려웠다. 이 흐름을 프로젝트·도구 의존성을 걷어낸 publish 스킬로 정리했다.

옮기면서 살린 건 절차 자체였다. 시안 육안 검증, raw 값 분석, 프로젝트 디자인 토큰 매핑, 구현 후 검증 게이트, 정보가 부족하면 추측하지 말고 질문을 먼저 하는 규칙까지 그대로 뒀다. 대신 React나 Next 같은 특정 프레임워크를 강제하지 않고, 대상 저장소의 구조와 규약을 먼저 따르도록 바꿨다. 사설 자동화를 범용 스킬로 옮겨보니 재사용의 핵심은 도구 이름이 아니라 판단 원칙과 완료 조건이었다.

Figma 원본 JSON이 프롬프트를 통째로 잡아먹었다

Figma nodeJson을 그대로 프롬프트에 넣으니 렌더링용 메타데이터와 숨김 노드까지 딸려 들어가 토큰을 과하게 소모했다. blendMode나 absoluteRenderBounds(Figma 노드가 들고 있는 필드로, 합성 모드와 렌더 후 실제 화면 경계를 나타내는 렌더링용 메타다) 같은 값은 레이아웃이나 스타일을 구현할 때는 판단에 쓰이지 않는 노이즈였다.

그래서 서버가 nodeJson에서 레이아웃·타이포그래피·색상·간격처럼 구현 판단에 필요한 필드만 뽑아 컴팩트한 Design IR(Intermediate Representation, 원본과 모델 사이에 두는 중간 표현)로 축약하게 했다. 숨김 노드와 노이즈 필드를 걷어내고, 색상 빈도표를 함께 만들어 어떤 색이 얼마나 쓰였는지 한눈에 넘겼다.

이때 책임 경계를 다시 그었다. 결정론적으로 정리할 수 있는 전처리는 TypeScript 서버가 맡고, 토큰 매핑이나 코드 작성처럼 추론이 필요한 부분만 LLM이 하도록 프롬프트를 바꿨다. 모델이 매번 같은 정리 작업을 반복하면 비용도 늘고 결과도 그때그때 흔들린다. 코드로 확실히 줄일 수 있는 정보를 먼저 정규화하니 비용과 결과 변동성이 같이 줄었다.

Design IR은 단순히 JSON을 압축한 포맷이 아니다. 서버가 관찰을 정리하고 모델이 판단한다는 책임 경계 그 자체다. 전처리를 단위 테스트로 고정해두니, 같은 입력이면 같은 IR이 나오는 지점이 코드로 보장됐다.

기본 스킬은 문서 파일 하나로 끝나지 않았다

publish 스킬을 설치 직후부터 쓰려면 패키지에 기본 내장(builtin)으로 심어야 했다. 처음엔 문서 파일 하나 넣으면 될 줄 알았는데 아니었다. 레지스트리 소스, 삭제 정책, UI 그룹, 패키징, 런타임 경로까지 제품 흐름 전체가 걸렸다.

패키지 내부 skills 디렉터리를 레지스트리의 builtin 소스로 추가했다. builtin 스킬은 기본으로 켜두고 삭제는 막되, 토글은 가능하게 뒀다. 내장 기능도 끄고 켤 수 있게 두면 기본 경험을 주면서도 사용자 제어권을 남길 수 있다. UI에는 별도 "기본" 그룹으로 묶어 사용자 커스텀 스킬과 구분했다.

경로에서 한 번 걸렸다. 소스를 그대로 실행하는 dev 레이아웃과 번들을 실행하는 dist 레이아웃은 디렉터리 구조가 달라서, 기본 스킬 경로가 두 환경에서 어긋났다. serve 단계에서 두 레이아웃을 모두 고려해 skills 경로를 해석하게 했다.

설치 후 기본 스킬이 통째로 빠지는 문제도 있었다. npm 패키지의 files 필드(tarball, 즉 npm이 배포할 때 만드는 압축 패키지에 어떤 파일을 넣을지 정하는 목록)에 skills가 없으면 설치 시점에 스킬 파일이 딸려오지 않는다. 포함 목록에 스킬을 추가하고, 빌드된 서버에서 builtin:publish가 기본으로 노출되는지 E2E(엔드투엔드, 빌드 결과물을 실제 실행 경로로 검증)로 확인한 뒤 v0.8.0을 냈다.

막힌 지점과 원인

기능을 붙이는 동안 네 곳에서 막혔고, 원인과 해결을 정리하면 아래와 같다.

아직 확인 못 한 것들

• 실제 디자인 노드별 raw JSON 대비 Design IR 토큰 절감률 측정
• 여러 프레임워크 프로젝트에서 builtin publish 결과 검증
• Design IR이 놓치는 Figma 속성을 사례 기반으로 보강
• 스킬 버전 관리와 사용자 커스텀 스킬 우선순위 정책 검토

v0.8.0은 새 화면을 붙인 릴리스가 아니라 기본 품질과 운영 비용을 손본 릴리스다. 이제 설치 직후에도 검증된 절차로 실행되고, Figma 데이터 크기에도 덜 흔들린다. 서버 연결에서 시작한 것이 방법론과 효율성까지 채워지면서 파이프라인이 제품으로 자리 잡는 단계에 들어섰다.