OpenWiki로 코드베이스 저장소와 AI 에이전트 문서 통합하기

개요

코딩 에이전트에게 저장소 맥락을 매번 물어보게 되면, 같은 아키텍처 설명이 대화마다 반복됩니다. 코드는 바뀌는데 문서는 뒤처진 채로 남기 쉽습니다.

OpenWiki는 저장소 문서를 로컬 위키로 만들고 유지하는 CLI입니다. code 모드는 현재 저장소에 openwiki/ 문서를 두고, personal 모드는 ~/.openwiki/wiki에 개인 지식 위키를 둡니다. 설치 명령은 공식 README의 npm 전역 설치 경로만 다룹니다.

시스템 아키텍처

code 모드: 저장소 루트에 openwiki/ 문서를 생성·갱신합니다.

에이전트 지침: 실행 시 AGENTS.md와 CLAUDE.md에 OpenWiki 전용 블록을 넣어 위키를 먼저 보게 합니다.

CI 갱신: GitHub Actions 예시 워크플로는 openwiki code --update --print로 PR을 엽니다.

커넥터(선택): personal 모드에서 git-repo, Notion, Gmail, Web Search, Hacker News 소스를 로컬로 모읍니다.

Node.js 22 이상과 추론 provider API 키 1개를 준비합니다. README 기본 예시는 OpenRouter 키와 OPENWIKI_MODEL_ID입니다. Windows면 npm 또는 pnpm 전역 설치를 권장합니다. bun install -g openwiki는 better-sqlite3 네이티브 빌드가 필요할 수 있습니다.

앞선 Marketing Skills 설치 글처럼 에이전트 지침 파일을 저장소에 두는 흐름과 맞물립니다. OpenWiki는 그 지침에 위키 참조 블록을 자동으로 끼웁니다.

설치 절차

저장소 루트에서 전역 설치 후 초기화합니다. 키와 모델은 첫 대화형 실행에서 묻거나 ~/.openwiki/.env에 미리 넣으시면 됩니다.

npm install -g openwiki
openwiki --init

초기화 기본값은 code 모드입니다. 개인 위키를 쓰려면 openwiki personal --init을 실행합니다. 설정과 비밀값은 ~/.openwiki/.env에 저장됩니다.

CI에 붙일 때는 공식 예시 examples/openwiki-update.yml을 .github/workflows/openwiki-update.yml로 복사합니다. 워크플로 핵심은 아래와 같습니다.

openwiki code --update --print

CI에서는 --init이 필요 없습니다. provider·모델 환경 변수가 있으면 --update가 첫 openwiki/ 문서도 만듭니다. 익명 신뢰성 텔레메트리를 끄려면 워크플로 env에 OPENWIKI_TELEMETRY_DISABLED=1을 넣으시면 됩니다.

1. 사용 방법

대화형 code 모드:

openwiki
openwiki "Please generate documentation for this repository"

한 번만 실행하고 끝내려면 -p 또는 --print를 붙입니다. 문서 갱신은 openwiki --update입니다.

OpenAI 호환 게이트웨이를 쓸 때는 README의 openai-compatible 설정을 씁니다. 값은 placeholder로 둡니다.

OPENWIKI_PROVIDER=openai-compatible
OPENAI_COMPATIBLE_API_KEY=<API_KEY>
OPENAI_COMPATIBLE_BASE_URL=http://localhost:20128/v1
OPENWIKI_MODEL_ID=<MODEL_ID>
openwiki --init

문서 형식은 Google Open Knowledge Format(OKF) v0.1 번들입니다. 개념 Markdown에 YAML front matter type이 들어가고, 루트 index.md는 okf_version: "0.1"을 선언합니다. 저장소 범위 메모는 openwiki/INSTRUCTIONS.md에 직접 적습니다. 이 파일은 일반 init/update가 덮어쓰지 않습니다.

적용 대상

• 맞는 경우: Claude Code·Codex 같은 코딩 에이전트가 같은 저장소를 반복 열고, 아키텍처·모듈 경계를 매번 다시 설명하기 싫은 팀
• 비교 기준: 사람 손으로 쓴 docs/만 유지하면 단순합니다. 코드 변경마다 에이전트용 맥락을 자동 갱신하고 PR로 검토하려면 OpenWiki 쪽이 맞습니다.
• 맞지 않는 경우: LLM 호출 비용·키를 쓰기 싫은 환경, 문서 자동 생성 자체를 허용하지 않는 저장소, personal 커넥터 OAuth를 열 수 없는 환경

저는 개인 서버·로컬 에이전트 조합에서는 code 모드 + 스케줄 워크플로를 먼저 보겠습니다. personal 커넥터는 키와 OAuth 범위가 늘어나기 때문입니다.

CI에 올린 provider 키는 저장소 secret으로만 넣고, 워크플로 로그에 모델 출력 전체를 남기지 않는 편이 안전합니다.

확인

로컬에서 아래 순서로 산출물을 확인합니다.

openwiki --help
openwiki --update
ls openwiki

openwiki/ 아래 문서와 루트 AGENTS.md·CLAUDE.md의 <!-- OPENWIKI:START --> 블록이 보이면 정상입니다. CI를 켠 경우 스케줄 또는 workflow_dispatch 실행 뒤 openwiki/update 브랜치 PR이 열리면 연결이 끝난 것입니다.