AI에게 화면을 구성하게 하는 개발을 하다 보면, 어떤 사실을 깨닫게 됩니다. 디자인 시스템을 전달해도 AI가 제대로 활용하지 못하는 경우가 있다는 것입니다. 컴포넌트가 있음에도 직접 코드를 짜기 시작하거나, 존재하지 않는 컴포넌트를 마음대로 발명하거나, 잘못된 컴포넌트를 추천하기도 합니다.

원인의 대부분은 디자인 시스템 측면에 있습니다. 인간이라면 '눈치껏' 보완할 수 있는 여백을 AI는 보완할 수 없기 때문입니다. 저는 자체 제작한 디자인 시스템(GUNJO)을 통해, 사전 지식이 전혀 없는 AI에게 공개된 docs(문서)만 전달하여 실제 업종의 화면을 175회 구성하게 하는 검증을 진행해 왔습니다. 그 과정에서 'AI가 한 번에 사용할 수 있기' 위해 효과적이었던 구체적인 방안을 5가지로 정리합니다.

1. 문서(Docs)만으로 완결시키기 (구전 방식을 없애기)

AI에게 있어 docs는 세계의 전부입니다. 인간이라면 "보통 이렇게 쓰겠지"라며 보완할 수 있는 부분을 AI는 보완할 수 없습니다. Slack의 과거 로그에만 적혀 있는 사용법, 핵심 멤버의 머릿속에 있는 전제——이러한 '구전(口伝)'에 의존하고 있는 부분은 AI의 손에서 대부분 누락됩니다.

따라서 사용법, 제약 사항, 조합은 전부 docs에 작성해야 합니다. 작성되어 있지 않은 것은 '없다'고 간주할 정도의 전제로 정비합니다.

2. 사양을 기계 판독 가능(Machine-readable)하게 배포하기

인간용 문서 페이지와는 별도로, 기계가 구조로서 읽을 수 있는 입구를 마련합니다. GUNJO에서는 각 컴포넌트 사양의 Markdown을 그대로 복사할 수 있게 했으며, 추가로 /api/specs/*를 통해 각 컴포넌트의 사양을 기계 판독 가능한 JSON 형식으로 배포하고 있습니다.

AI 에이전트는 산문 형태의 docs를 읽게 하는 것보다, 구조화된 스키마(Schema)를 전달했을 때 props의 타입(Type), 필수 여부, 열거값(Enumerated values)을 더 정확하게 받아들일 수 있습니다. '읽게 하는 것'에서 '전달할 수 있는 것'으로 바꾸는 공정입니다.

3. 사이트 루트에 llms.txt와 llms-full.txt를 배치하기

llms.txt(AI를 위한 단 한 장의 목차)와 llms-full.txt(모든 컴포넌트의 이름 + 한 줄 설명 + docs URL 목록)를 배치합니다. 이는 AI 크롤러나 에이전트가 가장 먼저 보는 '입구의 지도'입니다.

실제로 해보니 효과는 미미해 보일 수 있으나 확실했으며, "어디에 무엇이 있는지"에 대해 AI를 길을 잃게 만들지 않는 최소 비용의 투자였습니다.

4. 타입(Type) 그 자체를 사양으로 만들기 (TS 소스를 배포하기)

이것은 검증 과정에서 가장 큰 효과를 느낀 지점입니다. GUNJO는 TypeScript의 소스를 그대로 배포하고 있기 때문에, node_modules가 그대로 사양서가 됩니다.

실제로 AI에게 실제 화면을 구성하게 했을 때, API 레퍼런스를 참조하지 않고도 node_modules의 타입 정의로부터 각 컴포넌트의 props를 정확하게 읽어내어 구성해 냈습니다. 문서 페이지를 읽는 경로와는 별개로, '타입을 읽는' 경로가 하나 더 있는 셈입니다. AI는 코드를 읽는 데 능숙하므로 이 경로는 상상 이상으로 효과적입니다.

(GUNJO에서는 컴포넌트의 일차 정보를 .pen 기반의 SSOT(Single Source of Truth)로 관리하며, docs나 기계 판독 가능한 사양을 그로부터 생성 및 검증합니다. 타입은 코드가 정답이며, 그것을 4번과 같이 그대로 배포합니다. 근원을 통일해 두면 경로가 늘어나도 불일치가 발생하기 어렵습니다.)

5. "정말로 AI가 사용할 수 있는가"를 증명하는 QA 루프를 돌리기

1~4번을 정비해도 "AI가 사용할 수 있을 것이다"라는 추측에서 끝나기 쉽습니다. 그래서 저는 사전 지식이 전혀 없는 AI에게 docs만 전달하여 실제 업종의 화면을 구성하게 하는 검증을 반복했습니다. 이것이 콜드 테스트(Cold Test)입니다.

• AI가 직접 코드를 짜기 시작했다 → 그곳에 '없는 컴포넌트' 혹은 '찾을 수 없는 컴포넌트'가 있다
• AI가 잘못된 컴포넌트를 추천했다 → docs의 대응표나 명명 규칙(Naming)이 오도하고 있다
• 동일한 결함이 3개의 서로 다른 화면에서 독립적으로 나타났다 → 정말로 부족한 컴포넌트로 판단하여 제작한다

이를 175개 화면에 대해 반복하면, "AI가 사용할 수 있을 것 같다"는 생각이 "AI가 사용할 수 있음을 확인했다"로 바뀝니다. 기록은 모두 gunjo.jp/cold-tests 에 공개되어 있습니다.

솔직한 미흡함

좋은 점만 쓰면 거짓말이 되기에, 어려웠던 점도 말씀드립니다. GUNJO는 현재 베타 단계(0.1.0-beta.2)입니다.

하지만 alpha 단계에서는 npm에 공개된 버전과 리포지토리(Repository)의 HEAD 사이에 차이가 있었습니다. 수정되었어야 할 버그(SSR에서의 Provider 요구 등)가 공개 버전에는 아직 반영되지 않은 상태였습니다. 따라서 "리포지토리에서는 수정되었다"와 "사용자의 환경에서 수정되었다"는 별개의 문제로 보고, 공개 순서를 관리할 필요가 있었습니다. (beta.1은 이 HEAD를 publish한 것이므로, 이 차이는 일단 해소되었습니다.)

배움

AI가 사용할 수 있는 디자인 시스템은 "눈치채게 만드는" 설계에서 "명시하는" 설계로의 이동이었습니다. 구전(口傳)을 없애고, 기계 가독성(Machine-readable) 있게 배포하며, 타입(Type)을 사양(Specification)으로 만들고, AI를 위한 지도를 놓는 것. 그리고 마지막으로, "정말로 쓸 수 있는가"를 상상이 아닌 콜드 테스트(Cold test)로 확인하는 것입니다.

인간만을 상대로 했을 때는 약간의 모호함이 친절함이었습니다. 하지만 AI도 독자에 포함되면, 그 모호함은 그대로 결함이 됩니다.

관련 링크

• 디자인 시스템 GUNJO (MIT): gunjo.jp
• 콜드 테스트 175개 화면의 기록: gunjo.jp/cold-tests
• AI 생성 UI 검수 서비스: design-qa.com

이 기사는 저자가 AI (Claude)와 협업하여 제작하고 있습니다. 실험·검증 설계, 판단, 공개 전 사실 확인은 인간이 수행하며, 실제 작업과 초안 집필은 AI가 담당하고 있습니다.

GunjoUI by UIXHERO

Discussion