Design Sync Upload

design-sync-upload — Claude Design 업로드 (자동 + 수동 폴백)

개요

디자인 시스템 자산을 Claude Design에 올리는 방식은 환경에 따라 두 가지입니다. 이 스킬은 자동(DesignSync MCP)을 먼저 시도하고, 인증·가용성 조건이 안 되면 **수동 폴백(UPLOAD-GUIDE.md + 스테이징 폴더)**으로 자연스럽게 강등합니다. 어느 경로든 사용자가 손으로 파일을 흩뿌리지 않고 한 번에 업로드할 수 있게 만드는 것이 목표입니다.

이 SKILL.md는 인증 감지·자동(DesignSync MCP) 경로·수동 폴백·사용 예시를 모두 포함합니다. DesignSync는 method로 디스패치하는 단일 MCP 도구이며(파라미터 상세는 §자동 경로 참조), 미인증·미가용 시 조용히 수동 폴백으로 강등합니다.

트리거 키워드

Claude Design 업로드, DesignSync MCP, design-login, 디자인 시스템 동기화, UPLOAD-GUIDE, 자산 스테이징, write_files, register_assets

입력

경로 선택 — 인증 감지 분기

자산 준비
  → [감지] DesignSync MCP 가용 AND /design-login 인증됨?
      ├─ YES → 자동 경로 (DesignSync MCP)
      └─ NO  → 수동 폴백 (UPLOAD-GUIDE.md + 스테이징 폴더)

감지 신호

감지 순서(부작용 최소화): ① 도구 존재만 사전 확인 → ② 무해한 read 메서드(list_projects/get_project)로 인증 상태 판별(쓰기 없음) → ③ 여기서 미인증 에러가 나오면 폴백. 쓰기 메서드로 인증을 떠보지 않는다(부분 업로드 위험).

감지 실패 시 기본 강등 정책: 감지 자체가 모호하면(도구는 있으나 인증 상태 불명, read 호출이 애매한 에러 반환 등) 수동 폴백을 기본값으로 강등한다. 인증됨을 관측 없이 가정하고 자동을 강행하면 부분·중복 업로드 위험이 있으므로, 애매하면 항상 수동이다(미관측 상태를 성공으로 가정 금지).

자동 경로 — DesignSync MCP

/design-login 인증 상태에서 DesignSync MCP 도구로 자산을 직접 등록합니다.

DesignSync는 method로 디스패치하는 단일 도구다. 순서 의존성이 강제된다: read → finalize_plan → write. finalize_plan이 먼저 경로 집합을 잠근 뒤에야 write가 허용된다(플랜 밖 경로/planId 없는 write는 거부).

1. read (list_projects/get_project/list_files/get_file) — 대상 프로젝트 확인(쓰기 가능 + type: PROJECT_TYPE_DESIGN_SYSTEM) 후 원격 구조로 컴포넌트 단위 diff 구성. 전량 교체가 아니라 증분.
2. 승인 게이트 — finalize_plan 호출 전. 아래 §쓰기·삭제 승인 게이트. finalize_plan이 띄우는 런타임 권한 프롬프트가 이 게이트를 대신하지 못한다 — 그 프롬프트는 경로만 보여주고 그 경로에 무엇이 들어가는지는 보여주지 않는다.
3. finalize_plan — 승인된 경로 집합(writes/deletes, 글롭 허용)과 읽기 소스 디렉토리(localDir)를 확정 → planId 반환. 권한 프롬프트 발생.
4. write_files (+ delete_files) — planId로 파일 업로드. 각 파일은 localPath(디스크에서 직접 읽어 업로드 — 내용이 컨텍스트에 유입되지 않음, 권장) 또는 소량 인라인 data. 콜당 최대 256개(초과 시 같은 planId로 분할).
5. register_assets (레거시) — Design System 카드는 이제 preview HTML 첫 줄 <!-- @dsCard group="…" --> 마커에서 자동 인덱싱(앱이 _ds_manifest.json으로 컴파일)되므로 명시 등록 불필요. @dsCard 마커가 없는 수기 프로젝트에서만 사용.

