AI 시대의 Design System에 대한 생각

디자인 시스템은 오랫동안 인간 개발자가 소비하기 위해 설계되어 왔습니다. 표준 형태는 웹 docs 를 사람이 검색해 읽고 코드에 반영하는 방식이었습니다.

저는 1인 FE 체제로 다수의 내부 백오피스를 관리하면서, 코드 작성 주체의 상당 부분이 이미 AI로 옮겨갔습니다. 즉 제 디자인 시스템의 1차 독자는 인간이 아니라 AI가 되었습니다. 이것은 비단 저만 겪는 상황은 아니라고 생각합니다.

그렇다면 그 디자인 시스템은 어떻게 설계되어야 할까요. 정답이 정해져 있지는 않습니다만 일련의 시행착오 끝에 한 가지 방향성을 정리해봤습니다

AI 시대의 시스템은 자기 자신을 스스로 설명할 수 있어야 한다(self-describing).

이 글에서 그 방향성에 도달한 과정을 정리해봤습니다.

디자인 시스템의 1차 독자가 AI라면,

1인 FE 체제로 다수의 내부 백오피스를 관리하면서, 새 화면을 만들 때 코드의 첫 줄을 쓰는 주체는 사실상 AI입니다. 인간은 검토자·교정자 역할에 가까워졌습니다. 한 사람의 작업 방식이 그렇다는 게 아니라, 디자인 시스템 docs를 가장 자주 읽는 주체가 누구인지 따져봐도 마찬가지입니다. 사람이 docs 사이트를 방문하는 빈도보다 AI가 컨텍스트로 읽어들이는 빈도가 훨씬 많아졌습니다.

이 흐름은 일시적 유행이 아니라 도구 환경의 구조적 변화입니다. Cursor·Claude Code·Codex 등이 표준 작업 환경이 된 이상, AI 친화적이지 않은 디자인 시스템은 결국 인간에게도 외면 받을 가능성이 높다고 생각합니다. 그러므로 디자인 시스템을 새로 구축한다면, 1차 독자를 AI로 잡고 모든 설계 결정을 그 전제 위에서 다시 봐야 한다고 느꼈습니다.

사람을 위한 docs 구조가 여전히 필요할까

막상 AI를 작업의 1차 주체로 두고 보니, 상용 라이브러리나 디자인 시스템의 docs는 사람이 읽는다는 전제로 만들어져왔습니다. 그리고 그 구조도 특정 정보를 찾기 위해 docs를 읽는 사람에게 그다지 친절한 구조가 아니었다고 생각합니다. 그동안 이 구조가 사람에게 큰 문제가 되지 않았던 건, 사람이 능동적으로 해석에 개입해 빈 곳을 메워왔기 때문입니다. 정보를 한 덩어리로 묶어놓고, 외부 해석자가 의미를 끄집어내는 방식이었던 셈이죠.

저는 이런 구조위에 AI를 활용하면서 그 비효율이 가시화되는 경험을 했습니다. 외부 정보이고 어떻게 구조화되어 있는지 모르는 상태에서, 제대로 된 선택을 하기 위해 AI는 모든 문서를 읽어야 했고, 그 과정 자체가 토큰 비효율이었습니다. 그리고 그것이 AI가 실제 정보가 아닌 추론에 의지하는 판단으로 이어지는 경험을 종종 했습니다. 컴포넌트의 interface를 잘못 사용하거나, 아예 존재하지 않는 interface를 만들어 쓰는 식이죠. AI 코딩 도구를 쓰는 사람이라면 한 번쯤은 겪어봤을 장면이라고 생각합니다.

패키지 자체를 자기 기술적으로 만든다면

그래서 저는 AI가 이 디자인 시스템을 읽기 위한 엔트리포인트가 필요하다고 판단했습니다. 처음엔 MCP를 검토했습니다. AI가 디자인 시스템의 정보를 쿼리할 수 있는 자체 서버를 두는 방향이었죠. 그러나 디자인 시스템 한 라이브러리에 별도 서버까지 띄우는 것은 투머치였습니다. 본질을 풀자고 인프라 비용을 더 짊어지는 셈이었으니까요.

방향을 잡는 데 참고가 된 것은 llms.txt였습니다. 그 자체로 채택하지는 않았지만, 그 철학 - "엔트리포인트 인덱스 + 필요한 만큼의 상세" - 은 제 상황에 잘 맞았습니다. 웹사이트가 AI에게 자기를 설명하듯, 패키지도 자기를 설명할 수 있어야 한다고 봤습니다. 결국 제가 도달한 결론은, 패키지 자체를 자기 기술적으로 만드는 것이었습니다. 외부 사이트나 서버에 의존하지 않고, 패키지가 스스로 자기를 설명하게 하는 방향이죠.

소비자(AI)가 읽는 쪽은 두 층입니다. AGENTS.md(약 60줄)는 AI가 가장 먼저 보는 카탈로그입니다. 이 디자인 시스템의 컨셉, 기본 정보, 어떤 컴포넌트가 있고 각 컴포넌트가 어떤 경우에 쓰이길 바라는지를 짧게 담습니다. AI는 이걸 먼저 읽고 목적에 맞는 컴포넌트를 고릅니다. 고른 다음에는 docs/components/ 아래에서 그 컴포넌트의 상세와 인터페이스만 골라 읽습니다. 즉 필요한 것만 읽는 구조입니다. 앞에서 언급한 문제 - AI가 모든 문서를 읽고 그 과정에서 추론으로 때우는 - 를 풀어내기 위한 형태였습니다.

공급자 입장에서 이 두 층을 매번 손으로 관리하는 것은 비현실적이었습니다. 그래서 한 층을 더 구성했습니다. 컴포넌트마다 작성되는 Stories 메타데이터가 컴포넌트의 의미 - 언제 쓸지, 무엇과 헷갈리는지 - 를 코드 옆에 둡니다. 빌드 시점에 Stories의 소스가 위 두 문서로 자동 생성됩니다. 즉 공급자는 코드 옆에서 한 번 쓰고, 소비자(AI)는 그걸 두 층의 문서로 받는 구조입니다.

이 모든 갈래는 결국 한 가지 의도를 향합니다. 패키지가 자기 자신을 스스로 설명하게 하는 것입니다.

이 과정을 통해 구축한 디자인 시스템이 정답은 아니지만, 이 시행착오에서 얻은 인사이트는, "AI 시대의 시스템은 자기를 스스로 설명할 수 있어야 한다는 것" 그리고 "그 자기 서술의 방향과 무게는 시스템마다 다를 수 있다는 것".

어느 무게가 어떤 시스템에 맞는지, 어디까지 일반화 가능한지, 더 나은 형태가 무엇인지는 아직 잘모르겠습니다만, 예나 지금이나 분명한 건 "공급자가 자기를 어떻게 설명하느냐", 그리고 "소비자가 그것을 어떻게 효율적으로 가져가느냐" 이 두 질문이 공급자가 가져야할 본질적인 자세라는 것은 변함 없는 것 같습니다.