부록 C. 자주 겪는 문제와 해결법

Claude Design을 처음 도입하면 사람들은 대개 프롬프트를 먼저 의심합니다. 그런데 실제로는 프롬프트보다 더 자주 발목을 잡는 것이 따로 있습니다. 접근 권한이 아직 열리지 않았거나, 사용량 제한을 잘못 이해했거나, 디자인 시스템의 기준 파일이 낡았거나, 공유 방식이 목적과 맞지 않는 경우입니다. 즉, 문제는 창의력보다 배관에서 더 많이 생깁니다.

다행히 반복되는 문제는 패턴도 반복됩니다. 아래 항목들은 실무에서 자주 만나는 증상을 기준으로 정리한 해결 가이드입니다. 막막할 때는 "왜 안 되지?"라고 오래 고민하기보다, 증상에 맞는 첫 점검 순서를 밟는 편이 훨씬 빠릅니다.

가장 먼저 보는 1분 진단표

이 표만 기억해도 삽질의 절반은 줄어듭니다. 많은 문제는 "복잡한 버그"가 아니라 "먼저 확인할 순서가 바뀐 상태"이기 때문입니다.

접근 권한 문제

Design 메뉴가 안 보여요

가장 흔한 오해부터 바로잡아 보겠습니다. Claude Design의 공식 시작점은 데스크톱 설치 파일이 아니라 웹 경로입니다. 먼저 claude.ai/design으로 직접 들어가 보세요. Claude Design은 리서치 프리뷰로 공개되었고, Pro, Max, Team, Enterprise 구독자를 대상으로 순차적으로 롤아웃됩니다. Enterprise는 기본적으로 꺼져 있을 수 있어서, 같은 회사 안에서도 어떤 사람은 보이고 어떤 사람은 안 보일 수 있습니다.¹

이럴 때는 세 단계만 차례대로 보면 됩니다.

1. 정말 claude.ai/design 경로로 접속했는지 확인합니다.

2. 현재 계정이 Pro, Max, Team, Enterprise 중 하나인지 확인합니다.

3. Enterprise라면 조직 관리자가 Claude Design을 켰는지 확인합니다.¹

여기서 중요한 포인트는, 본인 계정에 아직 열리지 않은 것을 브라우저 문제나 설치 문제로 오해하지 않는 것입니다. 문이 잠긴 상태에서 손잡이를 바꾸는 셈이 되기 쉽습니다.

팀원은 되는데 저는 안 돼요

이 경우는 거의 늘 권한 범위 문제입니다. Claude Design은 점진적으로 열리고, Enterprise에서는 조직 설정이 영향을 줍니다.¹ 같은 팀이라도 개인 계정, 팀 워크스페이스 계정, 회사 SSO 계정이 섞여 있으면 보이는 메뉴가 다를 수 있습니다.

이럴 때는 "왜 내 브라우저만 이상하지?"라고 생각하기보다, 지금 로그인한 계정이 어느 워크스페이스에 속해 있는지부터 보세요. 특히 회사 계정과 개인 계정을 번갈아 쓰는 사람은 이 지점에서 자주 헷갈립니다.

사용량 제한과 응답 오류

"usage limit reached"가 떴어요

이 문구는 기분은 나쁘지만 뜻은 꽤 명확합니다. 사용량 한도에 걸렸다는 뜻입니다. Claude Code 계열 문서 기준으로는 세션 제한, 주간 제한, 특정 모델 제한처럼 종류가 나뉘며, 메시지에는 보통 리셋 시각이 함께 표시됩니다.³ 다시 말해, 이 문제는 계정이 고장 난 것이 아니라 미터기가 잠시 닫힌 상태에 가깝습니다.

이럴 때는 다음 순서가 가장 빠릅니다.

1. 오류 문구에 적힌 리셋 시각을 먼저 확인합니다.

2. 가능하면 /usage로 현재 한도와 초기화 시점을 확인합니다.³

3. 급한 작업이면 추가 사용량 옵션이나 상위 플랜을 검토합니다.¹³

4. 특정 고사양 모델이 막혔다면 더 가벼운 모델이나 작은 작업 단위로 우회합니다.³

많은 사람이 여기서 저지르는 실수는, 제한에 걸린 상태에서 같은 큰 요청을 계속 다시 보내는 것입니다. 물이 안 나오는데 수도꼭지를 더 세게 돌리는 격입니다.

