Claude Code를 이용해 디자인 작업을 할 때, CLAUDE.md 파일을 제대로 설정해두면 결과물의 품질과 일관성이 눈에 띄게 달라져요. CLAUDE.md는 Claude가 프로젝트를 시작할 때 자동으로 읽어 들이는 마크다운 형식의 지침 파일이에요. 여기에 디자인 원칙, 색상 시스템, 컴포넌트 규칙, 금지 패턴 등을 담아두면 Claude가 항상 그 기준을 따라 작업해줘요.
이 파일이 없으면 매 대화마다 같은 설명을 반복해야 하고, 프로젝트가 길어질수록 디자인 일관성이 흔들릴 수 있어요. 지금부터 디자인 작업을 위한 CLAUDE.md 파일을 어떻게 구성하고 작성해야 하는지 단계별로 알아봐요.
CLAUDE.md 파일이 디자인 작업에 미치는 영향
매 세션마다 다른 결과물 문제 해결
Claude와 디자인 작업을 하다 보면 오늘 만든 버튼 스타일과 내일 만든 버튼 스타일이 달라지는 문제를 경험할 수 있어요. Claude는 대화 맥락을 기억하지 못하기 때문에, 이전 세션에서 설정했던 기준이 다음 세션에서는 적용되지 않아요. CLAUDE.md 파일은 이 문제를 해결해줘요.
파일이 프로젝트 루트에 있으면 Claude Code가 세션을 시작할 때 자동으로 이 파일을 읽어서 기준을 세워요. 덕분에 오늘 작업하든 한 달 후에 작업하든 항상 같은 디자인 기준이 유지돼요.
팀 작업에서의 디자인 일관성
여러 명이 Claude Code를 함께 사용하는 팀이라면 CLAUDE.md 파일이 더욱 중요해요. 각 팀원이 자기 스타일로 Claude에게 디자인을 요청하면 결과물이 제각각이 되기 쉬워요. 공유된 CLAUDE.md 파일이 있으면 누가 요청하든 같은 디자인 기준으로 결과물이 생성돼요. Git에 커밋해두면 팀 전체가 동일한 기준을 공유할 수 있어요.
디자인용 CLAUDE.md 파일 기본 구조
파일 위치와 형식
CLAUDE.md 파일은 프로젝트 루트 디렉토리에 위치해야 해요. Claude Code가 프로젝트를 열 때 이 위치에서 파일을 자동으로 찾기 때문이에요. 파일 이름은 반드시 CLAUDE.md여야 하고, 마크다운 형식으로 작성해요.
파일 크기는 너무 길면 효율이 떨어질 수 있어요. Claude가 파일 전체를 컨텍스트로 읽기 때문에, 핵심 내용만 간결하게 담는 게 중요해요. 일반적으로 300~800단어 정도가 적당하며, 꼭 필요한 내용만 담는 것을 권장해요.
디자인 섹션의 기본 구성
CLAUDE.md의 디자인 섹션은 다음 구성을 기본으로 해요.
- 디자인 철학: 이 프로젝트의 UI가 추구하는 방향성 요약
- 색상 시스템: 사용 가능한 색상 목록과 용도
- 타이포그래피: 폰트, 크기, 가중치 기준
- 컴포넌트 규칙: 주요 UI 요소 작성 패턴
- 금지 사항: 절대 사용하지 말아야 할 스타일과 패턴
이 구조를 따르되 프로젝트 성격에 맞게 내용을 채우면 돼요. 처음에는 필수 항목만 채우고, 작업하면서 필요한 내용을 추가해나가는 방식이 가장 효과적이에요.
색상 시스템 설정하기
브랜드 컬러 정의 방법
색상은 브랜드 정체성의 핵심이에요. CLAUDE.md에 브랜드 컬러를 명확히 정의해두면 Claude가 임의의 색상을 사용하지 않아요. 정의할 때는 색상 이름과 실제 값을 함께 적고, 각 색상의 용도도 명시하는 게 좋아요.
예를 들어 “Primary: #2563EB – 주요 버튼, 링크, 강조 요소에 사용”, “Text: #111827 – 메인 텍스트”, “Background: #F9FAFB – 페이지 배경” 같은 방식으로 적어두면 Claude가 컴포넌트를 만들 때 이 팔레트에서 색상을 선택해요. 색상 이름을 CSS 변수 형식으로 정의해두면 Claude가 실제 코드에서도 변수를 사용해요.
다크 모드 지원 여부 명시
다크 모드를 지원하는 프로젝트라면 이를 명확히 명시해야 해요. Claude가 컴포넌트를 만들 때 다크 모드 클래스나 CSS 변수를 자동으로 포함시켜줘요. “Tailwind의 dark: 접두사를 사용하며, 시스템 설정에 따라 자동 전환해요”라고 적어두면 충분해요. 다크 모드가 필요 없다면 “다크 모드 미지원, 라이트 모드만 구현해요”라고 명시하면 Claude가 불필요한 다크 모드 코드를 추가하지 않아요.
타이포그래피 기준 설정
폰트 패밀리와 크기 체계
한국어 웹 프로젝트에서 폰트 선택은 가독성에 큰 영향을 미쳐요. 사용할 폰트와 그 로딩 방법, 크기 체계를 CLAUDE.md에 정의해두면 Claude가 텍스트 요소를 만들 때 일관된 폰트 체계를 적용해요.
- 한글 폰트: Pretendard (Google Fonts 또는 CDN)
- 영문 폰트: Inter
- 폴백 폰트: system-ui, sans-serif
- 기본 크기: 16px (1rem)
- 스케일: 12/14/16/18/20/24/32/40/48px
폰트 크기 스케일을 명시해두면 Claude가 임의로 13px, 15px 같은 비표준 크기를 사용하지 않아요. 정해진 스케일 안에서만 크기를 선택하기 때문에 타이포그래피가 자연스럽게 통일돼요.
컴포넌트 디자인 규칙
공통 UI 요소 스펙
자주 사용하는 UI 요소들의 기본 스펙을 정의해두면 Claude가 컴포넌트를 일관되게 만들어줘요. 완벽하게 모든 요소를 정의하지 않아도 돼요. 가장 많이 쓰이는 5~7개 요소만 정의해도 큰 효과가 있어요.
- 버튼: 높이 40px, 패딩 0 16px, 반경 8px, 호버 시 밝기 10% 증가
- 입력 필드: 높이 40px, 테두리 1px, 포커스 시 Primary 색상 테두리
- 카드: 배경 white, 그림자 shadow-sm, 반경 12px, 패딩 24px
- 헤딩: H1-H3만 사용, 페이지당 H1은 하나만
간격과 레이아웃 기준
간격은 디자인의 리듬감을 만드는 요소예요. 8px 단위 그리드를 기준으로 간격을 정의해두면 Claude가 여백과 패딩을 일관되게 적용해요. “간격은 4px 배수만 사용하며, 컴포넌트 간격은 최소 16px 이상”처럼 명확하게 적어두면 돼요.
금지 패턴 명시하기
코드 품질을 위한 금지 사항
금지 패턴을 명확히 적어두는 것은 CLAUDE.md에서 가장 강력한 효과를 내는 부분 중 하나예요. Claude는 금지 사항을 적극적으로 지키려고 노력하기 때문에, 자주 발생하는 문제 패턴들을 금지 목록에 담아두면 코드 품질이 크게 향상돼요.
- 인라인 스타일(style 속성) 사용 금지
- !important 사용 금지
- px 하드코딩 금지 (rem 또는 Tailwind 클래스 사용)
- 임의 z-index 값 사용 금지
- 디자인 토큰 외의 색상 직접 입력 금지
이 목록은 실제 코드 리뷰에서 자주 지적받는 항목들로 채우면 가장 효과적이에요. 팀원들과 함께 작성하면 공통된 품질 기준을 자연스럽게 만들 수 있어요.
마무리 – 디자인을 위한 CLAUDE.md 파일로 AI의 힘을 최대화해요
디자인 작업을 위한 CLAUDE.md 파일은 Claude Code를 단순한 코드 생성기에서 진정한 디자인 파트너로 업그레이드시켜줘요. 색상 시스템, 타이포그래피, 컴포넌트 규칙, 금지 패턴을 체계적으로 담아두면 매 작업마다 일관되고 완성도 높은 UI가 자동으로 만들어져요.
완벽한 파일을 처음부터 만들려고 하지 않아도 돼요. 가장 기본적인 색상 팔레트와 기술 스택부터 시작해서, 프로젝트를 진행하면서 하나씩 추가해나가면 충분해요. 오늘 바로 시작해봐요!