매번 같은 맥락 설명하기 지쳐서 직접 깎은 나만의 LLM Wiki 구축기

이 글에서 알 수 있는 것

• ChatGPT와 Claude가 똑똑해져도 별도의 LLM Wiki가 필요한 이유
• 내가 dev-wiki를 만들고 bono-wiki로 확장한 실제 배경과 시행착오
• 거대한 시스템 없이 index.md, current-status.md, decisions.md, CLAUDE.md 4개의 파일로 시작하는 방법

AI를 오래 쓸수록 이상했다. 모델은 계속 똑똑해지는데, 새 대화를 열 때마다 나는 같은 설명서를 다시 쓰고 있었다.

지금 하는 일과 이전 결정, 지켜야 할 기준을 다시 설명해야 원하는 답이 나왔다. 실력 좋은 동료가 매일 첫 출근을 하는 것과 비슷했다.

그래서 2026년 초, 기억상 2~3월 무렵부터 개발 업무용 지식 시스템인 dev-wiki를 쓰기 시작했다. 남아 있는 5월 기록을 보면 당시 이미 구조와 운영 원칙을 구체적으로 고민하고 있었다. 8월에는 그 구조를 개인 지식 위키인 bono-wiki에도 옮겼다.

LLM Wiki는 AI가 읽을 것을 전제로 정리해 두는 내 문서 묶음이다. 여기서는 LLM Wiki를 새로 정의하지 않는다. 직접 만들게 된 이유와 써보며 바뀐 생각을 정리한다.

“LLM Wiki의 목적은 AI의 기억이 아니라, 내가 맥락을 소유하는 것이다.”

1. LLM Wiki가 필요했던 이유

같은 배경을 반복해서 설명하는 문제는 AI의 지능이 아니라 맥락을 관리하는 방식에서 나온다. 이 장에서는 내가 겪은 문제 4가지와, 대신 만들고 싶었던 상태를 정리한다.

처음에는 내가 맥락을 잘 넣어 주면 해결될 거라 생각했다. 새 세션을 열 때마다 같은 배경과 기준을 다시 설명하면서 생각이 달라졌다. 설명을 잘 복사한다고 맥락까지 관리되는 건 아니었다.

여러 작업을 오가다 보니 과거 선택의 이유부터 흐려졌다. 결과는 남았지만 왜 그 방법을 골랐는지, 검토한 대안을 왜 버렸는지는 찾기 어려웠다. 필요한 정보는 문서, 대화, 코드, 메모에 흩어져 있었다.

당시 기록을 다시 보니 dev-wiki를 만든 이유는 4가지로 정리된다.

반복되던 문제	만들고 싶었던 상태
새 세션마다 같은 배경을 설명함	한 번 정리한 맥락을 다시 사용함
결과는 있지만 선택의 이유가 사라짐	결정과 근거를 함께 보존함
AI 도구마다 기준을 다시 설정함	어떤 도구도 같은 원본을 참고함
내가 계속 옆에서 방향을 알려줘야 함	필요한 문서를 스스로 찾아 작업을 이어감

표의 마지막 줄이 가장 중요했다. AI에게 모든 판단을 넘기고 싶었던 게 아니다. 내가 원한 건 매번 자료의 위치와 배경부터 설명하지 않아도 되는 환경이었다.

2. 채팅 기록과 AI 메모리가 지식 시스템이 아닌 이유

채팅 기록과 AI 메모리로도 기록은 남는다. 다만 둘 다 지금 믿어도 되는 결론이 무엇인지는 알려주지 않는다.

“그냥 예전 채팅을 검색하면 되지 않을까?”라고 생각할 수 있다. 나도 처음에는 그렇게 썼다.

한 대화 안에는 최종 결정, 폐기한 아이디어, 잘못된 추측이 함께 들어 있다. 검색으로 문장을 다시 찾아도 지금 믿어도 되는 결론은 다시 판단해야 한다.

AI의 자동 메모리도 비슷하다. 자동 메모리는 대화 중에 알게 된 내용을 AI가 알아서 저장해 두는 기능이다. 편하지만 무엇이 저장됐는지, 어느 시점의 내용인지, 다른 도구에서도 그대로 쓸 수 있는지를 사람이 완전히 통제하기 어렵다. 모델이나 서비스를 바꾸면 같은 맥락을 처음부터 다시 넣어야 한다.

