README.md는 이제 너무 익숙하다.
- 이 프로젝트가 뭔지
- 어떻게 실행하는지
- 개발자가 뭘 먼저 봐야 하는지
이건 README가 잘한다.
근데 AI가 디자인과 코드를 같이 건드리기 시작하니까, README만으로는 자꾸 비는 구멍이 보인다.
- 이 버튼은 왜 둥근지
- 이 화면은 왜 이렇게 단정해야 하는지
- 어떤 컴포넌트가 브랜드 톤인지
- 어디까지가 디자인 규칙이고 어디부터가 일회성 예외인지
이런 건 README에 넣으면 장황해지고, 피그마만 믿으면 코드 쪽 맥락이 빠진다.
그 틈에 Google Stitch가 던진 게 DESIGN.md다.
짧게 보면: Google은 2026년 3월 18일 Stitch 업데이트 글에서
DESIGN.md를agent-friendly markdown file이라고 소개했다. 역할은 단순하다. 디자인 시스템 규칙을 추출하고, 다른 Stitch 프로젝트나 코딩 도구로 가져갈 수 있게 만드는 문서 레이어다. 즉 DESIGN.md는 README 대체재가 아니라, 디자인 의도를 AI와 개발 도구가 읽을 수 있게 만드는 설계 문서에 가깝다. 그래서 디자인 시스템이 있고, 여러 화면이나 에이전트가 반복적으로 같은 스타일을 써야 하는 팀에선 꽤 의미가 있다.
이 글을 써먹을 상황
- AI로 UI 시안을 만들고 나서, 다음 단계 handoff에서 자꾸 깨지는 팀
- 피그마와 코드 사이에서 “이 규칙 어디 적어놨지?”가 반복되는 사람
- Stitch, MCP, 디자인 에이전트 흐름에 관심 있지만 그냥 발표 요약은 듣기 싫은 사람
- README는 있는데 디자인 의도 문서는 없는 팀
지금 결론
- DESIGN.md는 README를 대체하는 문서가 아니라, 디자인 규칙을 위한 별도 계약서에 가깝다.
- AI가 UI를 여러 번 생성·수정하는 시대엔 디자인 규칙도 텍스트로 남겨야 반복성이 생긴다.
- 디자인 시스템이 있는 팀일수록 효과가 크고, 없는 팀은 오히려 문서만 하나 더 느는 꼴이 될 수 있다.
- 핵심은 파일 이름보다, 디자인 의도를 코드와 에이전트가 읽을 수 있게 구조화하는 발상이다.
Google Stitch가 정확히 뭐라고 했나
Google은 2026년 3월 18일 Introducing “vibe design” with Stitch 글에서 Stitch를 AI-native design canvas로 확장한다고 설명했다.
여기서 중요한 포인트가 세 개 나온다.
- AI-native infinite canvas
- design agent
- design systems with
DESIGN.md
특히 Google은 DESIGN.md를 agent-friendly markdown file이라고 부른다.
그리고 설명도 꽤 직접적이다.
- URL에서 디자인 시스템을 추출할 수 있고
DESIGN.md로 디자인 규칙을 export/import 할 수 있고- 다른 디자인/코딩 도구로 가져갈 수 있다고 한다
즉 얘는 “멋진 신기능”이라기보다, 디자인 시스템을 문서 형태로 이동시키는 인터페이스에 더 가깝다.
왜 README 다음 문서가 필요해졌냐
실무에서 자주 깨지는 건 이런 구간이다.
- AI가 랜딩 페이지를 그럴듯하게 만든다
- 다음 화면도 비슷하게 만들어야 한다
- 개발 도구나 다른 에이전트가 이어받는다
- 근데 spacing, tone, hierarchy가 미묘하게 바뀐다
왜냐면 “프로젝트 설명”은 README에 있어도, 디자인 의도는 대체로 흩어져 있기 때문이다.
- 피그마 컴포넌트 설명
- 노션 안내서
- 슬랙 대화
- 머릿속 룰
이렇게 분산돼 있으면 AI가 매번 같은 판단을 하기 어렵다.
README는 실행법엔 강하지만, 디자인 시스템의 반복 규칙을 담기엔 성격이 좀 다르다.
그래서 DESIGN.md 같은 레이어가 등장하는 흐름 자체는 꽤 자연스럽다.
DESIGN.md가 있으면 뭐가 달라지나
내가 보기엔 효과는 네 가지다.
1. 디자인 규칙을 에이전트가 읽을 수 있다
중요한 건 파일 이름이 아니라 마크다운이라는 점이다.
AI는 텍스트 문서를 다루는 데 강하다. 즉 디자인 시스템도 텍스트로 정리돼 있으면:
- 새로운 화면 생성
- 기존 화면 수정
- 코드 변환
- 다른 프로젝트 재사용
에서 일관성을 더 가져가기가 쉽다.
2. handoff가 좀 덜 증발한다
보통 handoff가 깨질 때는 픽셀보다 의도가 먼저 사라진다.
예를 들면:
- “이건 신뢰감을 줘야 해서 그림자 약하게”
- “이 버튼은 공격적으로 보이면 안 됨”
- “표는 금융 서비스처럼 건조하게”
이런 건 툴 안에만 있으면 다음 단계에서 잘 안 살아남는다.
DESIGN.md는 이 의도를 문장으로 남길 수 있다.
3. 재사용성이 올라간다
Google이 직접 말한 부분도 이거다.
다른 Stitch 프로젝트에 적용해서 매번 바퀴를 다시 만들지 않아도 된다.
이건 팀 입장에서 꽤 중요하다.
- 브랜드 랜딩
- 대시보드
- 온보딩 화면
이 셋이 전부 다른 느낌으로 나오는 걸 줄일 수 있기 때문이다.
4. MCP/Skills 흐름과 잘 맞는다
Google 글은 Stitch의 MCP server, SDK, skills도 같이 언급한다.
즉 DESIGN.md는 단독 파일이라기보다, AI 디자인 에이전트가 읽는 컨텍스트 조각으로 보는 게 더 맞다.
그래서 이 파일이 진짜 의미 있으려면:
- 디자인 에이전트
- 코딩 에이전트
- export/import 파이프라인
이 같이 돌아야 한다.
언제 이게 진짜 유용하고, 언제 과하냐
유용한 경우
- 디자인 시스템이 이미 어느 정도 있는 팀
- 같은 톤의 화면을 반복 생성하는 팀
- AI가 시안과 코드 초안을 같이 만지는 팀
- handoff 비용이 자꾸 새는 팀
과한 경우
- 단발성 마케팅 페이지 하나만 만드는 경우
- 디자인 규칙 자체가 아직 없는 경우
- 파일만 늘고 실제 워크플로는 안 바뀌는 경우
즉 DESIGN.md는 만능 문서가 아니다. 규칙이 없는 팀에선 그냥 빈 양식 하나 더 생길 수 있다.
README와 뭐가 다르냐
| 항목 | README.md | DESIGN.md |
|---|---|---|
| 주로 답하는 질문 | 이 프로젝트가 뭐고 어떻게 쓰나 | 이 제품은 왜 이렇게 보여야 하나 |
| 주요 독자 | 개발자, 기여자, 운영자 | 디자이너, 코딩 에이전트, UI 생성 도구 |
| 핵심 내용 | 설치, 실행, 구조, 기여 방법 | 톤, 컴포넌트 규칙, spacing, brand intent |
| 실패할 때 생기는 문제 | 실행이 안 됨 | 일관성이 무너짐 |
이 표만 봐도 느낌이 온다.
README가 “프로젝트 설명서”라면, DESIGN.md는 “시각적 행동 규칙서” 쪽에 더 가깝다.
내가 넣고 싶은 최소 항목
만약 DESIGN.md를 진짜 만든다면, 내 기준 최소 항목은 이거다.
- 브랜드 톤 한 줄
- 색/타이포 원칙
- 컴포넌트 우선순위
- 금지 패턴
- 화면별 분위기 차이
- 코드 export 시 지켜야 할 규칙
중요한 건 거창한 디자인 백서가 아니다. 에이전트가 읽고 반복 적용할 수 있을 정도로 짧고 선명한 규칙이면 된다.
실수 TOP 5
1. README에 디자인 의도까지 다 욱여넣는 실수
그러면 README는 길어지고, 아무도 안 읽는다.
2. 피그마만 있으면 충분하다고 믿는 실수
피그마는 강력하지만, AI와 코드 툴이 바로 읽는 텍스트 레이어는 또 필요할 수 있다.
3. DESIGN.md를 스타일 토큰 모음집으로만 만드는 실수
색상 값만 적으면 의도는 안 남는다.
4. 예외 규칙을 안 적는 실수
브랜드 규칙보다 예외 상황이 더 자주 handoff를 망친다.
5. 파일은 만들고 워크플로엔 안 넣는 실수
문서는 연결되지 않으면 장식품이다.
FAQ
Q1. DESIGN.md는 README를 대체하나
아니다. README는 실행 규칙, DESIGN.md는 디자인 의도 규칙에 더 가깝다.
Q2. 피그마만 있으면 충분하지 않나
디자인 작업엔 충분할 수 있다. 하지만 AI와 코드 도구가 바로 읽을 수 있는 텍스트 레이어는 또 다른 장점이 있다.
Q3. 작은 팀도 지금 바로 만들어야 하나
작은 팀이라도 반복 생성되는 UI가 많다면 의미가 있다. 반대로 화면 몇 개만 만들고 끝나는 구조라면 아직 과할 수 있다.
2026년 4월 21일 source of truth 보충
이 글을 처음 썼을 때는 DESIGN.md 자체가 주인공이었다.
2026년 4월 21일 기준으로 다시 보면 질문이 조금 넓어졌다.
이제 핵심은 DESIGN.md를 쓸까 말까가 아니다.
디자인 작업의 source of truth를 어디에 둘 것인가다.
Figma 파일만 원본이라고 말하기엔, AI 코딩 도구가 실제로 읽는 문맥은 대체로 텍스트다.
반대로 텍스트 문서만 원본이라고 말하기엔, 디자이너와 PM이 합의하는 화면의 질감은 여전히 캔버스 위에서 생긴다.
코드만 원본이라고 말하기엔, 배포된 UI는 결과물이지 의도 전체는 아니다.
그래서 작은 팀은 원본을 하나로 합치기보다 책임을 나누는 편이 낫다.
첫째, Figma는 시각 합의의 원본이다.
버튼 모양, 화면 구조, 컴포넌트 관계를 사람이 빠르게 확인하는 장소다.
둘째, 코드는 실행 동작의 원본이다.
실제 접근성, 상태 처리, 반응형 동작은 결국 코드에서 검증된다.
셋째, DESIGN.md는 반복 의도의 원본이다.
AI가 다음 화면을 만들 때 다시 읽어야 하는 규칙을 짧게 남긴다.
이렇게 나누면 Google Stitch의 DESIGN.md도 더 또렷해진다.
DESIGN.md는 Figma를 대체하는 파일이 아니다.
코드를 대체하는 파일도 아니다.
Figma와 코드 사이에서 매번 말로 설명하던 디자인 의도를, 에이전트가 읽을 수 있는 텍스트로 고정하는 장치다.
그래서 Claude Design, Figma Make, Stitch를 같이 볼 때는 기능 목록보다 원본 책임표를 먼저 봐야 한다.
한 도구가 모든 원본을 먹어치운다는 상상은 멋지지만, 실무에서는 충돌이 생기기 쉽다.
작은 팀에는 더 소박한 원칙이 필요하다.
사람이 보는 원본, 코드가 증명하는 원본, AI가 반복해서 읽는 원본을 분리한다.
이 세 줄만 지켜도 디자인 handoff의 상당 부분이 덜 흔들린다.
내 결론
DESIGN.md가 중요한 이유는 새 파일 확장자가 생겨서가 아니다.
핵심은 이거다.
이제 디자인 시스템도 AI가 읽을 수 있는 텍스트 계약으로 옮겨가고 있다는 신호다.
그래서 이 흐름은 단순 유행이라기보다, README 다음 레이어가 생기는 과정으로 보는 편이 맞다.
한 줄로 줄이면:
README가 프로젝트의 실행 규칙이라면, DESIGN.md는 디자인 의도의 반복 규칙이 될 수 있다.