OpenWiki: 저장소 문서화를 위한 오픈소스 에이전트
TMThttps://www.langchain.com/blog/introducing-openwiki-an-open-source-agent-for-repo-documentation
오늘 코드베이스 문서를 생성하고 유지 관리하는 오픈소스 에이전트이자 CLI인 OpenWiki를 공개합니다.
에이전트는 자신이 작업하는 저장소를 이해할 때 더 나은 코드를 작성합니다. 핵심 로직이 어디에 있는지, 파일들이 서로 어떻게 연결되는지, 코드베이스가 어떤 패턴을 기대하는지 알아야 하죠. 좋은 문서는 에이전트에게 그런 맥락을 제공하고, 그 덕분에 더 근거 있는 코드 변경이 가능해지고 피할 수 있는 실수가 줄어듭니다.
문제는 문서를 최신 상태로 유지하기 어렵다는 점입니다. 처음 문서를 작성하는 데도 시간이 걸리고, 코드가 바뀔 때마다 문서를 갱신하는 일은 그보다 더 어렵습니다. PR이 자주 올라오는 대규모 저장소에서는 문서가 금세 낡아버릴 수 있습니다.
OpenWiki는 그 작업을 자동으로 처리합니다. 저장소를 위한 위키를 만들고, 그 위키를 코딩 에이전트에 연결하며, 코드가 바뀌면 위키를 최신 상태로 유지합니다.
왜 에이전트에게 위키인가
우리는 DeepWiki, AutoWiki, Karpathy의 LLM Wiki 개념 등 코드베이스 위키를 둘러싼 기존 작업에서 영감을 받았습니다. 공통된 아이디어는 단순합니다. 위키는 모든 맥락을 하나의 거대한 파일에 몰아넣지 않고도, 사람과 에이전트가 코드베이스를 구조적으로 이해할 수 있는 길을 열어 준다는 것입니다.
이 점이 중요한 이유는 대부분의 코딩 에이전트가 이미 AGENTS.md나 CLAUDE.md 같은 파일에서 지침을 읽기 때문입니다. 이런 파일은 유용하지만, 수백 페이지에 달하는 저장소 문서를 담아 두기에 알맞은 곳은 아닙니다. 이 파일들은 에이전트를 올바른 맥락으로 안내하는 역할만 하고, 필요한 내용은 에이전트가 직접 찾아오게 해야 합니다.
OpenWiki는 그 모델을 따릅니다. 저장소 위키를 생성한 뒤, 에이전트 지침 파일에 해당 위키를 가리키는 참조를 추가합니다. 그다음부터는 코딩 에이전트가 문서를 자동으로 발견하고 활용할 수 있습니다.
시작하기
OpenWiki는 커맨드라인에서 쉽게 실행할 수 있도록 설계되었습니다.
npm으로 설치하세요:
npm install -g openwiki그런 다음 실행하세요:
openwiki --initinit 명령은 모델 제공자와 API 키를 물어본 뒤, 저장소의 문서를 생성합니다.
OpenWiki는 OpenRouter, Fireworks, Baseten, OpenAI, Anthropic 등 오픈 모델과 클로즈드 모델 제공자를 모두 지원합니다. 기본으로는 OpenRouter와 오픈 모델을 사용하지만, 자신의 환경에 가장 잘 맞는 제공자를 설정할 수 있습니다.
OpenWiki는 DeepAgents 위에 만들어져 있어 LangSmith로의 트레이싱도 지원합니다. LangSmith API 키를 제공하면 OpenWiki가 실행 내역을 LangSmith 프로젝트로 남기므로, 문서를 생성하거나 갱신하는 동안 에이전트가 정확히 무엇을 했는지 들여다볼 수 있습니다.
OpenWiki가 코딩 에이전트와 연결되는 방식
위키를 생성한 뒤 OpenWiki는 저장소의 에이전트 지침 파일을 갱신합니다. 저장소가 AGENTS.md나 CLAUDE.md를(또는 둘 다) 사용한다면, OpenWiki는 생성된 위키를 가리키는 참조를 추가하고 에이전트가 언제 그 위키를 사용해야 하는지 설명을 덧붙입니다.
이런 방식을 선택한 이유는 위키 전체를 지침 파일 안에 넣으면 컨텍스트가 지나치게 커지기 때문입니다. 대규모 저장소에서는 위키가 수백 개의 파일에 이를 수 있습니다. 그것을 에이전트가 실행될 때마다 전부 불러오는 것은 낭비이고 유지 관리하기도 어렵습니다.
짧은 참조가 더 효과적입니다. 코딩 에이전트는 이미 지침 파일을 읽고 있으니까요. OpenWiki가 참조를 추가해 두면, 에이전트는 저장소 맥락이 필요할 때 위키를 찾아볼 수 있고, 여러분은 워크플로를 바꿀 필요가 없습니다.
위키를 최신 상태로 유지하기
문서를 한 번 생성하는 것도 유용하지만, OpenWiki의 진가는 문서를 최신 상태로 유지하는 데서 드러납니다.
OpenWiki에는 예를 들어 하루에 한 번처럼 일정에 따라 실행할 수 있는 GitHub Action이 포함되어 있습니다. 이 액션은 update 플래그와 함께 OpenWiki를 실행합니다. OpenWiki는 마지막 실행 이후 어떤 커밋이 반영되었는지 확인하고, git diff로 무엇이 바뀌었는지 파악한 다음, 관련 맥락을 반영해 위키를 갱신합니다.
즉, 이 워크플로는 백그라운드에서 돌아갈 수 있습니다. 코드베이스가 바뀌면 OpenWiki가 문서를 갱신하고, 코딩 에이전트는 기존 지침 파일의 참조를 통해 계속 최신 위키를 활용하게 됩니다.
코드베이스부터 시작합니다
이번 첫 릴리스는 코드베이스용 위키에 집중합니다. 개발자가 상세한 문서를 직접 작성하고 유지 관리하지 않아도, 에이전트가 자신이 작업하는 저장소를 더 쉽게 이해할 수 있게 하는 것이 목표입니다.
시간이 지나면 OpenWiki 개념이 더 폭넓게 적용될 수 있다고 생각합니다. 에이전트에게는 코딩만이 아니라 다양한 종류의 작업에서 오래 유지되는 맥락이 필요합니다. 코드베이스 문서화는 첫 번째 사용 사례일 뿐이고, 같은 패턴이 다른 워크플로에서도 에이전트가 유용한 맥락을 유지하도록 도울 수 있습니다.
직접 사용해 보세요
OpenWiki는 오픈소스이며 지금 바로 사용할 수 있습니다.
설치한 뒤 openwiki --init을 실행하면 몇 분 안에 저장소 위키를 생성할 수 있습니다.
저장소는 여기에서 확인하세요: https://github.com/langchain-ai/openwiki