livewiki

코드에 앵커된 문서 — 언제 낡었는지 스스로 아는 문서.

livewiki는 저장소를 Markdown 위키로 바꿉니다. 이 위키의 모든 코드 참조는 실제로 색인된 심볼에 앵커됩니다. LLM이 산문을 작성하고, livewiki는 결정적 작업, 즉 페이지 계획, 모델이 작성한 내용에 대한 구조적 환각 방지 검사, 변경된 앵커 심볼 추적, 그리고 사용자의 편집 보존을 수행합니다.

이 위키는 @livewiki/mcp 를 통해 모든 코딩 에이전트에 노출됩니다. 이는 위키를 읽고, 검색하고, 안전하게 작성하는 여덟 가지 도구를 제공하는 MCP(Model Context Protocol) 서버입니다.

livewiki view는 위키에서 자체 포함된 오프라인 사이트를 빌드합니다 — 그룹화된 사이드바, 오프라인 검색, 다이어그램, 다크 모드를 제공합니다.

livewiki가 외부 Python 저장소인 MoneyPrinterTurbo-Plus에 대해 생성한 예제 위키입니다.

왜

기술 문서는 코드가 변경되는 순간 낡아버립니다. livewiki는 이를 조용히 방치하지 않고 눈에 보이게 만들고 저렴하게 고칠 수 있게 합니다:

• 결정적 환각 방지 검사. 모든 코드 참조는 실제 색인된 심볼을 가리켜야 합니다. livewiki verify는 디스크에서 위키를 새로 읽어들여, 존재하지 않는 심볼, 깨진 앵커, 더 이상 일치하지 않는 시그니처에 대해 실패 처리합니다 — LLM이 몇 초 전에 작성한 참조도 index를 먼저 실행하지 않고, 토큰을 소비하지 않고 검사합니다. 구조적 검사이지 의미적 검사가 아닙니다. 아래 섹션에서 그 경계를 설명합니다.

• 사용자의 편집이 우선입니다. owner: human으로 표시한 페이지는 절대 다시 작성되지 않으며, lw:manual 블록은 바이트 단위로 보존됩니다.

• 부채는 발견되는 것이 아니라 추적됩니다. livewiki status는 어느 부분이 어긋났는지 순위를 매깁니다. GitHub Action은 토큰을 소비하지 않고 문서화 부채가 0일 때만 모든 머지를 허용하도록 게이트할 수 있습니다.

• 이미 사용하는 환경에서 동작합니다. 사용 중인 코딩 에이전트를 통해 부트스트랩하고 유지 관리하거나, 완전 자동화된 배치를 실행할 수 있습니다.

verify가 검사하는 것과 검사하지 않는 것

환각 방지 계층은 결정적이며 구조적입니다. livewiki verify는 디스크에서 위키를 새로 읽어 들이므로, LLM이 몇 초 전에 작성한 페이지도 index를 먼저 실행하지 않고 검사됩니다. 다음의 경우 실패합니다:

• 코드에 존재하지 않는 인용 심볼;

• 심볼이 이동, 이름 변경, 또는 삭제되어 깨진 앵커;

• 색인된 시그니처와 더 이상 일치하지 않는 인용 시그니처;

• 해석되지 않는 내부 링크;

• 디스크에서 누락된 참조 아티팩트;

• 형식 계약을 위반하는 프론트매터 또는 페이지 구조.

이로써 독자가 보기 전에, 토큰 비용 없이 허위 콘텐츠의 여러 유형, 즉 지어낸 함수, 존재한 적 없는 API, 조용히 썩어버린 참조가 제거됩니다. 실패한 항목은 병합되지 않고 거부되고 롤백됩니다.

문장의 진실성을 증명하지는 않습니다. 실제로 존재하는 코드에 대한 그럴듯하지만 틀린 설명은 위의 모든 검사를 통과합니다. 위의 모든 검사는 의미가 아니라 구조와 정체성에 관한 것이기 때문입니다. 여기서 '환각 방지'는 기계적으로 많은 종류의 허위 구성을 제거하고 코드가 산문 아래에서 움직이는 순간을 알려주는 계층으로 받아들이세요 — 사실적 정확성의 보장이 아닙니다. 설명 자체를 검토하는 일은 여전히 사용자의 몫입니다.

Related MCP server: 50 First Tapes MCP Server

빠른 시작

Node.js 24 이상이 필요합니다.

1. 설치

npm install -g @livewiki/cli

(npx @livewiki/cli도 전역 설치 없이 사용할 수 있습니다.)

2. 초기화

문서화하려는 저장소의 루트에서:

livewiki init

코드를 색인하고 livewiki/ 아래에 위키 뼈대를 만들며, .livewiki/ 아래에 파생 캐시도 만듭니다(.gitignore에 추가됨). 결정적입니다 — LLM 호출도, 토큰도 필요 없습니다.

3. 위키를 한 번 부트스트랩합니다

두 가지 방법이 있습니다 — 하나를 선택하세요.

방법 A — 코딩 에이전트를 통한 방법(API 키 불필요):

livewiki install

