이 글은 Claude Code 같은 AI 에이전트의 작업 맥락을 Obsidian 위키 하나에 모아 두고, 새 세션에서 다시 불러 쓰는 방법을 정리합니다. Andrej Karpathy가 공개한 LLM Wiki 패턴을 업무용으로 고친 것이고, 2026-08-20부터 2026-11-08까지 위키 문서 166개와 기록 140건이 쌓였습니다. 사용자가 무엇을 준비하고 어떻게 말하면 되는지를 중심으로, 그때 에이전트가 하는 일을 함께 설명합니다.

LLM Wiki란 무엇인가

LLM Wiki는 에이전트가 직접 정리하고 고쳐 나가는 마크다운 위키입니다. 문서를 올려 두고 질문할 때마다 관련 조각을 찾는 RAG 방식은 매번 처음부터 다시 찾습니다. LLM Wiki에서는 새 내용이 들어오면 에이전트가 기존 문서를 고치고, 충돌하는 내용을 표시해 둡니다. 사용자는 “기록해 줘”, “참조해 줘”라고 말하기만 하면 됩니다.

세션이 끊기면 에이전트는 앞에서 정한 것을 잊습니다. 위키에 결정과 실패 기록을 남겨 두면, 다음 세션은 처음부터 다시 설명받지 않고 위키를 읽고 이어서 일합니다. 다른 프로젝트의 세션이나 다른 에이전트도 같은 위키를 읽습니다.

위키 폴더는 세 칸으로 나뉩니다.

  • raw/ — 기사, 외부 문서, 대화 로그 같은 원문입니다. 사용자가 넣고, 에이전트는 읽기만 합니다.
  • wiki/ — 원문과 세션 결과를 정리한 결정, 실패 기록, 프로젝트 맥락입니다. 에이전트가 쓰고 고칩니다.
  • conversations/ — 아직 확정되지 않은 세션 인수인계입니다.

준비

위키 폴더를 Obsidian에서 vault로 열고, 위키 폴더 안에서 설치 스크립트를 한 번 실행합니다.

./scripts/install-global.sh

설치 스크립트는 Claude Code의 전역 설정에 짧은 안내 문서를 연결합니다. 안내 문서에는 “이런 말이 나오면 위키의 CLAUDE.md를 먼저 읽는다”는 내용만 있고, 실제 규칙은 위키 폴더의 CLAUDE.md 한 곳에만 있습니다. 그래서 어느 프로젝트 폴더에서 Claude Code를 켜도 위키를 부를 수 있습니다. 컴퓨터를 바꾸면 위키 저장소를 clone하고 이 스크립트를 다시 실행하면 됩니다.

준비가 끝나면 아무 프로젝트에서 “위키 참조”라고 말해 봅니다. 에이전트가 위키의 목차와 최근 기록을 읽고, 핵심 맥락과 열려 있는 일을 몇 줄로 알려 줍니다.

이렇게 말하면 된다

명령은 다섯 개이고, 한국어로 말하면 에이전트가 알아서 고릅니다. ‘위키’와 ‘옵시디언’은 같은 뜻으로 받습니다.

이렇게 말하면 에이전트가 하는 일
“위키 참조”, “이전 맥락 불러와” 목차와 최근 기록 10건을 읽고 맥락을 요약합니다. 아무것도 쓰지 않습니다
“위키에 기록해줘” 이번 세션 결과 중 남길 것을 골라 저장하고 커밋합니다
“raw를 위키로 올려줘” raw/의 원문을 읽어 정리하고 관련 문서에 반영합니다
“위키 기준으로 답해줘” 위키 문서를 근거로 답하고, 근거 문서 경로를 함께 보여 줍니다
“위키 점검해줘” 깨진 링크, 출처 없는 결정 같은 문제를 찾아 보고만 합니다

