Claude Context 입문: AI가 코드베이스 전체를 “진짜로” 이해하게 만들기

Claude Context는 벡터 데이터베이스 업체 Zilliz가 개발한 오픈소스 MCP(Model Context Protocol) 플러그인입니다. 핵심 포지션은 매우 명확합니다. AI 코딩 어시스턴트에 코드베이스 전체의 의미 이해 능력을 주입하는 것.

기존 워크플로에서는 낯선 코드베이스를 AI가 이해하도록 만들려면 파일 경로를 직접 복사하고, 프로젝트 구조를 설명하며, 모듈 간 관계까지 직접 풀어줘야 했습니다. 그런데 이건 원래 AI가 스스로 해내야 할 일입니다. Claude Context는 시맨틱 검색 기술을 통해 코드베이스 안의 함수, 클래스, 데이터 구조를 AI가 직접 질의할 수 있게 해 줍니다. 이제 수동으로 문맥을 주입할 필요가 없습니다.

이 프로젝트는 GitHub에서 zilliztech/claude-context로 호스팅되어 있으며, MIT 라이선스를 사용하고 코드 또한 완전히 오픈소스입니다.

---

난이도/소요 시간/얻는 것

입문급 | 약 20분 | 2개의 명령으로 어떤 코딩 도구든 수백만 줄 코드의 의미 이해 능력을 부여하는 방법을 익히고, 토큰 소모를 약 40%까지 줄이는 법을 배웁니다.

---

대상 독자

• 평소 Claude Code, Cursor, Windsurf, Cline 등 AI 프로그래밍 도구를 사용하는 개발자
• RAG(검색 증강 생성)과 벡터 검색에 대한 기본적인 이해가 있고, 이를 실제로 깊게 적용해 보고 싶은 분
• 토큰 비용을 낮추고, AI 응답의 정확도를 높이고 싶은 팀

---

핵심 의존성 및 환경

시스템 요구사항

• Node.js >= 20.0.0 && < 24.0.0
• 운영체제: macOS, Windows, Linux 모두 가능

서비스 의존성

• Zilliz Cloud(무료 티어만으로도 개인 사용에는 충분): 벡터 데이터베이스 백엔드 제공
• OpenAI API Key: embedding 모델이 벡터를 생성하는 데 사용(다른 embedding 제공업체로 교체도 가능)

---

전체 프로젝트 구조 트리

Claude Context는 순수 npm 패키지라서 로컬 코드를 클론하거나 빌드할 필요가 없습니다. 설치 후에는 자체 저장 구조를 관리합니다.

~/.claude/
└── plugins/
    └── claude-context/          # MCP 플러그인 디렉터리
        └── [인덱스 데이터 파일]        # 증분 Merkle 트리 스냅샷

Core 패키지를 앱에 직접 통합한다면 구조는 다음과 같습니다.

your-project/
├── node_modules/
│   └── @zilliz/claude-context-core/
├── .env                        # API Key 저장
└── your-codebase/              # 인덱싱할 코드

---

단계별 진행

1단계: Zilliz Cloud를 등록하고 벡터 데이터베이스 자격증명 얻기

Claude Context의 벡터 저장소는 Zilliz Cloud(또는 자체 호스팅 Milvus)에 의존합니다. 이 단계에서는 무료 계정을 생성해야 합니다.

zilliz.com/cloud 를 열고 이메일 또는 GitHub 계정으로 가입하세요. 로그인 후 콘솔에서 새로운 Serverless Cluster를 만듭니다.

1. Create Cluster 클릭
2. Serverless 타입 선택(무료 티어면 충분)
3. 가장 가까운 리전 선택(AWS us-west-2 또는 싱가포르가 자주 사용됨)
4. 클러스터 이름을 예: claude-context로 지정

클러스터 생성이 완료되면 클러스터 상세 페이지로 들어가 Connection Info를 찾아 아래 두 값을 복사해 두세요.

