최근 개인 프로젝트를 진행하면서 Claude Code, Codex, ChatGPT 등 여러 AI 도구를 함께 사용하고 있다.
도구마다 강점이 다르다 보니 상황에 맞춰 사용하고 있는데, 프로젝트가 늘어나면서 조금씩 번거로운 문제가 생기기 시작했다.
AI마다 알고 있는 프로젝트의 맥락이 다르다는 것이다.
어떤 세션에서는 이미 해결한 문제를 다른 세션에서는 처음부터 다시 설명해야 했다. 이전에 합의했던 설계 원칙을 모르는 AI가 기존 코드와 다른 방식으로 구현하거나, 오래된 문서를 기준으로 현재 상태를 설명하는 일도 있었다.
처음에는 프롬프트나 인수인계 문서를 조금 더 잘 작성하면 해결할 수 있을 거라고 생각했다.
그런데 여러 프로젝트를 오가다 보니 단순히 설명을 잘하는 문제는 아니라는 생각이 들었다.
결국 AI가 바뀔 때마다 맥락을 다시 전달하는 것이 아니라, AI들이 공통으로 참조할 수 있는 지식을 별도로 관리하는 편이 낫지 않을까?
이런 생각으로 로컬 기반의 개인 Wiki를 구축하기 시작했다.
이번 글은 그 과정에서 어떤 기술을 선택했고, 실제로 효과가 있었는지, 그리고 예상하지 못했던 어떤 문제가 발견됐는지를 정리한 기록이다.
1. AI가 기억하는 내용은 어디까지 믿을 수 있을까?
여러 AI를 함께 사용하는 과정에서 기억에 남는 사례가 있다.
기존에 Tailwind를 사용하던 프로젝트의 메인 페이지를 새로 구현하도록 AI에 요청한 적이 있었다.
Figma 디자인과 애니메이션 요구사항을 전달했는데, 결과물을 확인해 보니 기존 프로젝트와 다르게 styled-components를 사용하고 있었다.
당장 화면을 구현하는 데 문제가 있는 것은 아니었다.
다만 프로젝트의 다른 컴포넌트와 스타일링 방식이 달라지면 이후 코드를 수정하거나 재사용할 때 불필요하게 복잡해질 수 있다고 판단했다.
결국 기존 Tailwind 방식으로 다시 정리하고, Tailwind만으로 표현하기 어려운 애니메이션은 별도의 CSS 클래스로 처리했다.
이후에는 AI가 코드를 수정하거나 생성하기 전에 비슷한 역할의 기존 컴포넌트와 페이지를 먼저 살펴보도록 작업 지침을 보완했다.
이 경험에서 중요했던 것은 특정 CSS 기술의 우열이 아니었다.
AI가 현재 작업에 집중하는 동안 프로젝트 전체에서 지켜야 할 원칙을 놓칠 수 있다는 점이었다.
그 원칙이 다른 AI 세션에 전달되지 않는다면 비슷한 문제가 반복될 수도 있었다.
서로 다른 프로젝트가 같은 정보를 공유해야 한다면?
개인적으로는 오래전부터 구상해 온 하나의 창작 세계관을 소설과 게임이라는 서로 다른 매체로 확장하는 작업도 진행하고 있다.
두 프로젝트는 공통 설정을 공유하지만, 매체의 특성에 따라 일부 표현이나 구현 방식은 달라질 수 있다.
여기서도 비슷한 고민이 생겼다.
어떤 설정이 공식적으로 확정된 내용인지, 아직 아이디어 단계인지, 특정 매체에서만 적용하는 각색인지 구분할 필요가 있었다.
이를 여러 AI 세션에 나누어 전달하면서 작업한다면 이전 결정이 누락되거나 서로 다른 설정을 기준으로 결과물이 만들어질 위험이 있다.
소프트웨어 프로젝트에서도 같은 구조의 문제가 나타난다.
공통으로 유지해야 하는 규칙이 있고, 프로젝트마다 다른 구현이 있으며, 시간이 지나면서 기존 결정이 변경되기도 한다.
그렇다면 필요한 것은 단순히 긴 인수인계 문서가 아니라, 확정된 정보와 프로젝트별 해석, 변경의 역사를 구분해 관리하는 지식 기반이라고 생각했다.
2. 처음부터 거대한 RAG 시스템을 만들 필요는 없었다
개발자 커뮤니티에서 개인 로컬 Wiki를 구축하고 여러 AI 도구와 연동해 활용한다는 사례를 접했다.
마침 내가 겪고 있던 문제와도 연결되는 부분이 많았다.
다만 처음부터 모든 과거 대화를 수집하거나, 로컬 LLM과 벡터 데이터베이스를 붙여 거대한 지식 시스템을 만들 생각은 없었다.
과거의 모든 기록을 완벽하게 복원하는 것은 작업 범위도 너무 컸고, 무엇보다 그 과정에서 잘못된 정보를 확정된 사실로 가져올 위험도 있었다.
그래서 이번에는 현재를 기준점으로 삼기로 했다.
주요 프로젝트의 현재 상태와 최근에 확정한 결정만 먼저 정리하고, 이후 발생하는 활동과 판단을 지속적으로 기록하는 방식이다.
초기에 정한 요구사항은 비교적 단순했다.
- 프로젝트별 현재 상태와 의사결정 이력을 구분한다.
- 중요한 지식에는 출처와 확인 시점을 남긴다.
- AI가 제안한 내용과 승인된 내용을 구분한다.
- Claude Code 외의 다른 AI도 접근할 수 있어야 한다.
- 매번 전체 문서를 읽히는 대신 필요한 정보만 조회한다.
특히 이번 Wiki는 별도의 판매용 제품이 아니라 내 개발 환경을 지원하는 내부 인프라다.
따라서 기능을 많이 넣는 것보다 실제로 유지하고 사용할 수 있는 구조를 만드는 데 집중했다.
3. Markdown, SQLite, MCP로 시작한 구조
초기 구현에서는 Markdown과 Git을 지식 원본으로 사용하고, Node.js 내장 SQLite를 검색 색인에 활용했다.
Wiki에 저장할 데이터는 출처가 다른 여러 종류의 지식이다.
프로젝트 현황, 설계 결정, 테스트 결과, 문서, 현재 유효한 사실, 과거에 사용했던 표현 등이 포함된다.
이 정보를 AI가 동일한 방식으로 소비할 수 있도록 CLI를 만들고 MCP 서버를 연결했다.
현재 구현된 주요 기능은 다음과 같다.
기능역할
| hw validate | 지식 구조와 승인 상태 등의 유효성 검사 |
| hw search | 지식 검색 |
| hw show | 문서 원문 조회 |
| hw timeline | 시간순 변경 기록 |
| hw brief | 프로젝트별 현재 상태와 주요 맥락 요약 |
| hw ingest | 지원 대장 등 기존 데이터 가져오기 |
| MCP 서버 | 외부 AI 세션에서 Wiki 기능 호출 |
| 정적 HTML 뷰 | 프로젝트 허브, 검색, 타임라인, 관계 그래프 |
웹 화면은 현재 탐색을 위한 정적 스냅샷 형태다.
문서를 직접 편집하는 기능까지 웹에 구현하지는 않았다. 데이터 수정과 검증, 승인 기능은 기존 파일과 CLI를 중심으로 관리한다.
이렇게 하면 편집 UI를 위해 별도의 상태 동기화 구조를 추가하지 않아도 된다.
한국어 검색은 어떻게 처리할까?
초기에는 검색 방식부터 비교했다.
실제 문서 177개와 검색 질의 30개를 이용해 네 가지 검색 방식을 시험했다.
그 결과, 공백을 제거한 문자열에 trigram 검색을 적용하고 두 글자 이하의 질의에는 LIKE를 사용하는 방식이 준비한 평가 세트에서 가장 좋은 재현율을 기록했다.
평가 항목결과
| 평가 문서 | 177개 |
| 질의 | 30개 |
| 비교한 검색 방식 | 4가지 |
| 기본 방식 재현율 | 81.5% |
| 선택한 방식 재현율 | 100% |
기본 방식에서는 조사가 붙은 검색어를 놓치는 문제가 있었다.
물론 여기서 재현율 100%라는 것은 평가에 사용한 30개 질의에서 원하는 결과를 찾았다는 뜻이지, 모든 한국어 검색이 완벽하다는 의미는 아니다.
하지만 현재 문서 규모와 사용 목적에서는 더 복잡한 검색 시스템을 당장 도입할 이유가 충분하지 않았다.
그래서 벡터 검색과 로컬 LLM 기반 의미 검색은 일단 보류했다.
기능을 추가할 수 있다는 이유만으로 추가하지 않기로 했다.
4. 검색보다 먼저 해결해야 했던 문제: 무엇을 사실로 볼 것인가?
초기 데이터를 정리하는 과정에서 예상보다 많은 불일치를 발견했다.
그중 일부는 실제 오류였지만, 일부는 서로 다른 목적의 문서에서 발생한 정상적인 차이였다.
예를 들어 하나의 경험이라도 작성 목적에 따라 강조하는 부분이 달라질 수 있다.
기술적인 의사결정을 설명하는 문서에서는 구현 과정이 중요하지만, 외부에 제출하는 소개 자료에서는 해당 경험이 어떤 문제를 해결했는지가 더 중요할 수 있다.
따라서 특정 문서에 정보가 빠져 있다는 이유만으로 모순이라고 판단해서는 안 된다.
반대로 과거에 작성한 문서에 잘못된 내용이 존재할 수도 있다.
그 문서가 실제로 사용됐다는 사실과, 문서에 적힌 내용이 현재도 정확하다는 사실은 서로 다르다.
이 문제를 해결하기 위해 데이터를 세 가지 개념으로 분리했다.
Canonical Facts
현재 확인된 기준 사실이다.
실제 프로젝트의 구현 내용이나 사용자가 확인한 경력 사실처럼, 다른 문서를 작성할 때 기준으로 삼을 정보가 여기에 해당한다.
Contextual Representations
목적이나 대상에 맞게 기준 정보를 선별하고 표현한 결과다.
특정 프로젝트의 소개 문서나 외부 제출 자료처럼 같은 사실을 서로 다른 관점에서 설명할 수 있다.
Historical Snapshots
특정 시점에 실제로 사용했던 문서의 원본이다.
이후 오류가 발견되더라도 해당 문서를 과거에 사용했다는 기록까지 변경하지 않는다.
대신 현재 확인된 사실과 정정 기록을 연결한다.
이 구분은 단순한 문서 정리를 넘어, AI가 서로 다른 출처를 읽었을 때 무엇을 기준으로 판단해야 하는지를 정의하는 데 필요했다.
5. AI의 잘못된 분석이 다른 AI에게 전달된 사례
Wiki 설계 과정에서 실제로 흥미로운 문제가 발생했다.
Claude Code가 기존 자료를 분석하면서 회사 이름의 식별자가 일관되지 않다고 보고했다.
나는 그 분석을 다른 AI에게 전달했고, 다른 AI도 이를 데이터 모델의 문제로 받아들였다.
그런데 이후 실제 필드를 다시 검토해 보니 최초 판단이 잘못됐다는 사실이 드러났다.
표시용 이름과 이미 정규화된 식별자를 혼동한 것이었다.
실제로 개선해야 할 부분은 다른 데이터 목록에 식별자가 누락되어 있거나, 서로 다른 플랫폼의 동일한 항목을 연결하지 못하는 문제였다.
결과적으로 AI의 잘못된 최초 분석이 다른 AI의 판단 근거로 전달된 것이다.
이 과정을 보면서 단순히 출처를 저장하는 것만으로는 부족하다는 생각이 들었다.
어떤 결론이 왜 만들어졌고, 무엇을 근거로 수정됐는지도 추적할 수 있어야 했다.
그래서 기존의 잘못된 판단을 조용히 덮어쓰기보다 정정 이벤트로 남겼다.
이후에는 지식의 승인 상태도 별도로 검증하도록 했다.
실제로 첫 검증에서는 승인 기록 없이 확정 상태로 표시된 노트 등 여러 위반 사항이 발견됐다.
검증기가 이를 찾아내면서 데이터 구조를 바로잡을 수 있었다.
이번 작업에서 가장 의미 있었던 경험 중 하나는, Wiki를 구축하는 과정에서 발생한 오류 자체가 Wiki에 기록할 첫 번째 지식이 되었다는 점이다.
6. 실제 A/B 테스트: Wiki가 토큰을 줄여줄까?
기능이 어느 정도 갖춰진 뒤에는 원천 문서를 직접 읽는 방법과 Wiki를 사용하는 방법을 비교했다.
시험에는 별도의 Claude Code 서브에이전트를 활용했다.
질문과 정답 기준은 실험 전에 파일로 등록했다.
평가 조건은 다음과 같다.
조건 A — 원천 문서 직접 조회
기존 프로젝트 저장소와 관련 문서, 기록 파일을 직접 탐색한 뒤 질문에 답한다.
조건 B — Wiki 조회
Wiki CLI를 통해 필요한 정보를 조회하고 질문에 답한다.
두 조건에 동일한 13개 질문을 제공했다.
질문은 현재 프로젝트 상태, 과거 결정, 판단 근거, 기록의 기준일, 다른 프로젝트에서 사용한 해결 방식 등으로 구성했다.
기록에 없는 사실을 질문해 AI가 내용을 임의로 만들어내는지도 확인했다.
결과
평가 항목A: 원천 문서B: Wiki
| 정확한 답변 | 10 | 13 |
| 부분 정답 | 3 | 0 |
| 지어낸 답변으로 분류된 건수 | 0 | 0 |
| 동일 원천으로 답변 가능한 9문항 | 9/9 | 9/9 |
| 사용 토큰 | 235,242 | 101,097 |
| A 대비 토큰 사용량 | 100% | 43% |
이번 평가에서는 Wiki를 사용한 조건 B가 원천 문서 방식보다 약 57% 적은 토큰을 사용했다.
정확한 답변 수도 B가 더 많았다.
하지만 이를 곧바로 Wiki의 검색 방식이 더 정확하다는 의미로 해석할 수는 없었다.
전체 13개 질문 중 일부는 Wiki에만 반영된 최신 사용자 정정 정보를 필요로 했다.
반면 두 조건이 모두 접근할 수 있는 원천 정보만 필요한 9개 질문에서는 A와 B가 모두 정답을 기록했다.
따라서 이번 시험에서 확인한 성과는 동일한 정보로 답변할 수 있는 질문에서 정확도를 유지하면서 전체 토큰 사용량을 줄였다는 것에 가깝다.
또한 처음 설정했던 목표는 원천 문서 방식 대비 20% 이하의 토큰 사용량이었다.
실제 결과는 43%였으므로 목표를 달성하지 못했다.
이후 현실적인 다음 목표를 35% 이하로 조정했다. 아직 그 수치를 달성한 것은 아니다.
실험의 한계
이번 평가에서 답변은 완전히 블라인드로 채점하지 못했다.
근거에 문서 경로나 Wiki의 ID가 포함되어 있어 어느 조건의 답변인지 구분할 수 있었기 때문이다.
또한 사용한 질문은 13개에 불과하며, 평가에 활용한 문서와 질문도 현재 프로젝트에 맞춰져 있다.
따라서 이번 결과를 다른 프로젝트나 모든 AI 작업에 일반화하기는 어렵다.
다만 초기 시스템의 문제를 찾기 위한 실험으로서는 충분히 유용했다.
7. Wiki가 항상 더 좋은 답을 주는 것은 아니었다
A/B 평가에서 가장 흥미로웠던 부분은 전체 점수보다 개별 질문의 차이였다.
사례 A: 과거 문서의 잘못된 내용을 현재 사실로 받아들임
조건 A는 과거에 사용했던 문서를 읽으면서, 이후 정정된 정보를 반영하지 못한 사례가 있었다.
반면 조건 B는 기준 사실과 과거 문서를 구분해 관리하고 있어 올바른 정보를 선택했다.
이는 검색 결과에 출처가 있다는 사실만으로 그 내용이 신뢰할 만하다고 판단해서는 안 된다는 것을 보여준다.
문서를 정확하게 찾는 것과 그 문서의 내용을 현재의 사실로 채택하는 것은 다른 문제다.
사례 B: Wiki의 요약이 최신 기록을 놓침
반대로 조건 A가 더 잘 답한 질문도 있었다.
운영 중인 개인 프로젝트의 최근 기록에 미완료된 자동화 작업이 남아 있었는데, Wiki의 프로젝트 브리프에는 해당 최신 기록이 충분히 반영되지 않았다.
원문을 직접 읽은 A는 미완료 상태를 확인했다.
하지만 B는 요약된 프로젝트 상태를 참고하면서 일부 정보를 추론에 의존했다.
이 사례는 Wiki가 오래된 요약을 전달하면 최신 원문보다 불리해질 수 있다는 문제를 보여줬다.
이를 개선하기 위해 브리프에서 최근 갱신 문서를 함께 표시하도록 수정했다.
프로젝트의 현재 상태를 요약하더라도, 그 요약보다 최신인 기록이 존재한다면 AI가 이를 확인할 수 있어야 한다고 판단했기 때문이다.
8. 프로젝트마다 흩어진 지식을 연결하기 시작했다
A/B 평가 중 특정 질문에서 Wiki 조건이 같은 주제의 자료를 여러 번 검색하는 문제가 있었다.
원인을 살펴보니 중복 요청 방지와 관련된 기술적 판단이 여러 프로젝트에 흩어져 있었다.
프로젝트별 문서는 존재했지만 공통으로 재사용할 지식은 별도로 정리되어 있지 않았던 것이다.
그래서 관련 프로젝트에서 출처가 확인된 내용을 모아 하나의 공통 지식 노트를 작성했다.
다만 AI가 작성한 노트이므로 처음에는 승인 대기 상태로 남겼다.
이 과정에서 처음 구상했던 Wiki의 또 다른 목적이 드러났다.
프로젝트마다 별도의 기록을 남기는 것에서 그치지 않고, 여러 프로젝트에서 반복된 문제와 해결 경험을 연결해 재사용할 수 있어야 한다는 것이다.
아직 실제 개발 과정에서 재사용 효과가 얼마나 있는지는 확인하지 못했다.
하지만 적어도 검색 과정에서 발견한 비효율을 데이터 구조의 개선으로 연결하는 첫 사례가 되었다.
9. 지금까지 구현한 것과 앞으로 필요한 것
현재는 로컬 Wiki를 구축하고 MCP 연동까지 완료했다.
검색, 현재 상태 조회, 의사결정 히스토리, 출처 추적, 지식 제안과 승인, 그래프 탐색 등을 사용할 수 있다.
하지만 다른 AI 세션에서 작업한 내용이 아무런 개입 없이 자동으로 수집되고 학습되는 시스템은 아직 아니다.
현재 구현한 것은 여러 AI가 공통 지식을 조회하고, 새로운 지식을 제안할 수 있는 기반이다.
다음에는 개발 과정에서 발생한 중요한 결정과 구현 결과를 어떻게 수집할지 검토하려 한다.
그렇다고 모든 채팅 메시지를 무조건 저장하고 싶지는 않다.
개발 과정에서는 검토하다가 폐기한 아이디어도 있고, AI가 잘못 이해한 내용도 있고, 아직 검증하지 않은 추론도 나온다.
이것들이 모두 공식 지식으로 확정된다면 오히려 정보의 품질이 떨어질 수 있다.
따라서 자동 수집을 구현하더라도 수집, 제안, 검증, 승인 과정을 구분하는 원칙은 유지할 생각이다.
또한 현재 검색에서 해결되지 않는 문제가 확인되지 않은 이상 의미 검색이나 벡터 데이터베이스를 무리하게 추가하지는 않으려 한다.
10. 마무리하며
이번 작업은 원래 여러 AI에게 같은 맥락을 반복해서 설명하는 것이 번거로워서 시작했다.
그런데 실제로 자료를 정리하고 비교 실험까지 해보니 생각보다 해결해야 할 문제가 많았다.
AI가 이전 결정을 기억하지 못하는 것도 문제였지만, 잘못된 내용을 현재 사실로 받아들이거나 서로 다른 목적의 자료를 같은 기준으로 해석하는 것도 문제였다.
그리고 Wiki를 구축한다고 이런 문제가 자동으로 사라지는 것은 아니었다.
요약된 정보가 오래되면 최신 기록을 놓칠 수 있고, 출처가 있는 문서라도 사실이 잘못되어 있을 수 있었다.
그래서 이번 프로젝트에서 중요하게 생각하게 된 것은 검색 자체보다도 어떤 지식을 신뢰하고, 어떤 판단을 변경했으며, 그 근거가 어디에 있는지 추적할 수 있는 구조였다.
이번 초기 평가에서는 Wiki 사용 조건이 원문 직접 조회보다 약 57% 적은 토큰을 사용했다.
다만 실험 규모가 작고, 데이터 최신성에 차이가 있었으며, 처음 목표했던 토큰 사용량에도 미치지 못했다.
그럼에도 개인적으로는 만족스러운 출발이었다.
이제는 새로운 AI 세션을 시작할 때마다 내가 무엇을 했고 왜 그렇게 결정했는지 다시 설명하는 대신, 그 정보를 참조할 수 있는 기반이 생겼기 때문이다.
앞으로 개발하는 제품들이 원하는 성과를 내지 못하거나 중간에 방향을 바꾸더라도, 그 과정에서 얻은 판단과 검증 결과까지 사라지지는 않았으면 한다.
AI가 나를 얼마나 오래 기억하느냐보다, AI가 참고할 지식을 내가 얼마나 정확하게 관리할 수 있느냐.
지금은 그쪽이 더 중요한 문제처럼 느껴진다.
앞으로 실제 개발과 창작 작업에서 사용하면서 발견하는 문제들도 계속 기록해 볼 생각이다.
2026년 10월 25일 개인 개발 환경에서 진행한 초기 구현과 평가를 바탕으로 작성했습니다. 본문의 성능 수치는 제한된 평가 조건에서 얻은 결과이며, 다른 환경에서의 성능이나 지속적인 생산성 개선을 보장하지 않습니다.
'AI, LLM' 카테고리의 다른 글
| 로컬 LLM을 붙여봤다가, 안 쓰기로 했다 (0) | 2026.09.30 |
|---|
