DESIGN.md란 무엇이며 왜 당신의 에이전트에게 필요한가

Google은 지난 4월, 코딩 에이전트(coding agents)가 UI를 처리하는 방식을 이미 변화시킨 무언가를 조용히 오픈 소스로 공개했습니다. 그것은 바로 DESIGN.md라고 불리는 것으로, 코딩 에이전트에게 시각적 정체성(visual identity)을 설명하기 위한 일반 텍스트 형식의 명세(specification)입니다. 이 저장소(repo)는 출시 첫 두 달 만에 18,700개의 스타(stars)를 기록했으며, 처음 72시간 동안에만 5,200개를 획득했습니다. 커뮤니티 컬렉션인 awesome-design-md는 64,000개의 스타를 돌파했습니다. designmd.app의 서드파티 라이브러리는 이제 어떤 프로젝트에도 바로 적용할 수 있는 454개의 문서화된 디자인 시스템(design systems)을 인덱싱하고 있습니다.

📖 차트와 임베디드 소스가 포함된 전체 버전은 AgentConn에서 확인하세요 →

이러한 수치들은 어떤 개발 도구에게도 주목할 만한 것입니다. 실행 가능한 코드가 전혀 포함되지 않은 형식(format)으로서는 놀라운 수치입니다. DESIGN.md는 마크다운(markdown) 파일입니다. 이 파일은 README.md 및 CLAUDE.md와 함께 프로젝트의 루트(root) 디렉토리에 위치합니다. 그리고 이는 코딩 에이전트를 사용하는 모든 팀이 직면했던 문제, 즉 에이전트가 작동하는 코드는 작성하지만, 그 결과물이 당신의 디자인 시스템(design system)과 일치하지 않는 문제를 해결합니다.

DESIGN.md가 해결하는 문제

LLM(대규모 언어 모델)은 각 프롬프트(prompt)를 독립적으로 처리합니다. 저장소(repository) 내에 지속적인 참조(reference)가 없다면, 생성된 모든 컴포넌트(component)는 서로 다른 시각적 결정—서로 다른 간격(spacing), 서로 다른 테두리 반경(border radii), 서로 다른 타이포그래피 스케일(type scales), 서로 다른 색상 값(color values)—을 사용하게 됩니다. 에이전트가 틀린 것이 아닙니다. 당신이 무엇이 정답인지 알려준 적이 없기 때문에 에이전트는 추측을 하고 있는 것입니다.

이것은 Anthropic의 Claude Design Sync가 Claude Code 사용자들을 위해 해결하고자 하는 바로 그 고통입니다. 하지만 Design Sync는 Anthropic의 생태계에 종속된 독점 기술입니다. 만약 당신이 Claude Code, Cursor, Gemini CLI, Codex 또는 기타 다른 하네스(harness)를 넘나들며 작업한다면, 도구 안에 머무는 것이 아니라 저장소(repo) 안에 존재하는 휴대 가능한 형식(portable format)이 필요합니다.

그것이 바로 DESIGN.md가 존재하는 이유입니다. Google의 공식 발표에서는 이를 명확하게 설명합니다: "우리는 DESIGN.md의 초안 사양(draft specification)을 오픈 소스로 공개하여, 어떤 도구나 플랫폼에서도 사용할 수 있도록 합니다." Google의 David East는 더 간결하게 표현했습니다: "DESIGN.md는 이제 공개 사양(open specification)입니다. 어떤 프로젝트에서든 디자인 의도(design intent)와 토큰 값(token values)을 캡처하기 위한 공유 형식입니다."

커뮤니티 논의에서 계속해서 등장하는 비유는 매우 명쾌합니다: README.md가 인간 기여자에게 코드베이스를 설명한다면, DESIGN.md는 AI 에이전트에게 디자인 시스템(design system)을 설명합니다.

DESIGN.md에 들어가는 내용

