README.md는 이제 너무 익숙하다.
- 이 프로젝트가 뭔지
- 어떻게 실행하는지
- 개발자가 뭘 먼저 봐야 하는지
이건 README가 잘한다.
근데 AI가 디자인과 코드를 같이 건드리기 시작하니까, README만으로는 자꾸 비는 구멍이 보인다.
- 이 버튼은 왜 둥근지
- 이 화면은 왜 이렇게 단정해야 하는지
- 어떤 컴포넌트가 브랜드 톤인지
- 어디까지가 디자인 규칙이고 어디부터가 일회성 예외인지
이런 건 README에 넣으면 장황해지고, 피그마만 믿으면 코드 쪽 맥락이 빠진다.
그 틈에 Google Stitch가 던진 게 DESIGN.md다.
Quick Answer: 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가 많다면 의미가 있다. 반대로 화면 몇 개만 만들고 끝나는 구조라면 아직 과할 수 있다.
내 결론
DESIGN.md가 중요한 이유는 새 파일 확장자가 생겨서가 아니다.
핵심은 이거다.
이제 디자인 시스템도 AI가 읽을 수 있는 텍스트 계약으로 옮겨가고 있다는 신호다.
그래서 이 흐름은 단순 유행이라기보다, README 다음 레이어가 생기는 과정으로 보는 편이 맞다.
한 줄로 줄이면:
README가 프로젝트의 실행 규칙이라면, DESIGN.md는 디자인 의도의 반복 규칙이 될 수 있다.