AI로 프론트엔드를 만들면 코드는 동작해도 화면이 제품답지 않은 경우가 많습니다. 버튼은 둥글고, 카드는 떠 있고, 그라데이션은 과하고, 어디서 본 듯한 대시보드가 나옵니다. 기능은 대체로 맞지만 제품 고유의 디자인은 사라집니다. Atlassian은 이 문제를 “AI UI slop”이라고 부릅니다.
Atlassian이 공개한 DESIGN.md 실험 글 ↗은 AI 코딩 에이전트에게 디자인 시스템의 값과 의도를 전달하는 방법을 실제로 테스트한 보고서입니다. 디자인 토큰을 Markdown으로 적는 방법과 함께, 그 방식이 어디까지 효과가 있는지 수치로 비교합니다.
DESIGN.md는 MCP나 전용 스킬을 대체하지 못합니다. 대신 “우리 제품은 이렇게 보여야 한다”는 최소한의 디자인 컨텍스트를 파일 하나로 전달합니다. 이 파일은 Claude Code, Cursor, Stitch, Figma Make처럼 서로 다른 환경에 그대로 옮겨 쓸 수 있습니다.
2026-07-01 · Atlassian 공식 글, Google design.md README, design.md PHILOSOPHY, Atlassian DESIGN.md 스냅숏 기준입니다. design.md 포맷은 아직 alpha입니다.
이 글에서 다루는 내용:
- DESIGN.md가 무엇을 담는 파일인가
- Atlassian이 왜 MCP와 스킬이 있는데도 DESIGN.md를 테스트했는가
- 실제 실험에서 DESIGN.md가 어디까지 효과가 있었고, 어디서 비용이 커졌는가
- 우리 팀이 쓴다면 어떤 용도에 맞는가
DESIGN.md는 디자인 시스템의 압축 파일입니다
Google design.md README ↗는 DESIGN.md를 “coding agent에게 시각적 정체성을 설명하기 위한 포맷”으로 설명합니다. 파일은 두 부분으로 나뉩니다.
- 위쪽 YAML frontmatter에는 색상, 타이포그래피, spacing, radius, component 같은 기계가 읽기 좋은 디자인 토큰을 둡니다.
- 아래쪽 Markdown 본문에는 색을 왜 이렇게 쓰는지, 레이아웃은 어떤 밀도를 지향하는지, 어떤 UI 패턴을 피해야 하는지 같은 디자인 rationale을 적습니다.
Atlassian이 공개한 파일도 이 구조를 따릅니다. frontmatter에는 version, revision, theme, name 같은 메타데이터와 색상, 타이포그래피, spacing, rounded 토큰이 있습니다. 본문은 에이전트가 Atlassian Design System을 어떻게 해석해야 하는지 설명합니다.
DESIGN.md는 Figma 파일이나 컴포넌트 문서 전체를 대체하지 않습니다. Google의 PHILOSOPHY 문서 ↗는 토큰 값을 렌더링 지시문보다 컨텍스트로 봅니다. 그리고 구체적으로 쓴 설명문(prose)이 가장 중요하다고 말합니다. “modern, clean, premium” 같은 추상 형용사보다 “어떤 화면에서 어떤 밀도와 대비를 유지해야 하는가”를 적어야 에이전트가 따를 수 있습니다.
Google Stitch와 vibe design도 같은 문제를 다룹니다. AI가 제품다운 화면을 만들려면 프롬프트를 다듬는 것보다, 제품이 이미 쌓아 온 디자인 언어를 모델이 읽을 수 있는 형태로 바꿔야 합니다.
Atlassian은 이미 MCP와 스킬을 갖고 있었습니다
Atlassian은 DESIGN.md 이전에 이미 디자인 컨텍스트 전달 수단을 갖고 있었습니다. Atlassian Design System을 에이전트에게 전달하기 위해 structured content model을 만들고, 그 위에 ADS MCP 서버와 AI 스킬을 운영하고 있었습니다. 그래서 이 실험은 DESIGN.md를 MCP·스킬과 직접 비교할 수 있습니다.
MCP와 스킬은 필요한 정보만 그때그때 가져옵니다. 에이전트가 버튼을 만들어야 하면 버튼 관련 guidance만 가져오고, 토큰이 필요하면 필요한 토큰만 조회합니다. Atlassian 글은 ads_plan 같은 도구를 예로 듭니다. 이 방식에서는 모든 아이콘과 semantic token을 한 번에 컨텍스트에 넣지 않아도 됩니다.
Atlassian이 DESIGN.md를 테스트한 이유는 이식성입니다. 모든 도구가 Atlassian 내부 MCP를 쓸 수 있지는 않습니다. 어떤 환경에서는 파일 하나를 붙여 넣거나 프로젝트 루트에 두는 방식이 가장 빠릅니다. 이때 DESIGN.md가 최소한의 브랜드 감각과 UI 패턴을 전달합니다(portable context).
flowchart TD
A[사용자 요청] --> B{디자인 컨텍스트 방식}
B --> C[DESIGN.md]
B --> D[MCP / AI Skill]
C --> E[토큰과 디자인 의도를 한 번에 읽음]
D --> F[필요한 컴포넌트와 토큰만 조회]
E --> G[프로토타입 / 낯선 도구 / 고객별 테마]
F --> H[프로덕션 코드 / 기존 컴포넌트 사용 / 린트]이 방식은 Claude Code Memory에서 다룬 CLAUDE.md와 비슷합니다. CLAUDE.md는 프로젝트의 개발 맥락을, DESIGN.md는 제품의 시각적 맥락을 에이전트에게 알려줍니다. 두 파일 모두 사람이 알고 있는 암묵지를 모델이 읽을 수 있는 글로 바꿉니다.
프로토타입에서는 효과가 바로 보였습니다
Atlassian은 Team ‘26 keynote에서 Figma Make로 Teamwork Graph 기반 대시보드를 만들 때 DESIGN.md를 붙여 테스트했습니다. Atlassian에 따르면 결과물은 기본 출력보다 Atlassian의 색, 간격, 형태, 타이포그래피, elevation에 훨씬 가까웠습니다.
내부 MCP가 없는 도구, 빠르게 화면 방향을 잡아야 하는 프로토타입, 고객별 브랜드가 필요한 대시보드가 이런 경우입니다. 이런 곳에서는 완전한 컴포넌트 API보다 “어떤 느낌을 유지해야 하는지”가 먼저 필요합니다.
AI가 만든 UI가 계속 일반적인 SaaS 대시보드처럼 나온다면, DESIGN.md로 모델의 기본 스타일을 제품의 스타일 쪽으로 옮길 수 있습니다. 초기 탐색 단계에서는 이 정도로도 쓸 만합니다.
프로덕션 코드에서는 MCP와 스킬이 더 강했습니다
Atlassian의 프로덕션 코드베이스 테스트에서는 DESIGN.md의 한계가 드러났습니다. Atlassian은 같은 로그인 화면 작업을 여러 컨텍스트 방식으로 비교했습니다. 공식 글의 표를 요약하면 이렇습니다.
| 컨텍스트 방식 | 디자인 컨텍스트 반영 | 평균 토큰 | 평균 시간 | 평균 턴 |
|---|---|---|---|---|
| 없음 | 약 5% | 4.20M | 6분 19초 | 43.0 |
| ADS MCP | 약 80% | 3.75M | 5분 01초 | 35.1 |
| ADS Skill | 약 80% | 4.43M | 5분 23초 | 36.0 |
| DESIGN.md | 약 30% | 7.21M | 6분 46초 | 45.3 |
Atlassian도 이 결과가 논문식 벤치마크는 아니라고 밝힙니다. 표에서 DESIGN.md는 디자인 컨텍스트 반영률이 약 30%로 MCP·스킬(약 80%)보다 낮고, 평균 토큰은 7.21M으로 가장 많습니다. 파일 하나로 모든 디자인 컨텍스트를 한 번에 주입하면 편하지만, 프로덕션 코드에서는 토큰 비용과 탐색 비용이 커질 수 있습니다.
Figma MCP와 AI 에이전트 디자인에서도 같은 문제를 다뤘습니다. 프로덕션에서는 디자인을 “분위기”로만 전달하면 부족합니다. 기존 컴포넌트, 접근성 규칙, lint rule, 패키지 import 방식, 금지 패턴까지 함께 전달해야 합니다.
Atlassian은 세 가지 한계를 짚습니다.
첫째, DESIGN.md는 모든 내용을 한 번에 읽는(all-at-once) 방식입니다. 에이전트에게 지금 필요한 컴포넌트가 버튼 하나뿐이어도 파일의 토큰과 설명을 대부분 읽게 됩니다. 반면 MCP는 필요한 guidance만 가져옵니다.
둘째, 파일을 짧게 만들수록 중요한 사용 가이드가 빠집니다. Atlassian의 DESIGN.md는 약 80KB, 약 19,800 tokens 규모입니다. frontmatter를 제외해도 약 10,700 tokens입니다. 반면 내부 MCP와 스킬은 약 2.5MB 규모의 guidance를 필요할 때 압축해서 전달합니다. Atlassian은 공개 DESIGN.md를 만들면서 50개 이상의 컴포넌트 사용 가이드와 사용 빈도가 낮은 토큰을 뺐습니다.
셋째, DESIGN.md를 쓰면 에이전트가 컴포넌트를 “가져다 쓰는” 대신 “다시 만들” 수 있습니다. 프로덕션에서는 @atlaskit/button 같은 기존 컴포넌트를 import해 써야 합니다. 그런데 디자인 외형만 설명하면 모델이 비슷한 버튼을 직접 구현합니다. 그래서 Atlassian은 MCP/스킬에 디자인 시스템 ESLint rule을 더해 품질을 보완합니다.
그래서 어디에 써야 할까
DESIGN.md는 디자인 컨텍스트를 옮기는 최소 단위입니다. AI 프론트엔드 개발의 표준 전체를 담지는 않습니다.
잘 맞는 용도는 다음과 같습니다.
- 낯선 도구에서 빠르게 브랜드 감각을 맞춰야 하는 프로토타입
- 고객별 테마나 white-label UI처럼 제품별 변주가 필요한 화면
- Figma Make, Stitch, Claude Code, Cursor 등 서로 다른 도구에 같은 디자인 방향을 전달해야 하는 상황
- 디자인 시스템 전체를 연결하기 어려운 외부 협업 또는 실험 환경
프로덕션 코드에서는 DESIGN.md만으로 부족합니다. 기존 컴포넌트 사용법, 패키지 import, 접근성 규칙, 테스트, lint, 금지 패턴은 MCP나 스킬, 문서 검색, 정적 분석 규칙으로 보강해야 합니다. Atlassian의 실험에서도 ADS MCP와 ADS Skill이 DESIGN.md보다 안정적인 결과를 냈습니다.
역할은 다음처럼 나눌 수 있습니다.
DESIGN.md: 제품의 시각적 언어와 디자인 의도를 빠르게 전달하는 파일MCP: 필요한 컴포넌트 문서와 토큰을 작업 중에 조회하는 도구AI Skill: 반복 작업 절차와 팀 규칙을 압축해 전달하는 실행 지침lint/test: 모델이 실수해도 자동으로 잡아내는 품질 게이트
AI가 더 많은 UI를 만들수록 “그럴듯한 화면”과 “우리 제품다운 화면”의 차이가 커집니다. 디자인 시스템은 사람만 읽는 문서에서 에이전트가 실행 중에 참조하는 인터페이스로 바뀌고 있습니다.
DESIGN.md는 CLAUDE.md의 디자인 버전입니다
프로젝트 루트의 CLAUDE.md는 코드베이스의 구조, 명령어, 금지 사항, 선호 패턴을 알려줍니다. DESIGN.md는 UI의 색, 밀도, 형태, 컴포넌트 철학, 피해야 할 분위기를 알려줍니다.
두 파일 모두 혼자서는 충분하지 않습니다. CLAUDE.md가 테스트와 CI를 대체하지 않듯, DESIGN.md도 디자인 시스템과 컴포넌트 문서를 대체하지 않습니다. DESIGN.md는 에이전트가 첫 화면을 엉뚱한 방향으로 시작하지 않게 하는 초깃값입니다.
AI가 코드를 쓰면 디자인 시스템도 사람이 보는 문서, Figma 안의 토큰, 웹사이트의 컴포넌트 예시만으로는 부족합니다. 디자인 지식을 모델이 읽고, 도구가 조회하고, lint가 검증할 수 있는 형태로 다시 정리해야 합니다.
DESIGN.md는 그중 가장 가볍고 옮기기 쉬운 형식입니다. 프로토타입에는 바로 쓸 수 있고, 프로덕션에서는 MCP와 스킬을 도입하기 전 첫 단계로 쓸 수 있습니다. 프론트엔드 팀이라면 AI가 우리 제품의 디자인 언어를 제대로 읽고 있는지부터 확인합니다.