대규모 코드베이스 컨텍스트: claude-context vs RAG 2026
대규모 repo에서 토큰 비용이 폭증하는 이유
풀스택 입문자가 같은 벽에 부딪힙니다.
- 「repo 전체를 읽어줘」 — 200파일×약 2k 토큰 ≈ 40만 토큰(답변 전에 수 달러)
- grep 스파이럴 — 매 hit마다 파일 전체를 열어 무관한 import로 컨텍스트가 찹니다
- 망각 리팩터 — 3턴째에 1턴을 잊음(호스트가 히스토리 절단)
Cursor·Claude Code 증상: 「context full」, 요약 압축, 파일 내용 조용한 드롭.
해답은 더 큰 모델이 아니라 검색(retrieval)입니다. 8~20개의 작은 청크(각 200~600 토큰)를 가져오고 파일 8개 통째(각 3k+)는 피하세요.
두 접근 비교표
| 차원 | claude-context (MCP) | LlamaIndex RAG |
|---|---|---|
| 정체 | 기성 MCP+인덱서 (@zilliz/claude-context-mcp) | 직접 조립 Python |
| 청킹 | AST + Merkle 증분 | 선택 (CodeSplitter 등) |
| 검색 | 하이브리드 BM25+벡터 | 주로 벡터 |
| 벡터 DB | Milvus / Zilliz Cloud | Chroma, Qdrant, pgvector… |
| IDE 통합 | Claude Code, Cursor (MCP) | 스크립트, 커스텀 봇 |
| 첫 검색까지 | 약 30~90분 (10만~50만 LOC) | 튜닝 시 수시간~수일 |
| 지속 비용 | 임베딩 API+벡터 호스팅 | 동일(전 라인 자체 관리) |
| 최적 | IDE 「repo 검색」 | 혼합 코퍼스, 온프레만 |
참고: LlamaIndex 문서, claude-context GitHub.
claude-context 동작 (MCP)
Your repo ──► AST chunker + embeddings ──► Milvus/Zilliz index
│
User question ──► Claude/Cursor ──► MCP search_code ──► top-K chunks ──► model context
일반 도구: index_codebase, search_code, get_indexing_status, clear_index.
하이브리드가 코드에 필요한 이유: 순수 벡터는 UserAuthService_v2 같은 심볼을 놓칩니다. BM25는 식별자, 벡터는 「JWT 만료 검증 위치」 같은 의미를 잡습니다.
claude mcp add claude-context \
-e OPENAI_API_KEY=your_key \
-e MILVUS_TOKEN=your_zilliz_token \
-- npx @zilliz/claude-context-mcp@latest
세션에서 한 번 index 후 자연어 질의. 커스텀 MCP와 병행해 내부 API도 같은 호스트에 둘 수 있습니다.
LlamaIndex RAG (DIY)
Documents ──► LlamaIndex loaders ──► chunk ──► embed ──► VectorStoreIndex
│
Question ──► query_engine.query() ──► retrieved nodes ──► LLM prompt
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.embeddings.openai import OpenAIEmbedding
Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")
docs = SimpleDirectoryReader("~/my-monorepo", recursive=True).load_data()
index = VectorStoreIndex.from_documents(docs)
qe = index.as_query_engine(similarity_top_k=8)
print(qe.query("Where is rate limiting configured for the public API?"))
직접 추가: node_modules 제외, 언어별 스플리터, path:packages/api/** 필터, MCP 래퍼(선택).
강점: PDF 런북+Jira+코드를 한 retriever에 — claude-context는 코드 우선입니다.
토큰 산출 (감사 시나리오)
과제: 「모든 auth middleware 찾고 CSRF를 건너뛰는 라우트 나열」. 약 1,200파일, 6함수·4경로.
| 전략 | 주입 토큰(크기) | 비고 |
|---|---|---|
src/ 트리+무작위 10파일 | 12만~25만 | 가장 빠른 파산 |
| grep+전체 파일(5 hit) | 2.5만~6만 | 보일러플레이트 多 |
| claude-context top-8 | 3k~8k | 함수 단위 |
| LlamaIndex top-8 | 3k~1만 | 유사 |
| 사람(파일 2개) | 약 2k | RAG 이상형 |
탐색 작업에서 naive 「전부 읽기」 대비 70~90% 낮춤이 흔합니다. 한 줄 수정은 grep이면 충분할 때도 있습니다.
숨은 비용: 첫 인덱스(50만 LOC 약 $0.50~$5), 벡터 호스팅(무료 티어 $0~25/월), 대규모 머지 후 재인덱스.
시나리오별 선택
시나리오 A — Cursor / Claude Code, GitHub monorepo
「billing webhook 검증기 위치」를 @ 없이 묻고 싶다면 claude-context. 호스트는 Claude Code 대안 위에 MCP를 얹는 패턴이 많습니다.
시나리오 B — 컴플라이언스 에어갭
LlamaIndex + 로컬 LanceDB/Chroma. claude-context 기본은 외부 임베딩 API·Milvus 가정 — 오프라인 임베딩을 명시 설계하세요.
시나리오 C — OpenClaw / ECC 야간 스캔
OpenClaw 멀티 에이전트는 토큰을 증폭합니다. repo당 단일 인덱스를 모든 워커가 공유하는 편이 각자 src/를 재읽는 것보다 낫습니다.
시나리오 D — 긴 스레드에서 context 리셋
검색은 채팅 히스토리를 늘리지 않고 턴 주입을 줄입니다. 작업마다 새 세션, 청크만 pin, 2k줄 파일 재붙여넣기 금지. ECC 가이드 참고.
8단계 병렬 런북
1~4단계 — 공통 준비
- 베이스라인 측정 — 1주 「grep+전체 파일」 지출 기록.
- 파일럿 repo 하나 — 먼저 단일 서비스.
- ignore 규칙 —
node_modules,dist,.git, 생성 protobuf 제외. - 벤치마크 질문 3개 — auth, billing webhook, feature flag.
5~8단계 — 경로 A: claude-context
- MCP 등록;
claude mcp list확인. index_codebase;get_indexing_status완료 대기.- 「search_code: admin 라우트 CSRF 비활성 위치?」 — 인용이 chunk 크기인지 확인.
- 해당 턴 토큰을 베이스라인과 비교.
5~8단계 — 경로 B: LlamaIndex
- venv에서
pip install llama-index llama-index-embeddings-openai. persist_dir="./rag_index"로 영속화.- 20줄 CLI 또는 FastAPI로
query_engine래핑. - 동일 3질문으로 품질·임베딩 항목 비교.
로컬 호스팅 (선택)
인덱싱은 CPU+디스크 부담(API 임베딩이면 GPU 불필요). 상시 Mac 16GB로 Milvus Lite급 중형 repo, Ollama 병행 시 24GB. M4 메모리 매트릭스로 사이징 — 서울 노드 Anthropic API 중앙값 RTT 29ms(API 지연 참고만).
문제 해결
search_code 빈 결과
경로 오류·오래된 index → 절대 경로로 index_codebase 재실행, src/ ignore 여부 확인.
LlamaIndex가 잘못된 패키지
monorepo 혼합 → MetadataFilter(key="file_path", value="packages/api").
RAG 후에도 고비용
검색 후 전체 파일 읽기 → 「청크만, 부족할 때만 전체 파일」 프롬프트.
Node 24 실패
업스트림 Node <24 → nvm use 22.
권장 경로
| 상황 | 선택 |
|---|---|
| Claude Code / Cursor, 최단 효과 | claude-context |
| 문서+코드+티켓 혼합 | LlamaIndex |
| 클라우드 벡터 DB 제로 | LlamaIndex+로컬 DB |
| 기존 MCP | claude-context 추가 |
| 200줄 단일 파일 | 둘 다 불필요 |
MCP 호스트에서 repo 검색이 아프면 claude-context. 커스텀 코퍼스가 아프면 LlamaIndex.
FAQ
claude-context가 Claude 프로젝트 지식과 같나요?
아닙니다. 별도 인덱서이며 하이브리드 코드 검색·증분 동기화가 있습니다.
LlamaIndex가 대체하나요?
코드 Q&A에서 겹칩니다. LlamaIndex는 넓고 자체 호스팅, claude-context는 IDE 통합에 특화됩니다.
RAG가 잘못된 편집을 고치나요?
아닙니다. 발견을 개선합니다. 테스트·리뷰는 필수입니다.
재인덱싱 주기는?
대규모 머지 후 또는 활발한 main에서 주간이 일반적입니다.
중국 본토 npm/네트워크는?
안정적인 원격 개발 박스(SSH)에서 인덱싱해 경로를 일정하게 유지 — OpenClaw 원격 설정과 유사한 패턴입니다.