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는 결정적(deterministic) 규칙으로 찍어 냅니다. 흔들릴 이유가 없는 부분은 LLM에게 맡기지 않았습니다.

저는 CLI 대신 이 워크플로를 Claude Code 스킬로 포팅해서 씁니다. 코딩 에이전트는 그 자체로 LLM이고 파일 도구도 갖고 있으니, 업스트림이 프로바이더 API로 하던 일을 직접 시키면 API 키도 런타임도 필요 없습니다. 이렇게 여러 레포에서 위키를 유지하고 있는데, 돌아보면 위키에 남는 내용은 따로 있습니다. 예를 들어 claude-codex-imagegen의 quickstart는 이 프로젝트를 왜 만들었는지부터 설명합니다. 저는 API 과금 대신 구독에 포함된 사용량을 쓰려고, 오케스트레이션이 복잡해지는 쪽을 택했습니다. 이 트레이드오프는 코드 어디에도 적혀 있지 않지만 위키에는 있습니다. 이런 "왜"는 미래의 에이전트가 소스를 아무리 다시 뒤져도 알아낼 수 없습니다.

DeepWiki와 비교하면 이 차이가 더 또렷하게 보입니다. 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라는 브리프로 정하고, 에이전트는 diff 범위 안에서 조금씩만 고치고, 결과는 사람이 PR로 리뷰합니다. 구글이 GooWiki에서 g3doc으로 옮기며 배운 교훈은 지금도 그대로 통합니다. 주인이 있고, 일하는 길목에 놓여 있고, 리뷰를 거치는 문서만 살아남습니다. 에이전트는 그 원칙을 바꾸지 않았습니다. 원칙을 지키는 데 드는 품을 줄였을 뿐입니다.

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