pubuilder 08. 퍼블리싱 지침을 조립하는 스킬 슬롯 구조

pubuilder의 publish 스킬은 Figma 시안을 코드로 옮기는 절차를 담은 문서다. 시안 확인부터 토큰 매핑, 구현 후 검증까지 한 파일에 순서대로 적혀 있다. 이날은 그 한 파일을 코어와 교체 가능한 슬롯으로 쪼갰다. 그리고 슬롯에 꽂힌 지침을 순서대로 합쳐 프롬프트를 만드는 조립기와, 그걸 눈으로 조작하는 장비창 UI를 붙였다.

스타일 규칙만 바꾸고 싶은데 문서 전체를 건드려야 했다

프로젝트마다 다른 건 일부다. 스타일 작성 규칙, 컴포넌트 네이밍, 접근성 기준 정도. 시안을 읽고 검증 게이트를 통과하는 절차는 어느 프로젝트에서든 그대로 쓴다. 그런데 그 둘이 한 파일에 섞여 있으니 일부만 바꾸려 해도 문서 전체를 복사해 고치는 수밖에 없었다.

문제가 하나 더 있었다. 사용자가 스킬을 만들어 목록에 올려도 그게 실제 실행에서 어디에 끼어드는지가 불분명했다. 목록과 실행 프롬프트 사이에 "장착"이라는 개념 자체가 없었다.

그래서 고정 코어와 교체 가능한 슬롯을 결합하는 구조를 짰다. 아홉 개 슬롯을 두 계층으로 나눴다. 슬롯 타입과 장착 상태를 타입으로 정의하고, 저장소와 API까지 같은 모델을 관통하게 했다. 존재하지 않는 슬롯이나 없는 스킬을 꽂으려는 입력은 검증에서 막았다.

head와 tail 사이에 슬롯을 끼우는 형태로 조립했다

publish 스킬 한 덩어리를 세 조각으로 나눴다. 앞단 절차는 _core/head.md, 뒷단 검증과 마무리는 _core/tail.md, 그 사이에 들어갈 기본 슬롯 지침들. 코어 두 파일은 사용자가 못 바꾸고, 가운데만 갈아 끼운다.

조립기는 슬롯 순서대로 지침을 이어 붙여 하나의 문서를 만들고, 그 결과를 실행 프롬프트에 연결한다.

코어 파일을 쪼개니 기준 파일이 사라졌다. 서버는 소스를 그대로 실행하는 dev와 번들을 실행하는 dist 양쪽에서 내장 스킬 경로를 찾는데, 그 탐색이 예전 단일 파일을 기준으로 잡고 있었다. 기준을 실제 코어 파일로 바꾸고 두 환경 모두 테스트했다.

장비창은 여러 번 갈아엎고서야 자리를 잡았다

기존 화면은 발견된 스킬을 나열하는 목록이었다. 그걸 슬롯 중심의 SkillSlots 화면으로 교체하고 장착·초기화 API를 연결했다. FAB(Floating Action Button, 화면 위에 떠 있는 기본 동작 버튼)을 최상위 진입점으로 정리했고, 플레이그라운드 쪽에서 어긋나 있던 alias와 세션 자동 탐색도 같이 바로잡았다.

배치 방법은 세 가지를 다 열었다. 클릭, 더블클릭, 드래그. 꽂힌 슬롯은 X 버튼으로 비운다.

구조는 한 번에 안 나왔다. 중앙 다이얼로그로 띄워보고, 심플 레이아웃으로 가보고, 격자로 늘어놨다가, 작업 순서를 따라가는 워크플로우형 배치까지 빠르게 만들어봤다. 공통으로 걸린 건 정보 위계였다. 슬롯과 슬롯 상세와 스킬 목록을 한 화면에서 동시에 강조하니 어디를 봐야 할지가 흐려졌다.

INVENTORY를 중앙에 두고 스킬함을 우측 드로어로 빼는 어두운 오버레이 구조로 수렴했다. 슬롯을 보는 화면과 스킬을 고르는 화면의 역할을 나눈 것이다. 그 위에 배경 스크롤 잠금, z-index, active 상태, 슬롯 상세, 적용 버튼과 상세 문구를 붙였다. 시안을 여러 개 버렸지만 각 시안에서 얻은 판단이 다음 구조에 남아서 반복이 헛돌지는 않았다.

슬롯 이름이 내가 쓰던 구현 용어 그대로였다

화면이 자리를 잡고 나니 슬롯 이름과 설명이 눈에 걸렸다. 내부 개념을 그대로 UI 문구로 내보낸 상태였다.

PIPELINE 슬롯은 사실 교체할 대상이 아니었다. 성격상 고정 코어에 가까워서 GUIDE로 바꿨다. PRESETS는 쓰임이 겹쳐 없앴고, 스타일 관련 지침은 STYLING이라는 독립 슬롯으로 떼냈다.

각 슬롯에는 어떤 문서를 기대하는지 작성 가이드를 붙이고, 지금 무엇이 적용돼 있는지도 같이 보이게 했다. 설명은 기술 용어와 불필요한 접두사를 걷어내고 "이 슬롯의 MD에 무엇을 적으면 되는지"와 "적으면 무엇이 달라지는지" 중심으로 다시 썼다. 사용자가 슬롯에 좋은 입력을 넣으려면 장착 결과만 보여줘서는 부족했다.

막힌 지점과 원인

데이터 모델부터 조립기와 API, 장비창까지 한 줄로 이어붙였다. 커스터마이징을 파일 고르는 기능으로 봤다면 슬롯 모델까지 갈 일이 없었을 텐데, 안정적인 코어와 확장 지점을 어디에 열지의 문제로 보니 구조가 달라졌다.

지금은 슬롯을 꽂아도 조립된 지침이 어떻게 생겼는지 실행 전에 볼 수 없다. 장착 전 스킬 내용과 조립 결과를 미리 보여주는 화면이 필요하다. 로컬에 있는 사용자 스킬을 장비창으로 가져오는 흐름도 아직 없어서 발견된 스킬만 꽂힌다. 드래그 말고 키보드 같은 다른 방법으로도 슬롯을 채울 수 있는지 확인이 남았고, 슬롯 조합이 바뀌었을 때 프롬프트 품질이 유지되는지 볼 회귀 테스트도 더 필요하다.