500, 529, timeout이 반복돼요

이건 사용량 문제와 다릅니다. Claude Code 문서에서는 500은 내부 서버 오류, 반복된 529는 일시적 과부하, timeout은 정해진 시간 안에 응답이 끝나지 않은 경우로 설명합니다.³ 이런 오류는 내 계정만의 문제라기보다 서비스 쪽 변동일 가능성이 큽니다.

가장 좋은 대응은 단순합니다. 먼저 상태 페이지를 확인하세요. Anthropic의 상태 페이지에는 현재 운영 상태와 최근 장애 이력이 올라오며, 실제로 업로드 실패나 특정 기능 장애 같은 사건도 수시로 기록됩니다.⁴

그다음에는 작업을 잘게 쪼개는 편이 좋습니다. 한 번에 거대한 파일 묶음, 긴 문맥, 무거운 요청을 모두 태우면 timeout이 더 자주 납니다.³ 급하면 모델을 바꾸는 것도 현실적인 방법입니다. 한 모델이 붐비는 시간에는 다른 모델로 옮겨서 작업을 이어가는 편이 전체 속도는 더 빠를 수 있습니다.³

업로드가 실패하거나 웹 캡처가 들쭉날쭉해요

이 경우는 로컬 문제와 서비스 문제를 구분하는 것이 핵심입니다. 상태 페이지에는 실제로 파일 업로드나 특정 연동 기능 장애가 올라온 적이 있습니다.⁴ 그러니 첫 번째 질문은 "내 파일이 이상한가?"가 아니라 "오늘 서비스가 조용한가?"가 되어야 합니다.

상태 페이지에 이상이 없다면, 다음으로는 입력을 단순화해 보세요. 큰 파일 여러 개를 한 번에 넣기보다 한두 개씩 나눠 올리고, 꼭 필요한 자료부터 넣는 편이 좋습니다. 문제 재현도 쉬워지고, 어느 입력에서 실패하는지도 빨리 찾을 수 있습니다.

디자인 시스템 품질 문제

연결은 했는데 결과물이 우리 팀 디자인처럼 안 보여요

Claude Design의 강점은 온보딩 때 코드베이스와 디자인 파일을 읽고 팀의 색상, 타이포그래피, 컴포넌트를 반영한다는 점입니다.¹ 하지만 이 장점은 뒤집으면 조건문이기도 합니다. 읽어야 할 기준이 흐리면 결과도 흐려집니다.

가장 흔한 원인은 세 가지입니다.

• 연결한 저장소가 너무 넓거나 오래되었습니다.

• 디자인 토큰과 실제 배포 코드가 서로 다른 말을 합니다.

• 프롬프트에서 팀이 쓰는 실제 컴포넌트 이름을 쓰지 않았습니다.

공식 튜토리얼도 관련 패키지나 디렉터리만 연결하라고 권합니다. 거대한 모노레포 전체를 붙이면 느려질 뿐 아니라, Claude가 무엇을 기준으로 삼아야 할지도 흐려집니다.² 또한 프롬프트에서 Button, ProductCard, SettingsLayout처럼 실제 이름을 언급하면 더 안정적으로 기존 패턴을 따라갑니다.²

요령은 간단합니다. Claude가 "예쁜 걸 상상"하게 하지 말고, "우리 팀이 이미 쓰는 것을 조합"하게 만들어야 합니다.

브라우저가 버벅이거나 연결 후 멈춰요

이 문제는 생각보다 기술적이기보다 정리 문제인 경우가 많습니다. 공식 가이드에 따르면 아주 큰 저장소를 연결하면 지연이나 브라우저 안정성 문제가 생길 수 있고, 특히 .git이나 node_modules 같은 폴더는 제외하는 편이 좋습니다. Chrome이 거대한 파일 트리를 다루는 데 약한 경우도 있다고 안내합니다.²

이럴 때는 저장소를 더 크게 붙이는 게 아니라 더 작게 붙여야 합니다. 디자인 시스템 패키지, 프런트엔드 앱 폴더, 공통 UI 라이브러리처럼 실제로 필요한 범위만 연결하세요.² "전체를 다 보여 주면 더 잘 알겠지"라는 직감은 여기서는 자주 틀립니다. 너무 많은 힌트는 힌트가 아니라 소음이 됩니다.

