OpenWiki: CLI that writes and maintains agent documentation for your codebase

TL;DR Highlight

LangChain이 만든 CLI 도구로, AI 에이전트가 코드베이스를 이해하는 데 필요한 문서를 자동으로 생성하고 최신 상태로 유지해준다. 코딩 에이전트(Copilot, Claude 등)의 컨텍스트 품질을 높이고 싶은 개발자에게 유용하다.

Who Should Read

AI 코딩 에이전트(GitHub Copilot, Claude 등)를 팀 워크플로에 도입했는데, 에이전트가 코드베이스를 제대로 이해 못해 엉뚱한 코드를 생성하는 문제를 겪고 있는 개발자나 팀 리드.

Core Mechanics

OpenWiki는 npm으로 전역 설치(`npm install -g openwiki`)하고 `openwiki --init`으로 초기화하면, 현재 코드베이스를 분석해 에이전트 전용 문서를 `openwiki/` 디렉토리에 자동 생성한다.
한 번 설치하면 그걸로 끝이 아니라, 제공된 GitHub Actions 워크플로 파일(`openwiki-update.yml`)을 저장소에 추가하면 매일 한 번 자동으로 문서 업데이트 PR을 열어준다. 코드가 바뀌어도 문서가 자동으로 따라온다.
생성된 문서는 AGENTS.md(AI 에이전트 범용)와 CLAUDE.md(Anthropic Claude 전용) 파일에도 자동으로 참조 프롬프트를 추가한다. 해당 파일이 없으면 새로 만들어준다. 이를 통해 에이전트가 문서를 먼저 찾아보도록 유도한다.
인터랙티브 모드와 one-shot 모드를 둘 다 지원한다. 대화하듯 쓰려면 `openwiki`를 실행하고, 자동화 스크립트에서 쓰려면 `openwiki -p "요청"` 처럼 단일 명령으로 결과만 출력할 수 있다.
초기 실행 시 inference provider(어떤 LLM 서비스를 쓸지), API 키, 모델명을 설정한다. 특정 LLM에 종속되지 않고 provider를 선택할 수 있는 구조다.
문서가 이미 `openwiki/` 디렉토리에 존재하면 `--update` 명령으로 저장소 변경분만 반영해 갱신한다. 처음부터 다시 쓰는 게 아니라 차분(diff) 방식으로 유지보수하는 방식이다.
이 프로젝트 자체의 `openwiki/` 디렉토리가 OpenWiki로 생성한 문서 예시다. 직접 GitHub 저장소에서 어떤 형태의 문서가 나오는지 확인할 수 있다.

Evidence

"그냥 에이전트한테 문서 써달라고 하면 되는 거 아닌가?"라는 의견이 여럿 나왔다. 이에 대해 OpenWiki의 차별점은 에이전트가 스스로 문서를 유지(maintain)하는 자동화 루프를 제공하는 것이지, 단순히 문서를 한 번 생성하는 게 아니라는 반론이 있었다.
"결국 TypeScript로 만든 얇은 CLI 래퍼에 불과하다, 프롬프트/스킬로 충분히 대체 가능하다"는 비판이 있었다. 실제로 기능 자체는 좋은 프롬프트만으로도 비슷한 결과를 낼 수 있어 과잉 설계(over-engineered)라는 평가가 나왔다.
LLM 기반 wiki를 직접 유지해본 사람의 경험담이 공유됐다. 에이전트와 사람 모두가 쉽게 찾아볼 수 있도록 구조와 문서 품질을 유지하는 게 생각보다 훨씬 손이 많이 간다고 했다. OpenWiki 같은 자동화 도구의 필요성이 여기서 나온다.
"OpenWiki"라는 이름이 사람을 위한 wiki인지 에이전트를 위한 것인지 혼동을 준다는 UX 피드백이 있었다. 'Agent Wiki' 같은 이름이 더 적절하다는 제안도 나왔다.
코드 심볼 검색 능력이 Codegraph 같은 도구와 비교해 어떤지에 대한 질문이 있었고, LSP나 code intelligence MCP를 함께 쓰면 더 좋은 결과를 낼 수 있다는 의견이 있었다. 다만 동기나 비즈니스 맥락처럼 코드에서 추론할 수 없는 내용은 여전히 사람이 직접 채워야 한다고 지적했다.

How to Apply

Claude나 Copilot 같은 AI 코딩 에이전트를 도입했는데 에이전트가 레포 구조를 잘 모르는 경우, `npm install -g openwiki` 후 `openwiki --init`을 실행해 `openwiki/` 문서를 생성하면 에이전트의 컨텍스트 품질을 즉시 높일 수 있다.
코드가 자주 바뀌는 활발한 저장소라면, 제공된 `openwiki-update.yml`을 `.github/workflows/`에 추가해 매일 자동으로 문서 업데이트 PR이 열리도록 설정하면 문서를 별도로 관리할 필요가 없어진다.
CI/CD 파이프라인이나 GitHub Actions에서 one-shot으로 특정 모듈 문서를 생성하고 싶다면, `openwiki -p "Generate documentation for the auth module"` 처럼 비대화형(-p) 모드를 사용하면 스크립트에 쉽게 통합할 수 있다.
이미 AGENTS.md나 CLAUDE.md 파일을 관리하고 있다면, OpenWiki가 해당 파일에 문서 참조 프롬프트를 자동으로 추가해주므로 별도의 파일 편집 없이도 에이전트가 생성된 wiki를 자동으로 찾아보게 만들 수 있다.

Code Example

snippet

# 전역 설치
npm install -g openwiki

# 초기화 (provider, API key, LLM 설정)
openwiki --init

# 문서 생성 (대화형)
openwiki "Please generate documentation for this repository"

# 문서 생성 (비대화형, CI/CD용)
openwiki -p "Summarize what you can do"

# 기존 문서 업데이트
openwiki --update

# GitHub Actions 자동 업데이트 설정
# .github/workflows/openwiki-update.yml 파일 추가 필요
# 저장소에서 openwiki-update.yml 내용을 복사해서 사용

Terminology

AGENTS.mdAI 코딩 에이전트(Copilot, Cursor 등)에게 이 저장소를 어떻게 다뤄야 하는지 지시하는 마크다운 파일. 에이전트가 작업 시작 전 먼저 읽는 메뉴얼 같은 것.

CLAUDE.mdAnthropic의 Claude 에이전트 전용 컨텍스트 파일. Claude가 코드 작업할 때 참조하는 프로젝트별 지침서.

inference providerOpenAI, Anthropic, Google 등 실제로 LLM 모델을 실행해주는 서비스. OpenWiki가 문서 생성에 사용할 AI 서비스를 고르는 설정.

one-shot mode대화를 주고받지 않고 명령 한 번에 결과를 출력하고 종료하는 실행 방식. 자동화 스크립트나 CI/CD 파이프라인에서 유용하다.

LSPLanguage Server Protocol. 코드 편집기가 심볼 정의, 참조, 자동완성 정보를 얻기 위해 사용하는 표준 프로토콜. 에이전트가 코드 구조를 더 정확히 파악하는 데 활용 가능.

MCPModel Context Protocol. AI 에이전트가 외부 도구나 데이터 소스에 접근하기 위한 표준 인터페이스. 에이전트가 단순 텍스트 생성을 넘어 코드 검색 등 복잡한 작업을 할 수 있게 해준다.