AI 에이전트 전용 코드 문서화 도구 OpenWiki

지난해 개인 에이전트의 큰 흐름을 이끌었던 OpenClaw에 이어, 올해는 범용 메모리가 AI 기술의 다음 단계를 이끈다. LangChain은 코딩 에이전트 전용 오픈소스 문서화 도구 OpenWiki를 공개하며, 사람이 아닌 AI 에이전트가 코드를 더 효율적으로 이해하고 변경하도록 돕는 새로운 접근 방식을 제시한다. 이 도구는 에이전트 맞춤형 문서 구조와 자동화된 업데이트 기능을 핵심으로 한다.

OpenWiki, 에이전트를 위한 코드 문서화

OpenWiki는 코딩 에이전트가 코드베이스 문서를 생성하고 유지 관리하도록 돕는 CLI(명령줄 인터페이스) 도구이다. 이는 지난 3~4년간 에이전트 연구의 주요 영역이었던 ‘범용 메모리’ 문제를 해결하기 위한 시도이다. 기존 메모리 솔루션들이 특정 상황에만 유효했던 것과 달리, OpenWiki는 어떤 코드베이스에도 적용 가능한 범용 메모리 솔루션을 목표로 한다. 이 프로젝트는 최신 LLM(대규모 언어 모델)과 에이전트 아키텍처 덕분에 마침내 실현 가능해졌다.

OpenWiki의 세 가지 핵심 철학

OpenWiki는 세 가지 핵심 철학을 바탕으로 개발되었다. 이 철학은 에이전트가 코드를 이해하고 작업하는 방식을 혁신한다.

철학	설명
에이전트 맞춤형 문서	기존 문서화 도구들이 인간과 에이전트 모두를 위해 설계된 반면, OpenWiki는 오직 에이전트가 소비하도록 최적화한다. 현대 개발 환경에서 에이전트가 코드 작성의 많은 부분을 담당하므로, 문서 또한 에이전트의 소비 방식에 맞춰 생성되고 구조화되어야 한다는 생각이다. 이는 문서의 내용 구성과 표현 방식에 큰 변화를 가져온다.
쉬운 설정	개발자 도구는 설정이 간편해야 한다. OpenWiki는 CLI 방식으로 제공되어 설치가 쉽고, 초기 온보딩 과정이 매우 간단하다. 복잡한 설정 없이도 빠르게 문서를 생성하고 활용할 수 있도록 돕는다.
자동 업데이트	코드베이스 문서를 최신 상태로 유지하는 것은 어려운 문제이다. OpenWiki는 수동 작업 없이도 문서가 자동으로 업데이트되도록 설계되었다. 에이전트가 코드 변경 이력을 바탕으로 문서를 자동으로 갱신하여, 개발자가 별도로 문서 관리에 시간을 할애할 필요가 없다.

사람과 에이전트를 위한 문서 구조의 차이

사람과 에이전트가 문서를 소비하는 방식은 근본적으로 다르다. 이 차이 때문에 OpenWiki는 에이전트 최적화 문서를 만든다.

특징	인간용 문서	에이전트용 문서
내용 흐름	이야기를 담듯 서술하며, 빠른 시작 가이드와 배경 설명 등 전체적인 흐름을 중시한다. 문서 페이지 간 유기적인 연결이 중요하다.	전체 페이지보다 단편적인 조각(fragment)을 검색한다. 각 콘텐츠는 독립적으로 의미를 지녀야 하며, 특정 컨텍스트 없이도 이해 가능하도록 자체 포함적이다.
시각 자료	이해를 돕기 위해 스크린샷, 비디오 등 시각 자료를 적극 활용한다.	컨텍스트 윈도우에 최적화된 형식이어야 한다. 불필요하게 토큰을 많이 소모하는 base64 문자열 같은 데이터는 피한다.
색인 및 검색	대개 제목이나 키워드 기반으로 검색한다.	필터링과 검색을 위해 예측 가능하고 정밀하며 정확한 헤딩이 필수이다. 특정 유형이나 태그로 빠르게 정보를 찾도록 구조화한다.
컨텍스트 소비 방식	전체 문서를 읽고 맥락을 파악한다.	관련된 코드베이스를 효율적으로 탐색하기 위해 단편적인 정보와 링크를 활용한다.

결국 에이전트가 코드 작성을 주도하는 지금은, 에이전트의 정보 소비 방식에 맞춘 문서가 필요하다는 관점이다.

CLI로 간편하게 OpenWiki 설정하기

OpenWiki는 CLI 도구로서 매우 간편한 설정 과정을 제공한다. npm install open-wiki 명령어로 설치하고, open-wiki init 명령어로 위키를 초기화한다.

open-wiki init 명령어를 실행하면 API 키 설정, 모델 선택, 위키 개요(코드베이스 탐색 방식에 대한 상위 수준의 프롬프트) 구성 등의 설정 마법사가 나타난다. 이 과정이 완료되면 OpenWiki는 다음 파일들을 자동으로 생성하거나 수정한다.

