Wikis for Agents

제 레포에는 openwiki/ 디렉터리가 있습니다. 그 안의 마크다운 위키는 사람보다 에이전트가 더 자주 읽습니다. 읽는 쪽이 바뀌었을 뿐인데, 예전 같으면 미뤘을 문서 정리에 요즘은 공을 들이고 있습니다.

위키는 이렇게 죽습니다

검색으로 찾은 문서가 지금 코드와 다르면, 문서를 바로잡는 사람은 드뭅니다. 대부분은 그 문서를 믿지 않고 넘어갑니다. 신뢰는 한 번 무너지면 좀처럼 돌아오지 않습니다. 아무도 읽지 않는 위키는 아무도 고치지 않고, 그렇게 위키는 조용히 죽습니다.

『Software Engineering at Google』의 문서화 챕터는 이 악순환을 회사 차원에서 겪은 기록입니다. 초기 구글은 GooWiki라는 사내 위키에 문서를 모았는데, 주인 없는 문서는 그대로 낡아갔습니다. "문서를 고칠 수 있는 사람과 문서를 사용하는 사람이 달랐다"는 회고가 남아 있을 정도입니다. 구글이 찾은 답은 문서를 코드와 같은 저장소에 넣어 버전 관리하는 것이었습니다. g3doc이라는 프레임워크로 문서를 코드 옆에 두자, 변경 한 번으로 코드와 문서를 함께 고칠 수 있게 되었습니다.

위키가 죽는 이유를 게으름에서 찾으면 답이 나오지 않습니다. 이 책은 문서화가 왜 저평가되는지도 짚습니다. 문서를 쓴 덕은 한참 뒤에야, 그것도 대부분 쓴 사람이 아닌 다른 사람이 봅니다. 문서는 한 번 써 두면 수백 번 읽히지만, 쓰는 사람 눈에는 당장 드는 품만 보입니다. 남는 것이 없는 일이 계속될 리 없습니다.

이제 문서는 에이전트가 읽습니다

그런데 최근 들어 상황이 바뀌었습니다.

코딩 에이전트는 세션을 열 때마다 CLAUDE.md나 AGENTS.md 같은 문서를 읽습니다. AGENTS.md는 6만 개가 넘는 오픈소스 레포에서 사용하고 있습니다. Anthropic의 가이드도 CLAUDE.md를 "코드처럼 다루라"고 말합니다. 내용을 리뷰하고, 불필요한 내용을 주기적으로 지우고, 수정한 뒤에는 에이전트의 행동이 실제로 달라지는지 확인하라고 권합니다.

문서마다 관리할 사람을 정하고 리뷰를 거치게 한다는 점은 g3doc의 원칙과 같습니다. 이제는 에이전트가 읽는 문서에도 같은 원칙을 적용하는 것입니다.

쓰는 수고도 줄었습니다. Karpathy는 올해 4월 LLM이 유지하는 개인 위키 실험을 공유하면서, 지식 베이스 유지에서 힘든 것은 읽거나 생각하는 일이 아니라 장부 정리(bookkeeping)라고 짚었습니다. 문서 사이 링크를 갱신하고, 낡은 내용을 걷어내고, 수정 한 번에 파일 열다섯 개를 만지는 일이 그렇습니다. LLM은 이런 일을 지루해하지 않습니다.

이 아이디어는 곧 표준과 도구로 이어졌습니다. 6월에는 Google Cloud가 OKF(Open Knowledge Format) v0.1을 공개했습니다. YAML 프런트매터를 단 마크다운 파일 묶음으로 지식을 표현하는 스펙인데, SDK도 레지스트리도 없이 "플랫폼이 아니라 포맷"을 내세웁니다. 7월에는 LangChain이 openwiki를 내놓았습니다. 위키를 생성하는 데 그치지 않고 계속 유지하는 에이전트 CLI입니다. v0.2.0부터는 OKF를 그대로 채택했습니다.

저는 이 대목에서 영수증과 가계부를 떠올립니다. 질문이 생길 때마다 영수증 더미를 처음부터 다시 뒤지는 방법이 있습니다. 검색 기반 접근(RAG)이 하는 일이 대체로 이렇습니다. 가계부는 다릅니다. 한 번 정리해 두면 다음 질문부터는 장부를 펴면 되고, 새 영수증이 생기면 그 줄만 적어 넣으면 됩니다. "지식은 한 번 컴파일되고 이후에는 최신으로 유지된다"는 Karpathy의 말이 바로 이 이야기입니다.