이 형식은 두 개의 계층으로 구성됩니다. 상단의 --- 구분자 사이에 위치한 YAML 프런트매터(front matter)는 색상, 타이포그래피(typography), 간격(spacing), 브레이크포인트(breakpoints), 컴포넌트 패턴과 같은 기계 판독 가능한 디자인 토큰(design tokens)을 담습니다. 그 아래의 마크다운(Markdown) 산문은 왜 해당 값들이 선택되었는지, 어떤 제약 사항을 인코딩하는지, UI가 절대 해서는 안 되는 행동은 무엇인지와 같은 인간이 읽을 수 있는 근거(rationale)를 담습니다.

다음은 사양(spec)에 명시된 최소한의 구조입니다:

---
name: "Your Product"
version: "1.0"
...

프런트매터 아래에는 디자인 시스템의 의도를 설명하는 산문을 작성합니다:

## Typography

Inter가 기본 서체입니다. 코드 블록에는 JetBrains Mono를 사용하세요.
...

토큰은 에이전트가 프로그래밍 방식으로 파싱(parse)하는 요소입니다. 산문은 에이전트가 판단(judgment calls)을 내릴 때 사용하는 요소입니다. 두 계층 모두 중요하며, 실패 모드(failure mode)는 항상 동일한 곳에서 발생합니다.

제작 문제 (The Fabrication Problem)

DESIGN.md 생태계에서 가장 중요한 통찰은 과장된 홍보를 걷어낸 한 UX Collective 튜토리얼에서 나옵니다: "파일을 실제로 유용하게 만드는 부분은 인터뷰(interview)입니다. 즉, 제품이 무엇을 하는지, 누가 사용하는지, UI가 반드시 수행해야 하는 작업은 무엇인지, 그리고 절대 해서는 안 되는 작업은 무엇인지를 확립하는 질문들입니다."

이 튜토리얼은 인터뷰 과정을 건너뛰고 에이전트가 Figma 내보내기(export) 파일이나 스크린샷 세트를 기반으로 DESIGN.md를 생성하게 했을 때 어떤 일이 발생하는지 설명합니다: "토큰(tokens)은 완벽했습니다. 하지만 추론 계층(reasoning layer)은 조작되었습니다."

이것이 바로 유용한 명세서(spec)를 소음으로 변질시키는 저작(authoring)상의 실수입니다. 에이전트는 사용자의 색상, 타이포그래피 스케일(type scale), 테두리 반경(border radii)을 보고 이를 정확하게 추론합니다. 이는 기계적인 관찰입니다. 하지만 에이전트는 왜 1.333 대신 1.25 타이포그래피 스케일을 선택했는지, 왜 파괴적인 작업(destructive actions)에 차분한 경고색 대신 빨간색을 사용하는지, 혹은 왜 프로필 이미지가 정사각형인지 그 '이유'를 알 수 없습니다. 인간의 이러한 결정이 없다면, 에이전트는 그럴듯하게 들리지만 실제로는 틀린 근거를 스스로 만들어냅니다. 그러면 다음 에이전트가 그 조작된 근거를 읽고 이를 권위 있는 제약 조건(constraint)으로 취급하게 됩니다.

해결책은 간단합니다: 직접 산문(prose)을 작성하거나, 생성 작업이 이루어지기 전에 인간의 입력을 강제하는 구조화된 인터뷰를 사용하십시오. Stitch 기술 라이브러리는 정확히 이 패턴을 구현합니다. 이 기술은 무엇인가를 생성하기 전에 제품의 맥락(context), 기존 토큰, UI의 핵심 역할, 그리고 제약 조건을 확립하는 네 가지 필수 질문으로 시작합니다. 토큰은 코드에서 추출할 수 있습니다. 하지만 추론(reasoning)은 반드시 팀으로부터 나와야 합니다.

두 달 만에 구축된 생태계

DESIGN.md 생태계의 속도는 이것이 Google의 틈새 실험이 아니라는 가장 강력한 신호입니다. 오픈 소스로 공개된 이후 두 달 동안:

