필자가 참여하고 있는 kDS (kintone Design System) Team은 kintone, Slack, GitHub, Confluence 등 다양한 장소에 디자인 논의를 축적해 왔습니다. 하지만 정보가 분산되고 축적됨에 따라, 과거의 의사결정을 찾는 작업은 상당히 멤버들의 기억에 의존하고 있었습니다.

그래서 흩어진 논의를 LLM-Wiki로 가져와, 근거와 함께 검색할 수 있는 메커니즘을 도입했습니다. 이 기사에서는 디자인 시스템에 LLM-Wiki를 도입하여 얻은 효과와 팀에서 운용하기 위한 노하우를 소개합니다.

디자인 시스템에서 논의를 참조할 수 있다는 것의 의의

디자인 프로세스는 합의 형성의 축적입니다. 팀을 가로질러 다양한 스테이크홀더(Stakeholder)와 논의하는 장면은 드물지 않으며, 그 디자인에 이르기까지는 어떠한 배경이 있습니다.

「디자인 시스템」은 바로 이러한 합의 형성의 결과로서 존재합니다. 즉, 이 「디자인에 관한 논의의 결정체」에는 「왜 이 디자인이 되었는가?」에 대한 답변이 가득 담겨 있는 상태입니다.

「왜 이 디자인이 되었는가?」를 참조할 수 있는 상태라면, **「망설임 없는 일관된 판단」**이 쉬워지고, 근거와 자신감을 가지고 디자인을 개선할 수 있는 **「유연성」**으로 이어지며, 향후에 걸쳐 **「지속적으로 개선 가능한 디자인」**의 실현에 한 걸음 더 다가갈 수 있습니다.

나아가, 그것들이 언제 어디서든 누구나 참조 가능하다는 점이 중요합니다. 디자인 팀이나 디자인 시스템 팀뿐만 아니라, 「프로덕트에 관련된 누구나가」 디자인에 관심을 갖고 더 좋게 만들어 나갈 수 있기 때문입니다.

어느 하나라도 충족되지 않으면 디자인 변경에 대한 판단 비용은 높아지고, 개인의 역량에 의존하는 속인화(属人化) 현상이 발생하며, 지속적이고 오픈한 디자인 개선은 어려워질 것입니다.

Figma의 말을 빌리자면, 디자인 시스템은 「일관성을 유지하기 위한 일련의 구성 요소와 표준」이며, 「일관된 의사결정에 소요되는 시간을 대폭 단축하는 수단」입니다[1].

이와 같이 파악한다면, 디자인 시스템에 관한 논의를 참조할 수 있다는 것은 디자인 시스템의 구성 요소가 될 수 있을 만큼 중요한 일이라고 느껴집니다.

과제

kDS에서는 매일 방대한 양의 논의가 오가며 디자인 시스템에 관한 의사결정이 이루어집니다. 다른 멤버들이 따라가기 어려운 직능 횡단적인 논의도 많이 이루어집니다.

지금까지 팀은 가능한 한 디자인에 관한 의사결정을 남겨왔습니다. 대부분의 논의는 공개된 장소에서 이루어지며, 중요한 논의는 ADR을 작성하여 팀에 공유를 철저히 해왔습니다. 하지만 그럼에도 불구하고 실감하고 있는 과제는 많았습니다.

• 애초에 논의를 ADR/가이드라인화할지의 기준이 모호하여 케이스 바이 케이스(Case by case)임
• ADR/가이드라인이 있어도 떠올리는 것 자체에 시간이 걸리며, 시간이 지나면 형식화됨
• 선행 사례나 유사 사례가 있는지조차 알 수 없게 된 경우가 있어, 오래 근무한 멤버의 기억에 맡겨짐
• 새로 합류한 멤버가 과거의 경위를 파악하기 어려워 속인화됨
• 디자이너, 엔지니어 등 타 직능에 의사결정 경위가 전달되기 어려움
• 논의가 이루어지는 장소도 통일되어 있지 않아 검색하기 어렵고, 관련 논의를 찾기 어려움