물론 위키 정리는 가계부보다 손이 많이 갑니다. 숫자만 더하면 되는 가계부와 달리, 내용을 읽고 종합하고 판단해야 합니다. 그래도 한 가지는 똑같습니다. 손을 놓는 순간 빈 기록이 아니라 틀린 기록이 되어 갑니다. 위키는 만들고 나서부터가 진짜 일입니다.

레포 위키는 업데이트가 전부입니다

openwiki 코드 모드는 레포 안에 openwiki/ 디렉터리를 만들고 quickstart.md를 시작점으로 문서를 작성합니다. 여기까지는 다른 위키 생성기와 비슷합니다. 차이는 위키를 갱신할 때 드러납니다.

openwiki는 문서 생성이나 갱신에 성공하면 당시의 git HEAD를 openwiki/.last-update.json에 기록합니다. 다음에 실행할 때는 그 이후의 커밋만 읽고, 바뀐 소스가 어떤 문서에 영향을 주는지 확인해 수정 계획을 세웁니다. 프롬프트에도 이렇게 적혀 있습니다. "업데이트는 수술하듯 정밀해야 한다. 새 문단을 더하기보다 낡은 문장 하나를 바꾸는 쪽을 택하라." 바뀐 소스 파일이 다섯 개 미만이면 위키도 한두 페이지만 고치도록 제한하고, 변경이 없으면 수정하지 않습니다. CI에서 정기적으로 실행하도록 설정하면 갱신 내용을 PR로 받을 수 있습니다.

문서 구조는 OKF 형식을 따릅니다. 모든 페이지는 type, title, description, tags를 담은 YAML 프런트매터로 시작합니다. description은 에이전트가 필요한 문서를 검색할 수 있도록 작성합니다. 문서마다 개념 하나를 설명하고, 관련 개념을 다루는 문서에 링크를 겁니다. "A는 B에 디스패치한다", "C는 D를 통해 설정된다"처럼 관계를 설명하는 문장 안에 링크를 넣으면, 개념 사이의 관계와 그 근거를 함께 확인할 수 있습니다.

각 디렉터리의 index.md는 정해진 규칙으로 생성합니다. 항상 같은 결과가 나와야 하는 부분은 LLM에게 맡기지 않았습니다.

저는 CLI 대신 이 워크플로를 Claude Code 스킬로 포팅해서 씁니다. 코딩 에이전트에는 이미 LLM과 파일 도구가 있으므로, 원래 CLI가 프로바이더 API를 호출해 하던 일을 에이전트에게 직접 맡길 수 있습니다. 별도의 API 키나 런타임을 준비할 필요가 없습니다.

여러 레포에서 위키를 유지하다 보니, 코드만으로는 알 수 없는 내용을 남기는 일이 중요했습니다. 예를 들어 claude-codex-imagegen의 quickstart는 이 프로젝트를 왜 만들었는지부터 설명합니다. 저는 API 과금 대신 구독에 포함된 사용량을 쓰려고, 작업을 조율하는 구조가 복잡해지는 쪽을 택했습니다. 이런 선택의 이유는 코드에 없지만 위키에는 있습니다. 기록하지 않으면 나중에 에이전트가 소스를 다시 읽어도 알아낼 수 없습니다.

DeepWiki는 외부 서버에서 위키를 만들어 호스팅해 줍니다. 특정 시점의 코드를 정리한 스냅숏이라 낯선 레포를 처음 읽을 때는 유용하지만, 제 레포의 문서를 계속 관리하는 용도로 쓰기는 어렵습니다. openwiki로 만든 위키는 레포에 커밋하는 마크다운 파일입니다. git 이력이 남고, PR로 리뷰할 수 있으며, 에이전트가 로컬에서 바로 읽을 수 있습니다.

개인 위키는 흩어진 지식을 정리해 줍니다

정작 개인 지식은 레포 문서보다 더 엉망이었습니다. 읽을거리는 X 좋아요에 쌓였고, 클립과 번역은 블로그에 올라갔고, 정리한 노트는 Obsidian과 LLM이 관리하는 별도 위키에 흩어져 있었습니다. 저장소는 넷인데, 지금 제가 무엇을 하고 있고 무엇을 하기로 했는지 물으면 답해 주는 곳은 없었습니다.