토스 기술 블로그는 코드에는 결과가 남아도 그 결정의 이유는 빠질 수 있다고 설명한다. 신뢰할 수 있는 컨텍스트를 다룬 글은 검색만으로는 충분하지 않으며 출처, 최신성, 정보의 충돌까지 관리해야 한다고 짚는다.

우아한형제들의 업무 메모 실험도 비슷한 문제를 다룬다. 기록이 쌓일수록 필요한 맥락을 찾기 어려워졌고, 범위가 커지자 사람이 자료를 계속 넣어 주는 일이 다시 병목이 됐다.

채팅은 대화를 이어가는 공간이다. 위키는 현재의 결론을 관리하는 공간이다. 둘은 역할이 다르다.

RAG(Retrieval-Augmented Generation, 질문과 관련된 문서를 찾아 AI에게 주는 기술)를 붙여도 이 문제는 남는다.

LY의 RAG 기반 문의 봇 사례에서는 필요한 자료를 찾아 답하되, 답변이 부족하면 사람에게 넘긴다. 그렇더라도 어떤 문서를 믿을지와 언제 사람에게 넘길지는 별도 규칙으로 정해야 한다.

3. dev-wiki가 문서 창고 대신 읽는 순서인 이유

문서를 많이 모으는 것보다 필요한 문서까지 가는 길을 만드는 편이 낫다. AI가 훨씬 적은 분량을 읽고도 지금 기준으로 답하기 때문이다.

사람도 수백 개 문서를 전부 읽고 일을 시작하지 않는다. AI에게 전부 읽히면 시간과 토큰을 낭비한다. 토큰은 AI가 글을 읽고 쓸 때 세는 분량 단위라서, 많이 읽힐수록 비용과 대기 시간이 늘어난다. 오래된 문서까지 섞이면 AI는 지금 기준이 아닌 내용을 근거로 답한다.

그래서 dev-wiki에서는 문서의 양보다 라우팅, 곧 필요한 문서까지 가는 길을 먼저 만들었다. 아래는 AI가 위에서 아래로 따라 내려오며 필요한 문서만 여는 순서다.

CLAUDE.md / AGENTS.md   운영 규칙
          ↓
llms.txt / index.md     어디에 무엇이 있는지 안내
          ↓
프로젝트 허브           현재 상태와 다음 할 일
          ↓
decisions.md            결정과 그 이유
          ↓
필요한 상세 문서만 확인  근거, 설계, 문제 해결 기록

각 문서의 역할도 겹치지 않게 나눴다.

문서	남기는 것	남기지 않는 것
프로젝트 허브	현재 상태, 다음 할 일, 관련 문서 지도	긴 구현 설명
결정 로그	선택한 안, 이유, 기각한 대안	코드만 봐도 알 수 있는 사실
상세 문서	설계 근거, 반복되는 문제와 해결법	단발성 대화 전체
코드와 Git	실제 구현과 변경 이력	별도 문서에 중복 복사하지 않음

이 구조에서 역할은 둘로 나뉜다. 사람은 원본을 쓰고 중요한 판단을 내린다. AI는 관련 문서를 찾고, 초안을 정리하고, 링크나 누락을 검사한다.

자동 메모리에는 위키 내용을 통째로 복사하지 않았다. 원본 문서의 위치를 가리키는 포인터로만 사용했다. 포인터는 내용을 담지 않고 “그 내용은 이 문서에 있다”고 위치만 알려주는 짧은 메모다. 그래야 도구가 바뀌어도 맥락의 원본은 내게 남는다.

4. dev-wiki 원칙을 bono-wiki에 적용한 과정

dev-wiki에서 다듬은 구조를 bono-wiki로 옮겨 보고 얻은 교훈은 하나다. 문서 구조를 바꿀 때는 검사 도구도 같은 변경으로 다뤄야 한다.

순서를 먼저 정리해 둔다. bono-wiki에서 처음부터 새 운영 원칙을 만든 것이 아니다. dev-wiki를 쓰면서 v1에서 v2, v3로 고도화한 구조를 다른 위키에 이식해 본 것이다.

dev-wiki도 처음부터 완성된 시스템은 아니었다. 반복해서 같은 맥락을 설명하는 문제를 줄이려고 시작한 최소 구조가, 실제 사용을 거치며 프로젝트 허브와 결정 로그를 갖춘 라우팅 구조로 바뀌었다. 문서가 늘어난 뒤에는 어디에 무엇이 있는지만으로 부족했다.

