CodeWiki를 사용하여 모든 GitHub 저장소에 대한 AI 문서를 생성하는 방법

AI 코딩 도구들은 여전히 대규모 리포지토리를 이해하는 데 어려움을 겪고 있습니다.

CodeWiki는 개발자가 GitHub 프로젝트를 분석하고 구조화된 문서를 생성하도록 도와주어, 익숙하지 않은 코드베이스를 더 쉽게 탐색할 수 있게 합니다. AI 모델에게 흩어진 파일들로부터 리포지토리의 작동 방식을 추측하도록 시키는 대신, CodeWiki는 프로젝트에 대한 구조화된 이해를 구축합니다.

이 튜토리얼에서는 CodeWiki를 Atlas Cloud와 함께 사용하여 GitHub 리포지토리를 AI가 생성한 위키로 변환하는 방법을 알아봅니다.

CodeWiki가 GitHub 리포지토리를 분석하고 문서를 생성하는 방법

CodeWiki는 계층적 리포지토리 분석을 사용합니다

CodeWiki는 리포지토리를 하나의 거대한 텍스트 덩어리로 취급하는 대신, 다양한 수준의 구조를 통해 분석합니다.

워크플로우는 다음과 같이 요약할 수 있습니다:

plaintextCopy
1리포지토리
2      ↓
3프로젝트 구조 분석
4      ↓
5모듈 이해
6      ↓
7컴포넌트 분석
8      ↓
9문서 생성

이 접근 방식은 개발자가 익숙하지 않은 시스템을 학습할 때 사용하는 일반적인 워크플로우와 유사합니다:

1. 전체 아키텍처 이해
2. 주요 모듈 식별
3. 중요한 컴포넌트 탐색
4. 상세 구현 내용 읽기

CodeWiki는 AI 기반 리포지토리 분석을 통해 이 아이디어를 적용합니다.

CodeWiki는 코드 주석 이상의 것을 생성합니다

기존의 문서는 종종 개별 함수나 클래스에 집중합니다.

CodeWiki는 리포지토리 수준의 문서화에 집중합니다.

생성된 자료에는 다음이 포함될 수 있습니다:

• 프로젝트 개요
• 모듈 설명
• 아키텍처 정보
• 시각적 문서

목표는 단순히 각 파일이 무엇을 하는지 설명하는 것만이 아닙니다.

프로젝트의 구성 요소가 어떻게 서로 맞물려 있는지 더 명확한 지도를 만드는 것입니다.

단계별 가이드: CodeWiki로 GitHub 프로젝트를 위한 AI 위키 생성하기

워크플로우는 크게 4단계로 구성됩니다:

1. CodeWiki 설치
2. LLM 공급자 구성
3. 리포지토리 분석 실행
4. 생성된 문서 탐색

1단계: CodeWiki 설치

GitHub에서 직접 CodeWiki를 설치합니다:

plaintextCopy
1pip install git+https://github.com/FSoft-AI4Code/CodeWiki.git

설치 후 codewiki 명령어를 사용할 수 있습니다.

CLI를 사용할 수 있는지 확인하려면 다음을 실행하세요:

plaintextCopy
1codewiki --version

만약 cannot import name 'OpenAIModel' 오류가 발생하면 다음을 실행하세요:

plaintextCopy
1python -m pip uninstall pydantic-ai pydantic-ai-slim -y
2python -m pip install "pydantic-ai>=1.0.6,<2"

2단계: Atlas Cloud API 키 받기

Atlas Cloud 콘솔로 이동하여 API Keys 페이지를 열고, Create API Key를 클릭한 뒤 키를 복사하여 안전하게 보관하세요. Atlas Cloud는 키가 한 번만 표시된다고 안내하므로, 생성 시 안전한 곳에 저장해 두어야 합니다.

키를 비공개로 유지하세요. 공개 GitHub 리포지토리, 공개 기사 초안 또는 스크린샷에 붙여넣지 마세요.

API 키는 Bearer 토큰으로 전달되며, Atlas Cloud는 프로젝트에 직접 하드코딩하는 대신 환경 변수에 저장할 것을 권장합니다.

macOS 또는 Linux의 경우:

plaintextCopy
1export ATLASCLOUD_API_KEY="your-atlas-cloud-api-key"

Windows PowerShell의 경우:

