Read Original
#AI

LLM Wiki: 코드 기준으로 자동 최신화되는 도메인 지식 SSOT 만들기

LLM Wiki: 코드 기준으로 자동 최신화되는 도메인 지식 SSOT 만들기
01

Summary

코드만 짜면 문서가 알아서 바뀐다? 라인의 똑똑한 'LLM Wiki' 구축 대공개

문서 노후화와 AI 환각을 한 번에 격파하는 소스 코드 기반 SSOT 자동 구축 가이드

마이크로서비스 아키텍처(MSA)에서 늘 골칫거리였던 문서 자산화 문제를 혁신적으로 해결한 사례를 소개합니다. 소스 코드를 최상의 근거로 삼아 비즈니스 규칙을 자동 추출하고, GitHub Actions 파이프라인을 연동해 실시간으로 도메인 문서를 최신화하는 구조를 구현했습니다. 이를 통해 AI가 정확한 맥락에서 코드 설계를 돕는 진정한 스펙 주도 개발(SDD)을 달성했습니다.

  • 01소스 코드와 주석 및 설정에서 도메인 지식을 상시 추출하여 raw와 knowledge의 이중 구조로 체계적 보존
  • 02PR의 변경점(diff)과 주변 코드를 연계 분석하여 변경 이력을 누적하고 실시간으로 지식 문서를 자동 갱신
  • 03동일한 Markdown 문서 하나로 AI용 탐색 데이터(Frontmatter)와 개발자용 시각 자료(Knowledge Wiki)를 동시에 제공
  • 04식별자 무결성(Identifier integrity)을 비롯한 강력한 자가 진단(Lint) 검증 단계를 도입해 왜곡된 정보의 확산 방지
  • 05요구사항 스펙 구체화부터 코드 구현, 그리고 변경 전후 영향도 분석까지 연결하는 정밀한 개발 워크플로우 수립

RECOMMENDATION

프로젝트 규모가 커질수록 기하급수적으로 늘어나는 기술 문서 관리 공수를 줄이고 싶거나, AI 기반 자동 코딩 시 환각 현상을 획기적으로 낮추어 개발 프로세스를 고도화하려는 테크 리더와 아키텍트에게 필수적인 아티클입니다.

The Problem

마이크로서비스 아키텍처(MSA) 환경에서는 비즈니스 정책과 도메인 지식이 여러 서비스에 파편화되어 있어 최신 스펙을 파악하기 어렵습니다. 이로 인해 문서의 노후화와 AI의 환각 피드백 루프가 발생하여 개발 생산성이 저하됩니다.

The Solution

코드를 단일 진실 공급원(SSOT)으로 삼아 소스 코드로부터 비즈니스 스펙을 역추출하는 LLM Wiki를 구축했습니다. GitHub Actions를 통해 PR 병합 시 스펙 변경을 수집하여 raw(이력)와 knowledge(지식) 문서 구조로 동기화하고, 주기적인 lint로 정합성을 검증합니다.

The Result

자동화된 지식 동기화를 바탕으로 AI가 스펙 구체화 및 영향도 분석 시 최신화된 코드 맥락을 신뢰도 높게 활용할 수 있게 되었습니다. 동시에 개발자들 역시 Knowledge Wiki 정적 사이트를 통해 최신화된 MSA 전체 흐름을 손쉽게 이해하고 온보딩에 적용할 수 있게 되었습니다.

Trade-off

초기 베이스라인을 구축할 때 코드만으로 알 수 없는 도메인 정책의 경우 사람이 보완해야 하며, PR 스펙 변경 시에도 현재는 최종 수동 리뷰 단계가 필요합니다. 또한 자동 스펙 추출 파이프라인의 안전한 검증을 위해 사람이 직접 개입하는 과도기적 리소스 소모가 일부 발생할 수 있습니다.

03

Key Concepts

Concept · 01

LLM Wiki

안드레 카파시가 제안한 패러다임으로, 대규모 언어 모델이 원본 문서를 한 번 독파하여 신뢰도 높은 위키 형태로 정보를 가공해 두고 이후 질문들에 답하도록 유도하는 개념입니다.

  • 소스 코드 분석을 통해 비즈니스 룰을 추출하고 최신의 지식 문서를 스스로 편집하는 주체로 LLM을 활용했습니다.
Concept · 02

단일 진실 공급원 (SSOT)

시스템 내에서 참조하는 모든 정보나 규칙이 단 하나의 일관된 공식 채널에서 제공되도록 유도하여 데이터 파편화를 원천 차단하는 사상입니다.

  • 가장 신뢰할 수 있는 소스 코드를 바탕으로 비즈니스 정책을 역추출하여 무결한 위키 기반의 단일 채널을 구성했습니다.
  • 변경 이력을 관리하는 'raw' 층과 현시점의 최신 정책을 정적 사이트로 배포하는 'knowledge' 층으로 설계했습니다.
Concept · 03

스펙 주도 개발 (Spec-Driven Development)

실제 물리적 코드를 빌드하고 작성하기 앞서, 기능의 논리적 명세와 세부 사양을 구체적인 문서화 스펙으로 완전하게 확정한 후 개발 및 검토에 임하는 기법입니다.

  • 스펙의 생성부터 시작해 요구사항 상세화, 사전 및 사후 영향도 분석 전반을 LLM Wiki SSOT 데이터를 기준으로 일관되게 진행합니다.
Concept · 04

식별자 무결성 (Identifier Integrity)

문서 내의 API 엔드포인트, DB 스키마, Kafka 토픽명 등 실제 시스템을 식별하는 물리적 명칭들이 자연어로 요약되거나 누락되지 않도록 그대로 매칭되는 신뢰 속성입니다.

  • LLM이 정보를 요약하고 번역하는 와중에도 물리 식별자를 변형 없이 보존하도록 정밀 설계했습니다.
  • 주기적인 lint 실행을 통해 변형되거나 누락된 고유 명칭과 고아 페이지 링크를 추적하여 수정합니다.