문서 유형을 나누고, 파일명을 정리하고, 별칭을 보존하고, 링크와 고립 문서를 검사하는 규칙까지 붙었다. 별칭은 파일 이름을 바꿔도 예전 이름으로 계속 찾게 해 주는 이름이고, 고립 문서는 어디에서도 링크되지 않아 사실상 없는 것과 같은 문서다. 한 버전의 기능을 추가한 것이 아니라, AI가 읽는 순서와 사람이 유지하는 방법을 함께 다듬은 과정이었다.

2026년 8월 13일에는 그때까지 dev-wiki에서 검증한 허브·결정 로그·라우팅·린트 원칙을 bono-wiki에 적용했다. 린트는 규칙을 어긴 곳을 자동으로 찾아 주는 검사를 뜻한다. 이식 자체는 첫날 끝났지만, 실제로 쓰기 시작하자 원래 설계에 없던 규칙이 생겼다. 프로젝트 폴더 표준과 wiki-decision, wiki-lint 같은 작업 방식이 문서 수와 변경 압력에 맞춰 자연스럽게 추가됐다. 6일 뒤 blog 문서 29개를 유형별 폴더와 번호 체계로 재구성한 것도 같은 흐름이다.

그때 검사 도구의 한계가 드러났다. 기존 파일명을 aliases로 남겼지만, 위키를 점검하는 검사 스크립트 wiki_check.py는 별칭을 읽지 못했다. 재구성 직후 정상 문서 29개가 한꺼번에 깨진 링크와 고립 문서로 표시됐다. 검사 규칙에 별칭 읽기를 추가한 뒤에는, 별칭이 여러 개인 문서에서 일부만 읽는 문제가 이어서 나와 한 번 더 고쳤다.

이 일은 bono-wiki가 실패했다는 뜻이 아니다. dev-wiki를 고도화하며 얻은 원칙을 실제 규모의 다른 위키에 옮겼을 때, 문서 구조와 검사 도구가 서로 다른 버전에 머물러 있으면 품질 도구가 오히려 거짓말을 한다는 사실을 확인한 것이다.

그래서 지금의 목표는 문서가 한 번도 낡지 않는 위키가 아니다. 구조가 바뀌었을 때 무엇이 낡았는지 빨리 발견하고, 사람의 판단으로 고칠 수 있는 위키다. bono-wiki는 dev-wiki의 결과물을 복사한 곳이 아니라, dev-wiki에서 쌓은 운영 원칙을 다른 맥락에서 다시 검증하는 실험장이 됐다.

토스의 지식 거버넌스 글도 AI로 문서를 더 빨리 만들수록 중복되고 낡은 문서가 더 빨리 쌓일 수 있다고 지적한다. 무엇을 믿을지, 갱신할 시점과 버릴 대상을 정하는 기준이 자동 생성보다 먼저라는 뜻이다.

이 글을 준비한 과정도 같은 구조를 따랐다. 전체 bono-wiki를 처음부터 읽지 않았다. 블로그 허브에서 관련 작업 노트로 이동해 dev-wiki 설계와 적용 회고만 확인한 뒤 초안을 만들었다. 마지막에는 다시 허브와 작업 로그에 연결했다.

9월 6일 보완, 읽는 순서와 완료 확인을 함께 남겼다

위키를 참조하라고 해도 에이전트마다 일부 단계를 건너뛰는 문제가 남았다. 그래서 공통 운영 규칙은 AGENTS.md에 모으고, CLAUDE.md와 index.md에서는 그 원본으로 안내하도록 정리했다. 프로젝트 허브에는 현재 전략과 공통 작업 절차를 연결했다.

작업 기록에는 대상, 진행 상태, 검사 근거, 다음 행동을 남긴다. 글이 저장됐는지에 더해 공개 페이지와 사이트맵에 실제로 반영됐는지도 확인한다. 이 경로를 거치는 도구에서는 누락을 검사할 수 있지만, 모든 AI가 파일 이름만 보고 같은 절차를 자동으로 읽는 것은 아니다. 사용 중인 도구가 어떤 지침 파일을 읽는지 확인하고 시작 문서를 명시해야 한다.

5. 4개의 파일로 LLM Wiki 만드는 방법