커뮤니티 라이브러리가 폭발적으로 증가했습니다. 64K개의 스타를 보유한 awesome-design-md에는 주요 디자인 시스템인 Material, Tailwind, Shadcn, Radix, Chakra를 위한 사전 구축된 DESIGN.md 파일들이 포함되어 있습니다. designmd.app은 문서화된 토큰(tokens)을 가진 454개의 시스템을 인덱싱합니다. 이는 디자인에 적용된 mattpocock/skills 패턴으로, 단 한 줄의 코드를 작성하기 전부터 해당 형식을 유용하게 만들어 주는 커뮤니티 유지 관리형 마크다운(markdown) 디렉토리입니다.

도구 간 채택(Cross-tool adoption)이 실제로 일어나고 있습니다. DESIGN.md는 Claude Code, Cursor, Gemini CLI, Codex, Windsurf, Kiro, 그리고 프로젝트 루트(root)에서 마크다운을 읽는 모든 도구와 함께 작동합니다. Meng To는 그 가치 제안(value proposition)을 다음과 같이 포착했습니다: "Google은 AI를 위한 공유 디자인 언어를 원합니다. DESIGN.md는 디자이너, 개발자, 그리고 에이전트에게 프롬프트, 스크린샷, 흩어진 메모를 통해 취향을 번역하는 대신, 제품이 어떻게 보여야 하는지를 설명하는 하나의 표준화된 방식을 제공합니다."

Google은 이를 자체 에이전트 스택(agent stack)에 통합했습니다. Google Codelabs 튜토리얼은 Stitch + Antigravity + design-md MCP 스킬이 어떻게 하나의 파이프라인(pipeline)을 형성하는지 보여줍니다: Stitch에서 디자인하고, DESIGN.md를 내보낸(export) 후, 명세(spec)를 읽고 구현 코드(implementation code)를 생성하는 코딩 에이전트에게 전달합니다. X의 Stitch 계정은 다음과 같이 확인했습니다: "DESIGN.md를 사용하면 프로젝트 간에 디자인 규칙을 쉽게 내보내고 가져올(import) 수 있습니다."

"Complete Guide" 기사들이 이미 출시되고 있습니다. Marco Kotrotsos는 다음과 같이 작성했습니다: "새로운 것이 아닙니다. design.md는 AI 지원 코딩 (AI-assisted coding)을 위한 가장 중요한 개발자 경험 (Developer Experience) 개선 사항 중 하나입니다." Design Systems Collective는 이를 워크플로 (workflow)의 변화로 정의했습니다: "Google Stitch와 Claude Code는 DESIGN.md를 공유 컨텍스트 레이어 (shared context layer)로 활용하여 디자인-투-코드 핸드오프 (design-to-code handoff)를 조용히 변화시켰습니다."

DESIGN.md가 다른 컨텍스트 파일들과 관계를 맺는 방식

이미 코딩 에이전트 (coding agents)를 진지하게 사용하고 있다면, 프로젝트 루트 (project root)에는 아마 여러 개의 컨텍스트 파일 (context files)이 있을 것입니다:

파일	에이전트에게 알려주는 내용	관리 주체
README.md	프로젝트가 무엇인지, 어떻게 실행하는지	엔지니어링 (Engineering)
...

DESIGN.md는 별도의 독특한 위치를 차지합니다. CLAUDE.md가 에이전트에게 어떻게 *작업할지 (work)*를 알려준다면, DESIGN.md는 에이전트에게 사물이 어떻게 *보여야 하는지 (look)*를 알려줍니다. 이 둘은 상호 보완적이며, 둘 다 필요합니다.

