서론

"CodeWiki는 스스로를 문서화합니다."

이 글은 Open Source Project of the Day 시리즈의 #135번째 기사입니다. 오늘의 프로젝트는 CodeWiki입니다. 이는 FPT Software의 AI4Code 연구팀이 개발한 자동 코드베이스 문서화 생성 프레임워크로, ACL 2026(Association for Computational Linguistics 연례 컨퍼런스)에 채택되었습니다.

코드베이스 문서화는 수십 년 동안 해결되지 않은 문제입니다. 함수 수준의 주석은 "이 함수가 무엇을 하는가"를 다룹니다. 하지만 파일 간, 모듈 간의 아키텍처적 이해 — 즉, 왜 이 컴포넌트가 여기에 존재하는지, 어떤 데이터 흐름이 어떤 레이어를 통과하는지 — 에 대해서는 체계적인 해결책이 없었습니다.

CodeWiki의 접근 방식은 재귀적 멀티 에이전트 아키텍처 (recursive multi-agent architecture)를 통해 규모 문제를 해결하는 것입니다. Tree-Sitter가 AST (Abstract Syntax Trees, 추상 구문 트리)를 파싱하여 의존성 그래프를 구축하면, 위상 정렬 (topological sorting)이 처리 순서를 결정합니다. 리프(leaf) 모듈이 먼저 처리되어 상위로 합성되며, 단일 패스로 처리하기에 너무 복잡한 모듈은 자동으로 하위 에이전트 (sub-agents)를 생성합니다. 결과물은 Mermaid 아키텍처 다이어그램이 포함된 완전한 Markdown 문서입니다.

학습 내용

• CodeWiki의 3단계 파이프라인: AST 파싱 → 재귀적 멀티 에이전트 생성 → 계층적 합성
• 동적 위임 (Dynamic Delegation): 에이전트가 특정 모듈을 처리할 수 없다고 판단하고 작업을 분할하는 방법
• CodeWikiBench 평가 프레임워크: AI가 생성한 문서의 품질을 엄격하게 측정하는 방법
• DeepWiki, deepwiki-open, OpenDeepWiki와의 차이점
• 증분 업데이트 (Incremental update) 설계: --update를 통해 변경된 모듈만 재생성

사전 요구 사항

• AST (Abstract Syntax Trees)에 대한 기본적인 이해
• 코드베이스를 유지 관리해 본 경험 — 문서화가 왜 어려운지 이해하는 데 도움이 됩니다
• LLM 멀티 에이전트 시스템에 대한 어느 정도의 지식

프로젝트 배경

코드베이스 문서화가 어려운 이유

함수 수준의 주석 생성은 해결되었습니다. GitHub Copilot과 AI 코딩 어시스턴트들이 이를 처리합니다. 어려움은 더 높은 추상화 단계에서 시작됩니다:

함수 수준 (해결됨):
"이 함수는 user_id를 받아 데이터베이스를 쿼리하고,
사용자 객체를 반환합니다"
...

저장소(Repository) 수준에서의 과제: 의존성이 파일 간에 걸쳐 있으며, 아키텍처 설명에는 전역적인 관점이 필요하고, 대규모 코드베이스는 단일 LLM의 컨텍스트 창(Context Window)을 훨씬 초과합니다.

저자 / 팀

• 조직 (Organization): FSoft-AI4Code (베트남 최대 IT 기업인 FPT Software의 AI 연구팀)
• 논문 (Paper): ACL 2026 Findings (aclanthology.org/2026.findings-acl.288)
• 라이선스 (License): MIT
• 언어 (Language): Python 3.12+

프로젝트 통계

• ⭐ GitHub Stars: 1,500+
• 🍴 Forks: 218+
• 📄 License: MIT
• 🎓 Paper: ACL 2026

핵심 아키텍처: 3단계 파이프라인 (Three-Stage Pipeline)

1단계: 저장소 분석 (AST + 의존성 그래프)

# CodeWiki는 Tree-Sitter를 사용하여 모든 소스 파일을 파싱합니다
# 추출 항목: 함수, 클래스, 언어 간 의존성
# 모든 것을 depends_on 관계로 정규화합니다
...

의존성 그래프(Dependency Graph)가 중요한 이유는 A가 B에 의존한다(A depends_on B)는 것이 A를 이해하기 위해 먼저 B를 이해해야 함을 의미하기 때문입니다. 위상 정렬(Topological Sort)을 통해 처리 순서, 즉 의존 대상보다 의존성을 먼저 처리하도록 결정합니다.

2단계: 재귀적 멀티 에이전트 문서 생성 (Recursive Multi-Agent Documentation Generation)

이것이 CodeWiki의 핵심 설계입니다.

단순한 LLM 처리 방식의 문제점:

대규모 모듈 → LLM 컨텍스트 창 초과 → 잘림(Truncation) → 문서 품질 저하

CodeWiki의 동적 위임 (Dynamic Delegation):

모듈 처리
    ↓
모듈 복잡도 평가
...

각 리프 에이전트(Leaf Agent)는 다음을 부여받습니다:

• 해당 모듈에 대한 전체 소스 코드 접근 권한
• 전역 모듈 트리 가시성 (전체 아키텍처 내에서의 위치 파악)
• 의존성 그래프 탐색 도구 (상위 및 하위 의존성 쿼리 가능)
• 전역 레지스트리(Global Registry) 접근 (중복 생성을 방지하고 대신 상호 참조를 사용)

3단계: 계층적 합성 (Hierarchical Synthesis, Bottom-Up)

