오픈위키(OpenWiki): 코딩 에이전트가 읽을 저장소 문서를 자동으로 만들고 갱신하는 CLI

핵심 메시지

• 오픈위키는 코드 저장소의 문서를 만들고 유지하는 명령줄 도구다. 핵심은 그 문서의 독자가 사람이 아니라 코딩 에이전트라는 점이다.
• 출발점은 '범용 메모리'라는 판단이었다. 메모리는 몇 년째 프런티어 연구 영역이었지만 범용으로 잘 해낸 사례가 없다고 보고, 경계가 뚜렷한 코드베이스 문서부터 시작했다.
• 에이전트는 문서 전체가 아니라 조각을 검색해 가져간다. 그래서 개념마다 자기완결적이어야 하고, 제목은 예측 가능하고 정확해야 하며, 컨텍스트 창을 낭비하는 내용이 섞이면 안 된다.
• 구글의 오픈 놀리지 포맷을 채택해 모든 문서에 종류·제목·설명·태그 같은 고정 항목을 머리말로 붙였다. 문서를 만드는 일보다 어려운 검색 문제를 이 결정적 항목들로 푼다.
• 코딩 에이전트 벤치마크 일부로 돌린 초기 평가에서는 성공한 과제 수가 소폭 늘었고, 도구 호출과 검색 횟수가 줄면서 토큰 소비가 크게 떨어졌다.

쉽게 이해하기

랭체인의 응용 AI 총괄이 자사 밋업에서 오픈위키라는 프로젝트를 소개했다. 오픈위키는 코드 저장소의 문서를 생성하고 유지하는 명령줄 도구인데, 보통의 문서 생성기와 갈라지는 지점은 독자 설정이다. 이 문서는 사람이 읽으라고 만든 것이 아니라 코딩 에이전트가 읽어 소비하라고 만든 것이다.

출발은 사내에서 나온 질문이었다고 한다. 작년의 큰 흐름이 개인 에이전트였다면 올해의 흐름은 무엇인가라는 물음에 발표자는 범용 메모리를 답으로 내놨다. 메모리는 수년간 에이전트 연구의 최전선이었지만 범용적으로 잘 해낸 곳이 아직 없다는 판단이었고, 그래서 범위가 잘 정의된 코드베이스 문서를 첫 영역으로 골랐다. 여기서 통하는 방식을 만든 뒤 다른 메모리 영역으로 넓히겠다는 구상이다.

독자가 달라지면 문서의 구조가 달라진다. 사람을 위한 문서는 이야기를 끌고 가야 하고 빠른 시작 안내와 배경 설명이 필요하며 문서끼리 흐름이 이어져야 하고, 스크린샷과 영상도 들어간다. 반면 에이전트는 문서 하나를 통째로 읽기보다 조각을 뽑아 간다. 그래서 개념 하나하나가 스스로 완결되어야 하고, 걸러내고 검색하기 좋게 제목이 정확해야 하며, 도구 호출에 수만 토큰짜리 군더더기가 딸려 들어가지 않도록 정리돼 있어야 한다.

산출물은 특정 구조를 가진 마크다운 묶음이다. 항상 놓이는 빠른 시작 문서가 저장소 전체와 나머지 문서의 얼개를 알려주고, 디렉터리 구분은 무엇을 남길지와 함께 에이전트의 판단에 맡긴다. 팀이 주는 지침은 대략 몇 개의 파일을 어느 정도 크기로 쓸지, 파일 하나는 주제 하나에 집중하라는 정도다. 여기에 구글이 정의한 오픈 놀리지 포맷을 얹어 모든 파일 맨 위에 종류와 제목, 설명, 참조, 태그, 시각을 고정 형식으로 붙였는데, 발표자는 문서를 만드는 것보다 필요한 것을 꺼내오는 일이 훨씬 어렵다며 이 작은 머리말이 검색 단계에서 크게 남는 장사가 된다고 설명한다.

동작은 두 개의 명령으로 끝난다. 초기화 명령은 설정 마법사로 키와 모델과 저장소 안내 문구를 받고 에이전트를 돌려 문서를 쓰는데, 지금의 코드만 보는 것이 아니라 깃 이력까지 읽어 무엇이 어떻게 변해왔는지를 반영한다. 동시에 에이전트 안내 파일에 오픈위키의 존재를 적어 넣고 매일 도는 깃허브 액션을 심어두며, 갱신 명령은 변경이 없으면 넘어가고 변경이 있으면 그사이 병합된 커밋을 훑어 문서를 고친 뒤 병합 요청을 열어준다. 발표자는 팀이 틀렸던 전제도 솔직히 짚었다. 에이전트만 읽을 것이라 봤지만 사람도 읽고 싶어 했고, 위키가 저장소에 함께 커밋되는 만큼 변경 내역을 확인하려는 요구가 커서 결국 순서도나 상태도 같은 다이어그램을 추가했다는 것이다.

주요 인사이트

• 문서를 누가 읽느냐가 문서의 형식을 정한다. 이야기의 흐름과 배경 설명은 사람에게는 이해를 돕지만, 조각을 검색해 가져가는 에이전트에게는 오히려 맥락이 끊긴 파편을 만들어낸다.
• 생성보다 검색이 어렵다는 지적이 이 프로젝트 설계의 중심이다. 요즘 에이전트에게 문서를 쓰게 하는 일 자체는 쉬워졌기 때문에, 승부는 필요한 조각을 정확히 꺼내오는 쪽에서 갈린다.
• 고정된 머리말 항목을 강제하는 작은 규약이 검색 품질에서 복리로 불어난다. 종류나 태그 같은 결정적 필드가 있으면 의미 기반 추측 없이도 '설계 문서만' 같은 조건으로 후보를 줄일 수 있기 때문이다.
• 문서 도구의 진짜 난제는 처음 만드는 것이 아니라 계속 맞는 상태로 두는 것이다. 오픈위키가 깃허브 액션과 커밋 이력 추적을 기본으로 심는 이유도, 손이 가는 순간 문서는 다시 낡기 시작하기 때문이다.
• 성능 개선을 성공률만으로 읽으면 놓치는 것이 있다. 초기 평가에서 성공한 과제 수 증가는 작았지만 도구 호출과 검색과 출력이 함께 줄어 토큰 소비가 크게 떨어졌는데, 반복 실행되는 작업에서는 이쪽이 더 직접적인 이득이다.

자주 묻는 질문

관련 AI 소식