기술 (skills)과의 관계 또한 명확히 할 가치가 있습니다. DESIGN.md는 기술이 아닙니다. 절차적 지침이나 슬래시 명령어 (slash commands)를 포함하지 않습니다. 이것은 **컨텍스트 파일 (context file)**입니다. 즉, 에이전트가 한 번 읽고 세션 전체에 걸쳐 적용하는 정적 참조 자료 (static reference material)입니다. 기술은 행동을 조율 (orchestrate)하고, DESIGN.md는 판단 (judgment)에 정보를 제공합니다. 3계층 아키텍처 (three-layer architecture) (조율을 위한 기술, 레지스트리 (registry)를 위한 MCP, 실행을 위한 CLI)에서 DESIGN.md는 CLAUDE.md와 함께 세 계층이 작동하는 방식을 형성하는 컨텍스트 레이어 (context layer)의 일부로서 나란히 위치합니다.

제대로 작동하는 파일을 작성하는 방법

튜토리얼, 커뮤니티 패턴, 그리고 명세 (spec) 자체를 바탕으로 한 실무적인 작성 가이드는 다음과 같습니다.

토큰이 아니라 인터뷰부터 시작하세요. 무엇인가를 작성하기 전에 다음 네 가지 질문에 답하십시오:

1. 이 제품은 무엇을 하며, 누가 사용합니까?
2. 기존에 어떤 디자인 토큰 (design tokens)을 가지고 있습니까 (색상, 타이포그래피, 간격)?
3. UI가 항상 수행해야 하는 것은 무엇입니까? (예: "항상 로딩 상태를 표시할 것", "항상 폼 레이블을 왼쪽 정렬할 것")
4. UI가 절대 수행해서는 안 되는 것은 무엇입니까? (예: "확인을 위해 모달을 사용하지 말 것", "미디어를 자동 재생하지 말 것")

질문 3번과 4번이 가장 가치 있습니다. 이 질문들은 에이전트가 스크린샷만으로는 추론할 수 없는 판단력을 인코딩(encode)합니다.

네 가지 섹션으로 구성하세요:

1. 개요 (Brief) — 제품, 대상 고객, 디자인 태세를 설명하는 한 단락
2. 토큰 (Tokens) — 색상, 타이포그래피, 간격, 브레이크포인트 (breakpoints), 그림자(shadows)를 포함한 YAML 프런트 매터 (YAML front matter)
3. 컴포넌트 (Components) — 에이전트가 따라야 할 패턴 (카드 레이아웃, 폼 구조, 네비게이션)
4. 하지 말아야 할 것 (Don'ts) — 에이전트가 그럴듯해 보이지만 틀린 UI를 생성하는 것을 방지하는 명시적인 금지 사항

2,000 토큰 이내로 유지하세요. DESIGN.md는 모든 에이전트의 컨텍스트 윈도우 (context window)에 주입됩니다. 5,000 토큰 분량의 DESIGN.md는 에이전트가 사고할 수 있는 토큰을 5,000개 줄어들게 만든다는 의미입니다. 우리가 AgentConn에서 다루었던 토큰 압축 작업 (token compression work)이 여기에도 적용됩니다. 컨텍스트 윈도우의 모든 바이트에는 비용이 따릅니다. 간결하게 작성하세요. 근거를 설명하기 위해 긴 단락을 쓰고 있다면, 너무 많이 쓰고 있는 것입니다.

454개의 라이브러리 파일 중 하나를 시작점으로 사용하세요. designmd.app/library로 가서 귀하의 시스템과 가장 유사한 디자인 시스템을 찾아 복사한 뒤 맞춤화하십시오. 그러면 구조를 올바르게 잡을 수 있고 포맷팅에 드는 한 시간을 아낄 수 있습니다. awesome-design-md 컬렉션 또한 좋은 시작점입니다. "프로젝트에 하나를 떨어뜨려 놓기만 하면 코딩 에이전트가 그에 맞는 UI를 생성하게 하세요."

버전 관리하세요. DESIGN.md는 git에 존재합니다. 디자인 시스템이 변경될 때 — 그리고 반드시 변경될 것입니다 — DESIGN.md도 함께 변경됩니다. 바로 이러한 이유를 위해 명세(spec)의 YAML 프론트매터(front matter)에는 version 필드가 포함되어 있습니다.

공급망 문제 (The Supply Chain Question)