plaintextCopy
1$env:ATLASCLOUD_API_KEY="your-atlas-cloud-api-key"

Windows에서 장기적으로 사용하려면 시스템 속성 → 환경 변수에 ATLASCLOUD_API_KEY를 추가하세요.

3단계: CodeWiki에서 Atlas Cloud 사용하도록 구성

CodeWiki에는 이미 전용 atlas-cloud 공급자가 포함되어 있습니다. 따라서 범용 OpenAI 호환 엔드포인트로 수동 구성할 필요가 없습니다.

다음 명령어를 실행하세요:

plaintextCopy
1# Atlas Cloud — 기본 URL은 https://api.atlascloud.ai/v1으로 자동 설정됩니다;
2# --api-key를 생략하면 $ATLASCLOUD_API_KEY에서 API 키를 읽어옵니다.
3codewiki config set \
4  --provider atlas-cloud \
5  --main-model anthropic/claude-sonnet-4.8 \
6  --cluster-model anthropic/claude-sonnet-4.8 \
7  --fallback-model zai-org/GLM-5.2

이 모드에서 CodeWiki는 자동으로 Atlas Cloud의 기본 URL인 https://api.atlascloud.ai/v1을 사용합니다. --api-key가 생략되면 CodeWiki는 ATLASCLOUD_API_KEY 환경 변수에서 키를 읽어옵니다.

위 모델 ID는 CodeWiki의 자체 Atlas Cloud 예시에서 가져온 것입니다. Atlas Cloud 모델 페이지에서도 모델 ID가 API 요청에 직접 전달됨을 보여줍니다(예: anthropic/claude-sonnet-4.8 및 zai-org/GLM-5.2).

저장된 구성을 확인하세요:

plaintextCopy
1codewiki config show
2codewiki config validate

codewiki config show는 현재 구성을 검사하고, codewiki config validate는 설정이 유효한지 확인합니다. 두 명령어 모두 CodeWiki 구성 섹션에 나열되어 있습니다.

4단계: 프로젝트 문서 생성

문서화하려는 리포지토리로 이동합니다:

plaintextCopy
1cd /path/to/your/project

그런 다음 실행하세요:

plaintextCopy
1codewiki generate

기본적으로 CodeWiki는 생성된 문서를 ./docs/에 저장합니다. 출력물에는 overview.md, 모듈 수준 문서, module_tree.json, metadata.json이 포함되며, HTML 뷰어가 활성화된 경우 index.html이 포함됩니다.

GitHub Pages와 함께 사용할 수 있는 HTML 뷰어를 생성하려면 다음을 실행하세요:

plaintextCopy
1codewiki generate --github-pages --create-branch

CodeWiki의 README는 이를 GitHub Pages 워크플로우로 설명하며, 생성된 문서는 ./docs/ 아래에 배치된다고 명시하고 있습니다.

사용 예시

라이브 데모를 클릭하여 대화형 데모 및 예시를 확인할 수 있습니다.

리포지토리 문서화를 위해 CodeWiki와 Atlas Cloud가 잘 작동하는 이유

CodeWiki에 내장된 atlas-cloud 공급자는 리포지토리 문서화 작업이 보통 한 가지 모델만으로 해결되지 않기 때문에 유용합니다. 워크플로우는 메인 모델, 클러스터링 모델, 폴백 모델을 사용할 수 있으므로, 통합된 OpenAI 호환 공급자를 사용하면 설정 중에 모델 ID를 테스트하고 전환하는 번거로움이 줄어듭니다.

Atlas Cloud는 하나의 API, 하나의 엔드포인트, 하나의 결제 계정을 통해 300개 이상의 모델에 통합 접근할 수 있는 플랫폼입니다. 이 LLM 엔드포인트는 /v1에서 OpenAI와 호환되며, 이는 CodeWiki가 채팅 완성 모델에 필요로 하는 통합 방식과 일치합니다.

개발자에게 주는 실질적인 장점은 간단합니다. 문서화 품질을 테스트하면서 각 공급자별로 계정을 등록하고 설정을 다시 작성하는 대신, CodeWiki 명령어를 그대로 유지하면서 필요에 따라 모델 이름만 변경하면 됩니다.

미래의 AI 코딩 에이전트가 더 나은 리포지토리 컨텍스트를 필요로 하는 이유

