SoDam-Design-Kit
Figma 디자인을 shadcn/ui 코드로 만들고, 실제 브라우저 검증(Playwright + axe-core + 3개 화면 크기)을 통과해야만 "완료"로 인정되는 Claude Code 디자인 자동화 킷입니다.
한국어(현재 문서) | English
✅ 현재 상태 (2026-10-12 기준, 직접 실행해 확인): Phase 1(MVP)과 Phase 2(대시보드 · 화면 변경 자동 감지 · 한글 폰트 자동화)가 공식 완료되었고, Phase 3(고도화)도 상세페이지 · AI 생성 이력 기록 · 마케팅 이미지 생성(OG·포스터·배너·명함) · 라이선스 게이트 확장 · Claude Desktop용 MCP 확장(검증 이력 열람)까지 완료되었습니다(남은 항목은 베타 공개 여부뿐, 사용자 결정 사항). 자동 테스트는 정식 공개된 v0.5.0 기준 361개, 아직 공개 전인 수정 2건까지 담긴 현재 작업본 기준 374개가 전부 통과하고, 알려진 보안 취약점은 0건입니다(npm audit을 2026-10-12에 다시 실행해 확인 — 2026-09-11의 4건과 2026-10-11에 새로 보고된 5건은 모두 패치 완료). 간접 의존성까지 포함한 전체 패키지의 라이선스를 package-lock.json 기준 153개로 2026-10-12에 다시 집계했고, 강한 카피레프트(GPL·AGPL)는 0건입니다(13장). 사용 가능한 명령은 총 5개(setup · pipeline · open · detail-page · marketing-asset)이며, 전부 실제 프로젝트를 대상으로 왕복 검증(PASS 확인)까지 마쳤습니다. 자세한 이력은 7장을 참고하세요.
⚠️ 이 킷은 아직 버전 0.5.0(정식 출시 전, 개발 진행 중)입니다. 명령어 이름·동작 방식·파일 구조가 앞으로 바뀔 수 있습니다 — 바뀔 때마다 이 문서도 함께 갱신됩니다.
📌 이 문서를 읽는 법: 문서 안에서 "(공개 전)"이라고 적힌 내용은 이 문서가 쓰인 시점에 코드에는 들어 있지만 아직 GitHub에서 받을 수 있는 정식 버전(v0.5.0)에는 포함되지 않은 수정입니다. 정식 버전과 현재 작업본이 다른 곳은 그렇게 표시했습니다.
목차
- 이 문서를 시작하기 전에 (용어 5분 정리)
- 이 도구는 무엇인가
- 사전 준비물 · 필요 프로그램 (다운로드 방법 포함)
- 다운로드 및 설치 방법
- 빠른 시작 (5분 안에 첫 성공 보기)
- 실행 · 사용 · 작동 방법
- 명령어 표
- 업데이트 내용 요약
- 워크플로우
- 아키텍처 · 파일/문서 위치
0. 이 문서를 시작하기 전에 (용어 5분 정리)
이 문서는 컴퓨터 · AI · 메신저 앱을 거의 처음 써보는 분도 따라 할 수 있도록 썼습니다. 다만 아래 단어들이 문서 전체에서 계속 나오므로, 먼저 한 번 훑어보고 시작하면 훨씬 편합니다. 이미 익숙한 분은 건너뛰고 1장부터 읽어도 됩니다.
| 용어 | 쉬운 설명 |
|---|
| AI (인공지능) | 사람의 말(자연어)을 이해하고 대신 작업해주는 프로그램. 이 문서에서 "AI"는 곧 "Claude Code"를 가리킵니다. |
| Claude Code | Anthropic이 만든, 채팅으로 대화하면서 컴퓨터 작업(코드 작성 등)을 대신 시키는 프로그램. 메신저처럼 "채팅창"이 있고, 거기에 원하는 것을 문장으로 입력하면 됩니다. |
| 터미널 | 글자로 명령을 입력해 컴퓨터에게 시키는 화면. Claude Code를 설치하면 그 채팅창 자체가 터미널 역할도 겸합니다 — 따로 배우거나 설치할 필요가 없습니다. |
| 명령 / 슬래시 명령 | /(슬래시)로 시작하는, 미리 정해진 지시어. 오픈채팅방이나 디스코드에서 /공지처럼 /로 시작하는 채팅 명령을 써본 적이 있다면 원리가 똑같습니다. 이 킷도 /sodam-design-kit:setup처럼 /로 시작하는 명령 5개를 씁니다. |
| 플러그인 | 원래 프로그램(Claude Code)에 나중에 끼워 넣는 "추가 기능 묶음". 스마트폰에 새 앱을 설치하는 것과 비슷합니다 — 이 킷 자체가 하나의 플러그인입니다. |
| 마켓플레이스 | 플러그인을 모아 놓고 "이름으로 골라 설치"할 수 있게 해 주는 목록(앱스토어와 비슷). 이 킷은 sodam이라는 이름의 작은 마켓플레이스 하나를 가지고 있고, 그 안에 sodam-design-kit 플러그인이 들어 있습니다. |
| 의존성 | 이 킷이 일하는 데 필요해서 다른 사람이 만들어 둔 부품 프로그램들(예: 브라우저를 조종하는 Playwright). 이 킷에 직접 들어 있지 않고 설치할 때 인터넷에서 받아옵니다. 어떤 부품이 있는지, 각각의 사용 조건(라이선스)은 13장에 있습니다. |
| 복사본 (설치된 사본) | 플러그인을 설치하면 Claude Code가 원본을 자기 전용 폴더에 복사해 두고 그 복사본을 실행합니다. 그래서 원본을 나중에 고치거나 새 버전을 받아도, 업데이트하기 전까지는 복사본이 그대로입니다(3장). |
| 폴더 / 경로 | "폴더"는 파일을 담는 서랍이고, "경로"는 그 서랍이 컴퓨터 안 어디에 있는지 적은 주소(예: D:\내문서\프로젝트)입니다. |
| 다운로드 / 설치 | "다운로드"는 인터넷의 파일을 내 컴퓨터로 가져오는 것, "설치"는 그 파일을 컴퓨터가 쓸 수 있는 상태로 준비해두는 것입니다. |
| 브라우저 | 크롬(Chrome) · 엣지(Edge)처럼 인터넷 화면(웹사이트)을 보는 프로그램. 이 킷은 사람이 보는 브라우저 창을 직접 열지 않고, 눈에 보이지 않는 자동화된 브라우저로 화면을 대신 확인합니다. |
| 서버 (개발 서버) |
💬 정말 처음이신가요?: 이 킷을 쓰려면 최소한 "Claude Code를 열고 채팅창에 글자를 입력해본 경험" 정도는 필요합니다. 컴퓨터를 정말 처음 켜보는 단계라면, 먼저 claude.com/claude-code 공식 안내를 따라 Claude Code부터 설치하고 몇 마디 대화를 나눠본 뒤 이 문서로 돌아오시길 권합니다. (이 킷은 Node.js·Figma 계정 등 몇 가지가 더 필요한 개발 도구라, "앱 하나만 깔면 바로 되는" 종류는 아닙니다 — 2장에서 필요한 것을 전부 확인할 수 있습니다.)
1. 이 도구는 무엇인가
한 줄로 말하면: "Figma 디자인 → 실제로 작동하는 코드"를 자동으로 만들어 주되, 브라우저에서 실제로 확인해보지 않은 결과는 "완료"라고 말하지 못하게 강제로 막는 도구입니다.
- Figma에 그려진 화면(예: 버튼 하나)을 읽습니다.
- 그 화면과 같은 모양의 코드를 shadcn/ui(React 컴포넌트 모음) 스타일로 만듭니다.
- 만든 코드를 눈에 보이지 않는 자동화된 브라우저에 띄우고, 화면이 깨지지 않았는지 · 장애인 접근성(스크린 리더 등)에 문제가 없는지 · 휴대폰(360px) · 태블릿(768px) · PC(1440px) 3가지 화면 크기에서 다 괜찮은지 자동으로 검사합니다.
- 검사 결과(통과/실패)를 "판정서"라는 기록으로 남기고, 실패(FAIL)가 기록되면 "완료"라고 보고하는 것 자체를 시스템(훅)이 기계적으로 막습니다(AI가 실패를 못 본 척하거나 눈속임하려 해도 소용없습니다). 단, 검증을 아예 돌리지 않은 경우까지 이 장치가 막지는 못한다는 한계가 있습니다 — 정확한 조건은 8장에 적었습니다.
Figma 디자인 ──▶ 코드 생성 ──▶ 실제 브라우저에서 검사 ──▶ 통과해야만 "완료"
왜 이런 도구가 필요한가: AI에게 "이 디자인대로 코드 만들어줘"라고만 시키면, AI는 코드를 만들고 "다 됐습니다"라고 말할 수 있습니다. 하지만 그 코드가 실제로 화면에 정상적으로 나오는지, 글자가 깨지지는 않는지, 스크린 리더 사용자도 쓸 수 있는지는 AI 혼자 "말로만" 확인한 것일 수 있습니다. 이 킷은 그 마지막 확인을 사람이 아니라 진짜 브라우저 프로그램이 기계적으로 하게 만들어서, "말로는 됐다는데 실제로는 안 됐다"는 상황을 크게 줄입니다(검증을 돌린 경우에 한해, 위 한계 참고).
누구를 위한 도구인가: Figma로 디자인을 만드는 사람과, Claude Code로 그 디자인을 코드로 옮기는 사람(1인이어도 무방) — 특히 "AI가 코드는 만들었다는데, 실제로 화면이 제대로 나오는지는 안 봤다"는 불안을 없애고 싶은 사람.
누구를 위한 도구가 아닌가(정직한 한계 고지): 코딩을 전혀 모르는 채로 "완성된 웹사이트"를 통째로 만들어주는 도구는 아닙니다. 이 킷이 만드는 것은 이미 존재하는 프로젝트(Next.js + Tailwind + shadcn/ui) 안의 화면 부품 하나하나입니다 — 2장에서 이 전제를 자세히 설명합니다.
2. 사전 준비물 · 필요 프로그램 (다운로드 방법 포함)
이 5가지가 전부 준비되어 있어야 합니다. 하나라도 없으면 3장(설치)부터 진행할 수 없습니다.
| 번호 | 준비물 | 왜 필요한가 | 다운로드 / 확인 방법 |
|---|
| 1 | Claude Code | 이 킷 자체가 Claude Code의 "플러그인"이라 Claude Code가 없으면 실행할 수 없음 | claude.com/claude-code 공식 안내에 따라 설치. 설치 후 터미널에 claude --version을 입력해 버전이 나오면 성공 (이 문서의 설치 · 업데이트 절차는 2.1.296 버전에서 직접 실행해 확인했습니다) |
| 2 | Node.js 20.9 이상 (현재 LTS 권장) | 이 킷의 모든 검증 스크립트가 Node.js(자바스크립트 실행기)로 작성됨. 최소 버전이 20.9인 이유: 이 킷이 이미지 처리에 쓰는 부품 sharp가 Node 20.9 이상을 요구합니다(package-lock.json에 적힌 값을 직접 확인). 이전 문서에는 "18 이상"이라고 적혀 있었으나 이는 틀린 안내였습니다 | nodejs.org에서 "LTS" 버전 다운로드 · 설치. 설치 후 터미널(명령 입력 창)에 node -v 입력 → v20.9.0 이상의 번호가 나오면 성공 (이 문서의 절차를 마지막으로 확인한 PC는 v26.7.0) |
| 3 | 대상 프로젝트: Next.js + Tailwind CSS + shadcn/ui | 이 킷이 만드는 코드가 이 3가지 조합을 전제로 함(다른 프레임워크는 아직 미지원) | 이미 이 조합으로 만들어진 프로젝트가 있어야 함. 없다면 npx create-next-app@latest 등 Next.js 공식 방법으로 새로 만들고 shadcn/ui 공식 설치 안내를 따라 준비 |
| 4 | Figma 파일 접근 권한 | 코드로 옮길 디자인 원본이 Figma에 있어야 함 | claude.ai에 이미 연결된 Figma 커넥터를 쓰거나, 공식 Figma MCP(https://mcp.figma.com/mcp)로 로그인. Figma 계정 자체는 무료(Starter) 플랜도 가능하나 읽기 횟수 제한이 있습니다(제작 당시 실측은 월 6회, 이후 Figma 공식 문서 표기가 바뀐 것이 확인됨 — 정확한 현재 한도는 Figma 공식 안내에서 확인하세요. 뒤 10장 참고) |
| 5 | 인터넷 연결 · 여유 저장공간 약 1GB | 설치할 때 부품(의존성)과 검증용 브라우저 파일을 내려받아야 함 | 이 개발 PC에서 직접 잰 값: 설치된 킷 복사본 약 76MB(그중 부품 node_modules가 75MB) + 검증용 브라우저(Chromium) 약 690MB(415 + 269 + 3MB). 킷 버전을 올릴 때마다 복사본이 새로 생기므로(옛 버전 폴더가 남음) 조금씩 늘어납니다. 용량은 PC · 버전마다 다를 수 있습니다. Git이 필요한 경우는 3장의 "방법 A"를 참고하세요 |
처음 보는 단어가 있다면 0장 용어 사전을 먼저 확인하세요. 특히 "터미널"이 뭔지 모르겠다면: 글자로 명령을 입력해 컴퓨터에게 시키는 검은/흰 화면입니다. Claude Code를 설치하면 그 안에서 명령을 입력하는 창이 곧 터미널입니다. 별도로 새로 설치할 필요는 없습니다.
준비물 3번이 없다면?: 이 킷은 "이미 어느 정도 만들어진 웹사이트 프로젝트"가 있다는 전제로 작동합니다. 아무 프로젝트도 없는 상태에서 "웹사이트를 통째로 만들어줘"라는 용도로는 설계되어 있지 않습니다. 그런 프로젝트가 아직 없다면, Claude Code에게 "Next.js + Tailwind + shadcn/ui로 빈 프로젝트를 만들어줘"라고 자연어로 요청해 먼저 준비하는 것도 방법입니다.
3. 다운로드 및 설치 방법
✅ 이 절의 설치 · 업데이트 명령은 2026-10-12에 Windows + Claude Code 2.1.296에서 직접 실행해 결과를 확인한 것입니다. 시험은 평소 쓰는 설정을 건드리지 않도록 일회용 임시 설정 폴더에서 했고, 깨끗한 상태에서 처음 설치하는 상황을 그대로 재현했습니다. 한계: ① 검증용 브라우저 파일(약 690MB)을 인터넷에서 처음 받는 과정은 이 PC에 이미 설치돼 있어 처음부터 재현하지 못했습니다(명령이 오류 없이 끝나는 것까지만 확인). ② 시험한 PC는 GitHub에 로그인돼 있었습니다 — 이 저장소는 공개(PUBLIC)라 원칙적으로 로그인이 필요 없지만, 로그인하지 않은 PC에서는 확인하지 못했습니다. ③ macOS · Linux는 시험하지 않았습니다.
먼저 알아둘 3가지 (직접 확인한 동작)
- 설치하면 "복사본"이 만들어집니다. 플러그인을 설치하면 Claude Code가 원본을 자기 전용 폴더에 복사해 두고 그 복사본을 실행합니다. 위치는 Claude 설정 폴더 안의
plugins\cache\sodam\sodam-design-kit\<버전>입니다(설정 폴더는 보통 C:\Users\<내 이름>\.claude이며, 위치를 바꿔 쓰는 PC는 다릅니다). 그래서 원본 폴더를 고치거나 새 버전을 받아도 아래 "업데이트 방법"을 실행하기 전에는 복사본이 그대로입니다. (이전 문서에는 "복사본이 만들어지지 않는다"고 적혀 있었으나 이는 틀린 설명이었습니다.)
- 부품(의존성)은 자동으로 설치됩니다. 깨끗한 상태에서 설치했을 때 Claude Code가 복사본 안에 부품(Playwright · axe-core · sharp 등)을 스스로 설치했습니다. 따라서
npm install을 직접 칠 필요가 없습니다. 다만 설치나 업데이트 직후 바로 쓰면 부품이 아직 준비 중일 수 있으니, 처음 명령이 부품 관련 오류로 실패하면 1~2분 기다린 뒤 다시 실행하세요(정확한 소요 시간은 측정하지 못했습니다).
- 검증용 브라우저는 자동으로 설치되지 않습니다. 이 킷이 화면을 실제로 열어 보는 브라우저(Chromium)는 별도로 한 번 받아야 합니다 — 아래 방법의 4번 단계입니다. 이걸 빼먹으면 검증할 때
Executable doesn't exist ...라는 오류가 납니다(11장).
방법 A (권장) — GitHub 주소로 바로 설치 (저장소를 따로 내려받지 않음)
필요한 것: Git(Claude Code가 내부적으로 Git으로 내려받습니다).
-
마켓플레이스 등록 — Claude Code 채팅창에서 입력합니다:
/plugin marketplace add sodam-ai/SoDam-Design-Kit
(전체 주소 https://github.com/sodam-ai/SoDam-Design-Kit.git을 써도 됩니다. 두 가지 모두 2026-10-12에 성공을 확인했습니다. 터미널에서 같은 일을 하려면 claude plugin marketplace add sodam-ai/SoDam-Design-Kit.)
-
플러그인 설치:
/plugin install sodam-design-kit@sodam
-
Claude Code 완전 재시작 — 창을 완전히 닫았다가 다시 엽니다. 새로고침이 아니라 완전 종료 후 재시작이어야 합니다(11장 첫 항목).
-
검증용 브라우저 설치 (최초 1회) — 터미널(Windows는 PowerShell)에 입력합니다:
npx [email protected] install chromium
숫자 1.61.1은 정식 버전 v0.5.0이 쓰는 Playwright 버전(이 킷의 package-lock.json에 적힌 값)입니다. 킷 버전이 바뀌면 이 숫자도 바뀔 수 있으니, 나중에 검증이 Executable doesn't exist로 실패하면 그 오류 화면이 알려주는 명령(npx playwright install)을 따르거나 Claude Code에게 "Playwright 브라우저를 설치해 줘"라고 요청하세요. 버전이 다른 브라우저를 받으면 이 킷이 찾지 못합니다.
-
설치 확인 — 코드로 옮길 대상 프로젝트(2장 준비물 3번) 안에서 입력합니다:
/sodam-design-kit:setup
명령이 자동완성 목록에 뜨고 실행되면 성공입니다. 터미널에서 claude plugin list를 입력해 sodam-design-kit@sodam의 Status가 enabled로 나오는 것으로도 확인할 수 있습니다.
방법 B — 내 컴퓨터의 폴더로 설치 (코드를 직접 고쳐 쓰는 개발자용)
- 저장소를 내려받습니다:
git clone https://github.com/sodam-ai/SoDam-Design-Kit.git
- 마켓플레이스 등록에 폴더의 전체 경로를 줍니다(예:
/plugin marketplace add D:\내폴더\SoDam-Design-Kit).
- 이후는 방법 A의 2~5번과 같습니다(
/plugin install sodam-design-kit@sodam → 완전 재시작 → 브라우저 설치 → 확인).
- 이 방법도 복사본이 만들어집니다(방법 A와 동일하게 확인). 원본 폴더의 코드를 고쳤다면 반드시 커밋한 뒤 아래 "업데이트 방법"을 실행하세요 — 커밋하지 않은 수정이 복사본에 반영되는지는 확인하지 못했습니다.
- 이 킷의 자동 테스트(
npm test)를 돌리거나 스크립트를 플러그인 없이 직접 실행하려면 그 폴더 안에서 npm ci(또는 npm install)를 한 번 해야 합니다. 플러그인으로만 쓸 때는 필요 없습니다.
업데이트 방법 (새 버전이 나왔을 때)
터미널에서 아래 두 줄을 차례로 입력합니다(2026-10-12에 실제로 0.5.0 → 0.5.1로 올려 보며 확인한 순서입니다):
claude plugin marketplace update sodam
claude plugin update sodam-design-kit@sodam
→ "Restart to apply changes"가 나오면 Claude Code를 완전히 재시작해야 새 버전이 적용됩니다. claude plugin list의 Version으로 확인하세요. 새 버전 폴더가 plugins\cache\...\<새 버전>으로 따로 생기고 옛 버전 폴더는 그대로 남습니다(동작에는 영향이 없음을 확인한 범위입니다).
중요: 업데이트를 하지 않으면 평소 쓰는 Claude Code에는 옛 버전의 복사본이 계속 실행됩니다. 예를 들어 이 킷에 새 안전장치가 추가됐어도 업데이트 전에는 적용되지 않습니다.
설치가 안 됐다는 걸 어떻게 아나요?
채팅창에 /sod까지 입력했는데 자동완성 목록에 아무것도 안 뜨면 설치(또는 재시작)가 덜 된 것입니다. 11장의 첫 번째 항목을 확인하세요.
3장 보충 — Claude Desktop에서도 검증 이력을 보고 싶다면 (선택, 2026-08-20 추가)
위 1~5번은 Claude Code(터미널형 채팅) 전용입니다. Claude Desktop(일반 데스크톱 앱)에서도 이 킷이 만든 검증 이력·판정서·스크린샷을 보고 재검증을 실행하고 싶다면 아래 확장을 추가로 설치할 수 있습니다 — 둘은 서로 다른 앱이고, 이 확장은 선택 사항입니다.
-
먼저 방법 B(위)처럼 저장소를 내려받고 그 폴더에서 npm ci를 한 번 실행합니다(확장 파일 안에 부품이 이 폴더의 node_modules에서 함께 담기기 때문 — 2026-10-12에 만들어진 .mcpb의 내부에 node_modules가 들어 있는 것을 직접 열어 확인했습니다). 그다음 다음 명령으로 확장 파일(.mcpb)을 만듭니다(터미널, 이 저장소 폴더 안에서):
npx @anthropic-ai/mcpb pack .
이 저장소 폴더 이름을 딴 .mcpb 파일이 폴더 안에 새로 생깁니다(방금 만들어진 파일이니 폴더에서 바로 확인 가능합니다). 크기는 약 20MB입니다(v0.5.0으로 만든 파일이 20.3MB — 실제 브라우저로 재검증하는 기능이 들어있어 다른 확장보다 큰 편입니다. 이전엔 실수로 무관한 파일까지 포함돼 약 70MB였으나, 불필요한 파일을 제외하도록 고쳐 지금 크기로 줄었습니다. 2026-10-12에 파일 내부를 열어 개발 메모·세션 상태·설계 문서가 들어 있지 않은 것을 다시 확인했습니다).
-
생성된 .mcpb 파일을 더블클릭합니다. 정상이라면 Claude Desktop이 설치 화면을 띄웁니다 — 내용을 확인하고 설치를 승인하세요.
더블클릭했는데 "이 파일을 열 프로그램을 선택하세요" 같은 Windows 창이 뜨나요? 설치 실패가 아니라 이 컴퓨터에 .mcpb 파일 형식에 대한 연결이 아직 없어서 생기는 별개의 문제입니다(Claude Desktop이 이미 설치돼 있어도 발생할 수 있습니다 — 2026-09-01 실측 확인). 그 창에서 취소를 누르고, 아래 방법으로 설치하세요:
- Claude Desktop 앱을 열고 왼쪽 위
☰ → 설정(단축키 Ctrl+,)
- 왼쪽 목록에서 "확장 프로그램" 클릭
- 화면 맨 아래 "고급 설정" 클릭
- "확장 프로그램 개발자" 항목의 버튼 4개 중 맨 왼쪽 "확장 프로그램 설치" 클릭
- 파일 선택창에서 방금 만든
.mcpb 파일을 선택
- 확인 화면(이름·설명, 도구 5개 이름, "모든 요구 사항 충족됨", 제작사 SoDam AI Studio, 라이선스 Apache-2.0, 버전 표시)이 뜨면 설치를 클릭
-
설치 확인 (아래 둘 중 하나로 확인하면 됩니다):
- Claude Desktop에서 "최근 검증 이력을 보여줘"처럼 물어봤을 때 이 킷의 도구(
list_runs 등)가 호출되면 성공입니다.
- 또는 설정 → "개발자" → "로컬 MCP 서버" 목록에서
SoDam Design Kit이 running 배지로 표시되면 성공입니다.
이 확장으로 할 수 있는 것 / 못 하는 것 (정직 고지):
- 할 수 있음: 검증 이력 열람, 판정서·스크린샷 확인, 재검증 실행 — Claude Code의
/sodam-design-kit:open 대시보드와 같은 데이터입니다. (2026-08-20 추가) component-map.json에 이미 등록된 컴포넌트를 검증용 프리뷰 화면에 다시 연결하는 것도 가능합니다(Figma를 새로 읽거나 새 코드를 쓰지는 않습니다 — 이미 있는 매핑을 재사용할 뿐입니다).
- 못 함: 완료를 기계적으로 차단하는 것은 Claude Code 훅 전용 기능입니다. Claude Desktop에서는 재검증 결과(PASS/FAIL)를 보여줄 뿐, FAIL이어도 작업을 강제로 멈추지 않습니다. 또한 새 컴포넌트를 위한 실제 코드를 Claude Desktop이 대신 만들어 프로젝트에 넣어주지는 않습니다 — 검증 없이 실제 코드가 조용히 들어갈 수 있는 위험이 있다고 판단해 이번엔 의도적으로 포함하지 않았습니다.
- 이 확장의 재검증 기능은 내부적으로 실제 브라우저(Playwright)를 실행합니다. 확장 파일 안에는 부품(Playwright 프로그램 자체)이 들어 있지만 브라우저 파일(Chromium, 약 690MB)은 들어 있지 않습니다 — 위 방법 A의 4번 명령(
npx [email protected] install chromium)을 PC에서 한 번 실행해야 재검증이 동작합니다. (검증 이력 열람 · 판정서 · 스크린샷 보기는 브라우저 없이도 됩니다 — 브라우저가 필요한 것은 재검증뿐입니다.)
4. 빠른 시작 (5분 안에 첫 성공 보기)
준비물이 다 있고 설치까지 마쳤다면(검증용 브라우저 설치 — 3장 방법 A의 4번 — 까지 포함), 아래 순서로 첫 결과를 5분 안에 볼 수 있습니다. 브라우저를 아직 안 받았다면 2단계에서 Executable doesn't exist 오류가 납니다.
1단계 — 초기 설정 (최초 1회, 대상 프로젝트당)
/sodam-design-kit:setup
→ 성공 기준: .design-kit/config.json과 .design-kit/component-map.json이 생성되었다는 메시지가 나옴.
2단계 — 첫 파이프라인 실행 (이미 매핑된 컴포넌트가 있을 때)
/sodam-design-kit:pipeline
→ Figma 링크를 물어보면, 버튼 하나처럼 작은 단위의 Figma 공유 링크(주소에 node-id=가 포함된 링크)를 붙여넣습니다.
→ 성공 기준: 마지막에 PASS 판정과 함께 .design-kit/reports/에 판정서 파일이 생겼다는 메시지가 나옴.
3단계 — 판정서 확인
.design-kit/reports/2026-XX-XX-XXX.md
이 파일을 열어 **PASS** 표시와 360px/768px/1440px 스크린샷 경로 3줄이 있는지 확인합니다. 이게 보이면 "실제 브라우저 검증까지 완료됐다"는 뜻입니다.
실패(FAIL)해도 정상입니다 — 오히려 게이트가 제대로 작동한다는 뜻입니다. 11장 "완료가 차단됐다고 나와요" 항목을 보세요.
4단계(선택) — 만든 결과를 한눈에 보기
/sodam-design-kit:open
→ 브라우저 화면(대시보드)이 자동으로 열려서, 지금까지의 검증 이력 · 판정서 · 스크린샷을 한 곳에서 볼 수 있습니다. 다 봤으면 채팅창에 /sodam-design-kit:open --stop을 입력해 끌 수 있습니다(안 꺼도 무해하지만, 안 쓸 때는 꺼두는 것을 권장합니다).
5. 실행 · 사용 · 작동 방법
이 킷은 Claude Code 안에서 슬래시 명령(/로 시작하는 명령)으로 실행합니다. 사람이 터미널에 직접 Node 명령을 칠 필요는 없습니다(킷을 만드는 개발자가 자체 테스트할 때만 터미널 명령을 씁니다 — .PRD/04_PROJECT_SPEC.md "테스트 방법" 참고).
/sodam-design-kit:setup — 초기 설정
- 입력: 없음(현재 프로젝트 폴더를 자동으로 사용) / 선택: Figma 파일 링크
- 하는 일:
components.json(shadcn 설정)을 읽어 실제 컴포넌트 폴더를 찾고, 그 안의 .tsx 파일을 스캔해 .design-kit/component-map.json을 만듭니다. .design-kit/config.json(화면 크기 3종 · 자동재시도 3회 등 기본값)도 함께 생성합니다. 알아둘 점(코드로 확인): 이 config.json은 현재 기록용 기본값일 뿐이고, 어떤 프로그램도 이 값을 읽어서 동작을 바꾸지 않습니다. 화면 크기 3종(360 · 768 · 1440px)은 코드에 고정돼 있어서 이 파일을 고쳐도 검사 방식은 달라지지 않습니다.
- 작동 방법: 프로젝트당 1회만 실행하면 됩니다. 이미 설정이 있으면 자동으로 건너뛰고, 다시 스캔하려면
--force를 붙입니다(이때도 이미 확보한 Figma 매핑 정보는 보존되고 새 컴포넌트만 추가됩니다).
- 성공 기준: "완료" 메시지 +
.design-kit/ 폴더 생성.
/sodam-design-kit:pipeline — 디자인→코드→검증
- 입력: Figma 공유 링크(페이지/노드 단위 직접 링크, 파일 전체 링크 아님 — 10장 참고)
- 하는 일: Figma 읽기 →
component-map.json에 매핑 기록 → shadcn/ui 코드 생성 → 미리보기 화면(/design-kit-preview/{컴포넌트}) 자동 생성 → 개발 서버 자동 실행 → 실제 브라우저 검증(Playwright+axe-core+3뷰포트) → 판정서 기록.
- 작동 방법: 실패(FAIL)하면 AI가 판정서의 실패 사유를 읽고 코드를 고쳐 다시 검증합니다. 재시도는 최대 3회로 절차 문서(
commands/pipeline.md)가 AI에게 지시하는 것이고, 프로그램이 횟수를 강제로 세지는 않습니다. 또 "연속 2회 실패해야 최종 FAIL"이라는 규칙은 코드에 없습니다 — 실제로는 가장 최근 판정 기록 1건이 FAIL이면 그 즉시 완료가 차단됩니다(8장). 표준 검증 명령에는 TypeScript 타입 검사(--typeCheck)도 함께 들어 있습니다(tsconfig.json이 있는 프로젝트). 이미 매핑된 컴포넌트를 재사용하는 경로와, 매핑이 없는 완전히 새로운 컴포넌트를 처음부터 만드는 경로 둘 다 실제로 검증 완료(PASS)되었습니다. 신규 컴포넌트를 배치하기 전에는 색상 · 간격 같은 값이 하드코딩(예: #ff0000)되어 있지 않은지 자동으로 검사해서, 걸리면 배치 자체를 거부합니다.
- 성공 기준:
.design-kit/reports/에 **PASS**가 적힌 판정서 파일 생성.
/sodam-design-kit:open — 검증 이력 대시보드 열람
- 입력: 없음 / 종료할 때만
--stop
- 하는 일: 지금까지 쌓인 판정서 · 실행 기록 · 스크린샷을 사람이 보기 편한 브라우저 화면(대시보드)으로 열어줍니다. 화면에서 판정서를 눌러 상세를 보거나, "재검증" 버튼으로 다시 검사를 돌릴 수 있습니다.
- 작동 방법: 내 컴퓨터 안에서만 접속되는 주소(
127.0.0.1, 즉 "이 컴퓨터 자신"이라는 뜻)로 열리며, 다른 사람의 컴퓨터에서는 접속할 수 없습니다. 이미 켜져 있으면 새로 켜지 않고 기존 것을 재사용합니다.
- 성공 기준: 브라우저 창이 자동으로 열리고 판정서 목록이 보임.
/sodam-design-kit:detail-page — 상품 상세페이지 파이프라인 (Phase 3)
- 입력: 상품 데이터 파일(CSV 또는 JSON — 상품 이름 · 특징 등이 적힌 표 형식 파일)
- 하는 일: 상품 데이터를 읽어 → AI가 소개 문구(제목 · 핵심 장점 · 설명 · 자주 묻는 질문)를 작성 → 그 문구를 보여주는 상세페이지 코드로 연결 → 기존과 동일한 검증 게이트(실브라우저+접근성 검사+3개 화면 크기) 통과.
- 작동 방법: 상품마다 새 페이지 파일을 따로 만들지 않고, 페이지 틀(템플릿)은 1개만 만든 뒤 상품 데이터만 상품마다 저장하는 방식입니다(새 파일이 무한정 늘어나는 것을 방지).
- 성공 기준: 다른 명령과 동일하게
.design-kit/reports/에 **PASS** 판정서 생성.
/sodam-design-kit:marketing-asset — 마케팅 이미지(OG · 포스터 · 배너 · 명함) 생성 (Phase 3)
- 입력: 제목(필수) + 부제목(선택), 명함은 추가로 회사 · 전화 · 이메일 등 여러 줄(선택)
- 하는 일: 4가지 규격 중 하나로 이미지를 자동 렌더링합니다 — OG(1200×630, SNS 공유용) · 포스터(1080×1350, 인스타그램 세로형) · 배너(1200×400, 가로형) · 명함(1050×600, 3.5×2인치 실제 인쇄 규격). 규격 · 형식 · 용량 기준을 통과 못 하면 파일을 아예 만들지 않습니다.
- 작동 방법: 한글 폰트(Pretendard)를 자동으로 재사용해 글자가 네모로 깨지지 않게 렌더링하고, 만든 이미지 정보를 AI 생성 이력(
AI-GENERATION-LOG.md)에 자동으로 남깁니다.
- 성공 기준:
public/design-kit-assets/<규격>-<제목>.png 파일 생성. SNS 카드 등 그 외 규격은 아직 지원하지 않습니다(필요성이 확인되면 추가 검토).
P1 완료 확인 절차 (프로젝트 관리자용)
이건 일반 사용마다 할 일이 아니라, 이 킷이 "새 대화(세션)에서도 처음부터 똑같이 작동하는지"를 최종 확인하는 절차입니다(.PRD/01_PRD.md §9 성공 기준 5·6번). 새 Claude Code 세션에서 아래 순서대로 하면 이 문서만 보고도 그대로 재현할 수 있습니다.
- 대상 프로젝트를 정합니다 — 이미
/sodam-design-kit:setup을 마치고 Figma 매핑도 있는 프로젝트가 이상적입니다(Figma를 다시 호출하지 않아도 되어 무료 플랜의 월 읽기 한도를 쓰지 않습니다).
- 실행 직전, 판정서 폴더의 현재 상태를 먼저 확인해 기준으로 삼습니다 (PowerShell):
Get-ChildItem "<대상 프로젝트 경로>\.design-kit\runs" | Sort-Object Name | Select-Object -Last 3
여기 나온 파일 목록을 잠깐 기억해둡니다 — 나중에 "기존 파일이 안 지워졌는지" 비교할 기준입니다.
- Claude Code에서 아래를 실행합니다.
/sodam-design-kit:pipeline
대상 프로젝트 경로와 Figma 노드(또는 이미 있는 매핑)를 알려주면 됩니다.
- 성공 기준 (이게 전부 보이면 성공):
- 결과에
"verdict": "PASS"가 나온다
.design-kit\reports\ 폴더에 새 판정서 파일 1개가 생겼다- 2번에서 확인해둔 기존 파일들이 하나도 사라지지 않았다(덮어쓰기 없음)
- 에이전트가 임시 스크립트를 즉석에서 따로 만들지 않았다 —
verify-runner.mjs --target ... 명령 하나로 검증과 판정서 기록이 동시에 끝나야 합니다
- 꼭 PowerShell로 실행하세요 — Git Bash에서는
/design-kit-preview/...처럼 /로 시작하는 값이 경로로 잘못 해석되는 함정이 있습니다(11장 트러블슈팅 참고).
6. 명령어 표
| 명령 | 설명 | 입력 | 실행 위치 | 현재 상태 |
|---|
/sodam-design-kit:setup | config.json 생성 + shadcn 컴포넌트 스캔으로 component-map 초기 시드 | 없음(선택: Figma 파일 링크) | 대상 프로젝트(Next.js) 안 | ✅ 실측 검증 완료 |
/sodam-design-kit:pipeline | Figma 읽기 → 매핑 → shadcn/ui 코드 생성 → 검증 게이트 | Figma 페이지/노드 링크 | 대상 프로젝트(Next.js) 안 | ✅ 재사용(매핑) 경로 · 신규 컴포넌트 생성 경로 둘 다 실측 PASS |
/sodam-design-kit:open | 검증 이력 · 판정서 · 스크린샷을 브라우저 대시보드로 열람 + 재검증 트리거 (127.0.0.1 전용, 종료는 --stop) | 없음 | 대상 프로젝트 안 | ✅ 실제 백그라운드 기동 · 재사용 · 종료 왕복 실측 PASS |
/sodam-design-kit:detail-page | 상품 데이터(CSV/JSON) → 카피 생성 → 상세페이지 코드 → 동일 검증 게이트 (Phase 3) | 상품 데이터 파일(CSV 또는 JSON) | 대상 프로젝트(Next.js) 안 | ✅ 실측 PASS→FAIL(의도적 접근성 위반)→PASS 복귀 왕복 확인 |
/sodam-design-kit:marketing-asset | 제목/부제(+명함은 추가 정보) → OG · 포스터 · 배너 · 명함 이미지 자동 생성 (Phase 3) | 제목(필수) · 부제(선택) · 명함 추가 정보(선택) | 대상 프로젝트 안 (public/design-kit-assets/) | ✅ 4종 전부 실측 PASS(한글 렌더 · 규격 확인) |
킷 개발자(코드를 직접 고치는 사람) 전용 명령(일반 사용자는 몰라도 됩니다):
| 명령 | 설명 | 실행 위치 |
|---|
npm ci (또는 npm install) | 부품(Playwright · axe-core 등) 설치 — 플러그인으로만 쓸 때는 필요 없고(3장), 자동 테스트나 스크립트를 직접 돌릴 때만 필요. 검증용 브라우저 파일은 이 명령으로 설치되지 않습니다(npx playwright install chromium이 따로 필요) | 이 킷 저장소 폴더 |
npm test | 킷 자체의 자동 테스트 실행(2026-10-12 기준 정식 v0.5.0은 361개, 공개 전 수정까지 담긴 작업본은 374개 — 늘어날 수 있음) | 이 킷 저장소 폴더 |
node scripts/e2e-selftest.mjs --fixture <시험 프로젝트 경로> | 전체 파이프라인 왕복(PASS/FAIL/재검증) 자체 점검. --fixture로 검증 대상이 되는 별도의 Next.js 시험 프로젝트를 줘야 하는데(경로 없이 실행하면 사용법만 출력하고 종료), 그 시험 프로젝트는 이 저장소에 들어 있지 않습니다(처음 쓰는 분은 건너뛰어도 됩니다). package.json의 npm run selftest는 같은 명령의 줄임말이라 npm run selftest -- --fixture <경로>처럼 인자를 줘야 합니다 | 이 킷 저장소 폴더 |
검증 옵션 (선택 기능 5개) — 기본 검사 위에 더하는 스위치
기본 검증은 "화면이 그려지는가 · 콘솔 에러가 없는가 · 접근성 위반(심각/높음)이 없는가 · 3가지 화면 크기 스크린샷이 있는가" 4가지입니다. 아래 옵션은 거기에 검사를 더 얹는 스위치로, 검증 실행기(scripts/verify-runner.mjs) 명령 끝에 붙여서 씁니다. 슬래시 명령 pipeline · detail-page는 이 중 --typeCheck만 표준으로 붙여 실행하고, 나머지 4개는 꺼져 있는 것이 기본입니다(기존 프로젝트가 예고 없이 갑자기 FAIL로 바뀌지 않게 하려는 설계). 켜고 싶으면 Claude Code에게 "폰트 검사도 켜서 검증해 줘"처럼 요청하거나, 터미널에서 직접 붙입니다.
| 옵션 | 켜면 하는 일 | 이럴 때 FAIL | 알아둘 점 |
|---|
--typeCheck | TypeScript 타입 검사(tsc --noEmit)를 화면 검증보다 먼저 실행 | 타입 오류가 있을 때, 또는 검사를 실행하지 못했을 때(조용히 통과시키지 않음) | --project를 같이 줘야 합니다(없으면 거부). 개발 서버가 만드는 .next/ 안 파일의 오류는 제외. 이 옵션이 없으면 타입 오류가 있어도 화면만 뜨면 PASS가 나옵니다(직접 실험으로 확인) |
--fontGate | 프로젝트에서 찾은 폰트 파일이 .design-kit/ASSET-LEDGER.csv(자산 대장)에 등록돼 있는지 확인 | 대장에 없는 폰트 파일이 있을 때 | 이 킷이 자동으로 받은 Pretendard 등은 이미 등록되어 걸리지 않습니다 |
--assetGate | 이미지 · 아이콘 파일도 같은 방식으로 대장 등록 여부 확인 | 대장에 없는 이미지가 있을 때 | public/design-kit-assets/(마케팅 이미지 산출물)와 .design-kit/(검증 스크린샷)은 검사에서 제외됩니다. 출처 정리 문서 .design-kit/ATTRIBUTION.md는 이 옵션과 별개의 명령 node scripts/asset-ledger.mjs --project <대상 프로젝트> --generateAttribution으로 대장에서 만들어집니다 |
--visualRegression | 사람이 "이 화면이 맞다"고 승인해 둔 기준 화면과 지금 화면을 픽셀 단위로 비교 | 기준 화면과 달라졌을 때(차이를 보여주는 이미지가 생성됨) | 승인된 기준 화면이 아직 없으면 비교하지 않고 넘어갑니다(FAIL 아님) |
--promoteBaseline | 지금 화면을 새 기준 화면으로 승인 | (FAIL을 만드는 옵션이 아님) | 검증이 PASS인 화면만 승인되고, 반드시 사람이 직접 요청해야 합니다. 자동으로 승인되는 경로는 없습니다 |
예시(PowerShell, <킷 폴더>는 3장 방법 B로 내려받은 폴더 또는 설치된 복사본 폴더):
node "<킷 폴더>\scripts\verify-runner.mjs" --project "<대상 프로젝트 폴더>" --route /design-kit-preview/button --target "버튼 검증" --typeCheck --fontGate
- "다시 검증"(대시보드 버튼 · Claude Desktop의 재검증)은 처음 실행에서 켠 옵션을 그대로 이어받습니다.
--typeCheck는 정식 v0.5.0부터이고, --fontGate · --assetGate · --visualRegression은 (공개 전)입니다. 이어받지 않던 시절에는 옵션 검사로 FAIL한 기록을 "다시 검증"하면 파일이 그대로인데 PASS가 나와 완료 차단이 풀리는 우회로가 있었고, 직접 재현해 확인한 뒤 막았습니다. 다시 검증할 때 시각 회귀는 비교만 하고 기준 화면 승인은 하지 않습니다.
--screenshotDir(스크린샷 저장 위치)는 .design-kit/ 안쪽 경로만 허용합니다. ..로 바깥으로 나가는 값(예: ../../다른곳)은 아무것도 만들지 않고 오류(종료 코드 2)로 거부합니다 (공개 전) — 이전에는 이런 값을 주면 스크린샷이 프로젝트 밖에 저장되는 결함이 있었습니다.
7. 업데이트 내용 요약
아래 항목들은 접었다 펼 수 있는 "토글" 형태입니다 — 제목(▶ 표시가 있는 줄)을 클릭하면 자세한 내용이 펼쳐집니다. 가장 최근 것이 맨 위에 있습니다.
- 상태 구분: 아래 ①②는 코드에는 들어 있고 자동 테스트도 통과했지만, 이 문서를 쓴 시점에 아직 GitHub 병합 · 릴리스 전이라 GitHub에서 받을 수 있는 정식 버전(v0.5.0)에는 들어 있지 않습니다. ③은 이 README 자체의 정정입니다.
- ① 다시 검증의 우회로 나머지 3개를 막음: 바로 아래 v0.5.0 항목은
--typeCheck로 FAIL한 기록의 "다시 검증" 우회로만 막았습니다. 같은 구멍이 --fontGate · --assetGate · --visualRegression에도 있었습니다(옵션으로 FAIL한 기록을 다시 검증하면 파일이 그대로인데도 PASS — 폰트 · 자산 옵션은 직접 재현해 확인했고, 시각 회귀는 같은 구조라 함께 고쳤습니다). 이제 처음 실행에서 켠 옵션이 기록에 남고, 다시 검증이 그 옵션을 이어받습니다. 시각 회귀는 기준 화면과 비교만 하고, 기준 화면 승인은 사람이 직접 요청해야만 하도록 그대로 유지했습니다.
- ② 스크린샷 저장 경로가 프로젝트 밖으로 새던 결함을 막음:
--screenshotDir ../../ESCAPED처럼 ..로 바깥을 가리키면, 스크린샷이 프로젝트 밖에 저장되고도 성공(종료 코드 0)으로 끝나는 것을 직접 재현했습니다. 이제 .design-kit/ 안쪽이 아니면 아무것도 만들기 전에 거부하고(종료 코드 2), \ 구분자와 .design-kit-evil 같은 이름만 비슷한 옆 폴더도 막습니다. .design-kit/ 안에 머무는 ..(예: reports/../shots/x)는 막지 않습니다.
- ③ README 정정: 설치하면 복사본이 만들어지고 부품이 자동 설치된다는 점(이전 문서는 반대로 적혀 있었음), Node 최소 버전이 18이 아니라 20.9라는 점, 검증용 브라우저를 따로 받아야 한다는 점(이전 문서엔 단계가 없었음), 업데이트 방법, 재시도 횟수와 "연속 2회 실패" 규칙은 코드에 없다는 점,
config.json 값을 프로그램이 읽지 않는다는 점, 검증 옵션 표, 라이선스 패키지 수 재집계(153개), 저장소에 없는 파일로 연결된 깨진 링크 제거.
- 자동 테스트: 361개 → 374개(13개 추가, 테스트 파일 1개 신설) 전부 통과,
npm audit 0건. 새 부품(의존성) 추가 없음.
- 정직한 한계: ①은 실제 개발 서버 · 폰트 스캔 · 기준 화면 비교를 거친 실제 프로젝트 대상 종단 확인을 아직 하지 않았고(가짜 부품으로 바꿔 끼운 자동 테스트까지만 확인), 병합 · 릴리스 후에도 평소 쓰는 Claude Code에는 3장의 업데이트를 해야 반영됩니다.
- 지난번에 만든 선택형 검사
--typeCheck는 표준 절차의 실제 명령에는 들어 있지 않아, 평소 흐름에서는 한 번도 실행되지 않았습니다. 이제 pipeline·detail-page의 표준 검증 명령에 --typeCheck가 들어 있습니다(tsconfig.json이 있는 TypeScript 프로젝트).
- 타입 오류가 화면용 파일 밖(데이터·인증·저장·API 로직 파일)에 있으면, AI가 검사를 통과시키려고 그 파일을 고치지 않고 즉시 멈춘 뒤 사용자에게 보고하도록 지침을 넣었습니다. 검사를 실행하지 못한 경우(
tsconfig.json·typescript 없음, 시간 초과)도 재시도하지 않고 원인을 보고합니다.
- 직접 실험으로 우회로를 하나 찾아 막았습니다:
--typeCheck로 실패한 기록을 대시보드의 '재검증' 버튼이나 MCP reverify로 다시 돌리면, 파일이 그대로인데도 PASS가 나와 완료 차단이 풀렸습니다. 이제 재검증이 원래 실행의 타입 검사 설정을 이어받습니다(수정 전 PASS → 수정 후 FAIL, 파일을 원래대로 되돌리면 다시 PASS로 오탐 없음).
- 이 릴리즈에는 지난 릴리즈(v0.4.1) 이후 반영된 보안 취약점 5건 패치(sharp · MCP SDK 등)와 MCP 버전 표기 정정이 처음으로 함께 들어 있습니다. Claude Desktop 확장(
.mcpb)과 설치된 플러그인에 반영하려면 다시 만들고 재설치(완전 재시작)해야 합니다.
- 자동 테스트 361개 전부 통과,
npm audit 0건, 실제 화면 검증(정상/오류 판정과 완료 차단)도 다시 확인했습니다.
- 이 릴리스 시점에 아직 안 한 것: 시각 회귀·폰트·자산 선택 옵션은 재검증이 이어받지 않습니다(→ 바로 위 2026-10-12 항목에서 해결, 공개 전). lint·build는 여전히 검사하지 않습니다.
- 직접 실험해 보니, 화면에 쓰는 파일에 일부러 타입 오류를 넣어도 기존 검증은 PASS를 냈고 타입 검사 도구(
tsc --noEmit)만 실패했습니다. 개발용 화면은 타입 오류가 있어도 일단 그려지기 때문입니다.
verify-runner.mjs에 선택 옵션 --typeCheck를 추가했습니다. 기본은 꺼져 있습니다(이미 타입 오류가 있는 기존 프로젝트가 갑자기 FAIL로 바뀌지 않게). 켜면 타입 오류가 있을 때 FAIL이 나고, 검사를 실행하지 못했을 때도 FAIL입니다(조용히 통과시키지 않음). 개발 서버가 만드는 .next/ 폴더 파일의 오류는 제외합니다. --project 없이 쓰면 거부합니다.- lint(코드 스타일 검사)와 build(빌드)는 여전히 게이트가 실행하지 않습니다.
- 실제 프로젝트로 3가지를 확인했습니다: 일부러 넣은 오류 → FAIL, 원래 남아 있던 잔여 오류 → FAIL, 깨끗한 상태 → PASS. 자동 테스트 350개 전부 통과합니다.
npm audit(설치된 프로그램들의 알려진 보안 문제를 확인하는 명령)를 다시 돌리니 새로 5건(심각 1 · 높음 2 · 보통 2)이 보고됐습니다. 이 킷의 코드는 그대로이고, 보안 문제 목록이 갱신된 것입니다.- 5건 중 3건은 MCP(Claude Desktop 연결) 부품이 딸고 오는 간접 부품이고, 2건은 직접 설치한 이미지 처리 부품(sharp)과 MCP 부품 자체입니다. "높음 이상은 바로 조치" 규칙에 따라 전부 올렸습니다. 직접 설치 목록(
package.json)은 그대로이고 잠금 파일(package-lock.json)만 바뀌었습니다.
- Claude Desktop 확장(MCP)이 자신의 버전을
0.3.0이라고 잘못 알려주던 것을 package.json 버전(현재 0.4.1)을 따르도록 고쳤습니다(자동 테스트 1건 추가).
- 자동 테스트 334개 전부 통과,
npm audit 0건, 실제 화면 검증(정상/오류 판정과 완료 차단)과 실제 MCP 연결도 다시 확인했습니다.
- 이미 만들어 둔
.mcpb 파일과 설치된 플러그인에는 아직 반영되지 않았습니다(다시 만들고 재설치해야 반영됩니다).
- 바로 아래 두 항목(검증 대기시간 늘림, 보안 취약점 4건 수정)이 지난 정식 릴리즈(v0.4.0) 태그 이후에 추가됐는데, 태그·GitHub Release가 그 내용을 반영 못 하고 있었습니다.
- 코드나 문서를 새로 바꾼 것은 없고, 버전 번호만 0.4.0 → 0.4.1로 올리고 GitHub에 새 릴리즈로 등록했습니다(패치 버전 — 기능 추가가 아니라 이미 만든 수정사항을 정식 릴리즈에 포함시키는 작업입니다).
- 자동 테스트 333개 그대로 통과합니다.
- 컴퓨터를 막 켰거나 한동안 이 킷을 안 쓰다가 오랜만에 검증을 돌리면, 화면을 처음 준비하는 데 평소보다 시간이 좀 더 걸릴 수 있는데, 이 킷이 30초만 기다리고 "화면 준비 안 됨"으로 판단해 검증 자체를 실패 처리해버리는 문제가 있었습니다.
- 실제로 두 번(오늘과 지난 세션) 똑같이 재현해서 확인했습니다 — 같은 명령을 곧바로 한 번 더 실행하면 매번 정상적으로 성공했습니다. 즉 이 킷이 고장 난 게 아니라 "기다리는 시간이 조금 짧았다"는 뜻이었습니다.
- 기다리는 시간을 30초에서 60초로 늘려서 해결했습니다. 판정 로직 자체는 전혀 바꾸지 않았습니다. 자동 테스트 333개 전부 그대로 통과합니다.
- 11장 트러블슈팅에도 이 증상과 대처법을 추가했습니다.
npm audit(설치된 프로그램들의 알려진 보안 문제를 확인하는 명령)를 다시 돌려보니, 직접 설치한 적 없는데 다른 프로그램이 딸고 온 부품 4개에서 새로운 보안 문제(심각 2건 · 보통 2건)가 발견됐습니다 — 이 킷의 코드가 바뀐 게 아니라, 그 사이 보안 취약점 정보가 새로 등록된 것입니다.- 그중 하나(이미지 변환 프로그램 sharp)는 Figma에서 가져온 사진을 확인하는 데 실제로 쓰이는 부품이라, 버전을 한 단계만 올려서(0.35.3 → 0.35.4) 바로 해결했습니다. 나머지 3개는 Claude Desktop 확장 기능이 (이 킷은 안 쓰는) 다른 연결 방식을 대비해 딸고 온 것이라 실제 위험은 거의 없었지만, 마찬가지로 최신 버전으로 올려 전부 해결했습니다.
- 고친 뒤 자동 테스트 333개 전부 통과, 실제 화면 검증(정상/오류 판정과 완료 차단)도 다시 돌려 문제없음을 확인했습니다. 새 프로그램을 추가한 게 아니라 기존 프로그램들의 버전만 올린 것이라 동작 방식은 그대로입니다.
- 지난 릴리즈(0.3.0, 8월 19일)를 낸 뒤로 마케팅 이미지 3종 추가·라이선스 게이트 확장·AI 생성 이력 기록·Claude Desktop 확장·이번 보안 수정까지 반영되지 않고 있어, 버전을 0.4.0으로 올렸습니다.
- GitHub 저장소(공개 상태)의 보안 기능 3가지(비밀정보 자동 탐지 · 커밋 차단 · 오래된 의존성 자동 알림)가 열흘 넘게 꺼져 있던 걸 발견해서 켰습니다.
- 지금까지는 직접 설치하는 프로그램 8개만 라이선스를 확인했는데, 이번엔 그 8개가 딸려서 데려오는 나머지 프로그램까지 합쳐 총 126개 전부를 하나하나 확인했습니다. 문제가 될 만한 라이선스는 없었지만, 이미지 변환에 쓰는 프로그램(sharp)이 내부적으로 포함하는 부품 하나가 다른 종류의 라이선스(LGPL)를 쓰고 있다는 걸 새로 발견해서 13장에 정직하게 적어뒀습니다(법적으로 문제는 없습니다).
- 실제 발견한 결함: Claude Desktop용 확장 파일(
.mcpb)을 만들 때, 원래는 실행에 필요한 프로그램 코드만 들어가야 하는데, 실수로 이 킷 개발 중에만 쓰는 내부 기록 파일(CHECKPOINT.md 등)과 전혀 상관없는 대용량 테스트 파일까지 통째로 같이 포장되고 있었습니다. 즉시 원인부터 고쳐서, 확장 파일 용량이 약 70MB에서 약 20MB로 줄었고, 문제였던 파일들은 전부 빠진 것을 확인했습니다.
- 자동 테스트는 그대로 330개이며(이번 라운드는 문서 · 저장소 설정 수정), 330개 전부 통과합니다. 새로운 프로그램(의존성)은 추가하지 않았습니다.
- Figma 디자인 안에 사진이나 아이콘이 들어있는 화면을 코드로 만들 때, 지금까지는 그 이미지 주소를 임시 주소 그대로 코드에 넣고 있었습니다. 이 임시 주소는 Figma가 7일 뒤에 없애버리는 주소라서, 시간이 지나면 화면에서 그림이 갑자기 사라지는 문제가 있었습니다.
- 처음부터 이 문제가 있다는 건 문서에 적혀 있었지만, 실제로 막아주는 장치는 없이 "알아서 조심하기"에만 의존하고 있었다는 걸 이번에 재확인해서 고쳤습니다.
- 이제부터는 이미지가 있는 화면을 만들 때 그 이미지를 자동으로 내 프로젝트 폴더 안에 내려받아 저장하고, 코드에는 그 저장된 파일을 가리키게 만듭니다 — 7일이 지나도 그림이 사라지지 않습니다.
- 안전장치도 같이 넣었습니다: 진짜 이미지 파일이 맞는지 확인 후에만 저장하고, 아이콘 파일(SVG) 안에 위험한 코드가 숨어 있으면 저장을 거부합니다.
- 자동 테스트 15개 추가(314→329개), 전부 통과. 새로운 프로그램(의존성)은 추가하지 않았습니다.
- Claude Desktop 확장(바로 아래 항목에서 처음 추가)에 기능 1개를 더했습니다 —
component-map.json에 이미 등록된 컴포넌트를 검증용 프리뷰 화면에 다시 연결하는 기능입니다.
- 이 기능을 설계하면서 중요한 걸 하나 확인했습니다: 이 킷은 "Figma 디자인을 읽어서 새 코드를 자동으로 쓰는" 기능과 "이미 있는 컴포넌트를 프리뷰에 연결하는" 기능이 완전히 다른 위험 등급이라는 걸 코드를 직접 열어 확인했습니다. 전자(새 코드를 실제로 프로젝트에 쓰는 것)는 Claude Desktop에 "검증 통과 전엔 완료로 인정 안 함"을 강제하는 장치가 없어서, 검증 안 된 코드가 조용히 프로젝트에 들어갈 수 있는 위험이 있습니다.
- 그래서 이번엔 안전한 쪽(이미 있는 컴포넌트를 프리뷰에 연결하는 것)만 추가했고, 위험한 쪽(새 코드를 프로젝트에 쓰는 것)은 의도적으로 포함하지 않았습니다.
- 자동 테스트 6개 추가(308→314개), 전부 통과. 새로운 프로그램(의존성)은 추가하지 않았습니다(기존 기능을 그대로 재사용).
- 실제 테스트 프로젝트로 "컴포넌트를 프리뷰에 연결→재검증까지" 왕복이 실제로 되는 것을 직접 확인했습니다.
- 바로 아래 두 기능(Claude Desktop용 확장, 마케팅 이미지 규격 추가)을 다시 꼼꼼히 확인하는 과정에서 실제 문제 2건을 찾아 고쳤습니다.
- ① Claude Desktop 확장에서 "어느 프로젝트인지" 값을 빈 값으로 잘못 보내면, 오류로 알려주는 대신 엉뚱하게 확장 프로그램 자신이 있는 위치를 대상으로 삼아버리는 문제가 있었습니다. 이제는 빈 값을 주면 바로 명확한 오류로 알려줍니다.
- ② 명함 이미지를 만들 때 "추가 정보"(회사·전화번호 등)를 정해진 형식이 아닌 값으로 잘못 넣으면, 오류 없이 조용히 글자가 한 자씩 따로따로 그려진 잘못된 이미지가 만들어지고, 한참 뒤 엉뚱한 단계에서 알아보기 어려운 오류가 나는 문제가 있었습니다. 이제는 잘못된 형식을 넣는 즉시 명확한 오류로 알려줍니다.
- 재확인 결과 이 두 가지 외에 새로 발견된 문제는 없었습니다(경로 조작·비정상적으로 긴 입력값·잘못된 형식의 다른 값들은 전부 기존대로 안전하게 처리됨을 재확인).
- 자동 테스트 4개 추가(305→308개), 전부 통과. 새로 추가한 기능·명령은 없습니다(기존 기능의 안전장치 보강).
- 지금까지는 Claude Code(터미널형 채팅)에서만 이 킷을 쓸 수 있었는데, 이제 Claude Desktop(일반 데스크톱 앱)에서도 검증 이력·판정서·스크린샷을 보고 재검증을 실행할 수 있는 확장(
.mcpb 파일)을 만들 수 있습니다.
- 설계 도중 중요한 사실을 하나 발견했습니다 — 원래 계획은 "이미 있는 대시보드(웹 서버)를 그대로 같이 쓴다"였는데, 실제로 Claude Desktop의 이런 확장은 웹 서버 방식이 아니라 완전히 다른 방식(프로그램을 직접 실행해서 대화하는 방식)으로 동작한다는 걸 공식 문서를 직접 찾아보고 알게 됐습니다. 그래서 "서버를 같이 쓴다"가 아니라 "이미 만들어둔 기능을 그대로 재사용한다"는 더 간단한 방식으로 다시 설계했습니다.
- 정직하게 밝혀둘 점: 이 확장은 "검증 결과를 보여주는 것"까지만 하고, Claude Code처럼 실패했을 때 작업을 강제로 멈추는 기능은 없습니다(Claude Code 전용 기능이라 기술적으로 다른 프로그램에서는 안 됩니다). 이 사실을 도구 설명 자체에 명시해뒀습니다.
- 신규 자동 테스트 16개 추가(289→305개), 전부 통과. 새 의존성 2개(공식 MCP 도구 · 입력값 검증 도구) 추가,
npm audit 0건 유지.
- 다음 범위(Figma 데이터를 받아 코드를 직접 생성하는 기능)는 이번엔 포함하지 않았습니다 — 이번엔 "검증 이력을 보고 재검증하는 기능"까지만 먼저 확실하게 만들었습니다.
- 지금까지는 SNS 공유용 이미지(OG, 1200×630) 1가지만 만들 수 있었는데, 이제 포스터(1080×1350, 인스타그램 세로형) · 배너(1200×400, 가로형) · 명함(1050×600, 실제 명함 인쇄 규격) 3가지를 더 만들 수 있습니다.
- 명함은 이름·직함만으로는 부족해서(회사·전화번호·이메일 등도 필요) 여러 줄을 추가로 넣을 수 있는 기능(
--extraLines)을 새로 만들었습니다.
- 이전에 만든 OG 이미지 기능 자체가 "규격 하나를 검증했다고 다른 규격도 똑같이 되는 건 아니다"라고 미리 경고해뒀던 대로, 3가지 규격을 각각 실제로 만들어보고 눈으로 직접 확인했습니다(글자가 안 잘리고, 한글이 깨지지 않는지).
- 신규 자동 테스트 10개 추가(279→289개), 전부 통과. 새 의존성 없음(
npm audit 0건 유지).
- Phase 3 진행 순서의 네 번째 항목을 완료했습니다. 지금까지는 폰트만 "어디서 가져왔는지·무슨 라이선스인지"를 자동 기록·검사했는데, 이제 이미지·아이콘 파일도 같은 방식으로 확인할 수 있습니다(선택 기능 — 원할 때만 켬).
- 마케팅 이미지 자동 생성 기능(바로 아래 항목)이 만든 이미지와 검증용 스크린샷은 이 검사 대상이 아닙니다 — 그건 이미 다른 기록(AI 생성 이력)에 남기 때문입니다. 이 경계를 처음부터 정확히 설계하고 실제 프로젝트로 확인했습니다.
- 출처 정리 문서(
ATTRIBUTION.md)를 자동으로 만들어주는 기능도 함께 추가했습니다.
- 실측 검증: 실제 픽스처 프로젝트에 원래 있던 등록 안 된 이미지 파일(기본 아이콘 5개+파비콘 1개)이 정확히 걸리는 것을 확인했고, 그중 하나를 대장에 등록하니 그 파일만 정확히 목록에서 빠지는 것도 확인했습니다.
- 신규 자동 테스트 26개 추가(246→272개), 전부 통과. 새 의존성 없음(
npm audit 0건 유지).
- 새로 만든 기능(AI 생성 이력 기록·마케팅 소재 생성)을 정상 상황뿐 아니라 예외·실패 상황까지 폭넓게 재검증하다가 진짜 문제 3가지를 찾아 고쳤습니다.
- ① 존재하지 않는 프로젝트 경로를 주면 조용히 새 폴더를 만들어버리던 문제 → 명확한 오류 메시지로 바꿨습니다.
- ② 입력한 문구에 코드블록(백틱 3개)이 들어가면 기록 파일의 서식이 깨질 수 있던 문제 → 항상 안전하게 감싸도록 고쳤습니다.
- ③ 문장부호만 다른 비슷한 제목으로 이미지를 두 번 만들면 첫 번째 이미지가 조용히 사라지던(덮어써지던) 문제 → 자동으로 구분되도록 고쳤습니다.
- 회귀 테스트 5개를 추가했고, 전부 통과합니다(241개 → 246개).
- 제목·부제목을 주면 SNS 공유용 이미지(1200×630 규격)를 자동으로 만들어주는 기능을 추가했습니다.
- 한글 글자가 깨지지 않는지 이 컴퓨터에 실제로 설치해서 먼저 확인한 뒤 착수했습니다.
- 만들어진 이미지가 규격·형식·용량 기준을 통과하지 못하면 아예 파일을 만들지 않습니다 — "검증 없이 결과물이 나오지 않는다"는 이 킷의 원칙을 이미지에도 그대로 적용했습니다.
- 포스터·배너·명함 등 다른 규격은 이번 범위가 아니며, 나중에 추가할 때는 각각 따로 실제 검증을 거칩니다.
- 신규 자동 테스트 17개를 추가했고, 전부 통과합니다(224개 → 241개).
- 에이전트가 자유롭게 작성하는 콘텐츠(현재는 상세페이지 카피)를 언제·어떤 모델로·어떻게 만들었는지 자동으로 기록에 남기는 기능을 추가했습니다.
- 이 기록 파일은 검증 스크린샷 등과 달리 저장소에 실제로 커밋되는 파일이라, 프로젝트가 공개 저장소라면 기록에 시크릿(비밀번호·API 키 등)이 그대로 남을 위험이 있었습니다 — 기록하기 전에 항상 시크릿 패턴을 걸러내는 필터를 적용해 이 위험을 막았습니다.
- 신규 자동 테스트 18개를 추가했고, 전부 통과합니다(206개 → 224개).
- Phase 3(마케팅 소재+상세페이지+공개 검토)의 전제 조건("Phase 1+2가 본인 실사용에서 안정적")이 사용자의 실제 라이브 테스트(대시보드 스크린샷 확인 + 재검증 버튼 정상 작동 확인)로 충족되어, Phase 3의 첫 기능으로 상세페이지 파이프라인을 구현했습니다.
- 하는 일: 상품 데이터 파일(CSV 또는 JSON) 한 개에서 상품을 골라 카피(제목 · 핵심 장점 · 설명 · 자주 묻는 질문)를 작성하고, 그 카피를 보여주는 상세페이지 코드로 연결한 뒤 기존과 동일한 검증 게이트(실브라우저+접근성 검사+3개 화면 크기)를 통과해야 완료로 표시됩니다.
- 설계 원칙: 상품마다 새 페이지 파일을 만드는 대신, 페이지 템플릿은 1개만 만들고 상품 데이터만 상품마다 따로 저장합니다 — 이 킷이 스스로 "새 파일을 가장 많이 만드는 단계라 위험이 가장 크다"고 표시해둔 단계라, 파일 수를 늘리지 않는 방향으로 그 위험을 낮췄습니다.
- 실측 검증: 실제 픽스처 프로젝트에 더미 상품 데이터를 넣어 전체 과정을 실행해 PASS를 확인했고, 일부러 접근성 결함(대체 텍스트 없는 이미지)을 주입해 게이트가 실제로 FAIL을 내는 것까지 확인한 뒤 원상복구해 다시 PASS로 돌아오는 것까지 확인했습니다.
- 신규 자동 테스트 22개 추가(178→200개), 전부 통과. 새 의존성 없음(
npm audit 0건 유지).
- 상품 생성 이력을 자동으로 남기는 기능(AI-GENERATION-LOG.md)과 마케팅 이미지 소재 파이프라인은 다음 증분으로 남겨뒀습니다(이번 범위 아님).
- Phase 2가 처음으로 "AI가 픽스처로 검증"이 아니라 사용자 본인이 새 대화창을 열어 직접 사용하는 방식으로 시험됐습니다:
/sodam-design-kit:open(대시보드 열기) → 판정서 열람 → 재검증 버튼 클릭 → 폰트/화면 변경 감지 기능에 대한 자연어 질문까지 전부 직접 실행했습니다.
- 그 과정에서 진짜 결함 1건을 발견했습니다: 자체 점검(
e2e-selftest)이 만든 판정서에 원래 검사했던 화면 주소(route)가 기록되지 않아서, 대시보드의 "재검증" 버튼을 눌러도 영구적으로 재검증이 안 되는 문제였습니다. 발견 즉시 수정하고 재검증까지 마쳤습니다.
- 대시보드를 열고 판정서를 눌러보는 것까지는 "본인 실사용으로 확인됨"이라 볼 수 있지만, 폰트 자동화 · 화면 변경 감지 기능 자체를 명령으로 직접 켜본 것은 아니라서, 완전한 "실사용 확인"으로 보기엔 아직 이릅니다.
- 대시보드 화면(2026-08-09 완료 선언)이 실은 판정 스크린샷을 브라우저에 한 번도 제대로 못 보여주고 있었다는 것을, 이번에 헤드리스(눈에 안 보이는) 브라우저로 실제 화면을 열어보고서야 발견했습니다.
- 원인은 두 가지가 겹쳐 있었습니다: ① 이미지 파일 경로 앞부분이 중복으로 붙어 "파일을 찾을 수 없음(404)" 오류가 났고, ② 보안 설정(CSP)이 이미지가 사용하는 특수한 형식(blob:)을 허용하지 않아 브라우저가 화면 표시 자체를 차단했습니다. 둘 다 화면이 "조용히" 안 보이기만 하고 프로그램이 죽지는 않아서 지금까지 발견되지 않았습니다.
- 수정 전(콘솔 오류 3건) → 원인 하나씩 해결하며 재확인 → 수정 후(콘솔 오류 0건, 이미지 3개가 실제 픽셀로 화면에 나타남)까지 직접 확인했습니다. 자동 테스트가 175개 → 178개로 늘었고 전부 통과합니다.
- 교훈: "검증 완료"라고 표시된 과거 기능이라도, 실제 화면 요소(이미지 등)까지 사람 눈으로 본 것이 아니라 데이터 차원에서만 확인했을 가능성이 있다는 것을 이번에 알게 되었습니다. 앞으로 화면 관련 기능은 눈에 보이지 않는 자동화 브라우저로 실제 픽셀까지 확인하는 것을 기본으로 삼기로 했습니다.
- 프로젝트가 정식으로 등록해둔 한글 폰트가 아닌, 출처를 알 수 없는 폰트 파일이 섞여 있으면 검증을 실패(FAIL) 처리하는 검사를 새로 추가했습니다(선택 기능 — 켜고 싶을 때만
--fontGate 옵션으로 켤 수 있습니다).
- 실측 검증: 일부러 등록되지 않은 폰트 파일을 프로젝트에 넣고 검사를 돌려 실제로 FAIL이 뜨는 것을 확인했고, 그 파일을 지운 뒤 다시 PASS로 돌아오는 것까지 확인했습니다. 이미 정식 등록된 폰트(예: Pretendard)는 이 검사로 인해 잘못 걸리지 않는 것도 함께 확인했습니다.
- 자동 테스트가 157개 → 172개로 늘었고 전부 통과합니다.
- 대시보드가 판정서를 화면에 보여줄 때, "화면 변경 감지(시각 회귀)" 결과를 적어둔 부분을 스크린샷 파일로 착각해서 잘못 표시하려던 결함을 발견해 고쳤습니다.
- 스크린샷 파일이 손상돼 있을 경우 검증 프로그램 전체가 멈춰버리던(크래시) 결함도 함께 발견해 고쳤습니다 — 이제는 손상된 파일 1개 때문에 전체 검증이 멈추지 않습니다.
- 자동 테스트가 155개 → 157개로 늘었고 전부 통과합니다.
- 지금까지는 프로젝트에 한글 폰트를 직접 준비해서 넣어야 했지만, 이제는 상업적 이용이 자유로운 오픈소스 한글 폰트(Pretendard, Noto Sans KR) 중에서 골라 자동으로 다운로드하고 프로젝트에 바로 쓸 수 있게 설정해주는 기능이 생겼습니다.
- 다운로드한 폰트가 어떤 라이선스인지 자동으로 기록해두는 대장(
ASSET-LEDGER.csv)도 이때 처음 만들어졌습니다 — 나중에 "이 폰트를 어떤 조건으로 썼는지" 확인이 필요할 때 참고할 수 있습니다.
- 실측 검증: 실제 인터넷에서 Pretendard 폰트 파일(약 1.5MB)을 실제로 내려받는 것까지 확인했고, 같은 명령을 다시 실행해도 중복으로 받지 않는 것(멱등성)도 확인했습니다.
- 자동 테스트가 143개 → 155개로 늘었고 전부 통과합니다.
- 코드를 고친 뒤 화면이 이전과 비교해 실수로 달라지지는 않았는지, 스크린샷을 픽셀 단위로 자동 비교해주는 기능이 생겼습니다(선택 기능 —
--visualRegression 옵션으로 켤 수 있습니다). "이 화면이 맞다"고 사람이 승인한 기준 화면과 비교하는 방식이며, 기준 화면 승인은 반드시 검증을 통과(PASS)한 화면에 대해서만, 사람이 직접(--promoteBaseline) 하도록 만들어져 있습니다.
- 실측 검증: 기준 화면을 승인한 뒤 아무것도 안 바꾸면 "동일함"으로 나오는 것, 일부러 배경색을 바꾸면 3개 화면 크기 전부에서 "달라짐"으로 잡히며 검사가 실패(FAIL)하고 차이를 보여주는 이미지가 실제로 생성되는 것, 원상복구하면 다시 "동일함"으로 돌아오는 것까지 전부 확인했습니다.
- 자동 테스트가 135개 → 143개로 늘었고 전부 통과합니다.
- 이 킷이 자동으로 만드는 미리보기 화면에 "제목(
<h1>)이 없다"는 경미한 접근성 경고가 있었습니다. 화면에는 보이지 않지만 스크린 리더는 인식할 수 있는 방식으로 제목을 추가해 해소했습니다.
- 실측 검증: 실제로 다시 검증을 돌려 이 경고가 사라진 것(1건 → 0건)을 확인했습니다.
- 자동 테스트가 134개 → 135개로 늘었고 전부 통과합니다.
- 그동안 판정서 · 실행 기록은 파일로만 존재해서 하나하나 직접 열어봐야 했습니다. 이제
/sodam-design-kit:open 명령 하나로, 지금까지의 검증 이력을 브라우저 화면(대시보드)에서 한눈에 보고, 그 자리에서 바로 재검증까지 실행할 수 있습니다.
- 안전장치: 대시보드는 내 컴퓨터 자신(
127.0.0.1)에서만 접속 가능하고, 로그인 정보나 비밀번호 없이도 안전하도록 여러 겹의 보호 장치(경로 조작 시도 차단, 잘못된 요청 차단, 파이프라인 실행 중에는 재검증 요청을 거부하는 잠금 장치 등)를 함께 만들고 각각 실제로 공격을 흉내 내 막히는지 확인했습니다.
- 실측 검증: 실제로 대시보드를 켜서 → 브라우저에 정상적으로 화면이 뜨는 것 → 이미 켜져 있으면 새로 켜지 않고 재사용하는 것 →
--stop으로 끄면 정말로 꺼지는 것까지 전 과정을 실제로 확인했습니다.
- 자동 테스트가 123개 → 134개로 늘었고 전부 통과합니다.
- 완료 선언 전 마지막 관문("완전히 새로운 대화(세션)에서 처음부터 재현하기")을 실제로 4번 시도했습니다. 그 과정에서 이전에는 드러나지 않았던 진짜 결함 3가지를 실사용 중에 발견해서 고쳤습니다:
- 스크린샷이 프로젝트 폴더 밖(사용자의 다른 폴더)에 저장되던 문제: 검증 결과 스크린샷을 저장하는 경로를 상대 경로로 처리할 때, "지금 어느 폴더에서 실행 중인지"에 따라 엉뚱한 곳에 저장될 수 있었습니다. 판정서에는 "성공"이라고 정확히 적혀 있었지만, 정작 그 파일이 프로젝트 안에는 없는 상황이 실제로 발생했습니다. 이제는 항상 프로젝트 폴더를 기준으로 저장 위치를 다시 계산하도록 고쳤습니다.
- 스크린샷이
.design-kit 폴더 밖(같은 프로젝트 안이지만 관리 대상 밖)에 저장되던 문제: 1번을 고친 직후 발견한 조금 더 미묘한 문제입니다 — 프로젝트 폴더 "안"에는 저장되지만, 이 킷이 정식으로 관리하는 .design-kit/ 폴더 "밖"에 저장되어 자동 정리 대상에서 빠지고, git에 실수로 올라갈 수 있는 위치에 남는 문제였습니다. 기준 위치를 .design-kit/ 폴더 자체로 다시 잡아 해결했습니다.
- 이미 매핑된 컴포넌트인데도 Figma 파일 주소를 다시 물어보던 문제: "재사용" 경로(이미 연결된 컴포넌트를 다시 쓰는 경우)는 원래 Figma를 다시 호출할 필요가 없도록 설계되어 있었는데, 실행 절차 문서의 한 단계가 이 조건을 확인하지 않고 무조건 Figma 주소를 요구하도록 되어 있어서, 이미 연결이 끝난 컴포넌트인데도 진행이 멈추는 문제가 있었습니다. 절차 맨 앞에 "이미 연결돼 있으면 건너뛴다"는 확인 단계를 추가해 해결했습니다.
- 세 가지를 전부 고친 뒤 네 번째 시도에서 마침내 완전히 성공했습니다 — 임시로 급하게 짜맞춘 코드 없이, 기존 판정 기록을 하나도 지우지 않고, 스크린샷도 정확한 위치에 저장된 채로 끝까지 통과했습니다.
- 이로써
.PRD/01_PRD.md §9(성공 기준) 6개 항목이 전부 실제 증거로 충족되어, Phase 1(MVP)을 공식적으로 완료 처리했습니다.
- 자동 테스트는 68개 그대로이며(이번 라운드는 문서 · 실행 절차 수정이 대부분), 68개 전부 통과합니다.
- 자체 점검 명령이 조용히 엉뚱한 걸 실행하고 있던 문제: 이 킷을 관리하는 개발자가 쓰는
npm run selftest 명령이, 실제로는 존재하지 않는 옵션을 가리키고 있어서 진짜 점검(scripts/e2e-selftest.mjs)은 실행되지 않고 사용법 안내만 나오는 상태였습니다. 사용자가 이 명령을 직접 쓸 일은 없습니다 — 이 문서는 항상 올바른 스크립트 실행 방법을 안내해 왔으므로, 지금까지 이 문서를 따라온 사용자에게는 영향이 없었습니다. 그래도 발견 즉시 올바른 스크립트를 가리키도록 고쳤습니다.
- 정해진 순서(setup → pipeline)를 따르지 않고 검증만 따로 실행하면 스크린샷이 git에 노출될 수 있던 구멍: 이 킷을 안내된 순서대로 쓰면 스크린샷 폴더가 자동으로
.gitignore에 등록되지만, setup을 거치지 않고 검증 기능만 독립적으로 실행하는 예외적인 경로(주로 킷 개발자의 자체 테스트용)에서는 이 등록이 빠져 있는 것을 실제로 재현해서 확인했습니다. 판정서를 기록하는 코드에도 같은 등록 로직을 추가해 막았습니다. 이 경로 역시 안내된 순서대로 사용해 온 사용자에게는 영향이 없었습니다.
- 두 수정 모두 기존 자동 테스트 66개에 영향 없이 그대로 전부 통과합니다.
- 예전엔 접근성 검사(axe-core)가 실패해도 판정서에 "critical 1건"처럼 개수만 적혀 있어서, 정확히 어떤 부분이 왜 잘못됐는지는 사람이 다시 찾아봐야 했습니다.
- 이제는 판정서의 "위반 상세" 항목에 규칙 이름 · 설명 · 문제가 된 화면 요소까지 구체적으로 적히도록 만들었습니다. 자동 재시도 때도 이 상세 내용을 다음 시도에 참고하도록 넘겨줘서, 같은 이유로 계속 실패하는 상황을 줄입니다.
- 자동 테스트 5개를 새로 추가했고, 전부 통과합니다(61개 → 66개).
- 지금까지는 Figma에서 이미 매핑해둔 컴포넌트를 "재사용"하는 경로만 실제로 검증됐고, 매핑이 아예 없는 새 컴포넌트를 처음부터 만드는 기능은 계획만 있고 구현되지 않은 상태였습니다.
- 이제 이 경로도 실제로 구현하고 검증까지 마쳤습니다. 새로 만든 코드를 프로젝트에 배치하기 전에, 색상 · 간격 값이 숫자로 하드코딩되어 있으면(예:
#ff0000, 12px) 자동으로 배치 자체를 거부하도록 만들어서, 프로젝트가 원래 쓰던 디자인 값(토큰)을 우회하는 코드가 섞여 들어가는 것을 원천적으로 막습니다.
- 자동 테스트 8개를 새로 추가했고, 전부 통과합니다(53개 → 61개).
- 가장 심각했던 문제 — 검사한 게 진짜 내 프로젝트가 아닐 수도 있었습니다: 이 킷은 검사용 화면을 띄울 때 사용 중인 포트(예: 3000번)를 피해서 자동으로 다음 포트를 쓰도록 되어 있는데, 컴퓨터에 이미 다른 프로그램(예: 다른 프로젝트의 개발 서버)이 그 포트를 쓰고 있어도 "비어있다"고 착각하는 경우가 있었습니다. 이렇게 되면 검사 프로그램이 내 화면이 아니라 완전히 다른 프로그램의 화면을 열어서 검사하고서도, 마치 내 프로젝트를 검사한 것처럼 보이는 판정서를 만들어냈습니다.
- 실제로 이 문제가 일어나는 상황을 발견했습니다: 전혀 관련 없는 다른 프로젝트의 개발 서버가 3000번 포트를 쓰고 있었는데, 이 킷이 그 포트를 "비어있다"고 착각해서 그 다른 프로그램의 화면을 검사하고 있었습니다.
- 포트가 실제로 쓰이고 있는지 확인하는 방식을 더 정확한 방법으로 바꿔서 해결했습니다. 다른 프로그램이 여전히 포트를 쓰고 있는 상태에서 다시 확인해보니, 이번엔 정확히 다음 포트로 피해가서 내 프로젝트만 정확히 검사하는 것을 확인했습니다.
- 앞으로 같은 문제가 다시 생기면 자동으로 잡히도록 자동 테스트 1개를 새로 넣었습니다.
- 이 수정 덕분에 자동 테스트가 53개가 되었고, 53개 전부 통과합니다(2026-07-27 실제 실행 확인).
- 가장 중요한 수정 — "완료 차단"이 조용히 사라지던 문제: 이 킷이 설치된 폴더 경로에 띄어쓰기(예:
My Projects)나 한글(예: 윈도우 사용자 이름이 한글일 때 C:\사용자\홍길동\...)이 들어 있으면, 검사 프로그램이 아무 일도 안 하고 조용히 끝나는 문제가 있었습니다. 오류 메시지조차 안 나와서 사용자 입장에선 "잘 된 것처럼" 보입니다. 특히 완료를 막아주는 부분(hooks/verify-gate.mjs)에서 이 일이 벌어지면 검사 실패인데도 "완료"라고 보고되는 것을 못 막게 됩니다. 이 킷의 존재 이유가 사라지는 셈이라 가장 먼저 고쳤습니다.
- 실제로 세 가지 경로에서 재현해 확인했습니다: 띄어쓰기 있는 폴더 → 꺼짐 / 한글 폴더 → 꺼짐 / 영문 폴더 → 정상. 고친 뒤에는 세 경우 모두 정상입니다.
- 고치기 전 버전을 한글+띄어쓰기 폴더에서 직접 실행해 정말 아무것도 출력하지 않는 것을 눈으로 확인했고, 고친 버전은 같은 자리에서 정상적으로 "차단" 판정을 출력합니다.
- 앞으로 같은 문제가 다시 생기면 자동으로 잡히도록, 일부러 띄어쓰기와 한글이 들어간 폴더에서 실행해보는 자동 테스트 2개를 새로 넣었습니다.
- 자동 테스트가 실제로는 1개 실패하고 있었던 문제: 문서에는 "50개 전부 통과"라고 적혀 있었지만, 실제로 돌려보니 49개만 통과했습니다. 원인은 테스트 하나가 "2026년 7월 20일"이라는 날짜에 묶여 있어서 그 날 하루만 통과하고 다음 날부터 깨지는 구조였기 때문입니다. 날짜를 밖에서 넣어줄 수 있게 고쳐서 해결했습니다(실제 사용에는 아무 영향 없음).
- 위 두 가지를 합쳐 자동 테스트가 50개 → 53개가 되었고, 53개 전부 통과합니다(2026-07-27 실제 실행 확인).
- 검증과 판정서 기록을 명령 하나로 통합: 예전에는 "실제 브라우저 검증"과 "그 결과를 기록으로 남기기"가 별개 단계처럼 문서에 적혀 있었지만, 실제로는 기록 스크립트에 명령 실행 방법(CLI)이 없어서 AI가 매번 임시로 이어붙이는 코드를 직접 짜야 했습니다. 이제
verify-runner.mjs에 --target 옵션을 추가해 검증과 기록이 명령 하나로 끝나도록 고쳤습니다.
- 판정 기록이 조용히 사라지는 버그 수정: 판정서 파일 이름에 붙는 순번을 "지금까지 만들어진 파일 개수"로 계산하고 있었는데, 중간 파일이 하나라도 지워지면 이미 있는 번호와 겹쳐서 서로 다른 실행 결과가 파일 1개로 덮어써지며 사라지는 문제가 실제로 발생했습니다. 순번을 "실제로 존재하는 가장 큰 번호 + 1"로 계산하도록 고쳤고, 이 상황을 그대로 재현하는 자동 테스트 2개를 추가했습니다.
- 이 두 수정 덕분에 자동 테스트가 48개 → 50개로 늘었고, 전부 통과합니다.
- 초기 설정(setup), 디자인→코드 생성(pipeline-codegen), 미리보기 화면 자동 생성(preview-route), 실제 브라우저 검증(verify-runner), 판정서 기록(report-writer), 완료 차단 훅(verify-gate)까지 핵심 스크립트를 모두 구현했습니다.
- 실제 Figma 커뮤니티 파일(Coffee Shop Mobile App)의 화면 하나를 읽어 코드로 만들고, 실제 브라우저 검증까지 통과(PASS)하는 전체 과정을 실측으로 확인했습니다.
- 완전히 새로운 대화(세션)에서 설치부터 다시 해봐도 똑같이 동작하는지 확인했습니다(단, 이때는 위 항목의 수정이 있기 전 버전으로 확인한 것이라 — 고쳐진 버전으로 다시 한번 확인하는 절차가 남아 있습니다).
앞으로의 변경 사항은 이 섹션에 날짜순으로 계속 추가됩니다. 전체 개발 이력(내부 감사 기록 포함)의 정본은 .PRD/README.md입니다.
8. 워크플로우
사용자 Claude Code(AI) 이 킷의 코드
│ │ │
│ "이 버튼 코드로 만들어줘" │ │
├──────────────────────▶│ │
│ │ Figma 디자인 읽기 (MCP/커넥터) │
│ │◀── 레이어 구조 · 색상 · 글자 크기 ──┤
│ │ │
│ │ component-map.json에 매핑 기록 │
│ ├───────────────────────────▶│
│ │ │
│ │ shadcn/ui 코드 생성 요청 │
│ ├───────────────────────────▶│
│ │◀── 생성된 .tsx 파일 ────────────┤
│ │ │
│ │ 개발 서버 자동 실행 │
│ │ → 자동화 브라우저(Playwright)로 열기│
│ │ → 접근성 검사(axe-core) │
│ │ → 360px · 768px · 1440px 3종 검사│
│ │◀── PASS 또는 FAIL 판정 ─────────┤
│ │ │
│ ┌───── PASS ─────┐ │ 판정서(runs/·reports/) 기록 │
│ │ "완료" 보고 가능 │◀──┤ │
│ └───────────────┘ │ │
│ ┌───── FAIL ─────┐ │ AI가 사유 읽고 고쳐 재검증 │
│ │ 완료 보고가 │◀──┤ (권장 최대 3회 — 문서 지시) │
│ │ 훅으로 차단됨 │ │ │
│ └───────────────┘ │ │
핵심은 마지막 갈림길입니다: 검증 결과가 FAIL로 기록되면 "완료"라고 말하는 것 자체를 hooks/verify-gate.mjs가 기계적으로 막습니다. AI가 FAIL을 못 본 척하거나 눈속임하려 해도 소용없습니다.
이 차단이 정확히 어떤 조건에서 걸리는지(코드 hooks/verify-gate.mjs로 확인):
.design-kit/runs/의 가장 최근 실행 기록 1건이 FAIL이면 차단합니다. "연속 2회 실패" 같은 조건은 없습니다 — FAIL 한 번이면 그 기록이 최신인 동안 막힙니다. 이후 새 PASS 기록이 생기면 풀립니다.- 실행 기록 폴더를 읽을 수 없거나 가장 최근 기록 파일이 손상돼 있어도 차단합니다(원인을 따로 안내).
.design-kit/runs/ 폴더 자체가 없거나 기록이 하나도 없으면 막지 않습니다(이 킷을 쓰지 않은 프로젝트에서 방해하지 않기 위함). 즉 검증을 아예 돌리지 않고 "완료"라고 말하는 것은 이 훅이 막지 못합니다. 그 경우를 막는 것은 절차 문서(commands/pipeline.md)와 AGENTS.md의 "PASS 판정서 없이 완료 보고 금지" 지시이고, 이는 AI가 따르도록 한 지시일 뿐 기계적 강제가 아닙니다. 그래서 "완료"라는 말을 믿기 전에 .design-kit/reports/에 최신 PASS 판정서가 있는지 직접 열어 확인하는 습관을 권합니다.- 훅은 Claude Code가 열려 있는 폴더의
.design-kit/runs/만 봅니다. 대상 프로젝트가 아닌 다른 폴더에서 Claude Code를 열고 작업하면 그 프로젝트의 FAIL 기록은 보지 못합니다.
- 이 훅은 Claude Code 전용입니다. Claude Desktop 확장이나 다른 도구에는 없어서, 거기서는 결과를 보여줄 뿐 막지는 못합니다(3장 보충 참고).
9. 아키텍처 · 파일/문서 위치
이 킷 저장소 자체의 구조
SoDam-Design-Kit/ ← 이 킷의 저장소(지금 이 README가 있는 폴더)
├── .claude-plugin/
│ ├── plugin.json ← 플러그인 설명서(이름 · 버전)
│ └── marketplace.json ← 마켓플레이스 등록 정보(마켓 이름: sodam)
├── manifest.json ← Claude Desktop용 확장(.mcpb) 설명서 — plugin.json과는 별개 파일 (Phase 3)
├── commands/
│ ├── setup.md ← /sodam-design-kit:setup 명령의 실제 정의
│ ├── pipeline.md ← /sodam-design-kit:pipeline 명령의 실제 정의
│ ├── open.md ← /sodam-design-kit:open 명령의 실제 정의
│ ├── detail-page.md ← /sodam-design-kit:detail-page 명령의 실제 정의 (Phase 3)
│ └── marketing-asset.md ← /sodam-design-kit:marketing-asset 명령의 실제 정의 (Phase 3, og·포스터·배너·명함)
├── hooks/
│ └── verify-gate.mjs ← 완료 차단 로직(FAIL이면 차단)
├── skills/
│ └── design-pipeline/SKILL.md ← Claude Code에게 "언제 이 킷을 쓰는지"(Figma · 디자인 같은 말)와 핵심 규칙을 알려 주는 스킬 파일
├── scripts/ ← 실제 동작하는 엔진(전부 Node.js, 2026-10-12 기준 `scripts/` 폴더의 실제 파일 17개 + 화면 폴더 1개)
│ ├── setup-wizard.mjs
│ ├── pipeline-codegen.mjs
│ ├── detail-page-pipeline.mjs ← 상세페이지 파이프라인 엔진 (Phase 3)
│ ├── preview-route.mjs
│ ├── verify-runner.mjs ← 검증 실행기(개발 서버 기동 · 렌더 · 접근성 · 3화면 · 선택 옵션 5개)
│ ├── typecheck-gate.mjs ← 타입 검사 옵션(--typeCheck) 엔진
│ ├── execution-lock.mjs ← 같은 프로젝트에서 검증이 동시에 두 번 돌지 않게 하는 잠금 장치
│ ├── dashboard-server.mjs ← /open 대시보드 서버(127.0.0.1 전용) + 다시 검증 기능
│ ├── dashboard-web/ ← 대시보드 화면(index.html · dashboard.js)
│ ├── e2e-selftest.mjs ← 전체 왕복 자체 점검(시험 프로젝트 경로 필요)
│ ├── report-writer.mjs
│ ├── asset-downloader.mjs ← Figma 이미지·아이콘 자동 다운로드 엔진(7일 만료 URL 문제 해결)
│ ├── font-pipeline.mjs ← 한글 폰트 자동 다운로드/설정 엔진
│ ├── visual-regression.mjs ← 화면 변경 자동 감지 엔진
│ ├── ai-generation-log.mjs ← AI 생성 이력 자동 기록 엔진 (Phase 3)
│ ├── marketing-asset-pipeline.mjs ← 마케팅 이미지 자동 생성 엔진 (Phase 3, og·포스터·배너·명함)
│ ├── asset-ledger.mjs ← 라이선스 게이트 확장(이미지·아이콘 자산) + 출처 정리 문서 자동 생성 (Phase 3)
│ └── mcp-server.mjs ← Claude Desktop용 확장 엔진 — 검증 이력 열람 · 재검증 (Phase 3)
├── tests/ ← 자동 테스트(2026-10-12 기준 정식 v0.5.0은 361개, 공개 전 수정까지 담긴 작업본은 374개)
├── .PRD/ ← 이 킷의 설계 문서 정본(가장 상세한 근거 자료)
├── AGENTS.md ← Codex 등 Claude Code 밖의 도구를 위한 규칙 요약
├── LICENSE ← Apache License 2.0 전문
├── .mcpbignore ← Claude Desktop 확장 파일을 만들 때 넣지 않을 파일 목록(내부 메모 유출 방지)
├── README.md / README.en.md ← 지금 이 문서(한국어/영어, 마크다운)
├── README.html / README.en.html ← 같은 내용의 웹페이지 형식(브라우저로 열어 보기)
├── package.json / package-lock.json ← 부품 목록과 정확한 버전 고정
└── (저장소에 없음) CHECKPOINT.md ← 개발자 개인 작업 메모. 의도적으로 GitHub에 올리지 않는 로컬 전용 파일이라 받은 폴더에는 없습니다
대상 프로젝트(코드를 옮겨 넣는 쪽) 안에 생기는 것
/sodam-design-kit:setup을 실행한 대상 프로젝트 폴더 안에는 .design-kit/ 폴더 하나만 새로 생깁니다:
(대상 프로젝트)/.design-kit/
├── config.json ← 화면 크기 · 자동재시도 횟수 등 설정값 (지워도 setup으로 재생성 가능)
├── component-map.json ← 컴포넌트 ↔ Figma 노드 매핑 기록 (지우면 매핑 정보 사라짐 — 주의)
├── product-pages.json ← 상세페이지 템플릿 1개 + 상품 데이터 위치 목록 (Phase 3, /sodam-design-kit:detail-page)
├── runs/*.json ← 실행 기록(기계가 읽는 판정 원본) — git 커밋 대상
├── reports/*.md ← 판정서(사람이 읽는 결과) — git 커밋 대상
└── reports/screenshots/ ← 검증 스크린샷 — 최근 10개 실행분만 자동 보관(오래된 것은 자동 삭제)
위 목록은 대표 예시입니다(Phase 2가 추가한 fonts/ · ASSET-LEDGER.csv · .api-token · .lock · .dashboard.json · reports/baseline/ 등, Phase 3가 추가한 AI-GENERATION-LOG.md · ATTRIBUTION.md 등은 .PRD/02_DATA_MODEL.md가 정본입니다). 마케팅 이미지는 대상 프로젝트의 public/design-kit-assets/에 저장됩니다.
내 컴퓨터에는 이 두 곳이 따로 있다는 점을 기억하세요: ① 위쪽의 "이 킷 저장소" 구조는 GitHub에서 받은 원본과 같고, ② 실제로 실행되는 것은 Claude Code가 만든 복사본(<Claude 설정 폴더>\plugins\cache\sodam\sodam-design-kit\<버전>)입니다(3장). 검증 결과(.design-kit/)는 복사본이 아니라 대상 프로젝트 폴더에 쌓입니다.
지워도 되는 것: reports/screenshots/(자동 재생성됨). 지우면 안 되는 것: component-map.json(다시 만들려면 Figma를 또 읽어야 하는데, Figma 무료 플랜은 한 달 읽기 횟수 제한이 있습니다 — 10장 참고).
10. 보안 · 데이터 흐름
과장 없이, 사실만 적습니다.
- 외부와 통신하는 경우를 전부 적습니다 (2026-10-12에 이 킷의 코드 전체에서 네트워크 호출을 찾아 확인):
- Claude Code ↔ Anthropic 서버 (이 킷의 코드가 보내는 것이 아니라, Claude Code 자체의 기본 동작): 이 킷은 Claude Code 안에서 돌아가므로, 평소 Claude Code를 쓸 때와 똑같이 대화 내용과 AI가 읽은 파일 · Figma 디자인 데이터의 일부가 Anthropic의 서버로 전송됩니다. 그 처리 방침은 Anthropic의 공식 안내를 확인하세요. 그래서 개인정보나 실제 고객 데이터가 든 파일은 AI가 읽는 범위에 두지 마세요.
- Figma 서버: 사용자 본인의 Figma 로그인 정보로, 사용자가 지정한 디자인 페이지만 읽습니다. 로그인 정보(토큰 등)는 킷 코드가 직접 저장하지 않고, Claude Code에 이미 연결된 Figma 커넥터/공식 MCP의 기존 로그인을 그대로 사용합니다.
- 설치할 때만: 플러그인을 GitHub에서 내려받고, 부품을 npm 저장소에서 받고, 검증용 브라우저(Chromium)를 Playwright 배포 서버에서 받습니다(3장).
- 한글 폰트 자동 설정 기능을 쓸 때만: 코드에 고정된 허용 목록의 주소(
raw.githubusercontent.com의 Pretendard v1.3.9 · Noto Sans KR 폰트와 각 라이선스 파일)에서만 내려받습니다. 목록에 없는 폰트는 거부합니다.
- Figma 이미지 · 아이콘 다운로드 기능을 쓸 때만: Figma가 알려준
https:// 주소에서만 받습니다(http://는 거부, 주소가 중간에 http://로 바뀌어도 저장하지 않음, 10MB 초과 · 이미지가 아닌 파일은 저장하지 않음).
- 위 외에 사용 통계 · 원격 로그 · 오류 보고 등을 보내는 코드는 이 킷에 없습니다(관련 단어와 네트워크 호출을 코드 전체에서 검색해 확인).
- ⚠️ 검증하는 동안 잠깐 열리는 개발 서버는 "이 컴퓨터 전용"이 아닙니다 (2026-10-12 직접 측정): 이 킷은 개발 서버를 켤 때
127.0.0.1(이 컴퓨터 자신)에서만 열리도록 요청하지만, 실제로 같은 방식으로 띄워 확인해 보니 서버가 모든 네트워크 주소(::)에서 접속을 받는 상태였습니다. 즉 검증이 도는 수십 초 동안, 같은 네트워크에 있는 다른 기기가 그 임시 화면(만들고 있는 화면의 코드 · 개발용 정보)에 접속할 가능성이 있습니다. Windows 방화벽이 이를 막는지는 확인하지 못했습니다. 안전하게 쓰려면 카페 · 공용 Wi-Fi처럼 믿을 수 없는 네트워크에서는 검증을 돌리지 마세요. (이 사실은 개발자에게 개선 과제로 전달되어야 할 항목입니다 — 아직 고치지 않았습니다.) 반면 /sodam-design-kit:open 대시보드는 코드상 127.0.0.1에만 열리도록 되어 있습니다.
- 로컬(내 컴퓨터)에만 남는 것: 생성된 코드,
.design-kit/ 안의 설정 · 매핑 · 판정 기록 · 스크린샷 전부. 전부 내 컴퓨터 디스크에만 저장되고 외부로 전송되지 않습니다.
- Figma 이미지 주소는 7일 후 만료: Figma가 돌려주는 이미지 · 아이콘 등의 파일 주소는 임시 주소라 7일이 지나면 깨집니다. 이 킷은 코드에 그 임시 주소를 그대로 박아넣지 않고, 즉시 로컬로 내려받아 저장하도록 설계되어 있습니다.
- Figma 무료 플랜 읽기 한도 (수치가 바뀐 적이 있어 정확한 현재 값은 확정하지 못했습니다): 사용자 본인 계정이 무료(Starter/View) 플랜이면 Figma 읽기 횟수에 월 단위 제한이 있습니다. 이 킷을 만들 때 직접 확인한 값은 월 6회였고(유료 Dev/Full 플랜은 하루 200
600회), 2026-09-01에 Figma 공식 문서를 다시 보니 이 수치가 월 20회로 표기가 바뀐 것이 확인됐습니다(다만 그 수치가 내 계정 조건과 정확히 같은 값인지는 확정하지 못했습니다). 그래서 이 문서는 "월 6회20회 사이로 매우 적다"는 정도만 보증합니다 — 이 킷은 한 번 읽은 정보를 에 저장해두고 재사용하는 방식으로 이 한도를 아끼도록 설계되어 있습니다.
11. 문제/오류 대처 (트러블슈팅)
| 증상 | 원인 | 해결 방법 | 성공 기준 |
|---|
설치했는데 /sodam-design-kit:setup 명령이 안 보여요 | Claude Code가 옛날 설정을 그대로 기억하고 있음(캐시) | Claude Code 창을 완전히 닫았다가 다시 켜기(새로고침이 아니라 완전 종료 · 재시작) | 명령을 입력할 때 자동완성 목록에 /sodam-design-kit:setup이 뜸 |
| "완료가 차단됐다"는 메시지가 나와요 | 정상 동작입니다. 검증 게이트가 FAIL을 감지하면 "완료"라고 보고하는 것을 의도적으로 막습니다 | .design-kit/reports/의 최신 판정서를 열어 실패 사유를 확인 → 재시도 또는 사람이 직접 확인 | 판정서에 실패 사유가 구체적으로 적혀 있음 |
| 게이트 FAIL이 계속 반복돼요 | AI의 재시도(최대 3회 권장)로도 못 고치는 문제일 수 있음 | 판정서의 실패 사유(접근성 위반 항목 · 콘솔 에러 메시지)를 사람이 직접 읽고 원인 확인. .design-kit/config.json의 gateEnabled 값을 바꿔 게이트를 끄려는 시도는 동작하지 않습니다 — 어떤 프로그램도 그 값을 읽지 않기 때문입니다(코드로 확인). 게이트를 끄려 하지 말고 FAIL 사유를 고치세요 | 재시도 후 PASS로 바뀌거나, 사람이 원인을 파악함 |
| Figma 연결이 안 되거나 읽기가 부족해요 | Figma 커넥터 로그인이 끊겼거나, 공식 MCP 전환이 필요할 수 있음 | 커넥터 로그인 상태 확인 → 필요 시 공식 원격 MCP(mcp.figma.com/mcp)로 전환 | Figma 읽기 요청이 정상적으로 결과를 돌려줌 |
내 컴퓨터에 저장된 .fig 파일이 안 읽혀요 | Figma 커넥터 · MCP는 Figma 계정에 저장된 파일만 읽을 수 있고, 로컬 파일을 직접 읽지 못함 | Figma 데스크톱 앱에서 그 파일을 열어 계정에 저장한 뒤, 공유 링크를 사용 | 공유 링크로 정상 읽힘 |
| shadcn/ui가 설치되어 있지 않다고 나와요 | 대상 프로젝트에 shadcn/ui가 없음 | npx shadcn init 실행 여부를 물어보는 안내를 따름 | 안내된 설치가 끝난 뒤 명령이 정상 실행됨 |
검증할 때 browserType.launch: Executable doesn't exist at ...chromium_headless_shell... 오류가 나고, 아래쪽에 "Looks like Playwright was just installed or updated. Please run the following command to download new browsers"라고 나와요 | 검증용 브라우저(Chromium) 파일이 이 컴퓨터에 아직 없음 (2026-10-12에 브라우저 경로를 비워 놓고 그대로 재현한 실제 오류 문구입니다). 부품은 자동으로 설치되지만 브라우저는 자동으로 받지 않습니다 | 터미널에서 npx [email protected] install chromium 실행(3장 방법 A의 4번). 오류 화면이 안내하는 npx playwright install도 같은 목적입니다 | 같은 검증 명령이 오류 없이 PASS/FAIL 판정까지 진행됨 |
Cannot find package 'playwright' 같은 "패키지를 찾을 수 없다" 오류가 나요 |
12. FAQ (자주 묻는 질문)
Q. 코딩을 전혀 몰라도 쓸 수 있나요?
A. 명령을 실행하는 것 자체는 슬래시 명령 몇 개(/sodam-design-kit:setup, /sodam-design-kit:pipeline 등)만 알면 됩니다. 다만 "대상 프로젝트"(Next.js+Tailwind+shadcn/ui)는 누군가 미리 준비되어 있어야 합니다. 나머지는 전부 자연어로 AI에게 요청하면 됩니다.
Q. 컴퓨터 · 메신저 · AI를 정말 처음 써보는데 시작할 수 있나요?
A. 0장 용어 사전을 먼저 읽고 4장 빠른 시작을 그대로 따라 입력해보시길 권합니다. 다만 정직하게 말씀드리면, 이 킷은 "개발 도구"라서 Node.js 설치 · 터미널 사용처럼 컴퓨터를 어느 정도 다뤄야 하는 부분이 남아있습니다 — 완전한 비전공자 혼자보다는, 이미 준비된 프로젝트(2장 준비물 3번)를 옆에서 도와줄 사람이 한 명 있으면 훨씬 수월합니다.
Q. Figma 유료 플랜이 꼭 필요한가요?
A. 아니요, 무료(Starter) 플랜으로도 됩니다. 다만 한 달에 읽을 수 있는 횟수가 매우 적은 제한(제작 당시 직접 확인한 값은 월 6회, 이후 공식 문서 표기는 월 20회로 바뀜 — 정확한 현재 값은 Figma에서 확인)이 있습니다(10장 참고). 이 킷은 한 번 읽은 내용을 저장해두고 재사용하도록 만들어져 있어 이 한도 안에서도 여러 번 파이프라인을 돌릴 수 있습니다.
Q. 검증이 실패(FAIL)하면 제 코드가 잘못된 건가요?
A. 꼭 그런 건 아닙니다. 접근성 규칙 위반, 콘솔 에러, 화면 렌더링 실패 등 여러 이유가 있을 수 있고, 판정서에 구체적인 이유가 남습니다. 실패도 "이 킷이 정상적으로 검사하고 있다"는 증거입니다.
Q. 생성된 코드를 제가 마음대로 고쳐도 되나요?
A. 네, 생성된 코드는 사용자의 프로젝트 파일이 되므로 자유롭게 수정할 수 있습니다. 단, 다시 파이프라인을 돌리면 재검증이 이루어집니다.
Q. 이 킷을 상업적으로 써도 되나요? 다른 사람에게 나눠줘도 되나요?
A. 네, Apache License 2.0 조건을 지키면 가능합니다(2026-08-09 확정) — 라이선스 사본 동봉, 수정 사실 표시, 원저작물 고지 유지가 조건입니다. 단 "SoDam-Design-Kit" 이름 · 상표 자체를 쓸 권리는 포함되지 않습니다. 자세한 내용은 13장을 반드시 읽어보세요.
Q. 이 킷으로 만든 결과물(상세페이지 · 코드)을 팔거나 고객사에 납품해도 되나요?
A. 이 킷 자체의 라이선스는 그것을 막지 않습니다. 다만 원본 Figma 디자인의 저작권, 상품 데이터의 출처, AI 생성 코드/문구의 법적 지위는 이 킷과 별개의 문제이며 전적으로 사용자 책임입니다 — 13장에서 각각 자세히 설명합니다.
Q. Windows/Mac/Linux 다 되나요?
A. 이 킷은 Node.js 스크립트로 만들어져 있어 이론적으로 셋 다 실행 가능하지만, 지금까지 실제로 상세하게 검증된 환경은 Windows입니다(개발 · 테스트 환경). Mac/Linux에서의 실측 검증은 아직 이루어지지 않았습니다. Claude Desktop 확장(.mcpb)의 설명서(manifest.json)는 지원 운영체제로 Windows와 macOS만 명시해 두었고 Linux는 포함하지 않습니다. Node.js는 어느 운영체제에서든 20.9 이상이어야 합니다(2장).
Q. 이 킷은 안정적인 정식 버전인가요?
A. 아니요. 현재 버전은 0.5.0(정식 출시 전)입니다. 핵심 기능(Phase 1 · Phase 2 · Phase 3 대부분)은 실제 프로젝트로 왕복 검증까지 마쳤지만, 명령어 이름이나 세부 동작이 앞으로 바뀔 수 있습니다. 중요한 프로젝트에 쓰기 전에는 7장과 GitHub의 Releases 페이지에서 최신 상태를 먼저 확인하는 것을 권장합니다.
Q. 새 버전은 어떻게 받나요? 자동으로 업데이트되나요?
A. 이 문서를 쓴 시점에 확인한 범위에서는 자동으로 바뀐다고 확인하지 못했습니다. 설치된 것은 복사본이라, 3장의 "업데이트 방법" 두 줄(claude plugin marketplace update sodam → claude plugin update sodam-design-kit@sodam)을 실행하고 Claude Code를 완전히 재시작해야 합니다.
Q. 제 디자인 · 코드가 외부로 전송되나요?
A. 이 킷의 코드는 사용 통계나 원격 로그를 보내지 않습니다(코드 전체를 검색해 확인). 다만 Claude Code 자체가 대화 내용과 AI가 읽은 파일 · Figma 데이터를 Anthropic 서버로 전송하는 것은 이 킷과 별개로 일어납니다. 또 검증하는 동안 잠깐 열리는 개발 서버가 같은 네트워크의 다른 기기에서 접속 가능한 상태였던 것을 확인했습니다 — 자세한 내용과 주의는 10장을 꼭 읽어보세요.
Q. Codex 같은 다른 AI 도구에서도 쓸 수 있나요?
A. 일부만 가능합니다. AGENTS.md는 다른 도구가 이 킷의 핵심 규칙을 따르게 하려는 요약 문서입니다. 하지만 /sodam-design-kit:... 슬래시 명령과 "FAIL이면 완료를 막는" 훅은 Claude Code 전용이라 다른 도구에서는 작동하지 않습니다. 이 킷의 스크립트는 일반 Node 프로그램이라 이론상 다른 도구에서도 터미널로 실행할 수 있지만, 다른 도구에서 실제로 시험한 기록은 이 문서에 없습니다. 그런 도구로 쓴다면 검증 결과(.design-kit/reports/의 최신 판정서)를 사람이 직접 열어 PASS를 확인해야 합니다.
13. 법률 · 저작권 · 라이선스 · 상업적 용도
⚠️ 가장 먼저 읽어야 할 요약: 이 킷 자체는 상업적 이용 · 재배포가 가능합니다(Apache License 2.0). 하지만 이 킷으로 "만들어낸 결과물"(코드 · 문구 · 이미지)에 대한 법적 책임은 별개이며, 전적으로 사용자 본인의 책임입니다. 이 섹션은 법률 자문이 아니며 법적 효력을 보장하지 않습니다. 확정되지 않은 사항은 아래에 "미정"으로 명확히 구분해 표시했습니다. 상업적 이용 · 재배포 · 법적 판단이 필요한 경우 반드시 변호사 등 전문가의 확인을 받으시기 바랍니다.
이 킷(SoDam-Design-Kit) 자체의 라이선스 — Apache License 2.0 (2026-08-09 확정)
- 현재 상태(확인된 사실): 이 저장소 최상위에
LICENSE 파일(Apache License 2.0 전문)이 있습니다. 저작권자는 SoDam AI Studio, 연도는 2026년입니다.
- 이것이 의미하는 것: Apache License 2.0은 코드 · 문서의 사용 · 복제 · 수정 · 재배포 · 상업적 이용을 허용하는 permissive(허용적) 라이선스입니다. 단, 라이선스 사본을 함께 배포해야 하고, 수정한 파일에는 변경 사실을 표시해야 하며, 원저작물의 저작권 · 특허 · 상표 고지를 유지해야 합니다(라이선스 전문 4조 참고). "SoDam-Design-Kit"라는 이름 · 상표에 대한 권리는 이 라이선스에 포함되지 않습니다(라이선스 전문 6조 — 상표 조항).
- NOTICE 파일은 별도로 두지 않습니다(신규 저작물이라 승계할 상위 NOTICE가 없다고 판단).
- 책임 제한 · 보증 없음(라이선스 전문 7 · 8조): 이 킷은 "있는 그대로(AS IS)" 제공되며, 특정 목적에의 적합성이나 오류 없음을 보증하지 않습니다. 이 킷을 사용해 발생하는 모든 손해(직접 · 간접 · 특수 · 부수적 손해 포함)에 대해 제작자는 책임지지 않습니다.
해서는 안 되는 것 (엄격 기준 — 명확히 금지)
- ❌ "SoDam-Design-Kit"라는 이름 · 로고를 자신이 만든 것처럼 다시 배포하는 행위 (라이선스가 코드 사용은 허용해도 이름 · 상표권까지 주지는 않습니다)
- ❌ 저작권 · 라이선스 고지,
LICENSE 파일을 삭제하거나 가리고 재배포하는 행위
- ❌ 수정한 파일에 변경 사실을 표시하지 않고 원본인 것처럼 재배포하는 행위
- ❌ 타인의 Figma 디자인을 정당한 권한 없이 읽어와 상업적으로 사용하는 행위(디자인 원본의 저작권은 이 킷과 무관하게 그 디자인을 만든 사람에게 있습니다)
- ❌ 개인정보 · 실제 고객 데이터가 담긴 Figma 파일 · 상품 데이터를 이 킷에 연결하는 행위(10장 참고)
이 킷이 사용하는 오픈소스 구성요소(의존성) 라이선스 — 실측 확인됨
이 킷 자체의 라이선스와 별개로, 이 킷이 검증 기능을 위해 내부적으로 사용하는 오픈소스 라이브러리들은 각자의 라이선스를 따르며, 이 킷은 이들을 수정하지 않고 그대로(설치 의존성으로만) 사용합니다.
| 구성요소 | 라이선스 | 용도 |
|---|
| Playwright / playwright-core | Apache License 2.0 (실측 확인됨) | 자동화 브라우저로 화면을 실제로 확인 |
| axe-core / @axe-core/playwright | Mozilla Public License 2.0 (실측 확인됨) | 접근성(장애인 사용성) 자동 검사 |
| pixelmatch | ISC License (실측 확인됨) | 화면 변경 자동 감지의 픽셀 단위 이미지 비교 |
| pngjs | MIT License (실측 확인됨) | 화면 변경 자동 감지용 PNG 이미지 읽기/쓰기 |
| satori | Mozilla Public License 2.0 (실측 확인됨) | 마케팅 이미지 소재(OG 이미지 등)의 텍스트 레이아웃을 SVG로 렌더링(Phase 3) |
| sharp | Apache License 2.0 (실측 확인됨) | 마케팅 이미지 소재를 SVG에서 PNG로 변환(Phase 3) |
| @modelcontextprotocol/sdk | MIT License (실측 확인됨) | Claude Desktop용 확장(MCP) 공식 SDK(Phase 3) |
| zod | MIT License (실측 확인됨) | MCP 도구 입력값 형식 검증(Phase 3) |
이 라이선스들은 이 킷의 라이선스와 무관하게 각 프로젝트가 독자적으로 부여한 것이며, 각 구성요소를 직접 사용하고 싶다면 해당 프로젝트의 원문 라이선스를 확인해야 합니다.
간접 의존성까지 포함한 전체 패키지 라이선스 재집계 (2026-10-12)
위 표는 이 킷이 직접 설치하는 8개 패키지만 다룹니다(그 8개의 라이선스는 2026-10-12에 package-lock.json의 license 필드와 다시 대조해 표와 일치함을 확인했습니다). 이 8개가 각자 데려오는 간접 의존성까지 포함하면 package-lock.json에 153개 패키지가 기록되어 있습니다(2026-08-21 감사 때는 126개였고, 이후 부품이 갱신되며 늘었습니다). 이번에는 별도의 스캐너 없이, 153개 전부의 license 필드를 스크립트로 집계했습니다.
| 라이선스 | 패키지 수 |
|---|
| MIT | 106 |
| Apache-2.0 | 16 |
| LGPL-3.0-or-later | 10 |
| ISC | 10 |
| MPL-2.0 | 3 |
| Apache-2.0 AND LGPL-3.0-or-later | 3 |
| BSD-3-Clause | 2 |
| Apache-2.0 AND LGPL-3.0-or-later AND MIT | 1 |
| BSD-2-Clause | 1 |
| 0BSD | 1 |
| 합계 | 153 |
license 필드가 없는 패키지: 0개 · GPL · AGPL 등 강한 카피레프트: 0개.- 실제로 내 컴퓨터에 설치되는 수는 이보다 적습니다: 153개 중 29개는 "운영체제별 선택 설치" 부품이라, 모든 운영체제용이 목록에 적혀 있어도 내 컴퓨터에는 내 운영체제에 맞는 것만 설치됩니다.
- 주의가 필요해 따로 적는 발견 — LGPL-3.0-or-later를 포함하는 14개: 전부 이미지 처리 부품
sharp가 운영체제별로 데려오는 네이티브 부품입니다(@img/sharp-libvips-* 10개는 macOS · Linux용, @img/sharp-win32-* 3개는 Windows용, @img/sharp-wasm32 1개). 내 컴퓨터에는 그중 1~2개만 설치됩니다(Windows 64비트는 @img/sharp-win32-x64). 이는 libvips라는 라이브러리를 함께 담고 있기 때문입니다. 이 킷은 이들을 수정하지 않고 설치 의존성으로만 쓰므로, LGPL이 이 킷 전체로 번지지 않는 일반적인 사용 방식에 해당합니다(참고용 설명이며 법적 효력을 보장하지 않습니다).
- MPL-2.0 3개(
axe-core · @axe-core/playwright · satori): "파일 단위" 카피레프트입니다. 이 킷은 수정 없이 쓰지만, 사용자가 이 부품들의 파일을 직접 고쳐서 배포한다면 고친 파일의 소스를 MPL-2.0으로 공개해야 합니다.
- 이 부품들은 설치된 복사본과
.mcpb 파일 안에 통째로 들어 있습니다. 2026-10-12에 .mcpb 내부를 열어 보니 LICENSE 류 파일이 128개 들어 있었습니다. 이 파일들(특히 위 LGPL · MPL 부품의 LICENSE)을 지우거나 가리고 재배포하면 안 됩니다.
이 킷에 포함되지 않고, 별도로 받아서 쓰는 프로그램 (각자의 라이선스 · 약관이 적용됩니다)
- Chromium 브라우저: 3장 4번 명령으로 Playwright가 내려받는 약 690MB의 브라우저 파일입니다. 이 킷의 파일이 아니며, Chromium 프로젝트와 그 안에 든 제3자 구성요소 각각의 라이선스를 따릅니다. 정확한 조건은 해당 프로젝트의 공식 안내를 확인하세요(이 문서는 그 조건을 대신 보증하지 않습니다).
- Node.js · Git · Claude Code · Claude Desktop · Figma(서비스): 각자의 라이선스 또는 이용약관이 적용됩니다. 특히 Claude Code · Figma는 서비스 이용약관이 있어, 그 약관을 지키는 것은 사용자의 책임이며 이 킷이 대신 보증하지 않습니다.
상표 고지
Figma, Claude, Claude Code, Anthropic, shadcn/ui, Next.js, Tailwind CSS, Playwright, Node.js, GitHub 등의 이름은 각 권리자의 상표 또는 서비스 이름입니다. 이 문서는 이 킷이 어떤 도구와 함께 쓰이는지 설명하려고 이름을 적었을 뿐, 해당 회사들과 제휴하거나 보증 · 후원을 받았다고 주장하지 않습니다.
라이선스 표기 위치 (헷갈리기 쉬운 부분)
이 킷의 라이선스의 정본은 저장소 최상위의 LICENSE 파일입니다(203행에 Copyright 2026 SoDam AI Studio). Claude Desktop 확장 설명서 manifest.json에도 Apache-2.0이 적혀 있습니다. 반면 package.json과 .claude-plugin/plugin.json에는 라이선스 필드가 없으므로(2026-10-12 확인), 자동 도구가 이 파일들만 읽으면 라이선스를 "없음"으로 표시할 수 있습니다 — 판단은 LICENSE 파일을 기준으로 하세요.
이 킷이 자동으로 다운로드하는 폰트의 라이선스
7장의 "한글 폰트 자동화" 기능은 오픈소스 폰트 라이선스인 OFL(SIL Open Font License)을 따르는 폰트(Pretendard, Noto Sans KR)만 화이트리스트로 미리 정해두고 자동으로 내려받습니다. OFL은 폰트를 수정 · 재배포 · 상업적 이용하는 것을 허용하지만, 폰트 파일 자체를 단독으로 재판매하는 것은 금지합니다. 다운로드한 폰트 각각의 라이선스 근거는 대상 프로젝트의 ASSET-LEDGER.csv에 자동 기록됩니다.
Figma 디자인 데이터에 대한 책임
이 킷은 사용자 본인의 Figma 계정으로 사용자가 직접 접근 권한을 가진 디자인만 읽으며, Figma 디자인 데이터 자체를 재배포하거나 저장 · 전송하지 않습니다. 다만 읽어온 디자인을 코드로 옮겨서 사용할 권리(저작권)가 있는지는 전적으로 사용자의 책임입니다 — 디자인 원본의 저작권은 그 디자인을 만든 사람(또는 조직)에게 있으며, 이 킷이 그 권리 관계를 대신 확인하거나 보장하지 않습니다.
상품 데이터 · AI가 작성한 카피(문구)에 대한 책임 (Phase 3, /sodam-design-kit:detail-page)
이 기능이 만드는 상세페이지 카피(제목 · 설명 · 자주 묻는 질문 등)는 사용자가 입력한 상품 데이터를 근거로 AI가 작성합니다. 상품 정보의 사실 정확성 · 과장 광고 여부 · 표시 · 광고에 관한 법률(예: 전자상거래법, 표시 · 광고의 공정화에 관한 법률 등) 준수 여부는 이 킷이 판단하지 않으며, 실제로 그 문구를 상업적으로 게시하기 전에는 반드시 사용자가 직접 사실 확인과 검토를 거쳐야 합니다.
AI가 생성한 코드 · 문구에 대한 책임
이 킷이 생성하는 코드와 카피(문구)는 Claude(AI)가 만든 것입니다. AI 생성물의 저작권 귀속 · 보호 범위는 국가마다 법 해석이 다르고 아직 확립되지 않은 영역입니다. 생성된 코드 · 문구를 상업적으로 사용하기 전에는 사용자 본인의 책임 하에 필요 시 전문가 확인을 받으시기 바랍니다. 이 킷과 그 문서는 이에 대해 어떠한 법적 보장도 하지 않습니다.
요약 표 (Apache License 2.0 기준)
| 행위 | 현재 허용 여부 |
|---|
| 제작자 본인이 개인적으로 사용 | ✅ 가능 |
| 코드를 수정해서 나 혼자/우리 팀 내부용으로 쓰기 | ✅ 가능 |
| 제3자에게 이 킷 자체를 배포 · 복사해서 나눠주기 | ✅ 가능 — 라이선스 사본 동봉 + 수정 사실 표시 필요 |
| 이 킷을 활용한 유료 서비스 · 상품 판매 | ✅ 가능 — 위 조건 동일 적용 |
| 회사 · 고객사에 이 킷을 납품 | ✅ 가능 — 위 조건 동일 적용 |
| "SoDam-Design-Kit" 이름 · 상표를 그대로 써서 배포 | ❌ 금지 — 라이선스가 코드 사용은 허용하지만 이름 · 상표권까지 부여하지 않음 |
| 저작권 · 라이선스 고지를 지우고 재배포 | ❌ 금지 (라이선스 위반) |
| 이 킷이 생성한 코드 · 카피를 내 프로젝트 · 상품에서 쓰기 | ✅ 가능 — 단, 원본 Figma 디자인의 저작권 · 상품 정보의 사실 정확성 확인은 사용자 책임 |
| 타인의 Figma 디자인을 무단으로 가져와 상업적으로 사용 | ❌ 이 킷의 라이선스와 무관하게, 원 디자인 저작권자의 권리 침해가 될 수 있음(사용자 책임) |
| 이 킷이 내부적으로 쓰는 오픈소스(Playwright · axe-core · pixelmatch · pngjs · satori · sharp · @modelcontextprotocol/sdk · zod)를 별도로 직접 쓰기 | ✅ 각 프로젝트의 라이선스(Apache-2.0 / MPL-2.0 / ISC / MIT)를 따르면 가능 |
| 이 킷이 자동 다운로드하는 폰트(Pretendard 등)를 폰트 파일 자체로 재판매 | ❌ 금지 (OFL 라이선스 위반) |
설치된 복사본이나 .mcpb 파일을 다른 사람에게 그대로 나눠주기 | ⚠️ 가능하지만 조건이 겹침 — 이 킷의 Apache-2.0 조건에 더해, 안에 든 부품들(특히 LGPL · MPL 부품)의 LICENSE 파일을 지우지 않아야 함. 상업적 재배포라면 변호사 확인 권장 |
| Playwright가 내려받는 Chromium 브라우저 파일을 이 킷의 일부인 것처럼 함께 배포 | ❓ 이 킷은 Chromium을 포함하지 않음 — 별도 프로젝트의 라이선스를 확인해야 함(이 문서는 보증하지 않음) |
| Claude · Figma 등의 이름을 써서 "공식 제품 · 제휴 제품"처럼 홍보 | ❌ 금지 — 상표권 침해 · 오인 소지(위 "상표 고지") |
| 이 킷으로 Figma 데이터를 AI(Claude Code)에게 읽혀 작업하기 | ⚠️ 가능하지만 Claude Code가 그 내용을 Anthropic 서버로 보내는 것을 전제로 해야 함(10장) — 비밀 · 개인정보가 든 디자인이면 회사 정책 확인 |
책임 제한 · 보증 없음: 이 킷과 문서는 "있는 그대로(as-is)" 제공되며, 특정 목적에의 적합성이나 오류 없음을 보증하지 않습니다. 사용으로 인해 발생하는 모든 결과에 대한 책임은 사용자 본인에게 있습니다.
부록: 전체 설계 문서
이 문서에 담지 못한 더 상세한 사양 · 결정 근거 · 개발 이력은 .PRD/ 폴더가 정본입니다:
01_PRD.md — 무엇을 왜 만드는지, UI/UX · 보안 · 법률 · 문서화 · 성공 기준02_DATA_MODEL.md — 데이터 구조(config.json 등 파일 스키마)03_PHASES.md — 단계별(Phase 1/2/3) 개발 계획과 현재 진행 상태04_PROJECT_SPEC.md — 기술 스택, 절대 규칙(하지 말 것/항상 할 것).PRD/README.md — 개발 과정 전체 감사(audit) 이력- (참고) 개발자 개인용 작업 메모
CHECKPOINT.md는 의도적으로 GitHub에 올리지 않는 로컬 전용 파일이라 이 저장소에는 없습니다. 개발 이력의 정본은 위 .PRD/README.md입니다.
