AI 에이전트에 코딩 규칙과 디자인 규칙을 동시에 적용하는 Claude Code 팀 설정 — CLAUDE.md와 DESIGN.md 병용법

AI 코딩 에이전트를 팀에서 쓰다 보면 꼭 한 번은 이런 상황을 맞닥뜨리게 됩니다. 새 컴포넌트를 AI가 뚝딱 만들어줬는데, 코드 스타일은 완벽한데 버튼 색상이 브랜드 가이드와 전혀 다른 파란색. 혹은 반대로, 디자인은 예쁜데 async/await 대신 .then() 체인이 가득한 코드. 저도 처음엔 프롬프트를 더 길게 쓰면 해결될 거라 생각했습니다. 그런데 아무리 자세히 써도 한쪽을 맞추면 다른 쪽이 무너지는 일이 반복됐습니다.

해결책은 생각보다 훨씬 구조적인 곳에 있었습니다. CLAUDE.md로 코딩 규칙을, DESIGN.md로 디자인 규칙을 각각 명시하고 두 파일을 함께 Git에 커밋하면, 팀 전체가 동일한 AI 동작 기준을 공유하게 됩니다. 2026년 4월 Google이 DESIGN.md 포맷을 Apache 2.0으로 오픈소스화하면서 이 방식에 대한 관심이 급격히 높아지고 있습니다.

특히 Next.js + Tailwind CSS 같은 웹 프론트엔드 스택을 쓰는 팀에 가장 잘 맞는 내용입니다. 백엔드 중심 팀이라면 예시 2(모듈형 규칙 구성)부터 살펴보시면 도움이 될 것 같습니다.

핵심 개념

CLAUDE.md — AI 에이전트의 코딩 헌법

CLAUDE.md는 Claude Code가 세션을 시작할 때 자동으로 읽어들이는 마크다운 파일입니다. 아키텍처 결정, 빌드 명령, 테스트 패턴, 네이밍 컨벤션 같은 코딩 규칙을 담아두면 AI가 매 요청마다 그 기준에 맞춰 동작합니다. 프로젝트 루트에 놓고 Git에 커밋하는 것만으로 팀 전체가 동일한 AI 페르소나를 공유하게 됩니다.

Claude Code를 처음 접하는 분을 위해 — CLAUDE.md는 AI에게 보내는 "팀 약속집" 같은 파일입니다. 세션이 시작될 때마다 AI가 이 파일을 읽고 그 규칙 안에서 동작하게 됩니다.

설정 파일에는 우선순위 계층이 있습니다.