설치 프로그램이 사용자의 에이전트를 감지하고 MCP 서버, 문서화하면서 진행하는(document-as-you-go) 스킬, git 훅을 연결합니다. 그런 다음 에이전트에게 위키 부트스트랩을 요청하세요. 에이전트는 livewiki_next_task에서 작업을 가져와 이미 보유한 모델로 livewiki_write_doc을 사용해 페이지를 제출합니다.

방법 B — 구성된 LLM API 사용(무인 실행):

livewiki config

마법사가 제공업체 목록을 보여주고 API 키를 입력받은 다음(입력 내용은 화면에 표시되지 않음) 저장합니다. 구성되지 않은 저장소에서 그냥 livewiki를 실행하면 같은 마법사가 시작됩니다. 그런 다음:

livewiki init --batch

재개 가능한 파이프라인은 실제 페이지 단위를 계획하고 소스 파일과 폴더마다 페이지 하나씩 작성하며, 흐름, 개념 주제, 다이어그램, understanding.md 종합 문서도 작성합니다. 중단하려면 livewiki batch resume <runId>로 재개할 수 있습니다.

4. 검증 및 탐색

livewiki verify   # validate code references, internal links, and artifacts
livewiki view     # build an offline site with search, Mermaid, and dark mode

코딩 에이전트 연동

livewiki install은 13개의 에이전트를 자동 감지하여 MCP로 연결합니다(에이전트가 지원하는 경우 스킬과 훅도 포함):

Claude Code · Codex · Cursor · Kimi · Gemini CLI · OpenCode · OpenClaw · Cline · Kiro · Qwen · Warp · Zed · Hermes

수동 연결을 선호하시나요? stdio MCP 클라이언트는 모두 작동합니다:

{
  "mcpServers": {
    "livewiki": {
      "command": "npx",
      "args": ["-y", "@livewiki/mcp", "--repo", "/path/to/repo"]
    }
  }
}

언어

앵커된 페이지는 실제 심볼을 인용합니다. 산문 하한선은 모든 파일에 위키에서의 자리를 계속 제공합니다. 티어 1 언어 지원은 패턴이 입증됨에 따라 확장됩니다(Go, Rust, Java가 각각 이 방식으로 추가되었습니다).

제공업체

livewiki config는 다음 17개 프리셋을 나열합니다. 각 프리셋은 고유한 API 키 환경 변수를 읽습니다. livewiki config show는 선택한 프리셋이 기대하는 변수명을 출력하되 값은 절대 표시하지 않습니다.

ollama와 lmstudio는 로컬 서버에 키가 필요 없습니다. CI 및 헤드리스 자동화에서는 환경 변수를 직접 설정하세요 — 저장된 키보다 우선합니다.

생성된 페이지의 모습

이 저장소 자체의 livewiki/core-src/verify.md에서 발췌:

## Discovery: walking the wiki from disk

The verifier never trusts the index for which pages exist — a doc freshly written by an LLM must be caught without first running `index`. Two walkers enumerate the `livewiki/` directory from disk; both skip hidden directories but keep dot-prefixed files.

<!-- lw:anchors packages/core/src/verify.ts#collectWikiPages packages/core/src/verify.ts#collectWikiArtifactPaths -->

```ts
async function collectWikiPages(absRoot: string): Promise<{ relPath: string }[]>
```

산문은 구현을 설명하며, lw:anchors 마커는 해당 섹션을 실제 색인된 심볼과 연결하므로 낡음과 잘못된 참조가 기계적으로 감지됩니다.

작동 방식

• 결정적 계층(Deterministic layer) — CLI는 모델 없이 소스를 색인하고, 심볼을 추출하고, 낡음을 계산하고, 작업을 계획하고, 부채를 추적하고, 검증합니다.

• 작성 계층(Writing layer) — 연결된 에이전트(또는 API 기반 배치)가 허용된 심볼 키의 폐쇄 목록에서 산문을 작성합니다.

• 환각 방지 계층(Anti-hallucination layer) — 결정적이고 구조적입니다. 코드 앵커, 인용된 시그니처, 내부 링크, 아티팩트, 페이지 구조가 모두 디스크와 대조되어 검사되며, 유효하지 않은 쓰기는 롤백됩니다. 이는 의미적 오류가 아니라 허위 및 낡은 참조를 제거합니다.

• 인간 소유권(Human ownership) — owner: human 페이지는 절대 다시 작성되지 않으며, lw:manual 블록은 바이트 단위로 보존됩니다.

• 휴대 가능한 베이스라인(Portable baseline) — 모든 문서화 의무에 대한 승인된 상태가 버전 관리되는 livewiki/.baseline.json에 저장됩니다. 따라서 실제 베이스라인을 기준으로 부채가 적용되며 로컬 캐시가 삭제되어도 위키는 유지됩니다.

문서화 부채는 LLM 호출이나 토큰 없이 CI에서 모든 머지를 게이트할 수 있습니다 — GitHub Actions 템플릿을 참조하세요.

과거 비교 방법론과 날짜가 명시된 결과는 Benchmarks에 보관되어 있습니다.

패키지

문서

• SPEC.md — 동작 및 형식 계약

• VISION.md — 제품 근거 및 비목표(non-goals)

• docs/ROADMAP.md — 승인된 백로그 및 실행 순서

라이선스

MIT — LICENSE를 참조하세요.