각 메서드 파라미터 스키마 (핵심 필드)

순서 의존성: read → 승인 게이트 → finalize_plan(planId 발급) → write_files/delete_files → (필요 시) register_assets. planId 없이, 또는 플랜 밖 경로로 write/delete/register 호출 시 거부된다.

쓰기·삭제 승인 게이트

원격 디자인 시스템은 다른 사람이 쓰고 있는 공용 자산이다. 덮어쓴 파일의 이전 내용과 지운 파일은 원격에 남지 않는다 — 이 MCP에는 원자적 롤백이 없다(아래 §부분 실패 정책). 그래서 finalize_plan으로 경로를 잠그기 전에 멈춘다.

• [HARD] 승인은 §승인 요청 계약의 경로로 받는다. finalize_plan의 런타임 권한 프롬프트로 갈음하지 않는다 — 그 프롬프트는 경로 목록만 보여주고 digest·의미 diff·스냅샷 위치를 보여주지 않는다. 그 프롬프트는 경로 목록과 소스 디렉토리만 노출하며, localPath 경로는 내용이 컨텍스트에 유입되지 않는 것이 설계 의도이므로 사용자는 무엇이 덮어써지는지 보지 못한 채 승인하게 된다.
• [HARD] 글롭은 승인 전에 펼쳐서 보여준다. writes[]/deletes[]는 글롭을 허용한다. 펼치지 않은 글롭은 사용자가 의도한 것보다 훨씬 많이 매치될 수 있고, 그 차이는 승인 시점에 보이지 않는다. 실제로 매치된 경로를 하나씩 나열하고 개수를 함께 적는다.
• [HARD] 요약하지 말고 다음을 그대로 보여준다:

• [HARD] 이 MCP에는 안전한 복구 스냅샷 수단이 없다. 스킬이 대신 만들지 않는다. 원격 내용을 가져오는 유일한 경로는 get_file인데, 그 응답은 모델 컨텍스트를 통과한다. 자격증명·고객 자산·미공개 디자인이 섞여 있어도 그대로 지나가며, 받아 놓은 로컬 사본에는 권한·보존 기간·저장소 제외 규칙이 없다. 백업을 만들려다 유출 경로를 만드는 것이 더 나쁘다.
• [HARD] 대신 사용자에게 사실을 알린다. 덮어쓰거나 지울 경로 목록을 보여주면서 "이 파일들의 현재 내용은 이 작업으로 사라지며, 스킬은 사본을 만들지 않는다" 고 명시한다. 사본이 필요하면 사용자가 직접 내려받은 뒤 진행하도록 안내한다.
• 대상은 덮어쓰기·삭제 경로뿐이다. 신규 경로는 잃을 것이 없으므로 이 안내에서 뺀다 — 신규와 덮어쓰기를 나눠 보여주는 이유가 이것이다.
• 나중에 서버가 내용을 응답하지 않고 제한 권한 디렉터리로 직접 내보내는 기능을 제공하면 그때 자동 스냅샷을 다시 논한다. 그 전에는 "복구 사본을 받아 둡니다"라고 약속하지 않는다.
• [HARD] 의미 diff를 만들려고 원격 원문을 가져오지 않는다. 내용 대조를 하려면 get_file로 원격 전체를 받아야 하는데, 그것이 바로 위에서 막은 유출 경로다. 승인 화면에는 원문 없이 알 수 있는 것만 적는다 — 경로, 신규/덮어쓰기 구분, 로컬 파일의 크기와 digest, 삭제 대상.
• 내용 수준의 diff가 꼭 필요하면 사용자가 직접 받아 둔 사본을 건네줄 때만 만든다. 스킬이 원격에서 끌어오지 않는다.

승인 선택지는 이렇게 구성한다:

• [HARD] planId는 승인된 그 매니페스트에 묶인다. 승인 뒤 경로를 추가하거나 글롭을 넓히려면 재승인을 받고 finalize_plan을 다시 실행한다. 기존 planId에 슬쩍 얹지 않는다.
• [HARD] write_files 직전에 digest를 다시 계산해 승인 시점 값과 대조한다. write_files는 승인 뒤 localPath를 다시 읽는다 — 승인과 업로드 사이에 파일이 바뀌면 사용자가 승인한 적 없는 내용이 같은 경로로 올라간다. 동시 편집·빌드 산출물 갱신·파일 교체가 실제로 일어나는 구간이다.
• 하나라도 어긋나면 그 planId를 폐기하고 재승인을 받는다. 어긋난 파일만 빼고 진행하지 않는다 — 무엇이 왜 바뀌었는지 모르는 상태이기 때문이다.
• [HARD] 이 대조는 창을 좁힐 뿐 닫지 못한다. 그 한계를 사용자에게 숨기지 않는다. write_files 스키마에는 expectedDigest가 없고, 서버가 파일을 여는 시점은 스킬이 해시를 잰 뒤다. 그 사이에 파일이 바뀌면 막을 방법이 현재 계약에는 없다. 따라서 "승인한 바이트가 그대로 올라간다"고 보증하지 않는다 — 보증하는 것은 "직전까지 바뀐 흔적이 없었다"까지다.
• 창을 좁히는 실무: digest 재계산과 write_files 호출 사이에 다른 작업을 끼우지 않는다. 빌드·포맷터·동기화 도구가 도는 중이면 끝난 뒤에 시작한다. 승인 화면에서 업로드까지의 시간이 길어질수록 위험이 커진다.
• 서버가 expectedDigest를 받아 파일을 연 직후 검증하는 기능을 제공하면 그때 보증 수준을 올린다. 없는 기능을 전제로 계약을 쓰지 않는다.
• [HARD] 삭제는 쓰기와 같은 승인으로 묶지 않는다. 위 선택지에 "삭제는 빼고 쓰기만"을 항상 넣어, 삭제만 따로 거부할 수 있게 한다. 쓰기를 승인받으려고 삭제를 함께 통과시키는 형태가 되지 않게 한다.

부분 실패 재시도/롤백 정책

• write_files 실패: 같은 경로 덮어쓰기는 멱등이므로 최대 3회 재시도. 계속 실패하면 이미 기록된 파일을 사용자에게 고지하고 폴백.
• 256개 초과 분할 중 일부 실패: 실패 배치만 재시도, 성공 배치는 유지(같은 planId).
• MCP는 원자적 롤백을 제공하지 않음 → 부분 기록 상태를 가짜 완료로 보고 금지. 남은 파일만 이어서 쓰거나 수동 폴백으로 넘긴다(부작용 있는 호출은 상태 확인 후 재개 — 중복 업로드 방지).

에러 → 폴백 전환 조건

승인 요청 계약 (런타임 중립)

[HARD] 이 스킬의 게이트는 특정 도구 이름에 묶이지 않는다. AskUserQuestion은 Claude 런타임의 수단일 뿐이고, Codex를 비롯한 다른 런타임에는 그 도구가 없다. 도구 이름으로 계약을 쓰면 그 도구가 없는 런타임에서 게이트가 영구 blocker가 되어, 승인이 필요한 모든 작업이 그냥 멈춘다. 그건 안전이 아니라 고장이다.

승인은 아래 순서로 구한다. 위에서부터 실제로 가능한 첫 번째를 쓴다.

승인의 정의는 수단이 아니라 결과다: 승인서를 사용자에게 그대로 보여주고, 그에 대한 명시적 응답을 받는 것. 아래는 그 결과를 만드는 경로들이며, 위에서부터 가능한 첫 번째를 쓴다.

[HARD] 런타임의 도구 실행 권한 프롬프트는 승인이 아니다. 그 프롬프트는 "이 도구를 호출해도 되는가"를 물을 뿐, 게이트가 보여주기로 한 인자·견적·동의 문항을 표시하지 않는다. 승인서 전체와 선택지를 실제로 표시하는 경우에만 2번 경로로 인정한다.