• GitHub Actions 파일: 일일 크론 작업을 설정하여 코드 변경 이력을 기반으로 위키를 자동으로 업데이트한다.
• agent.md 또는 claw.md: 에이전트가 OpenWiki의 존재와 접근 방법을 인지하도록 컨텍스트를 주입한다.
• 다양한 마크다운 파일: Quickstart.md를 포함한 문서 파일들을 생성하며, 이는 에이전트가 코드베이스와 문서의 전체적인 흐름을 파악하는 데 활용된다.

이러한 파일들이 병합되면, 개발자는 OpenWiki에 대해 따로 신경 쓰지 않아도 에이전트가 자동으로 최신 문서를 활용하여 효율성을 높인다.

OpenWiki가 생성하는 핵심 파일

OpenWiki는 Karpathy의 LLM Wiki와 유사한 구조의 마크다운 파일들을 생성한다. 특정 구조를 가진 이 파일들은 링크로 서로 연결된다.

파일/디렉토리 유형	설명
Quickstart.md	에이전트가 리포지토리와 위키의 다른 문서 콘텐츠에 대한 개략적인 아이디어를 얻기 위해 참조하는 파일이다.
개별 마크다운 파일	OpenWiki는 에이전트의 판단에 따라 필요한 디렉토리로 문서를 분할한다. 각 파일은 특정 주제에 집중하며, 에이전트가 여러 곳에서 컨텍스트를 찾을 필요 없이 하나의 파일에서 필요한 정보를 얻도록 돕는다. Open Knowledge Format(OKF) 표준에 따라 YAML 프런트 매터가 추가된다.
index.md	해당 디렉토리 내의 모든 파일 목록을 제공하여, 에이전트가 특정 디렉토리의 내용을 빠르게 파악할 수 있도록 돕는다.
log.md	위키의 변경 이력을 담는 변경 로그 파일이다. 에이전트뿐만 아니라 인간 개발자도 위키 업데이트 시 어떤 내용이 바뀌었는지 파악하는 데 중요하게 활용한다. 이 로그를 통해 전체적인 변경 사항을 확인하고, 필요한 경우 특정 파일의 세부 내용을 검토할 수 있다.

구글 Open Knowledge Format (OKF)의 중요성

OpenWiki는 구글의 OKF(Open Knowledge Format) 0.1(곧 0.2 지원 예정) 표준을 채택한다. OKF는 모든 마크다운 파일 상단에 특정 YAML 프런트 매터를 추가하는 간단한 사양이다.

필드	설명
type	문서의 유형을 명시한다. 예를 들어 ‘아키텍처 문서’ 등으로 필터링할 수 있는 기준을 제공한다.
title	문서의 제목을 나타낸다.
description	문서의 간략한 설명을 제공한다.
resource_tags	문서와 관련된 키워드 태그를 포함한다. 이를 통해 특정 태그로 문서를 필터링할 수 있다.
timestamp	문서가 생성되거나 마지막으로 업데이트된 시각을 기록한다.
임의 필드	위 기본 필드 외에도 특정 개념이나 태그를 위한 임의 필드를 추가할 수 있다.

이 작은 프런트 매터 추가는 문서 검색과 필터링에 큰 이점을 제공한다. 문서를 생성하는 것보다 효율적인 검색이 더 큰 과제인데, OKF는 이러한 결정론적 필드를 통해 에이전트가 필요한 컨텍스트를 빠르고 정확하게 찾아내도록 돕는다. 또한, 문서 간 마크다운 링크를 강조하여 에이전트가 관련 컨텍스트를 빠르게 탐색하도록 한다.

DeepSWE 벤치마크 검증 결과

OpenWiki의 초기 평가는 DeepSWE 코딩 에이전트 벤치마크의 일부 태스크를 활용하여 진행되었다. OpenWiki 없이 태스크를 수행한 경우와, OpenWiki를 생성한 후 동일 태스크를 재수행한 경우를 비교한다.

지표	OpenWiki 미사용	OpenWiki 사용	변화
성공적인 태스크 수 (20개 중)	7~8개	9~10개	약간 증가
토큰 소모량	높음	낮음	상당히 감소
도구 호출 횟수	많음	적음	감소
검색 횟수	많음	적음	감소
출력량	많음	적음	감소

초기 DeepSWE 벤치마크 결과는 OpenWiki가 에이전트의 토큰 소모량을 대폭 절감하고 전반적인 효율성을 향상시킨다는 점을 시사한다. 이는 에이전트가 코드베이스를 더 효율적으로 탐색하고 변경 사항을 구현하도록 돕는다는 의미이다.

개발 과정의 교훈, 인간도 문서를 읽는다

OpenWiki 개발 초기에는 에이전트만을 위한 문서를 목표로 했다. 개발팀은 에이전트가 코드를 작성하는 시대에 인간 개발자가 문서를 직접 읽을 필요가 없다고 가정했다. 그러나 빠르게 인간 개발자들도 이 문서를 읽고 싶어 한다는 피드백을 받았다. 이는 인간이 여전히 소프트웨어 개발 과정의 중요한 부분임을 보여준다.

