들어가며
기획자가 기획은 잘 하는데, 화면 정의서를 안만들어줬다. 답답하면 니들이 뛰던가와 같은 기성용 마인드. Claude 스킬을 하나 만들었다. 구현된 화면을 있는 그대로(as-built) 읽어서, 기획자용 한국어 화면정의서를 Markdown + Mermaid 흐름도로 뽑아주는 스킬이다. 그리고 그 결과물을 그냥 파일로 던지는 게 아니라, 사내 화면정의서 사이트로 배포하게 만들었다.
일단, 사이트는 이미 돌아가고 있었다
이 글의 출발점은 “스킬을 만들었다” 가 아니라 “그 스킬로 진짜 사이트를 배포했다” 다.
Astro 정적 사이트 하나를 띄워두고, 스킬이 화면정의서를 그 레포에 Markdown 으로 떨군다. 커밋하면 사이트가 다시 빌드되고, 사내망에서 누구나 열어볼 수 있다. 왼쪽 네비에 도메인별로(대시보드·검측·일정·현장일지…) 화면이 쌓이고, Mermaid 흐름도는 빌드 때 SVG로 렌더된다. 각 문서엔 “언제, 어느 커밋 기준으로 쓴 문서인지” 가 박혀 있어서 — 시간이 지나 실제 화면과 어긋났는지(신선도)도 보인다.
기획자·디자이너는 코드를 안 봐도 된다. 그냥 사이트를 본다. 이게 핵심이었고, 실제로 잘 돌아갔다.
화면정의서 사이트 — 도메인별 화면 목록과 신선도 대시보드
도메인별로 쌓인 화면정의서, 그리고 “언제·어느 커밋 기준으로 썼는지” 가 보이는 신선도 표.
문제는 딱 하나였다.
그런데 그걸 채울 수 있는 건 나뿐이었다
사이트는 모두가 읽을 수 있는데, 거기에 화면정의서를 쓸 수 있는 건 나 혼자였다.
읽기는 전원, 쓰기는 나 1명, 1인 병목
스킬이 ~/.claude/skills/screen-spec/ 에, 그러니까 내 홈 디렉터리에 들어있었으니까. 새 화면이 나올 때마다, 화면이 바뀔 때마다, 결국 내 컴퓨터에서 내가 스킬을 돌려야 사이트가 갱신됐다. 사이트는 전사 자산인데 업데이트 권한은 1인 병목인 셈이다.
게다가 열어보니 스킬 안에 경로가 죄다 하드코딩돼 있었다.
/Users/kang/Desktop/develop/0000-frontend # 소스 레포
/Users/kang/Desktop/develop/0000-screen-spec # 사이트 레포내 맥북 경로다. 팀원 컴퓨터엔 kang 이라는 사용자도 없다. 그대로 주면 첫 줄부터 깨진다. “내 컴퓨터에선 잘 되는데요” 의 정석적인 사례..
그래서 다음 목표가 분명해졌다. 사이트를 채울 수 있는 사람을 나 혼자에서 전 직원으로 늘리는 것. 그러려면 스킬이 (1) 어느 컴퓨터·어느 레포에서든 돌아가야 하고 (2) 누구나 한 번에 설치할 수 있어야 했다.
마침 Claude Code엔 플러그인 마켓플레이스가 있다. git 레포 하나를 마켓플레이스로 등록해두면 팀원은 명령 한 줄로 그 안의 스킬을 설치한다. 이걸 써보기로 했다.
특정 컴퓨터에 묶이지 않게 - config로 분리
가장 큰 작업은 “내 환경 전용” 을 걷어내는 거였다. 출력 대상(사이트 레포 위치), 문서 형식, 언어까지 전부 내 상황에 박혀 있었다.
그래서 변하는 건 전부 레포별 설정 파일로 빼냈다. 스킬을 쓰는 레포 맨 위에 .screen-spec.json 하나를 두고, “어디에 저장할지 / 어떤 형식으로 쓸지” 를 거기서 읽게 했다.
{
"output": { "repo": "../0000-screen-spec" }, // 화면정의서를 떨굴 사이트
"preset": "astro-screen-spec" // 사이트 형식
}필수는 이 둘뿐. “어디에 저장할지” 가 사람이 아니라 레포에 묶여야 한다는 게 핵심이었다. 누가 돌리든 그 레포의 설정을 읽어 같은 사이트의 같은 위치에 떨구도록. 이래야 “모두가 같은 사이트를 채운다” 가 성립한다.
사소하지만 발목 잡힌 것 하나: Word/인쇄용 export에 쓰는 html-doc 디자인 스킬도 내 개인 스킬이었다. 그대로 두면 팀원 컴퓨터엔 없어서 export가 조용히 깨진다. 그래서 플러그인 안에 사본을 같이 넣어(vendored) 자급자족하게 만들었다.마켓플레이스로 배포
구조 자체는 단순하다. 새 레포(0000-claude-plugins) 하나를 파고:
0000-claude-plugins/
├── .claude-plugin/marketplace.json # "이 레포엔 이런 플러그인들이 있다"
└── plugins/screen-spec/
├── .claude-plugin/plugin.json
├── presets/ # astro-screen-spec / plain-markdown
└── skills/
├── screen-spec/ # 본체
└── html-doc/ # 번들된 export 스킬GitHub 사내 조직에 private로 올리면 배포 끝. 설치하는 쪽은 두 경우로 갈린다.
- 새로 도입하는 사람 은
/plugin marketplace add ...→/plugin install screen-spec@.... - 이미 세팅된 레포를 여는 팀원 은 아무것도 안 쳐도 된다. 레포에 설정만 박아두면, 열었을 때 “이 플러그인 설치할까요?” 가 뜨고 한 번 승인하면 끝.
이 “한 번 승인” 을 만드는 게 레포의 .claude/settings.json 이다. extraKnownMarketplaces 가 “이런 저장소가 있다”, enabledPlugins 가 “그중 screen-spec을 켠다”. 이 파일을 레포에 커밋해두면, 그 레포를 여는 모든 팀원이 같은 플러그인을 제안받는다. 즉 “이 프로젝트의 화면정의서는 저 사이트에 쓴다” 가 레포에 박힌다.
실제로 돌려보기 - 로그인 화면
설치하고 바로 로그인 화면으로 테스트했다. “로그인 화면정의서 만들어줘” 하면서 뒤에 Figma 프레임 링크를 같이 붙였더니 코드를 읽어 화면정의서를 쓰고, Figma 시안을 캡처해서 문서에 이미지까지 자동으로 끼워 넣고, 사이트 레포에 저장했다. 그리고 사이트를 빌드했더니 통과. 새 화면정의서 한 장이 사이트에 그대로 올라갔다.
생성된 로그인 화면정의서 - Figma 캡처 + 기능 목록 + 흐름도 + 분기 규칙
화면 정보, 기능 목록, 상태, Mermaid 흐름도, 분기 규칙까지 한 번에. 가운데 이미지는 Figma 시안을 자동 캡처해 넣은 것.
좋은 건, 이 과정에서 시안과 구현의 차이까지 잡아냈다는 것이다. 시안엔 “현장/본사 로그인” 탭이랑 “회원가입” 링크가 있는데 실제 코드엔 없었다. 스킬이 그걸 (확인 필요) 로 표시해줬다. 비밀번호 검증도 코드는 최소 6자인데 안내 문구는 “8자 이상” 이라 안 맞는 것도 같이 짚어줬다. as-built로 읽으니까 나오는 디테일이다. 손으로 옮겼으면 그냥 시안대로 적고 넘어갔을수도..
마치며
시작은 “스킬로 화면정의서 사이트를 배포했다” 였다. 근데 그 사이트를 채울 수 있는 건 내 컴퓨터에 나 혼자쓰는 스킬 하나뿐이었다. 하드코딩을 걷어내고, config로 범용화하고, 마켓플레이스에 올리고 나니 이제 누구든 자기 레포를 열고 프롬프트 한 번 누르면 같은 사이트에 화면정의서를 보탤 수 있다. 사이트가 “내가 만든 것” 에서 “모두가 같이 채우는 것” 이 됐다.
더 나아가, 각자가 직접 만든 스킬을 올리고 공유하는 Repo까지 만들고 공유했기에, 더욱 활발한 개발 문화로 바뀌었다는 점이다. 모두 서로 돕고 성장하는 코딩이 되는것 같아 기쁘다!