~/.claude/CLAUDE.md          ← 개인 전역 기본값 (내 모든 프로젝트에 적용)
./CLAUDE.md                  ← 팀 공유 프로젝트 규칙 (Git 커밋 대상)
./CLAUDE.local.md            ← 개인 로컬 오버라이드 (.gitignore 처리)
./.claude/rules/*.md         ← 모듈형 팀 규칙 (영역별 파일 분리)

Prompt Drift — AI 에이전트가 긴 대화 중 초기 지시를 점점 잊어버리거나 다른 패턴으로 흘러가는 현상입니다. 지시가 길고 복잡할수록 AI가 하단 규칙을 일관되게 따르기 어려워집니다. CLAUDE.md는 세션 시작 시 매번 로드되므로 이 현상을 구조적으로 억제하는 데 도움이 됩니다.

DESIGN.md — AI 에이전트가 읽는 디자인 시스템 명세

DESIGN.md는 Google Stitch 팀이 2026년 4월 Apache 2.0 라이선스로 오픈소스화한 포맷 명세입니다. 브랜드의 시각적 아이덴티티를 AI 에이전트가 직접 소비할 수 있는 마크다운 구조로 기술합니다. 핵심은 디자인 토큰을 기계가 읽을 수 있는 YAML 형식으로 저장하면서, 그 값을 왜 사용하는지 평문 설명을 함께 담는 것입니다.

2026년 4월 기준으로 아직 알파(alpha) 단계 포맷이라 스펙이 변경될 가능성이 있습니다. 현재 표준 구조는 9개 섹션으로 이루어집니다.

9개 섹션 중 저는 처음에 섹션 9(Design Guardrails)를 빠뜨렸다가 AI가 경고용 색상으로 헤더를 꾸미는 걸 보고 나서야 부랴부랴 추가했습니다. "파란색 계열 CTA에 흰 텍스트만 사용"처럼 하지 말아야 할 것을 명시하면 AI가 경계를 스스로 인식하는데, 이게 생각보다 훨씬 효과적입니다.

실전 적용

예시 1: CLAUDE.md + DESIGN.md 기본 연동

가장 간단한 연동 방식입니다. CLAUDE.md 파일에 DESIGN.md를 참조한다고 명시하고, 디자인 관련 결정 기준을 선언합니다.

## 디자인 시스템
- 컴포넌트 생성 시 DESIGN.md를 항상 참조하여 색상·타이포그래피·컴포넌트 스타일을 결정한다
- 디자인 토큰은 임의 값 사용 금지; DESIGN.md의 tokens 섹션에 정의된 값만 사용한다
- 새 컴포넌트 생성 시 DESIGN.md의 "Design Guardrails" 섹션을 반드시 확인한다
- 색상 값을 하드코딩하지 말고 CSS 변수 또는 Tailwind 토큰 클래스명으로 참조한다
 
## 코딩 규칙
- TypeScript strict mode 필수
- async/await 사용 (Promise.then() 체인 금지)
- 컴포넌트: Server Component 기본, 인터랙션이 필요한 경우만 Client Component
- 테스트: 신규 유틸리티 함수에는 단위 테스트 필수
- 2-space indentation
 
## 빌드 명령
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint`

이렇게 설정하면 Claude Code가 컴포넌트를 생성할 때 두 파일을 동시에 소비합니다. "버튼 컴포넌트 만들어줘"라고 하면 CLAUDE.md의 TypeScript + Server Component 규칙을 따르면서, DESIGN.md의 color-primary와 타이포그래피 토큰을 그대로 반영한 코드가 나옵니다.

앞의 CLAUDE.md가 "무엇을 쓰지 말 것"을 지시한다면, 아래 DESIGN.md는 AI가 실제로 참조할 구체적 수치를 제공합니다. 두 파일이 한 쌍으로 작동하는 구조입니다. DESIGN.md 파일의 Color Palette & Roles 섹션은 다음과 같이 작성할 수 있습니다.

# YAML 형식 — 들여쓰기가 구조를 결정합니다
 
color_palette:
  tokens:
    color-primary: "#0F62FE"
    color-secondary: "#6929C4"
    color-surface: "#F4F4F4"
    color-text-primary: "#161616"
    color-danger: "#DA1E28"
    color-text-on-primary: "#FFFFFF"
  roles:
    color-primary: "인터랙티브 요소와 CTA 전용. 장식 목적으로 사용 금지"
    color-danger: "에러 메시지, 삭제 확인 UI 전용. 강조나 장식 목적 사용 금지"
    color-surface: "카드, 패널, 배경 컨테이너 배경색으로만 사용"
 
design_guardrails:
  - "토큰에 없는 임의 색상 값 사용 금지"
  - "color-primary와 color-secondary를 동일 컴포넌트에 함께 사용하지 않기"
  - "14px 미만 폰트 크기 사용 금지 (접근성 기준)"

예시 2: 팀 영역별 모듈형 규칙 구성

프로젝트가 커지면 CLAUDE.md 하나에 모든 규칙을 몰아넣으면 문제가 생깁니다. 규칙이 길고 복잡해질수록 AI가 하단 규칙을 일관되게 따르기 어려워지고, 프론트엔드·백엔드·보안 팀이 같은 파일을 수정하다 머지 충돌이 납니다. .claude/rules/ 디렉터리 패턴이 이 문제를 해결합니다.

프로젝트 루트/
├── CLAUDE.md              ← 공통 아키텍처 규칙, 빌드 명령 (팀 전체)
├── DESIGN.md              ← 디자인 토큰, UI 규칙 (팀 전체)
└── .claude/
    └── rules/
        ├── frontend/
        │   ├── react.md       ← 프론트엔드 팀 소유·관리
        │   └── styling.md     ← 디자인 시스템 적용 세부 방법
        ├── backend/
        │   ├── api.md         ← 백엔드 팀 소유·관리
        │   └── database.md
        └── security.md        ← 보안 팀 소유·관리

.claude/rules/ 하위 파일이 로드되는 방식은 Claude Code 버전별로 동작이 다를 수 있으므로, 사용 중인 버전의 공식 문서에서 확인하는 것을 권장합니다. 프론트엔드 팀은 react.md와 styling.md만 관리하고, 백엔드 팀은 api.md와 database.md만 담당하게 됩니다. 각 팀이 머지 충돌 걱정 없이 자신의 영역을 독립적으로 발전시킬 수 있는 구조입니다.

.claude/rules/frontend/styling.md 파일은 다음처럼 구성할 수 있습니다.

## Tailwind CSS 토큰 매핑
- DESIGN.md의 color 토큰은 tailwind.config.ts의 theme.colors에 1:1 매핑되어 있음
- 색상 클래스는 반드시 `bg-primary`, `text-primary` 형식의 의미론적 이름 사용
- 임의 색상(`bg-[#0F62FE]`) 사용 금지 — Tailwind 토큰 클래스명으로 참조
 
## 컴포넌트 스타일 규칙
- 버튼 변형: primary, secondary, ghost, danger 네 가지만 허용
- 간격: 4px 베이스 그리드 기준 (4, 8, 12, 16, 24, 32, 48px)
- 반응형: mobile-first, sm/md/lg/xl 브레이크포인트 사용

예시 3: tailwind.config.ts로 디자인 토큰을 CSS 수준에서 강제하기

솔직히 이 방법이 실무에서 가장 안정감을 줬습니다. AI가 프롬프트 드리프트로 규칙을 잊더라도 CSS 레벨에서 한 번 더 걸러지기 때문입니다. 앞의 DESIGN.md가 AI에게 "이 값만 써"라고 말하는 것이라면, 이 설정은 CSS 프레임워크 레벨에서 그것을 물리적으로 강제하는 역할을 합니다.

// tailwind.config.ts — DESIGN.md 토큰을 직접 매핑
import type { Config } from "tailwindcss";
 
const config: Config = {
  theme: {
    extend: {
      colors: {
        // DESIGN.md color_palette.tokens와 1:1 대응
        primary: "#0F62FE",
        secondary: "#6929C4",
        surface: "#F4F4F4",
        "text-primary": "#161616",
        danger: "#DA1E28",
      },
      fontFamily: {
        sans: ["IBM Plex Sans", "sans-serif"],
      },
    },
  },
};
 
export default config;

이 세 레이어 중에서 실제로 가장 체감이 컸던 건 세 번째였습니다. AI가 아무리 실수해도 bg-[#FF0000] 같은 임의 색상은 Tailwind 설정에 없으니 lint 단계에서 잡히거든요. 세 레이어가 어떻게 다른 지점에서 규칙을 적용하는지 정리하면 이렇습니다.

• DESIGN.md: AI 프롬프트 수준 — 에이전트가 코드를 생성하기 전에 규칙을 인식
• CLAUDE.md: AI 코딩 수준 — 임의 값 하드코딩 금지를 직접 지시
• tailwind.config.ts: CSS 프레임워크 수준 — 토큰 외 색상을 물리적으로 차단

장단점 분석

장점

단점 및 주의사항

Tribal Knowledge (부족 지식) — 팀 내에 암묵적으로만 공유되는 노하우나 규칙. 문서화되지 않아 신규 팀원이 경험으로만 습득해야 하는 지식입니다. CLAUDE.md + DESIGN.md는 이를 기계가 강제할 수 있는 명시적 형태로 변환합니다.

실무에서 가장 흔한 실수

1. DESIGN.md에 추상적 색상 설명을 쓰는 것 — 처음에는 빠르게 쓰려고 "밝은 파란색"이라고 타이핑하게 됩니다. 그 순간이 위험합니다. 에이전트는 "밝은 파란색"을 만날 때마다 다른 값을 선택할 수 있습니다. 반드시 "#0F62FE" 같은 구체적 hex 코드를 사용해야 일관된 결과를 기대할 수 있습니다.

2. CLAUDE.md 한 파일에 모든 규칙을 몰아넣는 것 — 규칙이 길고 복잡해질수록 AI가 하단 규칙을 점점 신뢰하기 어려워집니다. 팀이 커질수록 "내가 쓴 규칙이 왜 안 지켜지지?"라는 불만이 생기는데, 대부분 규칙 파일이 너무 길어진 게 원인입니다. 영역별로 .claude/rules/에 분산하는 구조가 도움이 됩니다.

3. DESIGN.md를 업데이트하면서 tailwind.config.ts를 동기화하지 않는 것 — AI는 DESIGN.md 기준으로 코드를 짜는데 실제 스타일은 Tailwind 설정 기준으로 렌더링되어 불일치가 생깁니다. 두 파일을 같은 커밋에 묶어두는 습관이 도움이 됩니다. git add DESIGN.md tailwind.config.ts 한 줄로 충분합니다.

마치며

CLAUDE.md와 DESIGN.md를 함께 Git에 커밋하고 나면, 코드리뷰에서 반복 지적되던 스타일 불일치가 눈에 띄게 줄어드는 경험을 할 수 있습니다.

지금 바로 시작할 수 있는 3단계입니다.

1. 프로젝트 루트에 CLAUDE.md를 만들어봅니다. 빌드 명령(pnpm build, pnpm test), 아키텍처 원칙(TypeScript strict, Server Component 우선), 네이밍 컨벤션 세 가지만 담아도 충분한 시작입니다. 300줄 이내를 목표로 합니다.

2. DESIGN.md는 VoltAgent/awesome-design-md에서 자신의 프로젝트와 가장 가까운 브랜드(Stripe, Linear, Notion 등) 템플릿을 가져다가 색상 hex 코드와 폰트 패밀리만 교체하는 것부터 시작할 수 있습니다. 55개 이상 브랜드 예시가 있어서 참고하기 좋습니다.

3. 두 파일을 루트에 배치한 뒤 아래 명령으로 커밋하면, 팀 전체가 다음번 git pull부터 동일한 AI 동작 기준을 공유하게 됩니다.

git add CLAUDE.md DESIGN.md
git commit -m "설정: AI 에이전트 코딩·디자인 규칙 초기 설정"

참고 자료

• Google Stitch의 DESIGN.md 오픈소스 발표 | Google Labs 블로그
• 공식 DESIGN.md 포맷 스펙 | GitHub google-labs-code/design.md
• 브랜드별 DESIGN.md 모음 | GitHub VoltAgent/awesome-design-md
• Claude Code Best Practices 공식 문서 | Anthropic
• .claude 디렉터리 탐색 | Claude Code 공식 문서
• DESIGN.md Explained — The Format Reshaping How AI Builds UI | Department of Product
• Google Stitch + Claude Code 연동 | MindStudio
• CLAUDE.md, AGENTS.md & Copilot Instructions 비교 | DeployHQ
• Claude Code Agent Teams 공식 문서 | Anthropic
• CLAUDE.md 작성 모범 사례 | Builder.io
• AI 에이전트를 위한 공유 코딩 가이드라인 구축 | Stack Overflow Blog
• DESIGN.md 파일 작성 방법 | Design Project Blog