deepwiki-rs — Rust로 코드 문서와 AI-ready context를 생성하는 로컬 도구

sopaco/deepwiki-rs는 코드베이스를 분석해 사람이 읽는 기술 문서와 에이전트가 읽을 수 있는 AI-ready context를 생성하는 Rust 기반 CLI다. 고정 커밋의 실제 구현은 전처리 → 연구 에이전트 → 문서 조합 → 디스크/요약 출력의 단계형 pipeline이며, LLM·cache·외부 local documentation sync를 GeneratorContext 안에서 묶는다.

한눈에 보기

• 프로젝트 성격: Rust/Cargo로 작성된 로컬 코드 이해·문서 생성 엔진. CLI 이름은 Litho (deepwiki-rs)로 선언되어 있으며 기본 출력 경로는 ./litho.docs다.
• 공식 설명: “Turn code into clarity” — 프로젝트 구조를 분석하고 핵심 모듈·아키텍처를 찾아 전문적인 기술 문서를 만드는 도구.
• 고정 기준: main의 f90140edfc2fe871726862155b6aa461b14f017b, 2026-07-24, cache JSON에서 raw string을 추출하도록 고친 merge commit.
• 메타데이터 스냅샷: Rust, 1,501 stars, 167 forks, 5 open issues, MIT License, 비아카이브 상태. 수치는 2026-08-08 KST에 조회한 변동 가능한 GitHub snapshot이다.
• 주요 출력: 개요·아키텍처·workflow·핵심 모듈·boundary·조건부 database 문서를 DocTree와 Markdown 파일로 저장하고, 별도 summary report를 생성한다.
• 검증 범위: 저장소 tree와 선택 파일을 정적으로 조사했다. cargo build/test, 실제 대상 저장소 생성, LLM/API 인증, mermaid-fixer 설치, 외부 지식 동기화, 출력 품질 benchmark는 실행하지 않았다.

실행 pipeline

src/generator/workflow.rs의 launch()는 고정 커밋에서 다음 순서를 구현한다.

1. 시작 조건 확인: mermaid-fixer가 설치되어 있는지 확인하고, 없으면 실행을 중단하도록 한다.
2. 실행 컨텍스트 구성: LLMClient, CacheManager, in-memory Memory, Config를 GeneratorContext로 묶는다.
3. 외부 지식 sync: 설정된 local documentation source가 있고 stale하면 KnowledgeSyncer가 .litho/knowledge/local_docs 아래 cache를 갱신한다.
4. PreProcessAgent: 프로젝트 구조·파일·코드 insight를 먼저 수집해 Memory에 저장한다.
5. ResearchOrchestrator: C1 macro, C2 meso, C3–C4 micro에 해당하는 연구 agent와 boundary/database 분석을 실행한다.
6. DocumentationComposer: overview, architecture, workflow, key modules, boundary, 조건부 database editor가 Memory의 결과를 문서로 조합한다.
7. 출력: DiskOutlet이 DocTree를 저장하고 SummaryOutlet이 요약 리포트를 추가한다. 각 단계와 전체 실행 시간도 Memory에 기록한다.

이 구조는 단순한 README 요약기가 아니라, 전처리 결과를 공유 메모리로 전달하면서 분석과 문서화를 분리하는 staged generation pipeline으로 해석할 수 있다. 다만 이 해석은 구현 구조에 대한 분석이며, 실제 출력 품질을 측정한 결과는 아니다.

연구 에이전트 구조

src/generator/research/orchestrator.rs의 고정 소스에서 확인되는 순서는 다음과 같다.

단계	구현 agent	역할
C1 macro	SystemContextResearcher	시스템 전체 맥락
C2 meso	DomainModulesDetector	도메인/모듈 식별
C2 meso	ArchitectureResearcher	아키텍처 패턴
C2 meso	WorkflowResearcher	실행 workflow
C3–C4 micro	KeyModulesInsight	핵심 모듈 세부 분석
boundary	BoundaryAnalyzer	외부 경계·인터페이스
조건부	DatabaseOverviewAnalyzer	database 파일이 감지될 때만 실행

각 agent는 StepForwardAgent 추상화를 사용한다. 고정 소스는 required/optional data source, structured extract와 일반 prompt, formatter, prompt compressor, Memory retriever를 분리해 agent별 입력을 조정한다. 프로젝트 파일 수가 많으면 boundary 분석에서 전체 파일 대신 directory tree를 사용하도록 제한할 수 있다.

README와 일부 영어 문서는 이 구성을 “8 specialized agents”로 설명하지만, 고정 커밋의 orchestrator와 agent 디렉터리에는 항상 실행되는 6개와 조건부 1개, 총 7개 구현 agent가 확인된다. 이 문서에서는 문서의 마케팅/설명 수치보다 fixed source의 실행 경로를 우선하며, 이 불일치를 contested: true로 보존한다.

LLM·설정·cache

