저는 부동산 중개업을 하면서도 AI 도구로 사이드 프로젝트를 굴리는 사람입니다. 작년 봄까지만 해도 README.md 한 장이면 충분했습니다. 그런데 올해 들어 분위기가 완전히 바뀌었습니다. Claude Code를 켜고 "이 프로젝트 좀 이어서 작업해줘"라고 던지면, AI가 읽는 문서는 더 이상 README가 아니었습니다. AGENTS.md를 먼저 찾고, CLAUDE.md를 읽고, UI 작업이면 DESIGN.md를 들여다봅니다.
바이브코딩이라는 말이 나온 지 1년이 조금 지났습니다. 그 사이 코드를 한 줄도 안 짜고 서비스를 만드는 사람이 폭발적으로 늘었고, 동시에 보안 사고도 같이 늘었습니다. 이번 글에서는 그 흐름이 어떻게 시작됐는지, 왜 README로는 부족하다고 판단됐는지, 그리고 2026년 4월 구글이 던진 DESIGN.md라는 새 표준이 무엇인지 정리해 드리겠습니다. 마지막에는 제 프로젝트에 실제로 DESIGN.md를 도입한 4단계 절차도 공유합니다.
바이브코딩의 출발점은 명확합니다. OpenAI 공동창업자이자 전 테슬라 AI 책임자였던 Andrej Karpathy가 2025년 2월 2일 X에 올린 한 문장이었습니다. "fully give in to the vibes, embrace exponentials, and forget that the code even exists." 우리말로 풀면 "흐름에 완전히 몸을 맡기고, 지수 성장을 받아들이고, 코드가 존재한다는 사실 자체를 잊어라" 정도입니다. 이 트윗은 4.5M 회 이상 조회됐습니다. (출처: https://x.com/karpathy/status/1886192184808149383)
처음 그 트윗을 봤을 때 솔직히 저는 별생각이 없었습니다. "AI한테 자연어로 시키는 코딩을 멋지게 표현했네" 정도로 흘려보냈습니다. 그런데 1년이 지나고 보니 단순한 밈이 아니었습니다. Collins Dictionary가 2025년 올해의 단어로 "vibe coding"을 선정했습니다. 사전이 인정한 시점부터 바이브코딩은 농담이 아니라 산업 용어가 됐습니다.
저도 중개업 보조 도구를 Cursor와 Claude Code로 만들어 보면서 체감했습니다. 처음에는 "버튼 누르면 호갱노노 시세를 긁어오게 해줘" 같은 식으로 던졌습니다. 동작은 했습니다. 다만 일주일 뒤 같은 프로젝트를 다시 열면, AI가 제 의도를 까맣게 잊어버렸습니다. 변수명을 바꾸고, 폴더 구조를 흔들고, 멀쩡하던 함수를 재작성했습니다. 그때 깨달았습니다. 진짜 핵심은 "코드를 잊는 것"이 아니라, "AI가 내 맥락을 잊지 않게 만드는 문서"였습니다.
네이버 데이터랩 흐름을 봐도 그렇습니다. "바이브코딩" 검색은 24,915건 수준에서 사실상 포화 상태에 들어갔습니다. 반면 "DESIGN.md"는 12,342건으로 폭증세입니다. 신호는 명확합니다. 사람들은 이제 바이브코딩 자체보다, 그것을 어떻게 굴러가게 만들 것인가를 묻기 시작했습니다.
README.md는 1999년 GitHub 이전 시절부터 사람을 위해 만들어진 문서입니다. 설치 방법, 사용법, 라이선스, 기여 가이드. 사람이 처음 저장소에 들어왔을 때 길을 잃지 않게 해주는 안내판입니다. 사람한테는 충분합니다. AI 에이전트한테는 부족합니다.
차이는 한 줄로 요약됩니다. README는 "어떻게 쓰는지"를 알려주고, AI 친화 문서는 "어떻게 만드는지"를 알려줍니다. AI가 코드를 자동으로 짜려면 "어떻게 쓰는지"가 아니라 "이 프로젝트는 어떤 원칙으로 굴러가는지", "절대 건드리면 안 되는 폴더가 어디인지", "디자인 토큰의 정확한 색상값과 그 값을 고른 이유가 무엇인지"를 알아야 합니다.
저도 처음에는 README에 그냥 다 적으면 되지 않나 싶었습니다. 근데 막상 해보니 README가 길어질수록 사람 독자한테는 부담이고, AI한테는 잡음이었습니다. AI는 "Architecture / File Rules / Decisions / Safety / Context" 같은 명시적 섹션을 좋아했습니다. README의 줄글 설명보다 구조화된 규칙을 훨씬 잘 따랐습니다.
수치로 보면 더 분명합니다. AGENTS.md를 적용했을 때 작업 성공률이 4% 올랐고, 에이전트가 만드는 버그가 35~55% 줄었다는 보고가 있습니다. (출처: Augment Code 인용 보고) 4%는 작아 보일 수 있습니다. 그런데 매일 100개 작업을 굴리는 팀이라면 4개의 실패가 줄어드는 셈입니다. 하루 4개, 한 달이면 120개입니다. 사람 PR 리뷰어 한 명분 정도의 부담이 사라집니다.
제가 직접 해본 사례 하나 공유합니다. 중개업 시세 알림 봇을 만들면서 README에 "환경변수는 .env에 넣으세요"라고만 적었습니다. AI가 두 번째 세션에서 .env를 직접 수정하고 커밋해버렸습니다. 비밀키가 GitHub 공개 저장소로 올라갔습니다. 부랴부랴 키를 폐기하고 다시 발급받았습니다. 그날 이후 AGENTS.md에 "Never commit .env" 한 줄을 넣었습니다. 같은 사고가 다시 일어나지 않았습니다.
DESIGN.md는 구글 Stitch 팀이 2026년 4월 21일 Apache 2.0 라이선스로 오픈소스 공개한 문서 표준입니다. (출처: Google Blog https://blog.google/innovation-and-ai/models-and-research/google-labs/stitch-design-md/) 공개된 그날, 제 X 타임라인이 한 번 출렁였습니다. Claude Code, Cursor, Antigravity 같은 AI 코딩 도구들이 DESIGN.md를 즉시 소비할 수 있도록 만들어진 사양이었기 때문입니다.
핵심은 "디자인 시스템을 AI가 추측 없이 읽을 수 있게 한다"입니다. 일반 README나 디자인 가이드는 "메인 컬러는 따뜻한 파란색입니다" 같은 표현이 흔합니다. AI한테는 이 문장이 거의 무의미합니다. 따뜻한 파란색이 #1E88E5인지 #2196F3인지 #4FC3F7인지 모릅니다. DESIGN.md는 디자인 토큰을 YAML로 정확값까지 명시합니다. 동시에 "왜 이 값인지" plain text 주석을 붙입니다. AI는 추측 없이 WCAG(웹 접근성 기준) 검증을 할 수 있게 됩니다.
저는 처음 DESIGN.md 사양을 봤을 때 "또 하나의 사양 전쟁이 시작됐구나" 싶었습니다. 근데 바로 이어진 움직임을 보고 생각이 바뀌었습니다. VoltAgent가 운영하는 awesome-design-md라는 GitHub 컬렉션이 2026년 4월 23일 기준 69개의 실제 적용 사례를 모았습니다. Stripe, Vercel, Linear, Notion, Figma 같은 실리콘밸리 톱티어들이 영감 사례로 올라가 있습니다. 사양이 나온 지 이틀 만에 69개. 속도가 비정상이었습니다.
비교를 위해 부동산 쪽 이야기를 잠깐 빌리자면, 새 분양 단지가 떴을 때 시공사·세대수·일정이 명시된 자료와 "고급스러운 입지의 프리미엄 단지"라는 카피만 있는 자료의 차이입니다. 제가 중개업에서 매일 겪는 그 차이가 그대로 코드 문서 세계로 옮겨왔습니다. AI는 카피가 아니라 정확값을 원합니다.
지금 AI 친화 문서 표준은 크게 4종으로 정리됩니다.
| 문서 | 출처 | 용도 | 적용 도구 |
|---|---|---|---|
| AGENTS.md | OpenAI Codex 2025-08 공개 → 2025-12 Linux Foundation 산하 AAIF 이관 | 크로스툴 표준, 프로젝트 규칙 | 60,000+ 오픈소스 채택, 170+ 회원사 |
| CLAUDE.md | Anthropic Claude Code 전용 | 세션 시작 시 자동 로드 | Claude Code |
| .cursorrules / .cursor/rules/ | Cursor IDE | IDE 내 규칙 | Cursor |
| DESIGN.md | Google Stitch 2026-04-21 오픈소스 | 디자인 시스템 전용 | Claude Code, Cursor, Antigravity |
(출처: agents.md 공식 / OpenAI 발표 / Google Blog)
AGENTS.md가 가장 큰 표준입니다. 2025년 8월 OpenAI Codex가 처음 공개했고, 2025년 12월 Linux Foundation 산하 Agentic AI Foundation(AAIF)으로 이관되면서 중립 거버넌스가 잡혔습니다. Anthropic, OpenAI, Block이 창립 멤버로 들어가 있습니다. 2026년 4월 기준 6만 개 이상의 오픈소스 저장소가 AGENTS.md를 채택했고, 회원사는 170곳을 넘었습니다.
CLAUDE.md는 Anthropic의 Claude Code 전용입니다. 새 세션이 열릴 때 자동으로 읽히는 파일입니다. 저도 이 파일에 제 본인 프로필, 자주 쓰는 경로, 절대 규칙 같은 걸 다 박아 뒀습니다. 효과는 즉시 체감됐습니다. 매번 "내 옵시디언 경로는…"이라고 다시 설명할 필요가 없어졌습니다.
DESIGN.md는 위 셋과 결이 다릅니다. 프로젝트 규칙 일반이 아니라 디자인 시스템에 한정된 전문 문서입니다. UI를 다루지 않는 백엔드 프로젝트는 DESIGN.md가 필요 없습니다. UI가 들어가는 순간 DESIGN.md의 가치가 폭발합니다.
제 경우 작년에 만든 시세 대시보드를 다시 손볼 때 처음으로 DESIGN.md를 적용했습니다. 색상 토큰만 YAML로 빼두니, AI가 새 컴포넌트를 만들 때 색상을 헷갈리지 않았습니다. 같은 파란색을 똑같이 #1976D2로 썼습니다. 직전 프로젝트에서는 같은 파란색이 다섯 군데에서 다섯 가지 헥스값으로 흩어져 있었습니다.
DESIGN.md의 표준 5대 섹션은 다음과 같습니다.
Stitch 사양은 여기에 디자인 토큰을 추가로 얹었습니다. colors, typography, spacing을 YAML로 정확값 + 의도 + 컴포넌트 + 접근성으로 묶어서 적습니다.
가장 효과 큰 부분은 Safety 섹션의 "Never" 패턴입니다. "Never edit node_modules", "Never commit secrets" 같은 한 줄짜리 금지 규칙이 AI 사고를 압도적으로 줄입니다. 저도 가장 먼저 적은 게 "Never commit .env"였습니다. 그다음이 "Never push to main without confirmation"이었습니다. 둘만 박아 뒀는데 이후로 AI가 메인 브랜치를 망가뜨린 적이 한 번도 없었습니다.
지시문도 구체적일수록 좋습니다. 모호한 명령은 AI가 자기 스타일로 채워버립니다.
100줄, 3개 메서드, bcrypt만이라는 세 가지 제약이 결과물을 완전히 다르게 만듭니다. 제가 실험해 봤습니다. 모호한 지시는 매번 200~400줄짜리 거대한 클래스를 토해냈습니다. 구체적 지시는 거의 정확히 90줄 안팎으로 떨어졌습니다.
DESIGN.md 템플릿 시작점은 awesome-design-md 컬렉션에 있는 69개 사례 중 자기 프로젝트와 가장 가까운 것을 골라 베끼는 게 빠릅니다. 처음부터 백지에 쓰면 막막합니다. 저는 Linear 사례를 베이스로 깔고, 5대 섹션만 비워둔 채 한 줄씩 채워나갔습니다.
여기까지 읽으면 DESIGN.md만 깔면 다 해결될 것 같습니다. 현실은 그렇지 않습니다. 어두운 면을 직시해야 합니다.
먼저 Andrew Ng 교수의 진단입니다. 2025년 6월 그는 "vibe coding은 잘못된 이름이며 실제로는 지치는 진짜 일(deeply exhausting actual work)"라고 말했습니다. AI한테 던지면 다 되는 게 아니었습니다. 좋은 프롬프트, 좋은 문서, 좋은 검증이 받쳐줘야 했습니다.
수치는 더 가혹합니다. CodeRabbit이 2025년 12월 발표한 470개 PR 분석 결과를 보면, AI 공동작성 코드는 사람만 쓴 코드 대비 major 이슈가 1.7배, misconfigurations(설정 오류)가 75% 더 많았고, 보안 취약점은 2.74배 더 많았습니다. 같은 PR 1개당 보안 구멍이 거의 3배라는 뜻입니다.
대형 사고도 있었습니다. 2026년 3월 시가총액 66억 달러로 평가받던 Lovable이 기본 API 결함으로 모든 사용자의 소스코드, DB 자격증명, AI 채팅 내역이 48일 동안 외부에 노출됐습니다. AI 코드에서 발견된 CVE(공식 보안 취약점)는 2026년 1월 6건에서 3월 35건으로 급증했습니다. AI가 커밋한 코드의 시크릿 노출률은 3.2%로, 사람의 1.5%보다 2배가량 높았습니다.
저도 가까이서 본 일이 있습니다. 동료 한 명이 Lovable로 회원가입 페이지를 만들고 있었습니다. 작년 말 일이었습니다. 토큰을 프론트엔드 JS에 그대로 넣은 코드가 배포됐습니다. 다행히 공개 전에 발견했습니다. 만약 그대로 나갔다면 어떤 일이 벌어졌을지는 상상하고 싶지 않습니다.
이런 사고를 줄이는 1차 방어선이 바로 DESIGN.md, AGENTS.md의 Never 섹션입니다. "Never commit secrets"를 한 줄 박아두면 AI는 그 규칙을 세션 내내 기억합니다. 사람도 마찬가지입니다. 명문화된 규칙이 없으면 누구나 실수합니다. 중개업에서 계약서에 특약이 없으면 분쟁이 나는 것과 같은 원리입니다.
마지막으로 실전 도입 4단계입니다. 저도 이 순서로 적용했고, 작은 사이드 프로젝트부터 시작하는 걸 강력히 권합니다.
1단계. README는 그대로 둔다.
DESIGN.md가 README를 "대체한다"는 표현은 AI 영역에 한정된 이야기입니다. 사람 독자, 특히 처음 저장소에 들어오는 사람한테는 README가 여전히 첫 인상입니다. 절대 지우지 마시기 바랍니다. README는 그대로, AI용 문서를 옆에 추가하는 방식입니다.
2단계. AGENTS.md를 추가한다 (100줄 미만).
가장 먼저 만들 파일입니다. 100줄을 넘기지 않는 게 핵심입니다. 길어지면 AI가 우선순위를 잃습니다. Architecture 5줄, File Rules 10줄, Safety의 Never 항목 5~10줄, Context 현재 작업 5줄. 이 정도로 시작합니다.
3단계. UI가 있다면 DESIGN.md를 추가합니다.
백엔드 전용이면 건너뜁니다. UI 컴포넌트가 있다면 디자인 토큰부터 빼냅니다. colors, typography, spacing 셋이면 충분합니다. YAML 정확값과 함께 plain text 주석을 답니다. "primary blue #1976D2 — 파란색 중에서도 차분한 톤. 신뢰감을 강조하는 금융/부동산 맥락에 맞춤"처럼 의도까지 적습니다.
4단계. Claude Code를 쓴다면 CLAUDE.md에 @AGENTS.md import.
Claude Code 사용자라면 CLAUDE.md 안에 @AGENTS.md를 한 줄 넣어 import합니다. AGENTS.md의 모든 규칙이 CLAUDE.md를 통해 자동 로드됩니다. 두 문서를 따로 관리할 필요가 없어집니다.
저는 이 4단계를 부동산 사이드 프로젝트 3개에 모두 적용했습니다. 가장 효과가 컸던 건 1단계와 2단계였습니다. 3단계는 UI가 있는 프로젝트 1개에만 적용했고, 색상 일관성이 즉시 잡혔습니다. 4단계는 Claude Code를 메인으로 쓰면서부터 거의 자동으로 따라왔습니다.
한 가지 솔직히 말씀드리면, 모든 프로젝트에 4단계를 다 깔 필요는 없습니다. 한 번 쓰고 버릴 스크립트면 README 한 줄도 안 적습니다. 1년 이상 굴릴 프로젝트, 여러 사람이 만질 프로젝트, AI가 자주 손댈 프로젝트라면 4단계 도입 가치가 충분합니다.
Q1. README를 그대로 둬야 하나요, 아니면 DESIGN.md로 대체하나요?
README는 그대로 두시기 바랍니다. DESIGN.md는 AI용 보조 문서이지, 사람 독자를 위한 첫 인상 문서를 대체하지 않습니다. README는 설치·사용·라이선스를 담고, DESIGN.md는 디자인 토큰과 의도를 담습니다. 역할이 다릅니다.
Q2. DESIGN.md와 AGENTS.md 중 뭘 먼저 만들어야 하나요?
AGENTS.md를 먼저 만드시기 바랍니다. AGENTS.md는 모든 프로젝트에 통용되는 일반 규칙이고, DESIGN.md는 UI가 있는 프로젝트에만 필요한 전문 문서입니다. 백엔드 전용 프로젝트면 DESIGN.md 없이 AGENTS.md만으로 충분합니다.
Q3. Cursor에서도 DESIGN.md를 쓸 수 있나요?
가능합니다. DESIGN.md는 Stitch 팀이 Apache 2.0으로 공개한 오픈 표준이고, Claude Code, Cursor, Antigravity가 모두 이를 소비할 수 있도록 설계됐습니다. Cursor 사용자라면 .cursor/rules/ 폴더와 함께 쓰시면 됩니다.
Q4. 한국어로 DESIGN.md를 써도 AI가 이해하나요?
이해합니다. 다만 코드 식별자(클래스명, 함수명, 파일명)는 영어로 두시고, 의도와 설명만 한국어로 쓰는 방식을 권합니다. 디자인 토큰의 keys는 영어, comments는 한국어 — 이 조합이 가장 안정적이었습니다.
Q5. 언제 DESIGN.md를 도입해야 하나요?
프로젝트가 1년 이상 갈 것 같을 때, 여러 사람이 만질 때, AI 코딩 도구를 메인으로 쓸 때 도입하시기 바랍니다. 한 번 쓰고 버릴 프로토타입에는 오버스펙입니다. 반대로 디자인 시스템을 갖춘 프로덕트라면 첫날부터 깔아두시는 게 낫습니다.
바이브코딩이 흐름이 됐고, DESIGN.md가 그 흐름 위에 올라탄 첫 표준 디자인 문서입니다. 도구는 이미 다 있습니다. 남은 건 직접 한 줄 적어보는 일입니다.