리프 모듈 문서 (최하위 레벨, 의존성 없음)
        ↓
부모 모듈이 자식 문서들을 병합 + 아키텍처 요약 생성
...

출력 구조:

./docs/
├── overview.md ← 최상위 레벨 아키텍처 개요
├── module_A.md ← 모듈별 상세 문서화
...

평가: CodeWikiBench

CodeWiki는 AI가 생성한 코드베이스 문서화 (codebase documentation) 품질을 평가하기 위해 특별히 설계된 벤치마크인 CodeWikiBench를 함께 공개했습니다.

전통적인 텍스트 유사도 지표 (BLEU/ROUGE)는 문서화 품질 평가에 적합하지 않습니다. 기술적으로는 정확하지만 장황한 문서는 높은 점수를 받는 반면, 간결하고 정확한 문서는 낮은 점수를 받을 수 있습니다. 두 방식 모두 문서가 실제로 유용한지를 알려주지는 못합니다.

CodeWikiBench의 평가 방식:

1. 공식 프로젝트 문서에서 계층적 평가 루브릭 (evaluation rubrics) 추출
   여러 모델 (Claude Sonnet 4, Gemini 2.5 Pro, Kimi K2)에 의해 생성됨
   의미론적 신뢰도 (Semantic reliability): 73.65%, 구조적 신뢰도 (structural reliability): 70.84%
...

주요 결과:

빠른 시작 (Quick Start)

설치 (Installation)

git clone https://github.com/FSoft-AI4Code/CodeWiki.git
cd CodeWiki
pip install -e .

문서 생성 (Generating Documentation)

# 기본: 현재 디렉토리에 대한 문서 생성
codewiki run . --output docs/

...

지원되는 LLM 제공업체 (Supported LLM Providers)

유사한 오픈 소스 프로젝트와의 비교

이 분야에는 여러 프로젝트가 존재합니다:

deepwiki-open (AsyncFuncAI)

• ⭐ 17,100+ Stars
• Cognition AI의 DeepWiki 제품을 오픈 소스로 재구현함
• Python + TypeScript 지원, GitHub/GitLab/Bitbucket 지원
• 배포가 더 간편하며 Web UI 포함
• CodeWikiBench 점수: 50.05% (CodeWiki의 68.79% 대비)
• 적합한 용도: 빠른 배포, 웹 인터페이스를 원하는 팀

OpenDeepWiki (AIDotNet)

• C# 구현 (.NET 생태계)
• .NET 개발자를 대상으로 하는 DeepWiki의 재구현 버전
• CodeWikiBench 점수: 47.13%
• 최적 용도: .NET / Windows 엔터프라이즈 환경

context-labs/autodoc

• 초기 실험적 프로젝트 (2023년), GPT-4/Alpaca 기반
• LlamaIndex 스타일의 코드베이스 인덱싱 (Indexing) 접근 방식
• 유지보수는 덜 활발하지만, 이 카테고리의 기초적인 디자인 패턴을 확립함

요약 표 (Summary Table)

링크 및 리소스

• 🌟 GitHub: FSoft-AI4Code/CodeWiki
• 📄 논문 (Paper): ACL 2026 Findings · arXiv

결론

CodeWiki는 두 가지 측면에서 기여합니다: 사용 가능한 도구로서의 기여와 평가 벤치마크 (Benchmark)로서의 기여입니다.

도구 측면에서, 동적 위임 (Dynamic Delegation)은 실제 엔지니어링 문제를 해결합니다. 대규모 코드베이스는 단일 LLM 컨텍스트 창 (Context Window)에 담을 수 없습니다. 계층적 재귀 합성 (Hierarchical Recursive Synthesis)은 경계 부분에서 품질이 저하되는 대신, 86K에서 1.4M 라인에 이르는 코드베이스 전반에 걸쳐 문서화 품질을 유지합니다. 벤치마크 수치가 이 주장을 뒷받침합니다.

평가 측면에서, CodeWikiBench는 공백을 메워줍니다. 이 연구 이전에는 코드베이스 문서화 품질을 측정하기 위한 엄격하고 목적에 맞게 설계된 프레임워크가 없었습니다. 이러한 기여는 CodeWiki 도구 자체와는 별개로 독립적인 가치를 지닙니다.

한계점 또한 분명합니다. C 및 C++의 성능은 Python과 TypeScript에 뒤처집니다. Star 수 (1.5k)는 deepwiki-open (17.1k)에 비해 크게 뒤처지는데, 이는 품질 벤치마크만으로는 스스로 해결할 수 없는 사용성 및 커뮤니티 도달 범위의 격차를 나타냅니다.

대규모 코드베이스를 문서화해야 하고 출력 품질을 중요하게 생각하는 엔지니어에게, CodeWiki는 오픈 소스 옵션 중 가장 신뢰할 수 있는 벤치마크 수치를 보유하고 있습니다. 웹 인터페이스를 통한 빠른 배포를 원한다면, deepwiki-open이 마찰이 적은 선택지입니다.

PrimeSkills를 살펴보세요 — 엄선된 AI 에이전트(AI Agents)와 기술(skills)을 위한 마켓플레이스입니다. 각 기술은 실제 기업 워크플로우(enterprise workflows)에서 검증되었으며, 과장된 광고를 걷어내고 진정으로 작동하는 것만을 제공합니다.

더 유용한 통찰과 흥미로운 제품들을 확인하시려면 저의 홈페이지를 방문해 주세요.