[HARD] 2번 경로가 있으므로 "물을 수단이 없다"는 상황은 사실상 없다. 대화가 가능한 곳에서는 언제나 승인서를 글로 제시할 수 있다. fail-closed는 대화도 blocker 반환도 불가능한 완전 무인 실행에만 해당한다 — 그 경우에만 실행하지 않고 멈춘다.

[HARD] 3번을 쓸 때 blocker는 그 자체로 승인 요청서여야 한다. 상위가 무엇을 물어야 할지 모르면 되물을 수 없고, 그러면 교착된다. 다음을 모두 담는다:

• 승인받을 행위 한 줄 (무엇이 되돌릴 수 없는지 / 얼마가 나가는지)
• 게이트가 요구하는 인자 전부 (요약하지 않은 값)
• 선택지 목록 — 상위가 그대로 사용자에게 제시할 수 있는 형태
• 재개 방법 — 어떤 답을 받으면 무엇을 이어서 실행하는지

[HARD] 세 경로가 모두 불가능한 무인 실행에서는 실행하지 않는다(fail-closed). 물을 수단이 없다는 것은 승인을 받았다는 뜻이 아니다. 이때는 "승인 수단이 없어 진행하지 못했다"고 기록하고 멈춘다 — 조용히 진행하지 않는다. 반대로 대화가 가능한데 도구가 없다는 이유로 멈추는 것도 잘못이다. 2번 경로를 쓴다.

이 계약은 CLAUDE.local.md §범용성 원칙(OS 2종 × 런타임 2종에서 동일 동작)의 게이트 쪽 적용이다. 한 런타임에서만 도는 게이트는 미완성으로 본다.

수동 폴백 — UPLOAD-GUIDE.md + 스테이징 폴더

MCP가 없거나 미인증이면 사용자가 직접 업로드할 수 있는 산출물을 만듭니다.

1. 스테이징 폴더 구성 — 기본 ./design-sync-staging/에 DESIGN.md + 토큰 + 정리된 자산 사본 배치
2. UPLOAD-GUIDE.md 생성 — 업로드 우선순위·주의사항·Published 토글 절차 기재
3. 사용자 안내 — 폴더 전체를 claude.ai/design에 업로드하도록 지시

## Claude Design 업로드 가이드 (수동)

### 업로드 우선순위
1. DESIGN.md — 가장 먼저
2. 토큰 세트(DTCG/CSS/shadcn)
3. 로고 변형(SVG 우선)
4. 참고 자산

### 주의
- 모노레포 전체 X → 정리된 폴더만
- 민감 자산(고객 데이터·매출) 익명화 후 업로드
- 폰트 라이선스 확인

### Published 토글
1. 업로드 후 5-15분 대기(분석)
2. 테스트 프롬프트로 검증
3. 브랜드 일치 시 Published ON, 어긋나면 Remix

스테이징 폴더 레이아웃

./design-sync-staging/
├── DESIGN.md                    # 최우선
├── tokens/
│   ├── 02-tokens.json           # L1 DTCG SSOT
│   ├── colors_and_type.css      # L2 원시 CSS 변수
│   └── globals.css              # L3 semantic/shadcn + .dark
├── assets/
│   ├── logo/                    # 로고 변형(아래 매트릭스)
│   ├── fonts/                   # 라이선스 확인된 폰트
│   └── reference/               # 참고 이미지·캡처
└── UPLOAD-GUIDE.md              # 업로드 절차

UPLOAD-GUIDE.md 완전 템플릿

# Claude Design 업로드 가이드 (수동)

## 업로드 순서
1. DESIGN.md — 가장 먼저(디자인 시스템 요약)
2. tokens/ — L1 DTCG → L2 CSS → L3 globals.css 순
3. assets/logo/ — 변형별(가로/정사각/마스코트/화이트 녹아웃)
4. assets/fonts/ — 라이선스 확인된 것만
5. assets/reference/ — 톤 비교용 참고 자산

## 업로드 방법
1. claude.ai/design 진입 → Organization settings → Design systems
2. 위 폴더를 통째로 업로드(모노레포 전체 X)
3. `/design-login` 후 Claude Code 터미널이면 다음부터 자동 경로 사용 가능

