AI 요약
melta UI는 AI 에이전트(Claude Code, Cursor 등)가 Tailwind CSS 기반의 UI를 정확하게 생성할 수 있도록 돕는 'AI-Ready' 오픈소스 디자인 시스템입니다. 초기 개발 단계에서는 18KB에 달하는 단일 CLAUDE.md 파일에 모든 디자인 원칙과 76개의 금지 패턴을 담아 운영했으나, 시스템이 확장됨에 따라 문서 내용과 실제 사양이 어긋나는 '드리프트(Drift)' 현상과 수동 업데이트의 한계에 직면했습니다. 이를 해결하기 위해 저자는 시스템을 3개의 계층으로 분리했습니다. 첫째는 브랜드 사상과 퀵 레퍼런스를 담은 DESIGN.md(8.6KB), 둘째는 28개 컴포넌트 사양과 89개 금지 규칙을 JSON으로 구조화한 contracts, 셋째는 GitHub Actions를 통해 이들의 정합성을 자동 검증하는 harness입니다. 이 개편을 통해 생성 품질은 90점 이상의 높은 수준을 유지하면서도, 개발자가 장기적으로 시스템을 안정적으로 관리할 수 있는 기술적 토대를 마련했습니다.
핵심 인사이트
- 시스템 구성: melta UI는 28개의 컴포넌트, 99개의 디자인 토큰, 그리고 AI 에이전트가 호출할 수 있는 MCP(Model Context Protocol) 서버를 포함하고 있습니다.
- 3층 구조 도입: 단일 파일(CLAUDE.md) 중심에서 DESIGN.md(입구), contracts(사양), harness(검증)로 계층을 분리하여 '유일한 진실(SSoT)'을 확보했습니다.
- 데이터 드리프트 해결: 수동으로 기재하던 금지 패턴(89개)과 컴포넌트 메타데이터를 JSON화하고 자동 검증함으로써 문서와 실제 데이터 간의 수치 불일치 문제를 해결했습니다.
- 성능 벤치마크: 개편 전후의 UI 생성 품질을 비교한 결과, 평균 점수가 93점에서 92점으로 거의 동일하게 유지되어 구조화 후에도 AI의 이해도가 낮아지지 않음을 입증했습니다.
주요 디테일
- DESIGN.md (Layer 1): 브랜드의 7가지 절대 원칙과 즉시 코드 작성이 가능한 Quick Reference를 포함하며, 용량은 8.6KB로 최적화되어 Cursor나 Copilot 등 타 도구에서도 범용적으로 사용 가능합니다.
- 사양 구조화 (Layer 2): 전용 JSON 파일을 통해 컴포넌트의 바리안트, 사이즈, 접근성 요건 및 89건의 금지 패턴을 명확하게 정의했습니다.
- 자동 검증 (Layer 3): GitHub Actions와 연동된 harness 스크립트가 PR마다 실행되어 사양의 정합성이 깨질 경우 즉시 경고를 보냅니다.
- CLAUDE.md의 변화: 기존 18KB에서 5.5KB로 대폭 축소되었으며, 이제는 디자인 사양 대신 'Claude Code 전용 작업 절차'만을 기술하는 공간으로 활용됩니다.
- 구체적 금지 규칙 예시:
text-black대신text-slate-900사용 권장,shadow-lg사용 제한 등 구체적인 가이드라인이 시스템적으로 관리됩니다.
향후 전망
- AI 에이전트의 효율적인 협업을 위해 단순 프롬프트 기입을 넘어, 기계 가독형(Machine-readable) 사양과 자동 검증 체계를 갖춘 디자인 시스템 구축이 업계 표준이 될 것입니다.
- 문서의 노후화와 데이터 불일치를 막는 '하네스(Harness)' 기법이 AI 네이티브 개발 워크플로우에서 더욱 중요해질 것으로 보입니다.