OpenWiki로 Git 저장소 에이전트 문서 처음 만들기

개요

저장소가 커질수록 README 하나만으로는 에이전트가 필요한 맥락을 찾기 어렵습니다. OpenWiki는 현재 Git 저장소에서 코드 문서를 만들고 갱신하는 CLI입니다.

저는 새 저장소에 문서 자동화를 붙일 때 생성된 파일을 곧바로 믿지 않고 변경분부터 먼저 읽는 편입니다. OpenWiki는 코드 모드에서 openwiki/ 문서와 루트의 AGENTS.md, CLAUDE.md 안내 블록을 관리합니다. 이 글은 제목대로 현재 저장소에서 --init으로 첫 문서를 만드는 경로만 다룹니다.

OpenWiki 저장소에는 코드 모드와 개인 모드가 분리되어 있습니다. 개인 메모리 수집이 목적이면 openwiki personal --init 경로를 써주시면 됩니다.

사전 준비 사항

Node.js와 npm이 필요합니다. 전역 설치 뒤 대상 Git 저장소로 이동합니다. 앞서 Docker Compose로 n8n을 설치한 글에서처럼, 저는 자동화 도구를 붙일 때도 설정 파일과 생성물을 저장소 변경분으로 나눠서 보는 편입니다.

npm install -g openwiki
cd <Git_저장소_경로>
openwiki --init

첫 실행은 모델 제공자와 API 키, 모델을 설정합니다. 설정값은 ~/.openwiki/.env에 저장되므로 저장소의 .env 파일과 섞지 않는 편이 낫습니다. 초기화 화면에 표시되는 제공자와 모델 ID를 확인하시면 됩니다.

OpenWiki는 OpenAI, Anthropic, Gemini, OpenRouter, 그리고 OpenAI 호환 제공자까지 지원합니다. 로컬 게이트웨이를 쓴다면 base URL, API 키, 모델 ID가 게이트웨이에서 노출한 값과 같아야 합니다. 모델 ID가 다르면 초기화가 끝나도 호출 단계에서 멈춥니다.

전체 구성 흐름

먼저 현재 폴더를 코드 모드 대상으로 분석합니다. 이어서 openwiki/ 아래에 코드베이스 문서를 만들고, 루트의 AGENTS.md와 CLAUDE.md에 있는 OpenWiki 관리 블록을 추가하거나 갱신합니다.

마지막으로 생성된 문서와 안내 파일을 Git diff로 확인한 뒤 커밋하면 됩니다. 여기까지가 준비입니다.

이미 openwiki/가 있는 저장소는 openwiki --update로 갱신합니다. CI에서는 openwiki code --update --print로 문서 변경 내역을 출력할 수 있습니다. 저는 자동 병합보다 PR에서 문서 diff를 읽는 흐름을 먼저 둡니다.

확인

git status --short
find openwiki -maxdepth 2 -type f | sort

openwiki/ 파일과 AGENTS.md 또는 CLAUDE.md 변경이 보이면 초기화가 반영된 상태입니다. API 키가 git status에 나타나지 않는지도 함께 확인해주시면 됩니다.