kDS의 경우, 다음과 같은 플랫폼에서 매일 논의를 하고 의사결정을 기록하고 있습니다.

• GitHub: Issue, Pull Request, Discussion, Storybook의 가이드라인
• Slack
• Confluence
• kintone 상의 커뮤니케이션
• Figma
• Zoom의 의사록

어떤 형태로든 기록은 되어 있지만, 그것이 분산되어 있고 형식화되어 있기 때문에 결국 멤버의 기억에 의존하게 되는 장면도 적지 않았습니다. 그 자리에서 기억하고 있는 멤버가 없다면, 본래 다른 일에 쓸 수 있는 공수를 경위 조사에 소비해야 합니다. 또한, 타 직능에게는 여전히 난이도가 높아, kDS 팀에 질문이 오고 이에 답변하는 등의 커뮤니케이션 비용 문제도 있었습니다.

kDS 팀에는 다행히 텍스트 기반으로 커뮤니케이션하거나 의사록을 작성하는 문화가 뿌리내려 있었습니다. 남은 것은 분산되어 참조하기 어렵거나 참조되지 않는 정보를 풀 활용할 수 있게 만드는 것입니다!

LLM-Wiki

그래서 새롭게 활용하기 시작한 것이 LLM-Wiki입니다.

LLM-Wiki 자체는 단순한 개념이라기보다, LLM에게 Wiki(문서)의 유지보수를 맡기기 위한 패턴입니다. 이 패턴을 수중에 있는 Agent에게 전달하여 "xx에 대한 LLM-Wiki를 만들어줘"라고 지시하는 것만으로, 실제로 문서 검색 도구를 만들 수 있습니다. 이 파일 자체가 LLM-Wiki를 생성하기 위한 Skills와 같은 위치에 있다고 생각하면 이해하기 쉬울 것입니다.

구성 요소

주로 다음 세 가지입니다.

raw/

LLM이 집어넣는 1차 자료. LLM이 읽고 쓰며, 수동으로는 편집하지 않습니다.

wiki/

1차 자료를 참고하여 집필되며, LLM이 유지보수하는 문서. 사람이 읽을 수 있는(Human-readable) 형태이며, 예를 들어 다음과 같은 느낌입니다. 다음에 설명할 Query를 하거나 Ingest를 함으로써, Wiki는 점점 더 두꺼워지고 풍부해집니다.

AGENTS.md

AI Agent를 도메인의 "Wiki Maintainer"로 만들기 위한 토대가 되는 설정. 기본적으로는 "무엇을 1차 자료로 삼을 것인가", "어떻게 인용할 것인가", "기록이 없다면 어떻게 답할 것인가", "어떻게 운용할 것인가"와 같은 것들을 정의합니다. 원래의 gist 상태 그대로라면 팀에서 운용하기에는 꽤 부족할 것이라고 생각되므로, 이 부분을 본격적으로 커스터마이징하게 됩니다. 그런 의미에서, 해당 LLM-Wiki의 색깔이 가장 많이 반영되는 부분입니다.

조작

LLM-Wiki의 기본적인 조작은 대체로 다음 세 가지입니다.

• Query: Wiki에 질문하고, 유용한 답변을 Wiki에 기록하여 재사용할 수 있도록 합니다.
• Ingest: raw를 읽고, 기존 페이지와 연결하여 Wiki를 업데이트합니다.
• Lint: 모순, 오래된 기술, 고립된 페이지, 출처 부족을 검사합니다.

raw에 1차 정보를 전달하고, Ingest하여 wiki를 쓰고, 질문을 Query하여 좋은 답변은 wiki에 저장하고, Lint로 전체를 업데이트하여 정리하는 식의 워크플로우가 됩니다.

kDS에서는 여기에 더해, 다음과 같은 기능을 추가하여 운용하고 있습니다.

• Update: 각 문서 서비스로부터 1차 정보를 raw에 동기화하고, 검색용 인덱스를 업데이트합니다.
• Triage: 새로 늘어난 1차 정보나 Wiki의 부족함을 조사하여, 다음에 Ingest할 대상과 추가 조사가 필요한 토픽의 우선순위를 정합니다.
• Backfill: 과거의 1차 정보를 거슬러 올라가, 기존 페이지의 경위와 커버 범위를 보완합니다.