있는 컴포넌트도 자꾸 새로 만들어요

이 증상은 대개 Claude가 몰라서가 아니라, 사람 쪽에서 기준 이름을 충분히 주지 않아서 생깁니다. Claude Design은 연결된 코드베이스를 바탕으로 컴포넌트 구조와 스타일 패턴을 이해할 수 있고, 특정 컴포넌트 이름을 프롬프트에 직접 넣는 방식도 권장됩니다.²

예를 들어 "카드형 리스트를 만들어 줘"보다 "기존 ProductCard를 사용하고, 설정 화면은 현재 settings page와 같은 레이아웃 패턴을 따르게 해 줘"가 훨씬 잘 먹힙니다.² 디자인 시스템이 자동이라는 말은, 아무 말 안 해도 항상 완벽하다는 뜻이 아닙니다. 자동 변속차도 운전대는 잡아야 하는 것과 비슷합니다.

협업과 공유 문제

링크를 보냈는데 동료가 못 열어요

Claude Design의 공유는 조직 범위를 기준으로 동작합니다. 즉, 내부 URL은 조직 안에서 쓰기 좋지만, 조직 밖 사람에게는 그대로 통하지 않을 수 있습니다. 대신 목적에 따라 Canva, PDF, PPTX, 독립형 HTML로 내보낼 수 있습니다.¹

여기서 자주 생기는 문제는 링크가 틀린 것이 아니라 전달 방식이 틀린 경우입니다. 사내 리뷰면 내부 URL이 가장 편합니다. 외부 파트너나 고객 공유면 PDF나 PPTX가 안전합니다. 편집까지 이어져야 한다면 Canva가 낫고, 프로토타입 감각을 유지하려면 HTML이 더 적합할 수 있습니다.¹

쉽게 말해, "누가 볼 것인가"와 "어디까지 손댈 것인가"를 먼저 정해야 공유 사고가 줄어듭니다.

여러 사람이 만지다 보니 버전이 꼬여요

Claude Design은 함께 수정하기 좋은 대신, 그래서 더 쉽게 섞이기도 합니다. 특히 하나의 방향이 확정되기 전에 여러 사람이 동시에 각자 다른 수정을 넣으면, 결과는 풍성해지기보다 흐려집니다.

이럴 때는 최신본을 감으로 정하면 안 됩니다. 최종 리뷰용 버전 하나를 정하고, 큰 수정 전에는 스냅샷을 남기고, 채팅 안에 왜 그렇게 바꿨는지 짧게라도 기록하는 습관이 필요합니다. 공식 튜토리얼도 의사결정을 채팅에 남겨 두는 것이 핸드오프와 협업에 중요하다고 강조합니다.²

버전 충돌은 파일의 문제가 아니라 기억의 문제입니다. 그래서 해결책도 저장보다 기록에 가깝습니다.

내보낸 파일이 원본과 다르게 느껴져요

이것도 자주 나오는 불만입니다. 하지만 대부분은 내보내기 품질 문제라기보다 기대치 문제입니다. PDF는 보기에는 안정적이지만 편집이 거의 안 됩니다. PPTX는 발표와 후수정에 좋지만, 모든 상호작용을 그대로 담는 용도는 아닙니다. Canva는 협업 편집에 강하고, HTML은 독립 실행형으로 프로토타입 느낌을 살리기 좋습니다.¹

그러니 결과물이 달라 보인다면 먼저 "내가 필요한 것은 무엇이었지?"를 다시 물어야 합니다. 예쁜 정적 공유가 목적이면 PDF로 충분합니다. 발표 자료가 목적이면 PPTX가 맞습니다. 클릭감 있는 시연이 목적이면 HTML 쪽이 더 자연스럽습니다.¹

핸드오프와 구현 문제

Claude Code로 넘겼는데 구현이 자꾸 엇나가요

핸드오프는 파일 전송이 아니라 맥락 전송입니다. 공식 튜토리얼에 따르면 Claude Design에서 Claude Code로 넘길 때는 디자인 파일, 대화 내용, README가 함께 묶입니다.² 그런데 여기서 README가 비어 있거나, 왜 탭을 골랐는지 같은 의사결정이 채팅에 남아 있지 않으면, 구현 단계에서는 다시 추측이 시작됩니다.

