파일을 쌓는 것에서 흐름을 보는 것으로 — LLM Wiki LCL 시각화 대시보드 구현 사례

한 줄 요약

LLM Wiki LCL에 이미 축적되어 있던 Evolution report를 읽어, 제안·평가·승격·적용 준비 상태와 최근 작업 문서를 한 화면에서 탐색할 수 있는 독립 실행형 HTML 대시보드로 만들고 브라우저에서 실제 동작까지 검증한 사례다.

이 글을 읽으면 좋은 사람

• Markdown 기반 지식 저장소를 운영하지만 최근 작업과 미완료 검토 대상을 한눈에 보기 어려운 사람

• RAG나 검색 인덱스와 별도로, 지식 운영 상태를 시각화하고 싶은 사람

• 별도 웹 애플리케이션을 배포하지 않고 로컬 파일로 재현 가능한 운영 화면을 만들고 싶은 사람

• 대시보드가 원본 문서를 직접 수정하지 않도록 안전한 경계를 두고 싶은 사람

문제의식 — report는 있었지만 화면은 없었다

LCL에는 Shadow Promotion의 제안, 평가, 승격 기록, 적용 계획을 정리한 Markdown·JSON report가 이미 있었다. 숫자와 상태는 존재했지만, 담당자가 매번 여러 파일을 열어야 다음 질문에 답할 수 있었다.

• 어떤 작업이 현재 적용 준비 상태인가?

• 최근 어떤 문서가 검토 대상이 되었는가?

• lint와 source 수는 정상인가?

• review queue가 비어 있는가, 아니면 아직 확인하지 않은 것인가?

• 이 작업이 단순 위키 문서 수정인지, workflow 수정인지?

즉, 자료가 없었던 것이 아니라 운영 상태를 다시 탐색하는 표면이 없었다. 기존 report를 버리고 새로운 데이터베이스를 만드는 대신, 이미 검증된 report를 읽는 얇은 시각화 계층을 추가하기로 했다.

출발점 — 참고자료와 실제 근거를 분리했다

대시보드 정보 구조를 설계할 때 공개 Threads 참고자료 SRC-278을 배경 자료로 사용했다. 이 자료는 할 일, 최근 문서, 작업 이력, 개인 메모리, 공유 메모리라는 탐색면을 제안했지만, LCL의 법령·예규·판례 근거는 아니다.

따라서 다음처럼 역할을 분리했다.

SRC-278을 법률 근거처럼 사용하지 않고, 실제 LCL report와 workflow에 연결하는 설계 참고자료로만 처리한 것이 첫 번째 경계다.

구현 구조

구현은 별도 서버나 웹 프레임워크 없이 다음 흐름으로 제한했다.

latest-dashboard.json
latest-review-queue.json
latest-apply-plan-summary.json
latest lint report
latest AI access statistics
        │
        ▼
91_scripts/generate_visual_dashboard.py
        │
        ▼
50_reports/evolution/visual-dashboard.html
        │
        ├─ 브라우저에서 직접 열기
        ├─ 검색·상태·분류 필터 사용
        ├─ 작업 항목 상세 dialog 열기
        └─ 인쇄·PDF 출력

생성기는 report를 읽어 필요한 데이터를 HTML 안에 임베드한다. 외부 JavaScript와 네트워크 요청을 사용하지 않기 때문에 대시보드 파일 하나만 복사해도 같은 스냅샷을 볼 수 있다.

화면 캡처

아래 이미지는 생성된 HTML을 1440px 너비의 브라우저에서 렌더링해 저장한 전체 화면 캡처다.

그림 1. LLM Wiki LCL standalone visual dashboard. 요약 카드, 작업 흐름, 검증 상태, 최근 문서, 작업 항목, 정보 구조 카드를 한 화면에 배치했다.

캡처 원본은 visual-dashboard.html이며, PNG artifact는 visual-dashboard-screenshot.png로 보존했다.

화면이 해결하는 탐색 문제

1. 상태를 숫자 하나가 아니라 흐름으로 본다

상단에는 제안 13건, 평가 13건, 승격 기록 13건, 적용 준비 13건, 거절 0건이 표시된다. 이어지는 Pipeline은 제안 생성에서 적용 준비까지 같은 수가 어떻게 이어지는지 보여 준다.

이 화면의 목적은 “13건이 있다”는 사실을 반복하는 것이 아니다. 각 단계의 수가 어긋날 때 어느 계층에서 확인해야 하는지 빠르게 알려 주는 것이다.

2. 품질 상태를 작업 목록과 분리한다

검증 상태 카드에는 다음 값이 표시된다.

• LLM Wiki lint: PASS

• errors / warnings: 0 / 0

• broken graph links: 0

• indexed sources: 261

• AI access events: 2,064

품질 상태와 작업 항목을 같은 표에 섞지 않고 별도 카드로 둔 이유는, “작업이 많다”와 “검증이 실패했다”가 서로 다른 문제이기 때문이다.

3. 빈 review queue도 상태로 보여 준다

현재 review queue와 apply plan은 비어 있다. 대시보드는 이를 빈 공간으로 숨기지 않고 현재 검토 큐가 비어 있습니다라고 표시한다.

이것은 “할 일이 없다”는 성공 선언이 아니다. 현재 report에 기록된 검토 큐가 비어 있다는 관찰 결과다. 새 proposal이 생기면 다시 생성해야 화면에 반영된다.

4. 최근 문서와 전체 작업을 구분한다