현재는 다음과 같은 사이클을 돌리는 운용 방식입니다.

장점

대량의 1차 정보로부터 답변해 준다는 의미에서 RAG와 LLM-Wiki는 비슷합니다. 반면, RAG는 검색 결과로부터 매번 답변을 구성하는 것이 기본이므로, 이전에도 검색했던 내용을 참조할 수 없어 토큰 비용이 늘어나거나 답변의 질이 모델에 따라 들쭉날쭉할 수 있습니다.

LLM-Wiki는 답변을 Wiki로서 남기고, Ingest할 때마다 관련된 지식끼리 연결해 나갑니다. Ingest 비용을 한 번 지불하면, 그 결과는 다음부터 Query로 참조할 수 있게 됩니다. Query를 통해 좋은 답변을 낼 수 있다면, 그것은 Wiki 네트워크에 축적됩니다. 사용하면 사용할수록 눈덩이처럼 불어나며 질 좋은 답변을 낼 수 있도록 성장하는 것이 LLM-Wiki의 특징입니다. 똑똑한 모델을 사용하여 Ingest하고 Wiki를 만들면, 다음부터는 질 높은 답변을 비교적 빠르게 얻을 수 있습니다.

여러 리소스에 각각 MCP를 연결한 Agent에게 검색하게 하는 것보다 효율적인 것도 같은 이유입니다. LLM-Wiki는 raw로부터만 데이터를 가져오기 때문에, MCP에 비해 토큰을 절약할 수 있고 안정적인 품질의 답변을 빠르게 얻는 경향이 있다고 할 수 있습니다.

디자인 시스템에서의 활용

팀 내에서 활용하기

영향 범위가 큰 디자인 변경은 배경 사정을 확실히 조사하여 변경 여부를 판단하는 것도 kDS 팀 업무의 일부입니다.

최근에는 Form Controls 계열 컴포넌트의 폰트 사이즈가 14px와 16px로 통일되지 않은 디자인이 있었습니다.

본래라면 조사 태스크로 분리되어 누군가 공수를 들여 과거의 경위를 거슬러 올라가야 했을지도 모릅니다. 하지만 LLM-Wiki 덕분에 모든 곳에 흩어져 있던 경위를 단 몇 분 만에 거슬러 올라가 정리할 수 있었고, 단 한 번의 커뮤니케이션으로 이야기가 마무리되었습니다.

이 시점에서 매우 편리한 점은, 팀 내의 논의를 원활하게 진행할 뿐만 아니라 직군을 초월한 커뮤니케이션 비용 (Communication Cost)을 절감하는 데에도 도움이 되고 있다는 것입니다.

엔지니어 팀이 활용하는 방식: "왜 이런 식으로 구현되어 있나요?"

컴포넌트 라이브러리 (Component Library)가 왜 그러한 방식으로 구현되었는지 조사할 수도 있습니다.

디자인 시스템의 React 컴포넌트와 Figma는 기본적으로 동일한 모습이지만, 어떤 계기로 인해 모습이 어긋나는 경우가 있습니다. 개발 팀으로부터 "왜 구현에는 여백이 있나요? Figma에는 없는데, Figma에 맞춰 이 여백을 구현에서 없앨 수는 없나요?"라는 질문이 들어왔습니다.

이러한 질문에는 kDS 멤버가 컨텍스트 (Context)를 알고 있기 때문에 답변할 수 있지만, 현재 멤버 이외의 사람이 답변하기는 어렵습니다. 그런 경우에도 개발 팀은 LLM-Wiki에 질문을 그대로 던질 수 있습니다. 실제 답변은 다음과 같았습니다.

실제 답변 예시

