정산 멀티레포 도메인 지식을 LLM Wiki로 유지하기

정산 시스템 5개 레포를 오가며 일하는데 AI에게 물어볼 때마다 같은 설명을 반복하고 있었습니다. 그래서 도메인 지식을 마크다운 위키로 따로 만들고 유지 주체를 LLM에게 넘겨봤습니다. 구조와 운영 규칙, 만들면서 알게 된 한계를 정리합니다.

TL;DR

• 코드는 "어떻게"를 답하지만 "왜 이렇게 계산하는가"는 답하지 못합니다. 그 지식은 Jira와 Slack, 사람 머릿속에 흩어져 있었습니다.
• Karpathy가 제안한 LLM Wiki 패턴을 멀티레포 환경에 맞춰 적용했습니다. 원천 자료와 컴파일된 지식을 물리적으로 분리하는 게 핵심입니다.
• 지금 마크다운 123개를 유지하고 있습니다. lint와 검색, 그래프, llms.txt 내보내기를 스크립트로 붙여 사람도 LLM도 같은 파일을 씁니다.
• 가장 위험한 건 위키를 믿고 코드를 안 보게 되는 습관입니다. 그래서 "출발점은 위키, 최종 확인은 코드"를 운영 원칙에 못 박았습니다.

문제 정의: 코드를 읽어도 모르는 것

정산 도메인은 계산식 하나에 정책 히스토리가 겹겹이 쌓입니다. 어떤 컬럼이 왜 그 시점에 추가됐고 특정 취소 케이스를 왜 별도 분기로 뺐는지는 코드에 안 남습니다. 커밋 메시지에도 거의 안 남습니다. 그 맥락은 Jira 티켓과 Slack 스레드, 그리고 오래 일한 사람의 기억에 있습니다.

AI 코딩 도구를 쓰기 시작하니 이 문제가 훨씬 선명해졌습니다. 새 세션을 열면 매번 이런 일이 반복됐습니다.

1. 관련 파일을 다시 찾아 읽힙니다.
2. 도메인 배경을 다시 설명합니다.
3. 그래도 이전 세션과 다른 답이 나옵니다.

레포가 하나면 견딜 만합니다. 저희는 API와 배치, 수집, 외부 시스템 연동, 펌뱅킹이 각각 다른 레포에 있고 언어도 섞여 있습니다. 파일을 읽히는 비용만으로 컨텍스트가 반쯤 찼습니다. 무엇보다 매번 다시 설명하는 동안 그 설명은 어디에도 저장되지 않았습니다.

접근: 원천 자료와 컴파일된 지식을 분리한다

Karpathy가 정리한 LLM Wiki 패턴을 참고했습니다. 발상은 단순합니다. 사람이 원천 자료를 넣고 LLM이 그걸 읽어 위키 페이지로 컴파일하고 질문은 원천이 아니라 위키에 던집니다.

여기서 제가 중요하게 본 건 원천과 위키를 물리적으로 다른 디렉토리에 두는 것이었습니다. 둘을 섞으면 LLM이 원본을 요약으로 덮어쓰기 시작합니다. 한 번 덮이면 복구가 안 됩니다.

billyo-llm-wiki/
  AGENTS.md                 # 위키 운영 규칙. LLM이 가장 먼저 읽는다
  raw/                      # 원천 자료. 사람이 넣고 LLM은 읽기만 한다
    sources/                # repo 문서, Jira, PR, Slack, Confluence 요약
    assets/
  wiki/                     # LLM이 유지하는 지식 레이어
    index.md                # 주제 기반 카탈로그
    log.md                  # append-only 작업 로그
    overview/               # 시스템 개요
    entities/repositories/  # repo별 entity 페이지
    concepts/               # 정산·운영·아키텍처 개념
    questions/              # 재사용 가능한 질문과 답변
    reports/                # lint, 영향 분석, 회고
  templates/                # ingest / query / page 템플릿
  scripts/                  # lint, 검색, export
  outputs/                  # llms.txt 등 파생 산출물

운영 원칙은 네 줄로 줄였습니다. 길면 LLM이 안 지킵니다.

• raw/는 source of truth입니다. 기존 원천 자료를 덮어쓰지 않습니다.
• wiki/는 compiled knowledge입니다. 요약과 연결, 모순 표시, index와 log 갱신을 LLM이 담당합니다.
• 중요한 사실에는 출처를 남깁니다.
• 정산 로직 판단은 위키를 출발점으로 삼고 최종 확인은 실제 repo와 Jira, 운영 문서에서 합니다.

entity와 concept를 나눈 이유

처음에는 위키를 주제별로만 나눴습니다. 금방 무너졌습니다. "일별 정산 마감"은 개념인데 그걸 구현한 코드는 두 레포에 걸쳐 있고 반대로 한 레포에는 여러 개념이 섞여 있습니다. 주제 하나로 묶으면 페이지가 계속 비대해집니다.

그래서 두 축으로 쪼갰습니다.

• entities/repositories/ — 레포 단위 사실. 어떤 모듈이 있고 무엇을 책임지며 어디에 배포되는가.
• concepts/ — 도메인 개념 단위 사실. 이 개념이 무엇이고 어떤 규칙을 따르며 어느 레포에 구현돼 있는가.

둘을 wikilink로 연결하면 "이 개념을 건드리면 어느 레포가 영향을 받는가"가 그래프로 보입니다. 영향 분석을 할 때 이 연결이 제일 많이 쓰였습니다.