최근 작업 문서 카드는 현재 상태판에 기록된 최신 항목을 빠르게 보여 준다. 아래 전체 작업 테이블에서는 대상 문서, 분류, 평가 상태, promotion 상태를 확인할 수 있다.

검색창에 schema를 입력하면 13개 항목 중 schema/AGENTS.md에 해당하는 1개 항목만 남는다. 각 행의 보기 버튼을 누르면 proposal ID, 대상 경로, 평가 결과, 승격 상태, evidence와 acceptance criteria를 상세 dialog에서 확인할 수 있다.

5. 정보 구조와 구현 범위를 함께 보존한다

하단에는 SRC-278에서 참고한 다섯 탐색면을 LCL의 파일 구조와 함께 기록했다.

• 오늘의 할 일: latest-review-queue.json, latest-apply-plan-summary.json

• 최근 문서: latest-dashboard.json, index.md, log.md

• 작업 이력: evidence-ledger.jsonl, devlog, chronicle

• 개인 메모리: profile memory와 skills

• 공유 메모리: AGENT-COMMONS, LESSONS-LEARNED, QUALITY-CHECKS

이 카드들은 현재 모든 정보를 실시간으로 통합한다는 뜻이 아니다. 어떤 정보가 어느 경계에 속하는지 잊지 않게 하는 지도다.

구현하면서 지킨 것

원본 보존

10_sources/의 원본은 수정하지 않았다. 대시보드는 기존 report를 읽어 projection을 만들 뿐이며, live wiki 문서나 raw source에 자동으로 patch를 적용하지 않는다.

상태와 적용을 분리

화면에 적용 준비가 표시된다고 해서 실제 문서가 자동으로 변경된 것은 아니다. Shadow Promotion 기록은 검토와 승인 이후 별도 적용 절차를 거친다. 따라서 대시보드는 운영 상태를 보여 주지만, 적용 권한을 대신하지 않는다.

참고자료와 권위자료를 분리

SRC-278은 UI 문제정의의 배경자료다. 지방계약법령, 예규, 판례의 근거로 사용하지 않는다. 이 구분을 사례게시글과 workflow에 함께 남겨 출처의 역할이 섞이지 않도록 했다.

로컬 실행 우선

대시보드 생성 명령은 다음과 같다.

cd <LLM-Wiki_LCL>
./scripts/cli/llm_wiki_dashboard.sh

도메인 내부 wrapper를 직접 실행할 수도 있다.

cd <LLM-Wiki_LCL>/domains/local-contract-law
./llm_wiki_dashboard.sh --print-summary

검증 결과

구현 완료를 단순히 HTML 파일이 생겼다는 사실로 판단하지 않고 다음을 확인했다.

재현 가능한 운영 패턴

이 사례에서 다른 지식 저장소에도 적용할 수 있는 패턴은 다음과 같다.

1. 이미 존재하는 report를 데이터 기준으로 정한다.

2. 원본·검토·승격·품질 report를 읽기 전용 projection으로 묶는다.

3. 외부 서비스 없이 열 수 있는 standalone HTML을 생성한다.

4. 검색과 상세 보기를 넣어 요약 화면에서 원래 작업으로 내려갈 수 있게 한다.

5. 빈 큐와 적용 준비 상태를 성공처럼 과장하지 않고 관찰값으로 표시한다.

6. 브라우저 렌더링, 필터, 상세 dialog, console 오류를 실제로 확인한다.

7. 캡처와 생성기를 함께 보존해 결과 화면과 재현 절차를 연결한다.

8. 대시보드가 보여 주는 상태와 실제 문서 변경 권한을 분리한다.

한계와 다음 단계

현재 대시보드는 최신 report의 정적 스냅샷이다. 새 proposal, lint 결과, usage 통계가 생성되면 llm_wiki_dashboard.sh를 다시 실행해야 한다.

또한 다음 기능은 아직 구현하지 않았다.

• Obsidian 플러그인 기반 실시간 pane

• private/shared memory의 실시간 동기화

• 대시보드에서 live wiki 문서를 직접 편집하는 기능

• 사용자별 권한 관리와 서버 배포

• 자동 refresh 또는 scheduled rebuild

따라서 이 결과물은 “완성된 운영 플랫폼”이 아니라, LCL의 기존 지식 구조를 안전하게 읽어 시각화하는 검증된 standalone projection으로 보는 것이 정확하다.

결론

이번 작업의 핵심은 새로운 데이터를 더 쌓은 것이 아니라, 이미 쌓인 지식 운영 기록을 다시 읽을 수 있는 화면으로 바꾼 데 있다.

LLM Wiki가 오래 살아남으려면 원본과 문서만 축적해서는 부족하다. 무엇이 최근에 바뀌었고, 무엇이 검토 중이며, 어떤 상태가 검증되었는지 다시 찾을 수 있어야 한다. 이번 LCL 대시보드는 그 탐색 표면을 가장 작은 형태로 구현했다.

대시보드는 지식을 대신 판단하지 않는다. 대신 사람이 다음 판단을 시작할 위치를 빠르게 알려 준다. 그 경계를 지키는 것이 시각화보다 더 중요한 운영 원칙이다.

관련 문서

• LLM Wiki 에이전트 대시보드 설계 워크플로

• LLM Wiki RAG 운영 topic map

• LLM Wiki 개념 문서

• 시각화 대시보드 HTML

• Evolution Reports README

• 최신 LLM Wiki lint report

생명주기

• 상태: published

• 외부 게시: Lecture_Recap_Library case-library 발행 완료

• 캡처: visual-dashboard-screenshot.png

• 마지막 검증: 브라우저 렌더링·필터·상세 dialog·console·LCL lint