디자인 시스템 구축부터 Git 버전 관리, AI 활용까지 — WE-AR 실무 운영 기준
AI 기반 디자인 시스템 운영 · MD 파일 관리 · Wiki · Git 버전 관리
이 프로세스는 기존 방식과 무엇이 다른가. 도입 전/후를 구체적으로 비교합니다.
| 항목 | 기대 방향 | 비고 |
|---|---|---|
| 1차 시안 수정 반복 횟수 | 감소 | 파일럿 후 실측 |
| 디자이너–개발자 커뮤니케이션 비용 | 감소 | 파일럿 후 실측 |
| 신규 페이지 제작 속도 | 향상 | 파일럿 후 실측 |
| 프로젝트 간 자산 재활용 | 누적 성장 | 프로젝트가 쌓일수록 증가 |
| 항목 | 내용 |
|---|---|
| 전체 프로세스 | STEP 0~7, 8단계 AI 기반 디자인-개발 워크플로우 |
| MD 파일 관리 | 파일 작성 규격, 크기 제한, 구조 규칙 |
| Wiki 폴더 구조 | 디자인 시스템 폴더 규격 및 각 폴더의 역할 |
| Git 버전 관리 | 브랜치 전략, 커밋 규칙, PR 프로세스 |
| AI 활용법 | Claude Project, Claude Code, Figma MCP 연동 방식 |
모든 AI가 참조할 디자인 시스템 Wiki의 뼈대를 만든다. 두 단계로 진행한다.
아래 정보를 Claude에게 입력하면 foundations/ 파일 초안을 자동 생성한다.
README.md 브랜드 톤, 타겟 사용자, 기술 제약 기술 완료rules/ 금지사항, 필수사항 초안 작성 완료feat(ds): STEP 0 foundations 초안 확정먼저 서비스 전체 구조(사이트맵, 플로우)를 확정한 뒤, 페이지별 상세 기획서를 작성한다.
STEP 0에서 확정된 토큰을 바탕으로 컴포넌트 .md를 작성한다. 두 경로를 병행할 수 있다.
components/ 초안 생성components/*.md 업그레이드Claude가 생성한 코드를 Codex가 독립적으로 검증한다. 생성한 AI가 직접 검증하면 같은 오해를 반복할 수 있으므로 별도 AI를 사용한다.
기획서 + 디자인 시스템 Wiki → 코드 자동 생성. Figma 단계 없이 바로 프론트 시안으로 직행.
AI가 자동으로 토큰 위반, 접근성, 반응형 깨짐을 탐지하고, 사람이 시각적 밸런스와 브랜드 톤을 최종 판단한다.
rules/qa.md를 생성하여 체크리스트를 작성하고, 배포 전 반드시 검수하세요. 이 파일이 없으면 STEP 5를 완료로 처리하지 마세요.기획 단계에서 정의된 인터렉션을 구현. 초기 라이브러리 세팅에 영향을 미치므로 시안과 함께 완성한다.
배포 후 피드백을 분류하여 해당 STEP으로 되돌아간다. 디자인 시스템 수정 시 반드시 Wiki .md 파일도 함께 업데이트.
| 크기 (텍스트 기준) | 상태 | 조치 |
|---|---|---|
| 15KB 이하 | 정상 | AI가 한 번에 소화 가능. 유지. |
| 15~30KB | 주의 | 분할 검토. 하나의 주제인지 재점검. |
| 30KB 초과 | 분할 필요 | 즉시 카테고리별로 분리할 것. |
| 유형 | 저장 위치 | .md 파일 내 참조 방식 |
|---|---|---|
| 컴포넌트 스크린샷 / GIF | references/figma-exports/ |  |
| 페이지 시안 이미지 | pages/{page}/assets/ |  |
| 인터렉션 시연 영상 | 외부 호스팅 (Loom, YouTube 등) | [인터렉션 시연 영상](https://loom.com/...) |
# [컴포넌트명] ## 목적 이 컴포넌트가 왜 존재하는가, 어떤 문제를 해결하는가. ## 구조 / 상태 (States) / 변형 (Variants) ## 규칙 (Rules) ### ✅ DO ### ❌ DON'T ## 맥락 (Context) ## 코드 레퍼런스 ## 디자인 토큰 참조
| 유형 | 규칙 | 예시 |
|---|---|---|
| 기초 토큰 | 소문자, 단수형 | color.md, spacing.md |
| 컴포넌트 | 소문자, 단수형 | button.md, input.md |
| 패턴 | 소문자, 단수형, 하이픈 | loading-state.md |
| 페이지 기획서 | 폴더명은 URL 경로 기준, 단수형 | /pages/product-detail/spec.md |
README.md → foundations/ → rules/ → components/ → patterns/ → 해당 페이지 spec.md/design-system/
│
├── README.md # 프로젝트 개요, 브랜드 철학, 타겟 사용자
├── CLAUDE.md # Claude Code 자동 컨텍스트 로딩
├── foundations/ # 디자인 토큰 (colors, typography, spacing …)
├── components/ # UI 컴포넌트 .md
├── patterns/ # 복합 UI 패턴 .md
├── rules/ # 규칙 (dos-and-donts, ai-prompt-rules, qa …)
├── pages/ # 페이지별 기획서 spec.md
│ └── {page-name}/
│ ├── spec.md
│ └── notes.md
├── tokens/ # tokens.json, tokens.css
├── docs/ # 프로세스 문서
│ ├── ui-design-process.md
│ └── UI_Design_Process_Guide.html
└── references/
├── brand-guide-summary.md
└── figma-exports/docs/colors: 다크모드 시맨틱 컬러 토큰 추가 docs/button: Disabled 상태 규칙 명확화 tokens: --color-primary 값 수정 rules: 모달 안 버튼 Variant 규칙 추가 feat(ds): STEP 0 foundations 초안 확정
| 단계 | 내용 | 담당 |
|---|---|---|
| 1. 브랜치 생성 | 작업 내용이 명확한 브랜치명으로 시작 | 작업자 |
| 2. 작업 및 커밋 | .md 파일 수정, 필요 시 tokens.json/tokens.css 함께 수정 | 작업자 |
| 3. PR 생성 | 변경 이유, 영향 범위, 검토 포인트를 PR 설명에 기재 | 작업자 |
| 4. 리뷰 | 디자인 시스템 충돌 여부, 기존 규칙과의 정합성 확인 | 리드 디자이너 |
| 5. 병합 | 승인 후 main 병합. Squash merge 권장. | 리드 디자이너 |
page/ 브랜치가 같은 components/button.md를 동시에 수정하면 merge 충돌이 발생합니다.page/ 브랜치에서 components/, foundations/ 파일을 직접 수정하지 말고, 별도 ds/ 브랜치를 열어서 main에 먼저 병합 후 진행하세요.# 이 프로젝트의 디자인 시스템
## 필수 참조 파일 (반드시 이 순서로 읽을 것)
1. /design-system/README.md
2. /design-system/foundations/ (전체)
3. /design-system/rules/ (전체)
4. 작업 중인 페이지의
/design-system/pages/{page}/spec.md
## 코드 생성 규칙
- 디자인 토큰만 사용 (하드코딩 금지)
- components/에 정의된 컴포넌트 반드시 사용
- 반응형: mobile-first, breakpoints.md 참조
- 접근성: ARIA 라벨, 키보드 내비게이션 필수
## AI 자율 판단 규칙
- 필수 조건이 걸린 경우에도, 해당 조건을 지키지 않으면서
더 나은 방향이 있는지 검토하고 장단점을 분석하여
역으로 제안할 것
- 규칙을 따르다 더 좋은 선택지를 발견하면 반드시 제안할 것.
단, 제안과 구현은 구분하여 사용자가 결정하도록 할 것CLAUDE.md가 담당합니다.1. Claude Cowork 앱 실행 2. 프로젝트 Wiki 폴더 선택 3. Claude가 CLAUDE.md를 읽고 프로젝트 규칙 자동 인식 4. 자연어로 요청: "colors.md에 브랜드 컬러 팔레트 작성해줘"
# 저장소 루트에 CLAUDE.md가 있으면 자동 참조 claude # 실행 → 디자인 시스템 규칙 자동 인식
| 도구 | 역할 | 사용 시점 |
|---|---|---|
| Claude Project | DS Wiki를 Project Knowledge에 등록하여 일관된 결과 획득 | STEP 0 완료 후, 전체 기간 |
| Claude Code | 로컬 .md 파일 직접 참조하며 코드 생성. CLAUDE.md로 자동 컨텍스트 로딩 | STEP 4~6 |
| Figma MCP | Figma에서 직접 토큰·컴포넌트 정보 읽어 .md 초안 자동 생성 | STEP 2 |
| Codex | GitHub 저장소에 연결하여 rules/ 기준으로 코드 위반 항목 독립 검증 | STEP 3, STEP 5 |
/design-system/README.md 읽기/design-system/foundations/ 전체 읽기/design-system/rules/ai-prompt-rules.md 읽기모델을 잘 쓰는 것만큼 중요한 것이 프롬프트를 잘 쓰는 것입니다. 같은 결과를 더 적은 비용으로, 더 일관된 품질로 얻기 위한 실무 기준을 정리했습니다.
| 모델 | 언제 쓰나 | 쓰지 말아야 할 때 |
|---|---|---|
| Claude Haiku | 단순 질문, 텍스트 요약, 오탈자 수정, 반복적인 단순 변환 | 코드 생성, 구조적 판단이 필요한 작업 |
| Claude Sonnet ✅ 기본 | 컴포넌트 코드 생성, MD 파일 작성, 디자인 시스템 검토, 페이지 시안 생성, 일반 작업 전체 | 특별히 없음. 거의 모든 작업에 적합 |
| Claude Opus | 아키텍처 수준의 구조 설계, 매우 복잡한 로직 설계, 기술 의사결정이 필요한 경우 | 반복 작업, 단순 코드 생성, 일반 UI 작업 |
Claude는 대화창에 올라온 파일을 전부 읽습니다. 불필요한 파일을 첨부하면 관련 없는 내용이 응답에 섞입니다.
| 작업 유형 | 첨부할 파일 | 첨부 불필요 |
|---|---|---|
| 새 컴포넌트 제작 | color.md, typography.md, spacing.md, ai-prompt-rules.md | 완성된 다른 페이지 spec.md |
| 특정 페이지 시안 | 해당 페이지 spec.md + foundations/ 전체 + rules/ | 다른 페이지 spec.md |
| 버그 수정 / 스타일 조정 | 해당 코드 파일만 | 디자인 시스템 전체 |
| MD 파일 작성 | _template.md + 참고할 기존 md 1개 | foundations/, rules/ 전체 |
| 요소 | 설명 | 예시 |
|---|---|---|
| 역할 | Claude에게 어떤 관점으로 답할지 지정 | "너는 WE-AR 디자인 시스템을 관리하는 디자이너야" |
| 참조 | 어떤 파일/기준을 보고 작업할지 명시 | "첨부한 color.md와 button.md를 기준으로" |
| 지시 | 무엇을 만들어야 하는지 구체적으로 | "상품 카드 컴포넌트의 hover 상태 CSS를 작성해줘" |
| 제약 | 하면 안 되는 것, 형식 제한 | "하드코딩된 색상값은 쓰지 마. 토큰만 사용" |
| 출력 형식 | 어떻게 돌려줄지 지정 | "코드만 출력해줘, 설명은 필요 없어" |
첨부 파일의 디자인 시스템을 기준으로 [컴포넌트명] 컴포넌트를 만들어줘. 조건: - 디자인 토큰만 사용 (하드코딩 금지) - 상태: default / hover / active / disabled - 반응형: mobile-first 코드만 출력해줘.
첨부한 spec.md 기준으로 [페이지명]의 [섹션명] 섹션만 먼저 만들어줘. 전체 페이지는 나중에 할 테니 이 섹션만 집중해서 완성도 있게 만들어줘. 완성되면 다음 섹션 요청할게.
아래 코드에서 하드코딩된 색상값, px 값을 찾아서 첨부한 tokens.css의 CSS 변수로 전부 교체해줘. 로직은 건드리지 말고 스타일만 수정해. [코드 붙여넣기]
첨부한 _template.md 포맷에 맞춰서 [컴포넌트명] 컴포넌트의 .md 파일 초안을 작성해줘. 브랜드 기준: [간단한 브랜드 설명] 특이사항: [있으면 작성] 15KB 이하로 유지해줘.
처음 Git을 사용하는 팀원이 실제로 가장 많이 묻는 질문들을 모았습니다.
처음 한 번만 세팅하면 됩니다. 순서대로 따라하세요.
git --version
버전 번호가 뜨면 설치된 것. 아무것도 안 뜨면 https://git-scm.com 에서 Git 설치 후 다시 시작하세요.
git config --global user.name "홍길동" git config --global user.email "you@example.com"
GitHub 커밋 기록에 표시될 이름과 이메일입니다. 실제 GitHub 계정 이메일을 쓰는 것이 좋습니다.
git clone 복사한주소 실행cd 폴더경로git init — Git 저장소로 초기화git remote add origin GitHub주소 — 원격 연결git add . → git commit -m "첫 커밋" → git push -u origin main처음 push할 때 로그인 창이 뜨거나 비밀번호를 묻습니다. 비밀번호 입력란에는 GitHub 계정 비밀번호가 아닌 Personal Access Token(PAT)을 넣어야 합니다.
GitHub 저장소 페이지에서 확인합니다.
있습니다. 대표적인 케이스 3가지와 각 대처 방법입니다.
| 케이스 | 상황 | Git 반응 | 대처 |
|---|---|---|---|
| 동시 수정 | A와 B가 같은 파일을 동시에 고쳐서 각자 푸시 | 충돌(conflict) 발생 → 자동으로 막아줌 | 충돌 해결 후 재푸시. "이 파일 건드릴게요" 한 마디로 예방 가능 |
| 순서 작업 · 기준 불일치 | A가 버튼 색상을 바꿨는데 B는 모르고 이전 기준으로 다른 컴포넌트 작성 | 충돌 없음 — Git은 모름 | 작업 전 반드시 git pull. 커밋 메시지에 변경 이유 명시 |
| AI에게 오래된 파일 제공 | 최신 .md가 아닌 이전 버전을 Claude에 넣고 코드 생성 | Git은 모름 — 결과물만 틀어짐 | AI 작업 전 항상 최신 파일 pull 후 사용 |
git clone https://github.com/Naisyuna/UI-Process 입력git pull 한 번으로 최신 버전 업데이트 가능git pull 한 번으로 다른 사람이 올린 최신 파일을 바로 받을 수 있습니다.
| 명령어 | 하는 일 | 언제 쓰나 |
|---|---|---|
git pull | 원격(GitHub)의 최신 파일을 내 컴퓨터로 받아옴 | 작업 시작 전 항상 |
git add . | 변경된 파일 전체를 커밋 대기 상태로 올림 | 커밋 직전 |
git commit -m "메시지" | 변경 내용을 이력으로 저장 | add 직후 |
git push | 저장된 커밋을 GitHub에 올림 | commit 직후 |
git clone URL | GitHub 저장소를 내 컴퓨터에 처음 복사 | 최초 1회 |