파일 4개만 있으면 오늘 바로 LLM Wiki를 시작할 수 있다. 자료를 검색용으로 따로 저장하는 벡터 데이터베이스나, 문서를 자동으로 모아 처리하는 파이프라인은 처음에 필요하지 않다.

프로젝트 하나를 골라 아래 4개의 파일을 만든다. 파일 이름 옆의 설명이 그 파일에 적을 내용이다.

my-wiki/
├── CLAUDE.md           # AI가 지킬 운영 규칙
├── index.md            # 현재 상태와 문서 지도
├── current-status.md   # 지금 하는 일과 다음 할 일
└── decisions.md        # 중요한 결정과 그 이유

무엇을 적어야 할지 헷갈리면 2가지만 묻는다.

1. 앞으로 다시 설명할 가능성이 있는가?
2. 다음 작업이나 판단에 영향을 주는가?

둘 중 하나라도 맞으면 기록할 가치가 있다. 코드나 원본에서 바로 확인되는 내용, 한 번 쓰고 버릴 대화까지 모두 옮길 필요는 없다.

다만 안전 문제는 별개다. 파일이 내 컴퓨터에 있다는 사실만으로 AI 처리까지 로컬에서 이뤄지는 것은 아니다. AI가 읽는 자료에는 회사나 고객의 정보, 개인정보, 인증정보, 내부 주소처럼 외부 처리나 공개가 허용되지 않은 내용을 넣지 않아야 한다. 조직의 정책을 먼저 확인하는 것이 순서다. 공개 가능한 자료나 가상 예시처럼 필요한 맥락만 최소한으로 남겨야 안전하다.

자주 묻는 질문

Obsidian에 문서를 모으면 LLM Wiki가 되나요?

아니요, 문서를 모으는 것만으로는 부족하다. Obsidian은 좋은 저장 도구지만 어디부터 읽을지와 무엇을 최신 기준으로 볼지 정하는 규칙은 별도로 필요하다. 앱보다 index, 결정 로그, 갱신 절차가 핵심이다.

AI 자동 메모리를 잘 쓰면 충분하지 않나요?

정보의 종류에 따라 다르다. 개인 취향이나 짧은 선호를 기억시키는 데는 자동 메모리가 편하다. 다만 프로젝트 결정처럼 출처와 변경 이력을 확인해야 하는 정보는 사람이 읽고 고칠 수 있는 원본 문서에 두는 편이 낫다.

문서를 많이 만들수록 좋은가요?

아니요, 문서의 개수는 기준이 아니다. 다시 쓸 맥락과 판단 근거만 남기고 현재 기준이 아닌 문서는 갱신하거나 분리해야 한다. 많은 문서보다 믿을 수 있는 적은 문서가 낫다.

정리

• LLM Wiki는 AI의 부족한 지능을 보충하는 장치가 아니라 내 맥락을 내가 소유하는 구조다.
• dev-wiki는 반복 설명, 사라지는 결정 이유, 도구별 설정 반복을 줄이기 위해 시작했다.
• 핵심은 문서 저장이 아니라 운영 규칙 → 인덱스 → 허브 → 필요한 원문으로 이어지는 읽기 순서다.
• 사람은 원본과 판단을 맡는다. AI는 탐색, 정리, 검사를 보조하는 편이 안전하다.
• 시작은 거창할 필요 없다. 프로젝트 하나와 4개의 파일이면 충분하다.

“LLM Wiki의 목적은 AI의 기억이 아니라, 내가 맥락을 소유하는 것이다.”

다음 글에서는 Obsidian과 Claude Code를 기준으로 이 4개의 파일을 실제로 만들고 새 세션이 필요한 문서만 찾아 읽게 하는 최소 구성을 정리해 보려 한다.

직접 AI용 위키를 운영하고 있다면 어떤 정보는 남기고 어떤 정보는 빼는지 경험을 댓글로 알려주시면 좋겠다.

검증 기준

• 마지막 업데이트일: 2026-09-06
• 확인 환경: 2026-09-06 bono-wiki의 AGENTS.md·CLAUDE.md·프로젝트 허브·공통 절차·작업 기록 도구를 직접 대조. 과거 dev-wiki 구축 시점과 이식 경험은 기존 작성 기록을 유지했다.
• 주요 근거: Claude Code 메모리와 지침 파일