• Public Endpoint: https://xxx.api.gcp-us-west1.zillizcloud.com 같은 형태
• API Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 같은 형태

2단계: OpenAI API Key 가져오기

Claude Context는 embedding 모델로 코드 조각을 벡터로 변환합니다. 기본 text-embedding-3-small 모델을 구동하려면 OpenAI API Key를 준비해야 합니다.

platform.openai.com/api-keys 를 열고 Create new secret key를 클릭한 뒤, 생성된 값을 복사하세요(형식: sk-xxxxxxxx...).

3단계: Claude Context MCP를 Claude Code에 설치

이제 Claude Code에서 해당 MCP 서버를 등록합니다. 터미널을 열고 어떤 프로젝트 디렉터리든 들어간 뒤 아래 명령을 실행하세요.

claude mcp add claude-context \
  -e OPENAI_API_KEY=sk-your-openai-api-key \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
  -- npx @zilliz/claude-context-mcp@latest

다음 플레이스홀더를 자신의 실제 값으로 바꾸세요.

• sk-your-openai-api-key → 본인 OpenAI API Key
• your-zilliz-cloud-api-key → 본인 Zilliz Cloud API Key
• your-zilliz-cloud-public-endpoint → 본인 Zilliz Public Endpoint

명령이 성공하면 MCP 서버가 등록되었다는 메시지를 확인할 수 있습니다. 설치 검증:

claude mcp list

목록에 claude-context가 있고 상태가 running이어야 합니다.

다른 AI 코딩 도구를 사용한다면 설정 방식이 약간 다를 수 있습니다. 대표적인 몇 가지 시나리오:

Cursor(추천: 설정 파일 방식):

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/claude-context-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

Windsurf(역시 JSON 설정 사용):