AI 코딩 도구는 빠르게 발전하고 있습니다.

하지만 코드를 생성하는 것은 소프트웨어 엔지니어링의 일부분일 뿐입니다.

기존 시스템을 수정하기 전에 AI 에이전트는 컨텍스트가 필요합니다:

• 각 모듈은 무엇을 하는가?
• 컴포넌트들은 어떻게 상호작용하는가?
• 어떤 설계 결정 사항을 유지해야 하는가?

가능한 워크플로우는 다음과 같습니다:

plaintextCopy
1리포지토리
2      ↓
3지식 계층
4      ↓
5AI 에이전트
6      ↓
7코드 변경

누락된 계층은 또 다른 코드 생성기가 아닙니다.

AI가 기존 소프트웨어를 이해하도록 돕는 시스템입니다.

CodeWiki와 같은 도구는 이러한 리포지토리 지식 계층을 구축하기 위한 하나의 접근 방식을 나타냅니다.

자주 묻는 질문(FAQ)

AI는 어떻게 GitHub 리포지토리를 이해할 수 있나요?

AI는 코드베이스를 개별 파일 단위로만 처리하는 대신 구조적으로 분석할 때 GitHub 리포지토리를 더 잘 이해할 수 있습니다.

리포지토리 수준의 도구는 모듈, 컴포넌트 및 프로젝트 구조에 대한 정보를 구성하는 데 도움을 줍니다.

CodeWiki는 아키텍처 다이어그램을 생성할 수 있나요?

네. 공식 README에는 시스템 아키텍처 다이어그램, 데이터 흐름 시각화, 의존성 그래프, 시퀀스 다이어그램 등이 시각적 결과물로 나열되어 있습니다.

CodeWiki는 생성된 문서를 어디에 저장하나요?

기본적으로 생성된 문서는 ./docs/에 저장됩니다. 문서화된 출력 구조에는 overview.md, 모듈 문서 파일, 모듈 트리 JSON 파일, 메타데이터 및 선택적 index.html 뷰어가 포함됩니다.

CodeWiki는 문서를 GitHub Pages에 게시할 수 있나요?

네. CodeWiki는 codewiki generate --github-pages --create-branch와 같은 명령어를 통해 GitHub Pages 출력을 지원합니다.

CodeWiki에 어떤 모델을 사용해야 하나요?

메인 문서 작업에는 강력한 코딩 모델이나 긴 컨텍스트 모델을 사용하고, 폴백(fallback) 모델을 구성해 두세요. CodeWiki의 구성은 메인, 클러스터, 폴백 모델을 각각 지원하는데, 이는 모듈 클러스터링과 장문 문서화가 항상 동일한 모델 작업이 아니기 때문에 유용합니다.

CodeWiki의 결과물은 완전히 신뢰할 수 있나요?

아니요. 결과물을 엔지니어링 검토가 필요한 생성된 문서로 취급하십시오. CodeWiki는 구조화된 문서와 다이어그램을 생성할 수 있지만, 아키텍처 주장, 모듈 경계, 데이터 흐름 설명을 소스 코드와 대조하여 직접 검증해야 합니다.

CodeWiki는 ChatGPT에게 리포지토리 설명을 요청하는 것과 어떻게 다른가요?

채팅 프롬프트는 임시 설명을 얻는 데 유용하지만, CodeWiki는 반복 가능한 리포지토리 수준의 워크플로우로 설계되었습니다. 코드베이스를 분석하고 모듈로 분해하며, 구조화된 문서를 생성하고, 시각적 결과물과 탐색 가능한 뷰어를 생성할 수 있습니다.

핵심 요약

CodeWiki는 리포지토리 문서화를 엔지니어링 워크플로우로 바꿀 수 있다는 점에서 유용합니다. 설치하고, 공급자를 구성하고, 실제 리포지토리에서 실행하고, 생성된 개요와 모듈 문서를 검토한 후 검토가 완료된 후에만 뷰어를 게시하세요.

개발자에게 가장 큰 이점은 AI가 마크다운을 더 빨리 쓴다는 점이 아닙니다. 대규모 코드베이스를 탐색하기가 더 쉬워진다는 점입니다. 모듈, 의존성, 다이어그램, 아키텍처 메모가 한곳에 모이고, 프로젝트가 변경됨에 따라 워크플로우를 다시 실행할 수 있습니다.