questions/는 나중에 추가했습니다. 같은 질문을 두 번 하게 되는 걸 발견하고 만들었습니다. 답변을 페이지로 남기면 다음 세션이 그 페이지를 먼저 읽습니다.

append-only log를 둔 이유

wiki/log.md는 추가만 하고 수정하지 않습니다. LLM이 위키를 고칠 때마다 무엇을 왜 바꿨는지 한 줄씩 쌓습니다.

처음에는 없어도 될 것 같았습니다. 두 번쯤 겪고 나서 생각이 바뀌었습니다. LLM이 잘못된 요약을 위키에 반영하면 그게 언제 어떤 원천을 근거로 들어왔는지 추적할 방법이 필요합니다. git log로도 되지만 커밋 하나에 여러 페이지가 섞이면 이유를 못 찾습니다.

로그가 길어지면 log-archive.md로 잘라 옮깁니다. 이것도 규칙에 적어둬야 LLM이 로그 파일을 통째로 다시 쓰는 사고를 막습니다.

스크립트 4개

위키를 사람 손으로만 관리하면 금방 썩습니다. 표준 라이브러리만 써서 네 개를 만들었습니다.

python3 scripts/wiki_lint.py        # 깨진 wikilink, 고아 페이지, 출처 없는 사실 검사
python3 scripts/wiki_search.py X    # 위키 안에서 X 검색
python3 scripts/export_graph.py     # wikilink 그래프를 json / graphml로 내보내기
python3 scripts/export_llms.py      # llms.txt / llms-full.txt 생성

wiki_lint.py가 제일 많이 돌아갑니다. 존재하지 않는 페이지로 LLM이 링크를 걸어두는 일이 자주 생깁니다. 사실 이건 버그가 아니라 신호로 쓰는 편이 낫습니다. 깨진 링크는 "아직 안 쓴 페이지"이고 lint 결과가 곧 다음 작업 목록이 됩니다.

export_llms.py가 만드는 llms.txt는 위키 전체를 한 파일로 합친 결과물입니다. 다른 레포에서 작업할 때 이 파일 하나만 붙이면 도메인 배경을 다시 설명하지 않아도 됩니다. 애초에 이걸 원해서 시작한 일이었습니다.

그래프 내보내기는 Obsidian으로 대체할 수 있습니다. 실제로 저는 이 디렉토리를 Obsidian vault로 열어 그래프 뷰로 봅니다. 연결이 없는 섬 같은 페이지가 바로 눈에 띕니다.

ingest 흐름

새 자료를 넣는 절차를 고정했습니다.

1. raw/sources/YYYY-MM-DD-<type>-<slug>.md 로 원천 자료를 둔다
2. LLM에게 "AGENTS.md를 읽고 이 source를 ingest해줘"라고 요청한다
3. LLM이 wiki 페이지를 만들거나 갱신하고 index.md와 log.md를 고친다
4. wiki_lint.py를 돌려 깨진 링크를 확인한다
5. export를 다시 실행한다

파일명에 날짜와 타입을 넣는 규칙이 생각보다 중요했습니다. 나중에 "이 사실은 언제 시점의 것인가"를 판단할 때 파일명만 보면 됩니다. 정산 정책은 계속 바뀌므로 시점이 빠진 사실은 위험합니다.

알게 된 한계

첫째, 위키는 반드시 낡습니다. 코드는 배포되면 바뀌지만 위키는 누가 갱신하지 않으면 그대로입니다. 그래서 위키에 적힌 사실을 근거로 코드를 고치는 건 금지했습니다. 위키는 어디를 봐야 하는지 알려주는 지도이고 판단 근거는 코드와 운영 데이터에서 다시 가져옵니다.

둘째, LLM은 모순을 잘 안 표시합니다. 원천 두 개가 서로 다른 말을 하면 조용히 하나를 고릅니다. 규칙에 "모순을 발견하면 양쪽을 모두 남기고 표시하라"고 적어도 완벽하지 않았습니다. lint에 검사 항목을 추가하는 쪽이 그나마 나았습니다.

셋째, 문서 개수는 목표가 아닙니다. 123개라고 썼지만 이 숫자 자체는 아무 의미가 없습니다. 실제로 값을 준 건 반복 질문이 사라진 것과 다른 레포에서 작업할 때 배경 설명을 다시 안 하게 된 것입니다. 페이지를 늘리려고 원천 없이 추측을 적으면 위키가 오염됩니다. 한 번 그렇게 만들었다가 되돌렸습니다.

마무리

정리하면서 얻은 건 도구가 아니라 습관이었습니다. 예전에는 도메인 지식이 제 머릿속에 있는 걸 당연하게 여겼습니다. 지금은 새로 알게 된 사실이 생기면 raw/에 먼저 던집니다. 그러면 다음에 필요할 때 저도, AI도 같은 곳에서 꺼내 씁니다.

멀티레포 환경에서 AI 도구를 쓰는 분이라면 위키를 만드는 것보다 원천과 컴파일된 지식을 분리하는 원칙부터 정하는 쪽을 권합니다. 디렉토리 구조는 나중에 얼마든지 바꿀 수 있지만 원본을 요약으로 덮어쓴 건 되돌릴 수 없습니다.

개발 과정 자체에 검증 단계를 넣은 이야기는 AI를 코드 생성기가 아니라 검증 장치로 쓰기에 따로 정리했습니다.