이 문제를 줄이는 가장 좋은 방법은 핸드오프 전에 엣지 케이스를 먼저 드러내는 것입니다. 공식 가이드도 빈 상태, 오류 상태, 로딩 상태, 데이터 양이 달라질 때의 상태를 미리 보여 달라고 권합니다.² 구현이 엇나가는 이유는 보통 "메인 화면을 못 봐서"가 아니라 "주변 상태를 못 봐서"입니다.

Claude Code에서 Figma 연결이 안 돼요

이 문제는 먼저 경계를 분리해야 합니다. Claude Design 자체 접근과 Claude Code의 Figma 연결은 같은 일이 아닙니다. Claude Code에서 Figma 파일을 구조적으로 읽고 싶다면 공식 Figma MCP 연결 경로를 따라야 합니다. Figma 도움말은 원격 MCP 서버를 일반 사용자용 기본 옵션으로 권장하며, Claude Code에서는 공식 Figma 플러그인을 설치하고 인증하는 흐름을 안내합니다.⁵

설정 순서는 비교적 단순합니다.

1. 터미널에서 공식 Figma 플러그인을 설치합니다: claude plugin install figma@claude-plugins-official.⁵

2. Claude Code를 재시작하고 /plugin에서 설치된 Figma 서버를 인증합니다.⁵

3. 연결 후에는 Figma URL을 바탕으로 구현 요청을 하거나, /implement-design, /create-design-system-rules, /code-connect-components 같은 흐름을 활용할 수 있습니다.⁶

중요한 것은, Figma 플러그인이 연결되지 않았는데 Claude Design이 안 되는 것처럼 오해하지 않는 것입니다. 부엌 수도와 욕실 수도는 같은 집에 있어도 밸브가 다릅니다.

"이상하긴 한데 정확한 에러는 없어요"라는 상황

가장 어려운 유형이지만, 의외로 해결 방식은 명확합니다. 에러 문구가 없을수록 감이 아니라 증거가 필요합니다. 특히 아래 정보를 모아 두면 문제를 훨씬 빨리 좁힐 수 있습니다.

• 어떤 계정과 플랜을 쓰는지

• 어떤 경로에서 문제가 생겼는지 (claude.ai/design, Claude Code, Figma 플러그인 등)

• 정확한 시각과 타임존

• 오류 문구가 있었는지, 없었다면 어떤 동작에서 멈췄는지

• 브라우저와 운영체제

• 업로드한 파일 종류와 대략적인 크기

• 같은 문제가 재현되는 최소 단계

• 그 시각의 상태 페이지 이상 여부 ⁴

이 정보가 있으면 "잘 안 돼요"가 "4월 27일 오후 3시 12분, Team 워크스페이스, Chrome에서 HTML 내보내기만 실패"로 바뀝니다. 지원팀이든 팀 동료든, 후자는 훨씬 빨리 도와줄 수 있습니다.

끝까지 막힐 때의 우선순위

문제가 길어질수록 사람은 본능적으로 더 많은 것을 한 번에 바꾸고 싶어집니다. 하지만 그럴수록 원인은 더 안 보입니다. 그럴 때는 아래 순서를 지키는 편이 낫습니다.

1. 계정과 권한 문제인지 확인합니다.

2. 상태 페이지와 서버 상태를 확인합니다.⁴

3. 같은 작업을 더 작은 입력으로 재현해 봅니다.

4. 연결 범위를 줄여 디자인 시스템 기준을 선명하게 만듭니다.²

5. 공유 방식과 내보내기 형식이 목적에 맞는지 다시 고릅니다.¹

6. 구현 단계 문제면 핸드오프 맥락과 엣지 케이스부터 보강합니다.²

대부분의 문제는 이 여섯 칸 안에서 해결됩니다. 그리고 그 사실이 오히려 반갑습니다. 자주 생기는 문제는, 자주 고칠 수 있는 문제이기도 하니까요.

참고

¹Introducing Claude Design by Anthropic Labs

²Using Claude Design for prototypes and UX

³Error reference - Claude Code Docs

⁴Claude Status

⁵Claude Code and Figma: Set up the MCP server

⁶Figma – Claude Plugin | Anthropic