최근의 대규모 언어 모델 (LLM)은 코드에 대한 추론 능력이 비약적으로 향상되고 있습니다. 컨텍스트 윈도우 (Context window) 또한 수천 토큰에서 수백만 토큰으로 확장되고 있습니다. 하지만 개발자들은 대규모의 실제 리포지토리 (Repository)에서 작업할 때 AI 코딩 어시스턴트로부터 일관되고 정확한 답변을 얻는 데 여전히 어려움을 겪고 있습니다.

만약 여러분이 Claude Desktop이나 Cursor와 같은 에이전트가 새로운 리포지토리에서 복잡한 문제를 디버깅하려고 시도하는 것을 본 적이 있다면, 아마도 다음과 같은 "절망의 Grep 루프 (Grep Loop of Despair)"를 목격했을 것입니다:

1. 에이전트가 grep -r "AuthService" .를 실행합니다.
2. 500개의 결과가 나옵니다.
3. 무작위로 선택된 세 개의 파일에 대해 cat을 실행합니다.
4. 관련 없는 설정 및 테스트 데이터 40,000 토큰을 읽습니다.
5. 컴파일되지 않는 해결책을 환각 (Hallucination) 합니다.

그동안 지배적인 가정은 단순히 더 많은 파일을 더 큰 컨텍스트 윈도우에 밀어 넣으면 문제가 해결될 것이라는 점이었습니다. 하지만 그렇지 않았습니다.

이것은 모델의 추론 문제가 아닙니다. 이것은 검색 (Retrieval) 문제입니다.

코드에 대한 "청크 및 임베딩 (Chunk and Embed)" 방식의 결함

오늘날 대부분의 AI 검색 시스템 (RAG)에서 사용되는 표준 아키텍처는 예측 가능한 파이프라인을 따릅니다: 텍스트를 읽고, 글자 수에 따라 임의로 청크 (Chunk)로 나누고, 벡터 임베딩 (Vector embeddings)을 생성한 다음, 코사인 유사도 (Cosine similarity)를 통해 검색합니다.

이 아키텍처는 문서나 기업 위키 (Wiki)에는 놀라울 정도로 잘 작동합니다. 하지만 소프트웨어 리포지토리에서는 성능이 급격히 저하됩니다.

코드가 글자 수 단위로 청킹 (Chunking)되면 함수 경계가 파괴됩니다. 검색이 오로지 임베딩에만 의존하면, 결정론적인 심볼 조회 (Symbol lookups)가 확률적인 추측이 되어버립니다.

만약 개발자가 AI 어시스턴트에게 _"AuthMiddleware가 어디에 구현되어 있나요?"_라고 묻는다면, 그들은 _"인증과 관련된 무언가"_를 원하는 것이 아닙니다. 그들은 정확한 AuthMiddleware 클래스를 원합니다. 즉시, 그리고 결정론적으로 말입니다.

ContextOS 소개

저는 바로 이 문제를 해결하기 위해 ContextOS를 구축했습니다. 이는 AI 에이전트를 위해 소프트웨어 구조를 인덱싱하고 검색하도록 특별히 설계된 로컬 우선 (Local-first) 컨텍스트 엔진입니다.

1. AST 인식 추출 (AST-Aware Extraction)

단순히 문자로 청킹 (chunking) 하는 대신, ContextOS는 Tree-sitter를 사용하여 저장소 (repository)를 파싱합니다. 이는 함수 (functions), 클래스 (classes), 인터페이스 (interfaces), 메서드 (methods)를 개별적이고 논리적인 청크 (chunks)로 추출합니다. 50줄짜리 함수는 하나의 단일 청크가 됩니다. 이를 통해 코드의 구조적 무결성 (structural integrity)이 보존됩니다.

2. 임베딩 (Embeddings) 대신 BM25 사용

임베딩 (embeddings)은 개념적 유사성을 찾는 데는 뛰어나지만, 정확한 심볼 조회 (symbol lookups)에는 어려움을 겪습니다. ContextOS는 표준 패러다임을 뒤집습니다. 결정론적 어휘 검색 (deterministic lexical search)을 위한 기본 검색 메커니즘으로 SQLite FTS5 (BM25)를 사용하며, 오직 필요한 경우에만 의미론적 매칭 (semantic matching)을 위해 로컬 MiniLM ONNX 모델로 전환합니다.

3. 컨텍스트 압축 (Context Compression)

올바른 컨텍스트를 검색하는 것은 문제의 절반에 불과합니다. 만약 50개의 관련 청크를 LLM에 보낸다면, 모델의 주의력 (attention)을 희석시키게 됩니다. ContextOS는 컨텍스트를 압축하는 쿼리 인식 컴파일러 (query-aware compiler)를 구현합니다. 가장 중요한 노드 (nodes)들은 전체 내용이 전송되는 반면, 점수가 낮은 노드들은 단일 행 스텁 (single-line stubs)으로 압축됩니다 (예: interface User — path/types.ts:12-40).

Claude Code using ContextOS

결과

Redis 7.x C 코드베이스를 대상으로 한 100개 쿼리 벤치마크에서, ContextOS는 정확한 함수 쿼리에 대해 98%의 파일 수준 재현율 (file-level recall)을 달성했습니다. 결정적으로, 이는 쿼리당 평균 **589 토큰 (tokens)**만 사용하면서 이루어낸 결과입니다.

React 및 Next.js와 같은 현대적인 웹 프레임워크의 경우, 컨텍스트 점유율 (context footprint)은 더욱 낮아져 100% 정확도로 쿼리당 평균 약 280 토큰을 기록했습니다.

토큰 효율성은 지연 시간 (latency) 감소, API 비용 절감, 그리고 모델의 혼란을 현저히 줄이는 것으로 직결됩니다. 약 300개의 매우 관련성 높은 토큰을 분석하는 모델은, 노이즈가 섞인 40,000 토큰의 전체 파일 컨텍스트에 빠져 있는 모델보다 일관되게 더 나은 성능을 보여줄 것입니다.

ContextOS는 모델 컨텍스트 프로토콜 (Model Context Protocol, MCP) 서버로 작동하며, 이는 오늘날 Cursor, Claude Desktop 및 기타 모든 MCP 준수 클라이언트에 직접 연결할 수 있음을 의미합니다.

AI가 grep 출력 결과에 빠져 허우적거리게 두지 마세요. AI에게 그에 걸맞은 컨텍스트 엔진을 제공하십시오.

GitHub에서 리포지토리를 확인해 보세요.

커버 사진: Unsplash의 Fotis Fotopoulos