❯ 대상 컴포넌트에 대해 현재 구현과 디자인을 비교해 보면, 가장 아래 요소가 경계선이 아니라 그보다 조금 위에서 잘려 있습니다 (스크린샷에 빨간 원을 표시한 부분). 경계선에서 잘리도록 수정해도 문제없을까요? [Image #1]
...
결론: "경계선 바로 위에서 잘리는" 동작은 의도된 사양입니다. 경계선에서 잘리도록 되돌리는 수정은 권장하지 않습니다.
...

매우 높은 정확도로 근거가 포함된 답변을 얻을 수 있었고, 다음 행동 (Next Action)까지 제시해 주었습니다! 지금까지 디자인 시스템 팀에 물어보지 않으면 할 수 없었던 판단을 개발 팀 내부에서 할 수 있게 된 한 사례입니다.

디자인 팀이 활용하는 방식: "왜 이런 디자인이 되었나요?"

디자인 팀이 해당 디자인이 된 경위를 자발적으로 조사할 수도 있습니다.

디자인 팀은 컴포넌트의 레이아웃 디자인을 변경하는 검토를 진행하고 있었습니다. 해당 컴포넌트는 최소 너비 (Minimum Width)가 210px로 설정되어 있었는데, 이유를 알 수 없어 디자이너는 변경 가능한 디자인인지 판단할 수 없었습니다.

이에 디자인 팀이 LLM-Wiki를 이용하자 다음과 같은 답변이 돌아왔습니다.

실제 답변

대상 컴포넌트의 최소 너비 (min-width: 210px) 경위
"210px"라는 수치 자체의 근거는 기록되어 있지 않습니다. 반면, "고정 너비가 아닌 최소 너비로 설정한" 이유는 접근성 (Accessibility) 감사 대응으로서 명확하게 기록되어 있습니다.
경위 (시계열)
...

특히 별다른 이유 없이 이전의 px가 남아 있다는 사실을 알려주었습니다. 이유가 없다면 디자인을 재검토할 수 있습니다. 나아가, 접근성상의 이유로 의도적으로 width에서 min-width로 변경된 경위도 출력해 주었습니다. 디자이너는 width가 아닌 min-width 사용을 의식할 수 있을 것입니다.

운영상의 노하우

LLM-Wiki를 팀에서 운영할 때 고려한 설계 관점을 공유하고자 합니다.

LLM이 읽을 수 있는 범위를 기계적으로 제한하여 관리하기

사내 정보를 다루는 이상, 일반 정보 이외의 정보를 어떻게 다룰지가 가장 주의해야 할 포인트입니다. Slack이나 Confluence에는 비공개 공간도 포함되어 있습니다.

가져오는 정보는 관리 가능하게 하고, 기계적으로 제한하고 싶습니다. kDS의 LLM-Wiki에서는 Wiki가 인용해도 좋은 정보를 raw/에 존재하는 내용으로만 제한하고 있습니다. 또한, Python으로 작성된 동기화 (Sync) 스크립트를 준비하여 동기화를 할 때는 이를 사용합니다.

sync 스크립트는 허용 목록 (Allowlist)을 참조하며, allowlist에서 모든 접속 대상을 일괄 관리합니다. 추가되지 않은 대상에는 스크립트가 접속할 수 없습니다.

"""Canonical allowlist for every external source mirrored by this repository.
Review this file to see the complete acquisition boundary. Adding a repository,
space, channel, app, or kintone field requires a code change and review.
...

물론, 공개된 채널 (Channel)의 본문에 민감한 정보가 적혀 있는 경우까지 자동으로 판별할 수는 없기 때문에, 별도로 필요한 확인 절차도 거치고 있습니다.

목적을 명확히 하기

LLM-Wiki는 리소스가 많아질수록 노이즈도 증가하고 판단을 잘못하기 쉬워진다고 합니다. 따라서 정보는 목적에 맞춰, 가능한 한 핵심적인 내용으로 제한하는 것이 효과적입니다.

예를 들어 kDS의 경우 '디자인 시스템 합의 형성 과정을 추적하는 것'이 목적입니다. 목적이 명확하면 그와 관련된 필요한 정보를 선별할 수 있고, 불필요한 정보나 구현을 추가하지 않아도 됩니다.

만약 kDS LLM-Wiki의 목적이 '컴포넌트 라이브러리 구현 과정 추적'이라면, Slack의 디자이너 스레드나 Confluence는 그렇게 중요하지 않았을 것입니다.

데이터 가중치 부여

LLM-Wiki를 만들 때는 목적에 맞는 응집력 있는 정보부터 우선적으로 추가해 나갔습니다. 정리된 가이드라인이나 ADR(Architecture Decision Record)로 시작하고, 그것만으로는 부족하면 다소 정제되지 않은 회의록이나 채팅 같은 데이터도 보충하는 방식입니다.

이렇게 정보가 늘어나면 결국 무엇이 채택되었는지 파악하기 어려워지는 것이 단점입니다.

그래서 어느 정도 팀의 의사 결정 프로세스에 맞춰, 정보의 신뢰도 순으로 가중치(weight)를 정의했습니다. 예를 들어, 구현에 반영된 병합된 Pull Request는 Slack상의 대화보다 더 강력한 근거로 취급합니다. 팀의 의사 결정 프로세스에 따라 병합된 PR > 가이드라인 > ADR > Discussion > ... > 회의록와 같은 가중치 순서를 적용하고 있습니다.

순서는 팀마다 다를 수 있습니다. ADR이 가장 중요한 팀도 있고, 사양 리포지토리의 변경만을 공식적인 결정으로 간주하는 팀도 있을 것입니다.

양방향 링크로 관련 정보 역추적하기

'이 Issue가 어떤 Slack 스레드나 Confluence에서 참조되었는지'와 같은 **'역추적(Reverse Lookup)'**은 일반 검색으로는 매우 어렵습니다. GitHub의 경우, Issue를 언급한 PR을 Issue에서 추적할 수 있는 기능이 있지만, 플랫폼에 구애받지 않는 곳에서는 이 기능이 없습니다.

따라서 1차 자료에 포함된 참조를 인덱싱하여 역추적이 가능하도록 만들었습니다. 이를 통해 특정 PR에서 원래의 Issue를 거쳐, 그 Issue를 참조하는 Confluence나 Slack 스레드를 찾을 수 있게 됩니다. 최종적인 변경뿐만 아니라, 변경의 계기나 반대 의견까지 추적할 수 있습니다.

양방향으로 링크하면 기계적으로 관련성을 파악할 수 있어 빠르고 정확하며 재현성 높은 검색 결과를 얻을 수 있습니다. 필수 기능 중 하나입니다.

Git 히스토리 활용하기

'언제 어떤 계기로 이 구현이 되었는가?'를 알기 위해서는 소스코드 외에 Git의 히스토리, 특히 blame 기능을 사용하고 싶어집니다.

구현 과정을 조사할 때는 해당 라인의 blame을 통해 변경한 커밋(commit)을 특정하고, 연결된 Pull Request나 Issue까지 거슬러 올라갈 수 있도록 합니다. main 코드만으로는 알 수 없더라도, 변경을 추가한 Commit 메시지나 PR에 단서가 남아 있는 경우도 처리할 수 있습니다.

앞서 언급한 ### 엔지니어 팀이 활용하는 예시는 이것을 구현함으로써 답변의 질이 극적으로 개선되었습니다.

TODO

더 운영하기 쉽게 만들기 위해 아직 개선할 부분이 많습니다. 특히 데이터를 비용 효율적으로 유지보수하는 측면에서 CI(Continuous Integration) 부분을 정비해 나갈 가치가 높습니다.

데이터 자동 동기화 (Auto Sync)

GitHub, Slack, Confluence, kintone, Zoom의 정보는 매일 업데이트되기 때문에 raw 데이터를 주기적으로 업데이트해야 합니다.

현재 동기화 처리는 개인 환경과 인증 정보에 의존하고 있어, 각자가 인지했을 때(매일 사용하므로 거의 매일) 업데이트하고 있습니다.

호스팅

현행 Wiki는 개개인이 리포지토리를 클론하여 로컬의 Agent를 이용하는 형태입니다.

하지만 디자인 시스템의 의사 결정을 참조하는 사람은 개발자뿐만 아니라 디자이너, 그리고 그 외 이해관계자(stakeholder)에게도 전달될 수 있습니다. 그러한 사람들은 반드시 Wiki에 무언가를 추가하거나 편집하고 싶어 하는 것이 아니라, 단순히 검색 서비스 용도로 이용하고 싶은 경우가 대부분입니다. 현재 Git 기반 운영 방식으로는 Git에 익숙하지 않은 사람들에게 활용이 확산되지 않을 가능성이 높습니다.

Wiki를 「질문하는 사람」과 「키우는 사람」으로 나누어 생각할 수 있습니다.

「질문만 하는 사람」을 위해서는 클라우드 AI 서비스를 이용하여 브라우저에서 질문할 수 있도록 하는 형태도 고려해 볼 수 있을 것입니다. 다만, 클라우드 측은 기본적으로 읽기 전용 (read only) 상태로 유지하고 싶습니다.

Wiki의 충돌 (Conflict)

여러 명이 Wiki를 유지보수(maintenance)하면, 동일한 Wiki를 여러 명이 편집하는 타이밍이 발생하게 됩니다.

하지만 Wiki의 충돌 (conflict)을 해결하는 것 자체가 그리 본질적인 문제는 아닙니다. 인간에게는 Query를 수행한 결과가 중요하기 때문에, Wiki의 내용은 최악의 경우 AI가 참조할 수 있기만 하면 되기 때문입니다.

이러한 전제하에, 각 Wiki 파일은 파일 끝에 각자가 내용을 추가해 나가는 규칙을 적용해도 좋을 것입니다. 내용은 중복되겠지만, 동일한 파일을 여러 명이 편집하더라도 충돌 (conflict)은 발생하지 않게 됩니다. 중요한 것이 Query를 수행한 결과라면, 이 방식도 큰 문제가 되지 않을 것으로 보입니다.

물론 사람이 Wiki를 참조하지 않을 가능성이 제로라고 단정할 수는 없습니다. Wiki를 정기적으로 정돈할 필요가 있다면, Lint를 CI (지속적 통합)에 포함시키고, CI 상에서 에이전트 (Agent)가 실행하도록 하는 운영 방식이 필요할 것입니다.

마치며

kintone Design System 팀의 미션은 **「kintone에 대해 아웃풋을 내는 사람들이, 일관성 있는 사용자 경험과 디자인 품질을 사용자에게 제공할 수 있는 상태를 만드는 것」**입니다.

하지만 그 구성 요소인 디자인 시스템의 컴포넌트 (component)도, Figma도, 디자인 토큰 (design token)도, 가이드라인도, 어느 날 갑자기 완벽한 상태로 만들어지는 것은 아닙니다.

사용자의 니즈가 있는 한, 디자인도 프로덕트의 경험도 매일 개선 방안이 검토됩니다. 그 아이디어를 치열하게 논의하고, 단계를 밟아가며 점진적으로 「더 나은」 상태를 목표로 나아갑니다. 처음부터 완벽한 것을 만들 수는 없으며, 언제 완벽함에 도달할지 예측할 수도 없을 것입니다.

그렇기에 「더 나은」 상태를 목표로 하기 위해, 현재 상황을 높은 해상도로 파악하는 것에 의미가 있습니다. 「왜 이렇게 되었는가?」, 「어떤 니즈가 있었는가?」, 「그 외에는 무엇이 검토되었는가?」, 「누가 어떻게 관여했는가?」와 같은 「논의」와 「배경」을 이해하는 단계는 그 수단으로서 효과를 발휘할 수 있습니다.

현상을 깊이 이해하고 사실에 기반한 효율적인 논의를 이끌어내는 것은, 끊임없이 변화하는 사용자 및 디자인 니즈를 조금이라도 예측하고 일관된 더 나은 디자인을 만드는 열쇠가 될 것입니다.

디자인 시스템을 논의로부터 통째로 LLM-Wiki화 하는 것은, 이를 실현하는 디자인 시스템의 새로운 형태가 될 수 있을지도 모릅니다.

참고

Discussion