사람이 아닌 에이전트를 위한 문서 작성법: OpenWiki 내부 공개

OpenWiki는 코딩 에이전트가 소비하도록 특별히 구축된 리포지토리 문서를 생성하고 유지하는 데 사용할 수 있는 CLI(Command Line Interface) 도구입니다. 이 도구의 핵심 목표는 에이전트가 코드베이스를 효율적으로 이해하고 상호작용할 수 있도록 돕는 것입니다. 이는 기존의 인간 중심 문서화 방식으로는 충족하기 어려운 에이전트의 특정 요구사항을 해결하기 위해 개발되었습니다.

OpenWiki 팀은 코드 기반 문서화부터 시작하기로 결정했는데, 이는 이 영역이 잘 정의되어 있고 모든 유형의 코드베이스에 적용할 수 있는 범용 메모리 솔루션을 구축할 수 있다고 믿기 때문입니다. 이 접근 방식은 에이전트가 코드의 맥락과 구조를 이해하는 데 필수적인 정보를 제공하며, 장기적으로는 더 넓은 범위의 AI 애플리케이션에 적용될 수 있는 기반을 마련합니다.

OpenWiki는 개발자 도구로서 설정이 간편해야 한다는 점을 중요하게 고려했습니다. 이를 위해 CLI 방식을 채택하여 사용자들이 쉽게 설치하고 사용할 수 있도록 했습니다. 개발자들이 복잡한 과정 없이 즉시 문서화 작업을 시작할 수 있도록 함으로써, 도구의 채택률을 높이고 개발 워크플로우에 원활하게 통합될 수 있도록 했습니다.

인간을 위한 문서는 대개 이야기를 전달하는 내러티브 중심으로 구성되지만, 에이전트를 위한 문서는 근본적으로 다른 구조를 가집니다. 에이전트는 문서의 파편을 검색하여 사용하므로, 모든 개념이 자체 포함되어 있어야 합니다. 즉, 에이전트가 특정 스니펫을 가져올 때, 그 스니펫만으로도 완전한 의미를 이해할 수 있도록 설계되어야 합니다. 이는 에이전트의 검색 및 이해 과정을 최적화하기 위한 핵심적인 고려사항입니다. OpenWiki는 이러한 차이를 반영하여 에이전트가 필요한 정보를 정확하고 효율적으로 추출할 수 있도록 문서 구조를 재설계했습니다.

OpenWiki CLI 도구는 설치와 초기화 과정을 극도로 단순화했습니다. npm을 통해 하나의 명령어로 설치할 수 있으며, 이후 'open wiki init' 명령어를 실행하는 것만으로 위키를 초기화할 수 있습니다. 이러한 간결한 설정 과정은 개발자가 빠르게 OpenWiki를 도입하고 문서화 작업을 시작할 수 있도록 돕습니다.

OpenWiki는 항상 'quick start.mmd' 파일을 포함하여 에이전트가 저장소의 전반적인 개념을 파악할 수 있도록 프롬프트합니다. 이 구조화된 마크다운 파일은 저장소의 핵심 정보를 간결하게 요약하여, 에이전트가 불필요한 탐색 없이 빠르게 작업에 필요한 컨텍스트를 얻을 수 있도록 돕습니다. 이를 통해 에이전트의 정보 습득 효율성을 극대화합니다.

OpenWiki는 Google의 Open Knowledge Format(OKF)을 채택하여 문서의 데이터 규격을 표준화했습니다. OKF는 모든 마크다운 파일에 결정론적인 YAML 프런트 매터를 추가함으로써, 문서의 메타데이터를 구조화합니다. 이 방식은 문서의 유형, 제목, 설명, 리소스 태그 및 타임스탬프와 같은 정보를 명확하게 정의하여, 에이전트가 문서를 분류하고 검색하는 과정을 훨씬 효율적으로 만듭니다. 결과적으로, 에이전트가 필요한 정보를 더 빠르고 정확하게 찾아낼 수 있게 됩니다.

OKF는 매우 간단한 스펙을 가지고 있으며, 기본적으로 모든 마크다운 파일 상단에 특정 프런트 매터를 추가하는 방식입니다. 이 프런트 매터에는 'type', 'title', 'description', 'resource tags', 그리고 'timestamp'와 같은 필드가 포함됩니다. 이러한 결정론적인 구조는 문서의 일관성을 유지하고 에이전트가 메타데이터를 기반으로 정보를 처리하기 쉽게 만듭니다.

모든 위키 문서 상단에 OKF 섹션을 추가하는 것은 문서 검색 효율성 측면에서 상당한 이점을 제공합니다. 문서 검색은 위키 생성보다 더 큰 과제일 수 있는데, OKF의 결정론적 필드는 에이전트가 문서를 검색하고 필터링하는 과정을 정교하게 만듭니다. 이를 통해 에이전트는 방대한 문서 내에서 필요한 정보를 더욱 정확하고 빠르게 찾아낼 수 있게 됩니다.