## 주의
- 민감 자산(고객 데이터·매출 박힌 덱)은 익명화 후 업로드
- 폰트 라이선스 확인 — 불명 자산 제외
- 누락된 로고 변형은 "미제공"으로 표기(임의 생성 금지)

## Published 토글
1. 업로드 후 분석 대기(5–15분)
2. 테스트 프롬프트로 검증("마케팅 랜딩 페이지 디자인해 줘" 등)
3. 브랜드 일치 → Published ON / 어긋나면 Remix 또는 자산 추가

자산 변형 매트릭스 매핑 규칙

매핑 규칙: 원본 로고를 위 4변형으로 분류하고 각 변형에 용도 태그를 부여해 UPLOAD-GUIDE.md에 명시한다 — 업로드 후 Claude Design이 문맥별로 올바른 변형을 고르게 하기 위함. 제공되지 않은 변형은 "미제공"으로 표기하고 임의 생성하지 않는다.

출력 형식

## Claude Design 업로드 [자동 / 수동]

### 경로
- 선택: 자동(DesignSync MCP) / 수동 폴백
- 사유: [인증 상태 / MCP 가용성]

### (자동) 등록 결과
- finalize_plan: planId 발급 / writes N · deletes N
- write_files: N개 (localPath 업로드)
- register_assets: (레거시) @dsCard 자동 인덱싱 또는 N개 수동

### (수동) 산출물
- ./design-sync-staging/  (DESIGN.md + 토큰 + 자산 N개)
- ./design-sync-staging/UPLOAD-GUIDE.md

### 다음 단계
- (자동) 5-15분 분석 대기 → 테스트 프롬프트 → Published 토글
- (수동) 폴더 업로드 → 위 가이드 따라 진행

사용 예시

예시 1 — 인증됨 → 자동 등록

사전: DesignSync MCP 로드됨 + list_projects 정상 반환(인증됨)
동작: finalize_plan(writes=DESIGN.md+토큰+로고, localDir=./staging)
      → write_files(planId, localPath로 8개) → (@dsCard 자동 인덱싱)
출력: 자동 등록 완료 → 분석 대기
보고: finalize_plan planId 발급, write_files 8, 카드 자동 인덱싱

예시 2 — 미인증 → 수동 스테이징

사전: list_projects 호출 시 "DesignSync needs design-system authorization. Run
      /design-login to authorize it with your claude.ai account" 에러
동작: 자동 포기 → ./design-sync-staging/ 구성 + UPLOAD-GUIDE.md 생성
출력: 스테이징 폴더(DESIGN.md + tokens/ + assets/) + 가이드
안내: 폴더째 claude.ai/design 업로드. /design-login 하면 다음엔 자동 경로

예시 3 — 자동 시작 후 에러 → 폴백 전환

사전: 인증됨으로 자동 시작
동작: finalize_plan OK → write_files 진행 중 5개 중 2개 반복 실패
전환: 실패 배치 3회 재시도 후에도 실패 → 부분 기록 상태 고지 → 남은 자산 수동 스테이징
출력: (자동 부분: write_files 3개 완료) + (수동: 실패 2개 스테이징 + 재개 안내)
보고: 부분 성공을 완료로 보고하지 않음 — 미기록 파일 명시, 중복 방지 재개 안내

주의사항

Do

• 자동을 먼저 시도하고, 조건 미달 시 조용히 수동으로 강등 — 사용자 작업 흐름을 끊지 않음
• 수동 폴백에서도 사용자가 손으로 파일을 흩뿌리지 않도록 폴더를 완결적으로 구성
• 민감 자산은 업로드 전 익명화 안내

Don't

• /design-login 미인증 상태에서 자동 경로 강행 금지 — 즉시 수동 폴백
• 자동 부분 성공을 완료로 보고 금지 — finalize_plan까지 확정돼야 완료
• 폰트 라이선스 미확인 자산을 업로드 세트에 포함 금지

관련 스킬