“위키 참조해서 결제 모듈 어떻게 하기로 했지”처럼 질문이 붙으면 질문에 답하는 쪽으로 갑니다. 저장은 사용자가 말할 때만 합니다. 에이전트가 알아서 위키에 쓰지 않으니, 세션을 마칠 때 남길 만한 결과가 있으면 “위키에 기록해줘”라고 말합니다.

저장이 끝나면 에이전트가 무엇을 만들거나 고쳤는지, 무엇을 저장하지 않았고 왜 그랬는지, 다음 세션이 먼저 읽을 문서는 무엇인지 알려 줍니다. 위키는 git 저장소라서 저장마다 커밋과 푸시까지 하고, 그 결과도 보고에 들어갑니다.

무엇이 저장되나

“기록해 줘”라고 해도 전부 저장되지는 않습니다. 에이전트는 저장하기 전에 다섯 가지를 확인하고, 하나도 해당하지 않으면 위키에 올리지 않습니다.

  1. 이후 반복해서 다시 쓸 정보인가?
  2. 다른 세션이나 동료가 이어받으려면 꼭 읽어야 하는가?
  3. 결정의 근거와 결정권자를 나중에 추적해야 하는가?
  4. 다시 시도하면 안 되는 실패 정보인가?
  5. 모두가 맞춰야 하는 공통 규칙인가?

일회성 답변, 중간 생각, 아직 승인하지 않은 제안, 근거 없는 추측은 위키에 올라가지 않습니다. 나중에 근거로 볼 값어치가 있으면 conversations/에만 남깁니다. 많이 저장할수록 다음 세션이 무엇이 중요한지 가려내기 어려워지기 때문입니다.

에이전트는 문서마다 확인한 정도도 적습니다. 직접 실행해 확인한 것, 사람이나 문서가 그렇다고 한 것, 추론한 것을 나눠 두고, 추론만 있는 문서는 확정 상태로 올리지 않습니다.

이 구분은 다른 세션이 쓴 내용을 확인할 때 쓸모가 있습니다. 2026-10-25에 실기기 테스트 도구 문서를 여러 세션이 나눠 기록한 뒤, 새 세션에 기록이 맞는지 확인을 맡겼습니다. 한 기능이 동작하지 않은 원인이 추측인 채로 적혀 있었고, 이슈 댓글의 기록으로 원인을 확정해 고쳤습니다. 끝까지 확인하지 못한 다른 줄은 “정황까지만”으로 낮춰 적었습니다.

여러 세션이 같이 쓸 때

여러 프로젝트의 세션이 동시에 위키에 기록해도 됩니다. 문서 파일은 주제마다 갈라져 있어서 부딪히지 않고, 모든 저장이 함께 고치는 목차(index.md)와 기록(log.md)은 에이전트가 잠금을 걸고 고칩니다. 잠금 없이 동시에 고쳤을 때는 실측으로 120건 중 77건이 사라졌고, 잠금을 건 뒤에는 0건이었습니다. 잠금 방식은 같은 아이디어를 먼저 구현한 oh-my-claudecode의 wiki 스킬에서 가져왔습니다.

커밋도 섞이지 않습니다. 에이전트는 이번 작업이 건드린 파일만 골라 커밋하고, 다른 세션이 남긴 변경은 따로 커밋하거나 그대로 둡니다. 에이전트 커밋은 작성자가 Claude (agent)로 남아서, 사람이 직접 고친 것과 구분해 볼 수 있습니다.

git log --author="Claude" --oneline   # 에이전트가 기록한 것

오래 쓰다 보면 점검도 사용자가 챙겨야 합니다. 저장은 세션마다 요청하게 되지만 점검은 따로 말하지 않으면 돌지 않습니다. 2026-11-08에 점검 스크립트를 돌리자 기계 점검에서 23건이 나왔습니다. 21건은 원문을 통째로 옮겨 왔을지 모르는 큰 문서이고, 2건은 어디서도 링크되지 않은 문서입니다. 큰 문서가 원문 복사인지, 정당하게 길어져 쪼갤 때가 된 것인지는 에이전트가 정하지 않고 사람이 읽고 판단합니다.

참고