Claude Code의 컨텍스트 낭비를 해결하기 위해 로컬 문서 CLI 도구를 개발했습니다

커뮤니티 반응

작성자가 직접 개발한 도구에 대해 긍정적인 반응이 예상되며, 특히 컨텍스트 비용 절감 측면에서 실무적인 관심을 받고 있다.

주요 논점

01찬성다수

로컬 RAG를 통해 컨텍스트 낭비를 막고 에이전트의 정확도를 높이는 접근 방식이 효율적이다.

합의점 vs 논쟁점

합의점

대규모 문서를 에이전트에 직접 붙여넣는 방식은 컨텍스트 낭비가 심하다.
로컬 벡터 DB를 활용한 검색 방식이 비용과 성능 면에서 유리하다.

실용적 조언

Claude Code 사용 시 컨텍스트 부족 문제를 겪는다면 Docmancer를 설치하여 로컬 문서 DB를 구축하십시오.
docmancer install 명령어를 통해 에이전트에 스킬을 추가하면 별도 설정 없이 문서 검색 기능을 사용할 수 있습니다.

섹션별 상세

작성자는 Claude Code 사용 시 Stripe나 AWS 같은 대규모 문서를 직접 붙여넣으면 컨텍스트의 절반이 소모되고 모델이 잘못된 API를 생성하는 문제를 겪었다. 입력 데이터가 많아질수록 모델의 추론 성능이 저하되고 불필요한 토큰 비용이 발생하는 한계가 명확했다. 이를 해결하기 위해 문서를 로컬에 임베딩하고 필요한 부분만 검색하여 주입하는 로컬 RAG 방식을 채택했다. 이 방식은 에이전트가 방대한 문서 전체를 읽지 않고도 정확한 API 명세를 참조하게 한다.

Docmancer는 GitBook, Mintlify, Docusaurus 등 다양한 소스에서 문서를 수집하여 청킹한 뒤 로컬 Qdrant DB에 저장하는 프로세스로 작동한다. 사용자가 특정 질문을 던지면 CLI가 DB에서 가장 유사도가 높은 문서 조각을 검색하여 에이전트의 컨텍스트로 전달한다. Claude Code가 CLI 명령어를 직접 실행하여 DB에서 관련 섹션만 조회하도록 설계되어 컨텍스트 낭비를 최소화한다. 로컬 환경에서 모든 처리가 이루어지므로 데이터 유출 우려가 적고 응답 속도가 빠르다.

bash

docmancer ingest https://docs.example.com
docmancer query "How do I authenticate?"
docmancer install claude-code

Docmancer CLI의 주요 명령어 사용 예시이다.

Docmancer CLI의 도움말(--help) 화면 스크린샷이다. — Screenshotfetch, ingest, query, install 등 도구의 핵심 명령어와 사용 예시를 나타낸다. 특히 docmancer install claude-code 명령어를 통해 에이전트에 기능을 연동하는 과정을 확인할 수 있다.

이 도구는 별도의 API 키나 계정, MCP 서버 없이 로컬에서 즉시 실행 가능하며 MIT 라이선스로 공개됐다. 설치 후 docmancer install 명령어를 실행하면 Claude Code의 스킬로 등록되어 에이전트가 자율적으로 문서를 검색할 수 있게 된다. Claude Code뿐만 아니라 Cursor 및 Codex와도 호환되어 다양한 코딩 에이전트 환경에서 범용적으로 활용할 수 있다. 오픈소스 프로젝트로서 커뮤니티의 피드백을 수용하며 지속적인 기능 개선을 목표로 한다.

용어 해설

검색 증강 생성(RAG): — 외부 지식을 검색하여 LLM의 응답 정확도를 높이는 기술이다. 문서를 벡터화하여 저장한 뒤 질문과 관련된 부분만 추출해 컨텍스트로 제공함으로써 환각 현상을 줄이고 최신 정보를 반영한다.
컨텍스트 윈도우(Context Window): — 모델이 한 번에 처리할 수 있는 토큰의 최대 범위를 의미한다. 긴 문서를 모두 입력하면 이 범위를 초과하거나 비용이 급증하므로 효율적인 관리가 필수적이다.
벡터 데이터베이스(Vector Database): — 데이터를 고차원 벡터로 변환하여 저장하고 유사도 기반 검색을 수행하는 저장소이다. RAG 시스템에서 관련 문서를 빠르게 찾아내는 핵심 인프라 역할을 한다.

언급된 도구

Docmancer추천링크

코딩 에이전트용 로컬 문서 RAG CLI 도구

Qdrant추천

로컬 벡터 데이터베이스 저장소

언급된 리소스

GitHubDocmancer GitHub Repository