openwiki 퍼스널 모드는 이렇게 흩어진 자료를 모아 정리합니다. ~/.openwiki/wiki에 위키를 만들고, 연결된 로컬 레포와 웹, 피드를 읽어 주제별로 기준이 되는 canonical 페이지에 내용을 정리합니다.

quickstart에는 현재 상태와 다른 문서를 찾을 수 있는 링크를 둡니다. themes에는 여러 자료에서 반복해서 나타나는 내용을 모으고, commitments에는 약속과 할 일을 적습니다. open-questions에는 아직 답을 모르는 질문을 남깁니다. 소스별 페이지에는 근거만 간결하게 남깁니다. 프롬프트는 이를 "소스 덤프가 아니라 종합 레이어"라고 부릅니다.

주장마다 근거의 확실성을 나타내는 confidence 라벨도 붙입니다. 여러 소스에서 교차 확인한 내용에는 confirmed를, 한 소스에서만 확인한 내용에는 source-backed를 붙입니다. 아직 근거가 약한 내용은 watchlist로 표시합니다. 에이전트가 위키를 근거로 답할 때 그 답을 얼마나 신뢰할 수 있는지도 확인할 수 있어 개인 위키에서 특히 유용합니다.

LangChain은 이 모드를 능동적(proactive) 메모리라고 소개합니다. 채팅 메모리는 제가 말해 준 것을 기억하지만, 위키는 제가 이미 일하고 있는 레포와 피드를 읽으며 스스로 배웁니다. 몇 주 써 보니 세션을 여는 순간부터 다릅니다. 지난주에 무엇을 하기로 했는지 제가 설명하는 대신, 에이전트가 위키를 읽고 이미 알고 있습니다.

처음부터 세워 둔 규칙이 하나 있습니다. 회사 일과 관련된 내용은 로컬 위키에만 남기고 어떤 외부 서비스로도 내보내지 않습니다. 위키에 무엇을 넣을지 못지않게, 넣은 것을 어디까지 내보낼지도 신경 써야 합니다.

관리 없이 생성한 문서는 성능을 깎습니다

ETH 취리히의 연구는 실제 파이썬 과제 138개로 컨텍스트 파일의 효과를 측정했습니다. LLM이 생성한 컨텍스트 파일을 사용하자 성공률은 약 3% 떨어지고 비용은 20% 넘게 올랐습니다. 사람이 쓴 파일도 개선 폭은 4% 남짓이었습니다.

DeepWiki가 있지도 않은 설치 방법을 사실처럼 안내해 프로젝트 관리자가 공개적으로 항의한 사례도 있습니다. openwiki의 HN 스레드에는 "LLM 위키의 품질 유지가 생각보다 훨씬 힘들다"는 증언이 쌓여 있습니다. 장황하고 낡은 문서는 에이전트 성능을 오히려 떨어뜨립니다.

다만 실패한 사례는 하나같이 사람 손을 거치지 않고 한 번에 만들어 낸 문서입니다. 리뷰도 없었고, 갱신 루프도 없었습니다. 위키가 소용없는 것이 아니라, 관리 없는 위키가 소용없습니다.

openwiki에서는 사람이 INSTRUCTIONS.md에 작업 방향을 적습니다. 에이전트는 코드의 변경 범위에 맞춰 문서를 조금씩 고치고, 사람은 그 결과를 PR로 리뷰합니다.

구글이 GooWiki에서 g3doc으로 옮기며 배운 원칙은 지금도 적용할 수 있습니다. 문서를 관리할 사람이 있고, 실제 작업 중에 읽으며, 변경할 때 리뷰를 거쳐야 합니다. 에이전트를 쓰더라도 이 원칙은 같습니다. 다만 문서를 읽고 갱신하는 수고를 줄일 수 있습니다.

문서 남기기는 오랫동안 미래의 동료를 위한 선의에 가까웠고, 그래서 늘 뒤로 밀렸습니다. 이제는 아닙니다. 오늘 위키에 적는 한 문단이 다음 에이전트 세션의 컨텍스트가 되고, 그 세션이 내놓는 결과물의 품질을 좌우합니다. 문서 관리는 이제 성능 엔지니어링입니다.