OpenWiki 사용법: 작은 저장소로 문서 생성과 갱신 확인하기
OpenWiki로 코드 설명 문서를 만들기 전에 준비할 환경과 비용, 연결 방식을 정리하고, 할인 함수 하나를 예로 생성 문서와 코드를 대조하고 변경을 반영하는 순서를 설명합니다.

세 줄로 먼저 읽기
- OpenWiki는 LangChain이 공개한 오픈소스 도구로, 코드 저장소를 설명하는 마크다운 위키를 AI로 만들어 openwiki 폴더에 두고 코드가 바뀌면 갱신합니다.
- Node.js 22.22.0 이상에서 npm으로 설치한 뒤 Codex나 Claude Code에 프로젝트 범위로 연결하거나 독립 CLI의 openwiki --init으로 시작하고, 변경 반영에는 openwiki --update를 씁니다.
- 자동 갱신 예시는 실패한 실행에서도 일부 문서를 PR로 남기므로 PR 본문의 실행 결과를 읽고 코드와 실행 결과, 현재 문서 설명이 서로 맞는지 대조합니다.
OpenWiki는 코드 저장소를 설명하는 문서를 AI로 만들고 갱신하는 LangChain의 오픈소스 도구입니다. 저장소는 코드와 변경 이력을 함께 관리하는 프로젝트 폴더이고, CLI는 터미널에 명령을 입력해 쓰는 프로그램입니다. 결과물은 주로 openwiki/ 폴더에 쌓이는 마크다운 문서입니다. 마크다운은 제목과 목록 등을 간단한 기호로 표시하는 텍스트 형식입니다.
코드의 할인율은 바뀌었는데 설명서에는 예전 비율이 남아 있는 일이 흔합니다. OpenWiki는 이런 설명을 코드에 맞춰 갱신하는 데 씁니다. 다만 생성된 문서가 실제 코드와 맞는지는 사람이 대조합니다. 이 글은 2026년 10월 4일 공식 안내를 기준으로, 작은 저장소에서 위키를 처음 만들고 갱신을 확인하는 순서를 다룹니다.
위 화면은 공식 시각화 예시입니다. 점 하나가 문서 하나이고, 연결선은 문서 사이의 링크입니다. 점을 고르면 그 문서의 마크다운 본문이 함께 표시됩니다.
지침 파일과 참고 문서는 역할이 다릅니다
AGENTS.md나 CLAUDE.md는 AI 코딩 도구에 작업 규칙을 알려 주는 지침 파일입니다. OpenWiki의 위키는 저장소의 구조와 기능을 필요할 때 찾아보는 참고 문서입니다. 공식 소개도 큰 위키 전체를 지침 파일에 넣지 않고, 지침 파일에서 필요한 위키 문서로 안내하는 방식을 설명합니다.
지침 파일과 OpenWiki 위키의 역할
| 항목 | ||
|---|---|---|
| 담는 내용 | 작업 규칙 | 구조와 기능 설명 |
| 읽는 때 | 작업을 시작할 때 | 필요한 문서만 찾아서 |
| OpenWiki가 바꾸는 범위 | 자체 관리 블록만 | 문서 전체 |
사람도 위키에서 필요한 부분만 찾아 읽고, AI도 상황에 따라 여러 문서를 읽습니다. 그래서 문서의 한 부분만 떼어 읽어도 뜻이 통하게 쓰는 것이 중요합니다.
| 설명 예 | 무엇을 알 수 있나요? |
|---|---|
| ‘이 함수는 위에서 설명한 값을 처리합니다.’ | 함수와 값이 무엇인지 이 문장만으로 알기 어려움 |
| ‘discount 함수는 양의 정수 가격을 받아 10% 할인한 금액을 반환합니다.’ | 함수 이름, 입력과 결과를 함께 알 수 있음 |
두 번째 문장처럼 구체적으로 쓴 설명이라도, 코드가 실제로 그렇게 동작하는지는 코드를 열어 대조합니다.
시작 전에 환경과 비용을 확인합니다
설치 조건은 Node.js 22.22.0 이상입니다. Node.js는 자바스크립트 프로그램 실행 환경이고, npm은 패키지를 설치하는 도구입니다. Git은 파일의 변경 이력을 관리하는 도구입니다. 터미널에서 다음 명령을 입력해 세 도구의 버전 번호가 나오면 준비된 것입니다.
node --version
npm --version
git --version명령을 찾을 수 없다고 나오거나 Node.js 버전이 낮으면 해당 도구부터 설치합니다. 회사 장비라면 회사의 설치 절차를 따릅니다. 이 단계에서는 AI 모델을 호출하지 않습니다.
OpenWiki는 오픈소스지만, 문서를 생성하는 AI 모델의 이용료가 따로 들거나 구독 한도가 줄어듭니다. 연결할 모델과 그 모델로 코드가 전송되는 조건을 미리 봅니다. 처음 돌려 볼 저장소는 파일 수가 적고 고객 자료나 API 키가 없는 것으로 고릅니다. API 키는 서비스 접근용 비밀값이라서 코드나 문서에 적지 않습니다.
설치 전에 볼 것
1. Node.jsnode --version
22.22.0 이상
2. npm과 Git버전 번호가
나오는지
3. 모델 비용이용료와 구독 한도
코드 전송 조건
4. 첫 저장소파일이 적고
비밀값이 없는 것
연결 방식은 둘 중 하나를 고릅니다
공식 빠른 시작은 이미 쓰는 코딩 에이전트에 OpenWiki를 연결하는 방식입니다. 코딩 에이전트는 Codex나 Claude Code처럼 터미널에서 코드를 읽고 고치는 AI 도구입니다. 모델 제공자를 직접 설정하는 독립 CLI 방식도 있습니다.
두 연결 방식의 차이
| 항목 | ||
|---|---|---|
| 전제 조건 | Codex나 Claude Code에 로그인된 상태 | 모델 제공자와 인증 정보 |
| 시작 명령 | integrations install | openwiki --init |
| 변경 반영 | 에이전트에게 갱신 요청 | openwiki --update |
어느 방식이든 먼저 패키지를 설치합니다. 이 명령은 사용자 계정 전체에 프로그램을 추가합니다.
npm install -g openwiki기존 에이전트로 시작할 때: 저장소 폴더에서 쓰는 도구에 맞는 명령 하나만 실행합니다. Codex라면 다음 명령입니다.
openwiki integrations install codex --project .Claude Code라면 위 명령 대신 다음을 실행합니다.
openwiki integrations install claude --project ..은 현재 폴더라는 뜻입니다. --project .를 빼면 기본 설치 범위가 사용자 전체라서 다른 저장소에도 연결됩니다. 연결한 뒤 에이전트를 다시 시작하고 같은 저장소를 엽니다.
독립 CLI로 시작할 때: 저장소 폴더에서 아래 명령을 한 번 실행해 모델 제공자와 인증 정보를 설정하고 위키를 생성합니다. 설정 중 LangSmith 연결은 선택 사항입니다. LangSmith는 AI 실행 과정을 기록해 살펴보는 LangChain의 서비스라서, 연결한다면 어떤 자료가 기록되는지 팀 기준과 맞춰 봅니다.
openwiki --init작은 저장소에서 위키를 처음 만듭니다
예를 들어 저장소에 할인 금액을 계산하는 discount.js 파일이 있다고 해 봅시다. 반올림이나 입력 오류 처리는 없고, 가격에 0.9를 곱해 돌려주는 함수 하나뿐입니다.
function discount(price) {
return price * 0.9;
}
console.log(discount(10000));위키를 만들기 전에 코드가 실제로 어떻게 동작하는지 한 번 실행해 둡니다. 이 결과가 나중에 위키 설명과 대조할 기준이 됩니다.
README.md에는 ‘양의 정수 가격에 10% 할인을 적용하는 코드’라고 적어 두었다고 합시다. 위키를 만들기 전에 두 파일을 커밋해 둡니다. 커밋은 지금 상태를 변경 이력에 기록하는 일이고, 나중에 OpenWiki가 이 기록을 기준으로 바뀐 부분을 찾습니다.
git add discount.js README.md
git commit -m "Add discount function"에이전트 연결 방식이라면 에이전트에게 다음처럼 요청합니다. 독립 CLI 방식이라면 openwiki --init의 안내를 따라 생성까지 진행합니다.
현재 저장소의 코드와 README를 근거로 OpenWiki를 초기화해 주세요.
discount 함수의 입력과 반환값, 예시를 설명해 주세요.
코드에 없는 반올림이나 입력 검증 기능을 있다고 쓰지 마세요.
코드 파일을 수정하거나 외부로 게시하지 마세요.위키를 한 번 만든 뒤에는 초기화 명령을 다시 쓰지 않습니다. 재초기화는 기존 위키를 새로 만들기 때문에, 코드 변경을 반영할 때는 갱신을 씁니다.
생성 후에는 무엇을 읽나요?
생성된 문서에서 할인 함수 설명을 찾아 코드와 한 줄씩 맞춰 봅니다.
할인 함수 설명을 코드와 대조할 곳
| 항목 | ||
|---|---|---|
| 입력 | price | 가격 하나 |
| 반환값 | price * 0.9 | 가격의 90% |
| 예시 | discount(10000) | 결과 9,000 |
| 반올림, 오류 처리 | 제공하지 않음 | 없다고 적거나 언급하지 않음 |
어떤 파일이 새로 생기고 바뀌었는지는 터미널의 git status --short로 봅니다. git diff는 이미 기록된 파일의 바뀐 줄만 보여 주고 새 파일의 본문은 보여 주지 않으므로, 새로 생긴 위키 문서는 편집기에서 직접 엽니다.
OpenWiki는 AGENTS.md에 자체 관리 블록을 두고, CLAUDE.md가 이미 있으면 그 파일의 관리 블록도 갱신합니다. 블록 바깥에 적어 둔 기존 작업 규칙은 그대로 두도록 만들어져 있으니, 처음 생성한 뒤 두 파일의 바뀐 부분이 관리 블록 안뿐인지 git diff로 봅니다.
할인율을 10%로 정한 이유처럼 코드에 없는 설계 배경은 AI가 코드만 보고 알 수 없습니다. 이런 내용을 위키에 넣으려면 결정 기록 문서를 저장소에 함께 두고 그 문서를 근거로 쓰라고 요청합니다.
문서 맨 위의 표시는 무엇인가요?
OKF(Open Knowledge Format)는 문서의 종류와 근거 등을 일정한 형식으로 담는 규격입니다. 현재 규격은 v0.2이고, 문서 첫 부분의 YAML 프런트매터에서 type이 필수입니다. YAML 프런트매터는 문서 맨 위 --- 사이에 항목과 값을 적는 부분입니다. 제목과 태그 등은 더할 수 있습니다. 아래는 이해를 돕기 위해 직접 쓴 예입니다.
---
type: Reference
title: 할인 함수 설명
description: discount 함수의 입력과 반환값
tags: [discount]
---generated에는 문서를 생성한 주체와 시각을, verified에는 근거를 확인한 주체와 시각을 적습니다. 생성 날짜가 최근이어도 사람이 검토했다는 표시는 아닙니다. 자동 도구가 확인한 내용은 사람의 검수로 바꿔 적지 않습니다.
한 줄 바꾼 뒤 갱신을 확인합니다
할인율을 20%로 바꾸는 경우를 예로 들면, 코드와 README를 고치고 커밋한 뒤 위키를 갱신하고 결과를 대조합니다.
할인율을 20%로 바꿨을 때 갱신 순서
1. 코드와 README 수정0.9 → 0.8
10% → 20%
2. 실행node discount.js
8000이 나오면 성공
3. 커밋두 파일의 변경을
이력에 기록
4. 위키 갱신openwiki --update
또는 에이전트에게 요청
5. 위키 대조20% 할인,
결과 8,000
3단계의 커밋 명령은 다음과 같습니다.
git add discount.js README.md
git commit -m "Change discount to twenty percent"에이전트 연결 방식이라면 4단계에서 ‘지난 성공 실행 이후의 변경에 맞춰 OpenWiki를 갱신하고 할인율과 예시 결과를 확인해 주세요’라고 요청합니다. 독립 CLI 방식이라면 다음 명령을 실행합니다.
openwiki --update위키의 현재 동작 설명이 20% 할인과 8,000원 결과로 바뀌었으면 갱신이 된 것입니다. 변경 이력을 설명하는 부분에는 예전 10%가 남아 있을 수 있으니, 현재 동작을 설명한 부분과 구분해 읽습니다. 위키가 그대로라면 명령을 실행한 저장소가 맞는지, 커밋이 기록됐는지, 실행 결과에 오류가 있는지 차례로 봅니다. 명령이 끝났다고 완료된 것이 아니라, 코드, 실행 결과, 현재 문서 설명이 서로 맞아야 완료입니다.
자동 갱신은 수동 갱신을 확인한 뒤 설정합니다
GitHub Actions는 GitHub 저장소에서 정해진 때에 작업을 실행하는 기능입니다. 공식 예시대로 워크플로 파일과 제공자 인증, 쓰기 권한을 설정해 두면, GitHub Actions가 예약된 시각에 위키를 갱신하고 문서 변경 PR을 만듭니다. PR은 변경 내용을 검토한 뒤 합치기 위한 요청입니다. OpenWiki를 설치한다고 예약 작업이 저절로 켜지지는 않고, 저장소마다 이 설정을 따로 합니다.
자동 갱신 PR이 만들어지기까지
1. 워크플로 파일공식 예시 파일을
저장소에 추가
2. 제공자 인증모델 제공자의
인증 정보 등록
3. 쓰기 권한PR을 만들 수 있게
권한 설정
4. 예약 실행위키 갱신 후
문서 변경 PR
5. PR 검토본문의 실행 결과와
작업 로그 읽기
이 예시 워크플로는 실행이 중간에 실패해도 그때까지 완료한 문서를 PR로 남깁니다. 그래서 PR이 열렸다는 것만으로 갱신이 끝났다고 보지 않고, PR 본문의 실행 결과와 작업 로그에서 일부만 생성됐는지 봅니다. 모델 제공자와 LangSmith 기록 설정도 팀 기준에 맞춰 고릅니다.
문서 구조를 그림으로 보려면 생성한 뒤 openwiki visualize를 실행합니다. 화면은 내 컴퓨터의 로컬 주소에서 열리지만, 화면을 그리는 라이브러리는 공용 CDN에서 불러오므로 인터넷 연결이 필요합니다. CDN은 웹 파일을 여러 지역 서버에서 나눠 전달하는 서버망입니다. 이 화면을 파일로 내보내는 일과 외부에 게시하는 일은 별개의 작업입니다.
팀에서 쓸지는 같은 질문을 위키 없이 한 번, 위키를 쓰게 해서 한 번 AI에게 물어 비교해 보고 정합니다. 답이 맞았는지, 근거로 어느 파일을 댔는지, 답을 확인하는 데 시간이 얼마나 걸렸는지를 기록해 두면 비교할 근거가 생깁니다.
Sources

제대로 이해했는지 한 문제로 확인해 볼까요?
답을 고르면 바로 풀이가 나와요.
OpenWiki 갱신 PR이 만들어졌다면 무엇을 확인해야 하나요?

새 글과 AI 소식을 메일로 받아 보세요
AI가 바꾸는 일과 도구, 측정 실무 이야기를 매주 한 번 보내 드려요.
이 글이 도움이 되었나요?
메일, 회의록, 리포트처럼 반복되는 일을 AI로 자동화하는 순서와 안전장치를 다룹니다
코스 전체 보기 →