OpenWiki는 코딩 에이전트 벤치마크인 DeepSWE를 활용하여 성능을 평가했습니다. DeepSWE의 일부 태스크를 OpenWiki 없이 실행한 후, 해당 태스크에 대한 위키를 생성하고 다시 실행하는 방식으로 비교했습니다. 실험 결과, OpenWiki 없이 실행했을 때는 보통 7~8개의 태스크가 성공했지만, OpenWiki를 사용했을 때는 9~10개의 태스크가 성공하여 에이전트의 성공률이 향상되었음을 확인했습니다. 이는 OpenWiki가 에이전트의 코드 이해도를 높여 더 많은 작업을 성공적으로 완료할 수 있도록 돕는다는 것을 의미합니다. 또한, OpenWiki는 불필요한 토큰 소모를 줄여 효율성을 개선하는 데 기여했습니다.

처음 OpenWiki를 개발할 때는 코드를 작성하는 데 에이전트만 사용할 것이라는 생각으로 에이전트 소비에 초점을 맞췄습니다. 그러나 곧 사용자들로부터 자신들도 이 문서를 읽고 싶다는 피드백을 많이 받았습니다. 엔지니어링 과정에서 인간의 역할이 여전히 중요하기 때문에, 개발자들은 코드 문서 또한 읽기를 원했습니다. 이에 OpenWiki는 에이전트 친화적인 구조를 유지하면서도 인간 사용자를 위한 가독성을 개선하는 방향으로 확장되었습니다. Mermaid 다이어그램과 같은 시각적 요소를 도입하여 복잡한 개념을 인간이 더 쉽게 이해할 수 있도록 지원합니다.

OpenWiki CLI는 'init'과 'update' 두 가지 주요 명령어를 제공합니다. 'init'은 레포지토리를 처음 설정할 때 실행하는 명령어로, 설정 마법사를 통해 API 키 설정, 모델 선택, 그리고 리포지토리에 대한 구체적인 정보를 제공하는 상위 수준 프롬프트인 'instructions'를 설정하게 됩니다. 이 과정은 CLI 에이전트가 해당 레포지토리에 대해 더 정확하게 이해하고 작업할 수 있도록 돕습니다.

OpenWiki는 GitHub Actions 워크플로우를 활용하여 문서를 자동으로 작성하고 최신 상태로 유지합니다. 이 워크플로우는 매일 크론 작업을 실행하여 코드베이스의 변경 사항을 기반으로 위키를 자동으로 업데이트합니다. 개발자가 수동으로 문서를 관리할 필요 없이, 코드 변경이 발생할 때마다 자동으로 문서가 반영되므로 문서의 정확성과 최신성을 항상 유지할 수 있습니다.

OpenWiki는 단순히 현재 리포지토리의 코드만 읽는 것을 넘어, Git 히스토리를 분석하여 코드의 변경 과정과 진행 상황을 파악합니다. Git 커밋 메시지와 제목을 활용해 더 깊이 있는 문서 작성을 수행하며, 이는 코드의 현재 상태뿐만 아니라 그 이면에 있는 개발 의도와 변경 이력까지 문서에 반영할 수 있도록 합니다. 이러한 접근 방식은 에이전트가 코드의 '왜'와 '어떻게'를 이해하는 데 중요한 컨텍스트를 제공합니다.

OpenWiki의 업데이트 프로세스는 Git 히스토리를 먼저 확인하여 효율성을 극대화합니다. 마지막 업데이트 이후 변경 사항이 없으면 에이전트를 실행하지 않아 불필요한 리소스 낭비를 방지합니다. 이러한 최적화는 CI/CD 파이프라인에서 OpenWiki를 사용할 때 컴퓨팅 자원을 절약하고 업데이트 시간을 단축하는 데 기여합니다.

OpenWiki는 MIT 라이선스를 따르는 오픈소스 프로젝트입니다. 이는 사용자가 npm을 통해 쉽게 설치할 수 있을 뿐만 아니라, 필요에 따라 자신의 리포지토리 환경에 맞게 직접 포크하고 수정할 수 있는 자유로운 확장성을 제공합니다. 오픈소스 커뮤니티의 기여를 장려하며, 다양한 개발 환경과 요구사항에 맞춰 OpenWiki를 유연하게 활용할 수 있도록 합니다.

OpenWiki는 앞으로 더 큰 규모의 리포지토리를 분석할 수 있도록 프롬프트를 개선할 계획입니다. 현재의 텍스트 기반 문서 전달 방식에서 벗어나, 에이전트가 위키를 직접 쿼리할 수 있는 전용 검색 및 필터링 도구를 도입할 예정입니다. 이 도구는 에이전트가 필요한 정보를 더욱 정확하고 효율적으로 찾아낼 수 있도록 돕고, 궁극적으로는 에이전트의 자율성을 더욱 높이는 데 기여할 것입니다.