이 피드백에 따라 OpenWiki는 인간 친화적인 요소를 일부 추가한다. 가장 큰 변화는 Mermaid 다이어그램의 도입이다. 초기에는 에이전트가 텍스트를 통해 충분히 정보를 얻을 수 있다고 보아 다이어그램을 추가하지 않았다. 그러나 다이어그램은 순서도, 상태 다이어그램, 흐름도 등을 통해 인간 개발자의 이해를 크게 돕는다. 에이전트가 다이어그램을 생성하고 소비할 수 있으므로, 다이어그램은 에이전트에게도 유용할 수 있지만, 주된 목적은 인간 개발자의 문서 소비 경험을 향상하는 데 있다.

OpenWiki CLI 작동 원리

OpenWiki CLI는 크게 두 가지 핵심 명령으로 작동한다.

1. open-wiki init

init 명령은 리포지토리를 처음 설정할 때 실행한다.

1. 설정 마법사:
   • LLM 키, 모델, 에이전트 구성: API 키 설정, 사용할 모델 선택, 리포지토리에 대한 에이전트의 상위 수준 지침(프롬프트) 설정 등을 진행한다.
2. 파일 자동 생성:
   • GitHub Actions 워크플로: 위키를 자동으로 최신 상태로 유지하기 위한 크론 작업을 설정한다. 이는 코드베이스 변경 사항을 기반으로 위키를 주기적으로 업데이트한다.
   • agent.md 또는 claw.md 수정: 에이전트가 OpenWiki의 존재, 접근 방법, 참조 시점 등을 인지하도록 관련 컨텍스트를 주입한다.
   • 크론 작업 설정: GitHub Actions에 매일 실행되는 크론 작업을 설정하여 위키 자동 업데이트를 보장한다.
3. 에이전트 실행:
   • 리포지토리 분석: 에이전트는 리포지토리의 현재 스냅샷뿐만 아니라 Git 히스토리(커밋, 제목 등)를 분석하여 코드 변경의 흐름과 맥락을 이해한다.
   • 문서 작성: 분석을 바탕으로 문서를 작성한다.
   • 결정론적 검증: 모든 문서가 OKF 표준을 준수하는지 확인하고, index.md 및 change log를 자동으로 작성한다. 에이전트는 변경된 내용을 change log에 추가한다.

이 과정을 통해 개발자는 초기 설정 후 OpenWiki 관리에 대해 신경 쓸 필요 없이 효율성 향상을 얻는다.

2. open-wiki update

update 명령은 init 명령으로 설정된 GitHub Actions 크론 작업에 의해 자동으로 실행된다.

1. Git 히스토리 확인: 마지막 실행 이후 코드 변경이 있었는지 Git 히스토리를 확인한다.
   • last_update.json 파일: 이 파일에 마지막 업데이트 시점이 기록되어 변경 여부를 추적한다. 변경이 없으면 업데이트를 건너뛴다.
2. 에이전트 실행: 변경 사항이 있을 경우 에이전트가 다시 실행된다.
   • Git 로그 분석: 에이전트가 마지막으로 실행된 이후 병합된 모든 커밋을 분석한다. (기본적으로 하루 한 번 실행되지만, 커밋이 많은 경우 4~8시간 간격으로 변경할 수 있다.)
   • 리포지토리 업데이트: 변경된 내용을 기반으로 위키를 업데이트한다.
   • PR 생성: 업데이트된 위키에 대한 Pull Request를 자동으로 생성한다.

개발자는 생성된 PR을 병합하는 것으로 위키를 최신 상태로 유지한다.

오픈소스 라이선스와 향후 계획

OpenWiki는 MIT 라이선스를 따르는 오픈소스 프로젝트이다. 개발자들은 GitHub에서 코드를 확인하고, NPM을 통해 설치하며, 필요에 따라 포크하여 특정 사용 사례에 맞게 수정할 수 있다. 현재 10~15개 이상의 LLM 제공자를 지원한다.

OpenWiki의 향후 계획은 다음과 같다.

• 프롬프트 개선: 현재 진행 중인 DeepSWE 평가를 통해 더 큰 리포지토리를 분석하고 업데이트하는 프롬프트 성능을 지속적으로 향상한다.
• 검색 및 검색 도구: 현재는 agent.md에 OpenWiki에 대한 정보를 주입하는 방식으로 에이전트가 위키를 인지한다. 다음 단계로, 에이전트가 위키를 검색하고 질의하며 필터링할 수 있는 전용 도구를 제공할 계획이다. 이러한 전용 도구는 이미 일부 평가에서 효율성 향상을 보여주었으며, 곧 병합될 예정이다.

LangChain은 개발자들이 가장 문서화가 미흡한 리포지토리에 OpenWiki를 적용해 보기를 권장한다.

출처

• Tech Bridge. (2026-08-17). [한글자막] 사람이 아닌 에이전트를 위한 문서 작성법: OpenWiki 내부 공개. YouTube.