• 설정 모델은 project name/path, output path, .litho internal path, target language, dependency 분석 여부, hidden/git-tracked file 정책, exclude directories, LLM, cache, knowledge, boundary analysis를 포함한다.
• 지원 provider enum은 openai, moonshot, deepseek, mistral, openrouter, anthropic, gemini, ollama다. 기본 provider는 OpenAI이며, Ollama는 local provider로 API key 없이 사용할 수 있도록 설명되어 있다.
• CLI는 efficient/powerful model을 분리해 받고, API base URL·API key·max tokens·temperature·parallelism·tool concurrency·target language를 override할 수 있다. 위키에는 어떤 secret 값도 저장하지 않았다.
• cache는 prompt hash, response, token usage, model name, timestamps 등을 기록하는 구조이며, cache 비활성화·강제 재생성 옵션이 CLI에 있다. 고정 커밋의 마지막 수정은 cached JSON Value를 JSON 직렬화한 문자열이 아니라 raw string으로 추출하도록 고친 것이다.
• target language 목록은 CLI에 zh, en, ja, ko, de, fr, ru, vi로 선언되어 있다.

외부 지식과 agent context

KnowledgeSyncer는 현재 local documentation source를 중심으로 동작한다.

• category별 glob 경로를 확장해 Markdown/문서 파일을 처리한다.
• chunking 설정과 category metadata를 사용하고, 결과를 language·category별 cache에 기록한다.
• agent가 특정 category와 filter로 cached knowledge를 읽어 prompt context에 결합할 수 있다.
• SyncKnowledge CLI subcommand는 stale cache를 재사용하거나 --force로 강제 sync하는 표면을 제공한다.

저장소에는 .ai-context/와 .agents/skills/ai-context-generator/도 함께 포함되어 있다. 이들은 프로젝트 essence, architecture, decisions, dynamics, maintenance 지식을 정리하고 AI agent가 코드베이스를 다룰 때 먼저 읽을 context를 만드는 절차를 제공한다. 따라서 deepwiki-rs는 생성된 문서 output뿐 아니라, 이후 agent 작업에 재사용할 context artifact를 별도 관심사로 취급한다.

포함된 skills

• .agents/skills/ai-context-generator: 프로젝트 구조와 코딩 규칙을 분석해 AI context 문서를 갱신하는 skill.
• skills/smart-docs: progressive analysis, architecture pattern recognition, C4 model, Mermaid diagram, Markdown output을 강조하는 Claude Code용 skill. 저장소 설명은 이를 외부 API 비용이 없는 Litho/deepwiki-rs 대안으로 포지셔닝하지만, 실제 skill 실행은 이번 ingest에서 확인하지 않았다.
• skills/README.md는 위 skills를 코드베이스 문서화·온보딩·아키텍처 이해 workflow에 연결한다.

설계상 강점과 주의점

강점

• 전처리·연구·조합·출력을 분리해 각 단계의 결과와 실행 시간을 Memory에 남긴다.
• 연구 agent와 문서 editor를 분리해 “무엇을 조사하는가”와 “어떻게 문서화하는가”를 구분한다.
• OpenAI-compatible 계열과 여러 provider, Ollama, cache, target language를 설정으로 노출한다.
• local documentation sync를 generator context에 연결해 프로젝트 자체 코드 외의 내부 지식을 category 단위로 주입할 수 있다.
• Markdown 문서와 Mermaid 중심의 구조를 사용하고, mermaid-fixer 의존성을 시작 시 확인한다.

주의점

• 실행 시 mermaid-fixer가 별도 설치되어 있어야 하며, 이 조건을 실제 환경에서 검증하지 않았다.
• LLM provider·API key·모델 품질·prompt 길이·parallelism이 결과와 비용을 좌우한다.
• README/docs의 agent 개수와 fixed source의 실제 agent 개수가 일치하지 않는다.
• pinned tree에 dedicated tests/ 디렉터리가 보이지 않는다. 이는 테스트가 전혀 없다는 증거가 아니며, 이번 캡처에서는 별도 test 실행도 하지 않았다.
• GitHub API의 별(star)·fork·issue 수는 현재 상태를 보장하지 않는 시점 snapshot이다.

재현·검증 경계

이번 ingest에서 확인한 것

• GitHub REST metadata와 recursive tree (241 entries, truncated: false).
• main과 HEAD의 fixed commit 일치.
• README, Cargo metadata, English docs, .ai-context, skills, pipeline과 핵심 Rust 파일의 내용·SHA-256.
• CLI provider/config 표면, 연구 agent 호출 순서, documentation composer, cache·knowledge sync 구현 구조.
• 선택 Rust 파일과 JSON/TOML/YAML 문서의 정적 provenance 기록.

아직 확인하지 않은 것

• cargo build, cargo test, release binary 실행.
• 실제 다른 저장소를 대상으로 한 문서 생성과 output completeness/accuracy.
• API key를 사용한 OpenAI·Anthropic·Gemini·DeepSeek·OpenRouter 등 외부 provider 호출.
• Ollama local inference, prompt/token 비용, parallelism 및 cache hit-rate benchmark.
• mermaid-fixer 설치·Mermaid diagram repair.
• SyncKnowledge를 이용한 실제 local docs 수집·chunking·cache read-back.
• 생성된 Markdown을 브라우저/문서 사이트로 발행하는 end-to-end 검증.

출처

• Raw provenance: raw source: github-sopaco-deepwiki-rs
• GitHub repository: sopaco/deepwiki-rs
• Fixed commit: f90140edfc2fe871726862155b6aa461b14f017b
• README fixed raw: README.md

관련 MOC

• moc-ai-agents
• moc-ai-agents-orchestration
• moc-ai-coding
• moc-dev-tools