// ~/.windsurf/mcp_settings.json
{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/claude-context-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

4단계: 첫 번째 코드베이스 인덱싱하기

설치가 끝나면 프로젝트 디렉터리로 들어가 Claude Code를 실행하세요.

cd your-project-directory
claude

대화에서 아래 명령을 입력해 인덱싱을 트리거합니다.

Index this codebase

Claude Context가 즉시 코드베이스 분석을 시작합니다. 전체 과정은 두 단계로 나뉩니다.

1. 파일 스캔: 디렉터리를 순회하면서 확장자 기준으로 처리할 코드 파일을 필터링
2. 벡터 임베딩: 각 코드 파일을 AST(추상 구문 트리)로 청킹한 뒤 embedding 모델을 호출해 벡터를 생성하고, 벡터 데이터베이스에 저장

인덱싱 과정 중 언제든 진행 상황을 물어볼 수 있습니다.

Check the indexing status

응답에는 현재 인덱싱 진행률(퍼센트)과 완료된 파일 수가 표시됩니다.

5단계: 검색 결과를 검증하고 반환 결과를 이해하기

인덱싱이 완료되면 이제 시맨틱 검색을 시작할 수 있습니다. 대표적인 질의 예시는 다음과 같습니다.

특정 기능의 구현 찾기:

Find functions that handle user authentication

결과에는 관련 함수명, 파일 경로, 코드 조각, 그리고 관련성 점수(0~1 사이)가 포함됩니다. 점수가 높을수록 더 관련성이 큽니다.

모듈 간 관계 이해하기:

How does the payment module connect to the order module?

설정/구성 관련 코드를 빠르게 찾기:

Where is the database connection pool configured?

반환 결과의 형식은 아래와 같습니다.

File: src/database/connection.ts:45-78
Score: 0.94
Content:
  const pool = new Pool({
    max: 20,
    idleTimeoutMillis: 30000,
    connectionTimeoutMillis: 2000,
  });

인덱스를 정리하고 처음부터 다시 시작하려면 다음을 실행합니다.

Clear the index for this codebase

---

자주 발생하는 문제 해결

Q1: Node.js 버전 비호환, 명령 실행 시 오류

증상: claude mcp add에서 에러가 나거나, MCP 서버가 실행된 직후 곧바로 종료됩니다.

원인: Claude Context는 현재 Node.js 24.x를 지원하지 않습니다.

해결:

# 현재 Node 버전 확인
node -v

# 24.x라면 20.x(LTS)로 다운그레이드
nvm install 20
nvm use 20

Q2: 환경변수 설정 오류로 인덱싱 실패

증상: Index this codebase에 아무 반응이 없거나, Milvus connection failed 오류가 반환됩니다.

점검 사항:

1. MILVUS_ADDRESS에 https:// 접두사를 포함하지 말고, 호스트 이름 부분만 사용했는지 확인
2. MILVUS_TOKEN이 Zilliz Cloud 콘솔에 표시된 API Key와 완전히 동일한지 확인
3. OPENAI_API_KEY가 sk-로 시작하는지 확인

올바른 형식 예시:

-e MILVUS_ADDRESS=in-xx-xxxxxxxx.api.gcp-us-west1.zillizcloud.com
-e MILVUS_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-e OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Q3: 인덱싱 진행이 멈춘 듯 보이고 진전이 없음

증상: 인덱싱 명령을 실행한 뒤 계속 응답이 없습니다.

해결:

1. 먼저 Check the indexing status를 실행해 현재 상태를 확인
2. 네트워크 연결 확인(필요: OpenAI API 및 Zilliz Cloud 접속)
3. 클러스터 생성 직후라면 엔드포인트가 아직 초기화 중일 수 있으니, 1~2분 후 다시 시도

Q4: 검색 결과가 비어 있거나 전혀 관련이 없음

증상: 쿼리로 매칭될 만한 내용이 있는데도 결과가 비어 있거나 엉뚱하게 나옵니다.

원인: 인덱스 파일이 불완전할 수 있거나, 질의 표현이 코드 내 명명과 차이가 너무 클 수 있습니다.

해결:

1. 먼저 인덱스 상태 확인: Check the indexing status
2. 더 구체적인 질의 시도(코드에 실제로 존재하는 변수명 또는 함수명 사용)
3. 코드가 존재하는데도 검색이 안 된다면, 인덱스를 지우고 다시 인덱싱:

Clear the index for this codebase
Index this codebase

Q5: 증분 인덱싱이 반영되지 않아, 수정한 코드가 검색되지 않음

증상: 어떤 파일을 수정했는데도 시맨틱 검색 결과가 여전히 예전 버전을 가리킵니다.

원인: Claude Context는 Merkle 트리 스냅샷으로 파일 변경을 감지합니다. 스냅샷 파일을 수동으로 삭제했다면 증분 감지가 동작하지 않을 수 있습니다.

해결: 인덱스를 지우고 다시 시작하면 됩니다.

Clear the index for this codebase
Index this codebase

Q6: MCP 연결 실패로 도구를 사용할 수 없음

증상: 도구 목록에서 search_code, index_codebase 같은 도구가 보이지 않습니다.

해결:

1. Claude Code를 재시작(때로는 MCP 서버를 다시 로드해야 함)
2. MCP 설정에 문법 오류가 없는지 확인(JSON 형식에서 쉼표와 따옴표 주의)
3. claude mcp list에서 해당 플러그인 상태가 running인지 확인

claude mcp list

상태가 stopped이라면 수동으로 재시작:

claude mcp remove claude-context
# 그리고 다시 3단계의 설치 명령을 실행

---

추가 읽기 / 고급 방향

커스텀 Embedding 모델 사용

OpenAI의 text-embedding-3-small이 기본 선택이지만, Claude Context는 다양한 embedding 제공업체를 지원해 완전 로컬화된 배포가 가능합니다.

Ollama(로컬 모델) 사용:

claude mcp add claude-context \
  -e EMBEDDING_PROVIDER=ollama \
  -e OLLAMA_BASE_URL=http://localhost:11434 \
  -e OLLAMA_MODEL=nomic-embed-text \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
  -- npx @zilliz/claude-context-mcp@latest

VoyageAI 사용:

claude mcp add claude-context \
  -e EMBEDDING_PROVIDER=voyageai \
  -e VOYAGEAI_API_KEY=your-voyageai-key \
  -e VOYAGEAI_MODEL=voyage-code-3 \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
  -- npx @zilliz/claude-context-mcp@latest

LangChain/LangGraph로 고급 RAG 구현

자신의 애플리케이션에서 Claude Context의 기능을 직접 통합하고 싶다면 Core 패키지를 사용할 수 있습니다.

import { Context, MilvusVectorDatabase, OpenAIEmbedding } from '@zilliz/claude-context-core';

// embedding과 벡터 데이터베이스 초기화
const embedding = new OpenAIEmbedding({
    apiKey: process.env.OPENAI_API_KEY || 'your-openai-api-key',
    model: 'text-embedding-3-small'
});

const vectorDatabase = new MilvusVectorDatabase({
    address: process.env.MILVUS_ADDRESS || 'your-zilliz-cloud-public-endpoint',
    token: process.env.MILVUS_TOKEN || 'your-zilliz-cloud-api-key'
});

const context = new Context({ embedding, vectorDatabase });

// 코드베이스 인덱싱, 진행 상황을 리스닝
const stats = await context.indexCodebase('./your-project', (progress) => {
    console.log(`${progress.phase} - ${progress.percentage}%`);
});
console.log(`Indexed ${stats.indexedFiles} files, ${stats.totalChunks} chunks`);

// 시맨틱 검색 실행
const results = await context.semanticSearch('./your-project', 'vector database operations', 5);
results.forEach(result => {
    console.log(`File: ${result.relativePath}:${result.startLine}-${result.endLine}`);
    console.log(`Score: ${(result.score * 100).toFixed(2)}%`);
    console.log(`Content: ${result.content.substring(0, 100)}...`);
});

자세한 예시는 evaluation/retrieval/custom.py를 참고하세요.

VSCode에서 시각적으로 검색

IDE에서 작업하는 게 더 편하다면 Semantic Code Search 플러그인을 설치해, VS Code 안에서 바로 시맨틱 검색을 수행하고 Claude Code를 별도로 실행할 필요가 없습니다.

다중 코드베이스 관리 전략

Claude Context는 여러 코드베이스를 동시에 관리할 수 있습니다. 서로 다른 디렉터리에서 각각 Index this codebase를 호출하면, 각 디렉터리는 독립된 인덱스를 유지합니다. 디렉터리명을 지정해 구분할 수도 있습니다.

# 작업 디렉터리 A
cd ~/projects/frontend && claude
# 대화에서 Index this codebase 실행

# 작업 디렉터리 B
cd ~/projects/backend && claude
# 대화에서 Index this codebase 실행

AST 청킹 원리와 Merkle 트리 증분 인덱싱

Claude Context의 코드 이해 능력은 두 가지 핵심 기술에 기반합니다.

• AST 기반 청킹(Chunking): 추상 구문 트리를 사용해 코드 구조를 분석하고, 단순히 줄 수로 자르는 것이 아니라 함수/클래스/모듈 경계를 기준으로 분할합니다. 이렇게 해야 각 chunk가 의미적으로 완결된 코드 단위가 됩니다.
• Merkle 트리 증분 인덱싱: 파일이 변경된 뒤 Merkle 트리 비교를 통해 변경된 파일만 다시 인덱싱하고, 전체를 전면 재구성하지 않습니다. 대규모 코드베이스의 유지 비용을 크게 낮춥니다.

이 두 기술의 구현 세부사항이 궁금하다면 zilliztech/claude-context 저장소의 packages/core 소스 코드를 확인해 보세요.