나는 MCP가 단순한 Tool Calling인 줄 알았다. 그러다 Repository Intelligence 시스템을 구축하게 되었다.

몇 주 전, 나는 MCP (Model Context Protocol)를 배우기로 결심했다.

나의 가정은 간단했다:

도구를 만든다.

그것을 Claude에 연결한다.

끝.

그게 얼마나 어렵겠는가?

결과적으로, 나는 완전히 틀렸다.

MCP를 이해하려는 시도로 시작된 것이 결국 RepoMind로 이어졌다. 이는 Claude에게 전체 코드베이스를 이해하고, 의존성(dependencies)을 분석하며, 변경 영향을 추정하고, 기여자가 익숙하지 않은 프로젝트를 탐색할 수 있도록 돕는 Repository Intelligence 시스템이다.

하지만 RepoMind를 구축하기 전에, 나는 MCP가 실제로 무엇인지에 대해 내가 알고 있던 생각을 버려야만 했다.

나의 MCP 이해를 바꾼 실험

나는 계산기 도구로 시작했다.

거창한 것은 없었다.

그저 Claude가 호출할 수 있는 도구일 뿐이었다.

그러다 이상한 생각이 떠올랐다.

계산기가 올바르게 작동하게 만드는 대신, 의도적으로 틀리게 만들었다.

상상해 보라:

a + b = 뺄셈

이제 질문은 다음과 같다:

만약 사용자가 "5 + 3은 무엇인가요?"라고 묻는다면, Claude는 자신의 추론을 사용하여 8이라고 답할까, 아니면 도구를 사용하여 2라고 답할까?

답변은 나를 놀라게 했다.

Claude는 종종 자신의 추론을 선호했다.

그 작은 실험은 나에게 중요한 것을 가르쳐 주었다:

MCP는 단순히 도구를 만드는 것이 아니다.

그것은 모델이 언제, 왜 해당 도구들을 사용해야 하는지 아는 시스템을 설계하는 것에 관한 것이다.

과제는 도구 생성이 아니었다.

과제는 아키텍처(architecture)였다.

진짜 문제

새로운 프로젝트에 온보딩하든, 오픈 소스에 기여하든, 혹은 자신의 코드베이스를 개선하려고 노력하든, 여러분은 개발자보다는 탐정 역할을 수행하는 데 더 많은 시간을 소비하곤 한다.
파일을 검색하고, 함수 호출(function calls)을 추적하며, 의존성을 이해하고, 심지어 어디서부터 시작해야 할지 파악하는 데 수 시간이 소요된다. AI 도구들이 도움을 주지만, 대개 여러분이 저장소 전체에서 컨텍스트(context)를 수동으로 떠먹여 주어야 한다.
그 결과는? 소프트웨어를 구축하는 시간은 줄어들고, "잠깐... 이 함수가 도대체 어디서 사용되는 거지?"라고 묻는 시간은 늘어난다. 😭

이제 과제는 소프트웨어를 구축하는 것이 아니라, 이미 구축된 수천 줄의 코드를 탐색하는 것입니다.

다음과 같은 질문들은:

• 실행은 어디서 시작되는가?
• 어떤 파일들이 중요한가?
• 이 함수는 어디에서 사용되는가?
• 이 모듈을 수정하면 무엇이 망가지는가?
• 데이터가 시스템을 통해 어떻게 흐르는가?

단순하게 들립니다.

하지만 이에 답하기 위해서는 보통 다음과 같은 과정이 필요합니다:

• 수십 개의 파일을 열기
• 수동으로 임포트 (import) 경로 따라가기
• 함수 호출 (function calls) 추적하기
• 문서 읽기
• 폴더 전체를 검색하기

현대의 AI 도구들이 도움을 주지만, 여전히 모델에 저장소 컨텍스트 (repository context)를 수동으로 입력해 주어야 합니다.

저장소가 커질수록, 이러한 경험은 더욱 악화됩니다.

이제 문제는 코드를 생성하는 것이 아닙니다.

문제는 코드를 이해하는 것입니다.

기존 AI 도구들이 어려움을 겪는 이유

대부분의 AI 어시스턴트는 현재 컨텍스트 윈도우 (context window) 내에서 사용 가능한 정보에 대해서만 추론할 수 있습니다.

저장소 수준 (repository-level)의 질문은 다릅니다.

이러한 질문들은 다음과 같은 능력을 요구합니다:

• 저장소 탐색 (Repository exploration)
• 파일 간 추론 (Cross-file reasoning)
• 의존성 분석 (Dependency analysis)
• 아키텍처 이해 (Architecture understanding)

다음과 같은 질문들은:

이 모듈을 수정하면 어떤 파일들이 영향을 받을까?

또는

새로운 기여자는 어디서부터 시작해야 할까?

몇 개의 코드 스니펫 (code snippets)을 복사해서 붙여넣는 방식으로는 신뢰할 수 있는 답변을 얻을 수 없습니다.

모델은 저장소 자체에 접근할 수 있어야 합니다.

그 깨달음이 RepoMind의 토대가 되었습니다.

RepoMind 소개

아이디어는 간단했습니다:

Claude가 수동으로 붙여넣은 코드에 의존하는 대신, 저장소 전체를 탐색할 수 있다면 어떨까?

저장소 분석이 수동 작업이 아닌 하나의 도구가 된다면 어떨까?

RepoMind는 MCP, 검색 시스템 (retrieval systems), 의존성 인텔리전스 (dependency intelligence), 그리고 특화된 에이전트 (specialized agents)를 결합하여 Claude에게 저장소 수준의 이해력을 제공합니다.

사용자는 컨텍스트를 수동으로 제공하는 대신, 단순히 GitHub 저장소 URL을 제공하기만 하면 됩니다.

그러면 다음과 같은 질문을 던질 수 있습니다:

이 함수는 어디에서 사용되나요?

이 파일을 수정하면 무엇이 망가지나요?

이 프로젝트의 아키텍처를 설명해 주세요.

새로운 기여자는 어디서부터 시작해야 하나요?

RepoMind가 실제로 작동하는 모습을 보고 싶으신가요? 작업 내용을 보여주는 짧은 데모를 첨부했습니다. 구현 방식에 대해 더 자세히 알고 싶다면, 언제든지 GitHub 저장소를 탐색해 보세요.

데모 (Demo): https://github.com/kanika10-hub/REPO-INTELLIGENCE-RepoMind-/tree/main/DEMO

GitHub: https://github.com/kanika10-hub/REPO-INTELLIGENCE-RepoMind-

RepoMind의 작동 원리

워크플로우는 다음과 같습니다:

GitHub URL
    ↓
Clone Repository (저장소 복제)
...

저장소가 처리되고 나면, Claude는 더 이상 추가적인 컨텍스트 (Context)가 필요하지 않습니다.

RepoMind가 이를 자동으로 제공하기 때문입니다.

검색 레이어 (Retrieval Layer) 구축하기

첫 번째 주요 과제는 검색 (Retrieval)이었습니다.

저장소를 단순히 LLM (대규모 언어 모델)에 던져 넣을 수는 없습니다.

그래서 저는 저장소 인제스션 파이프라인 (Repository ingestion pipeline)을 구축했습니다.

흐름은 다음과 같습니다:

Repository (저장소)
    ↓
File Collection (파일 수집)
...

이 프로젝트는 다음을 사용합니다:

• 저장소 인제스션 (Repository ingestion)
• 시맨틱 청킹 (Semantic chunking)
• 임베딩 (Embeddings)
• ChromaDB 벡터 스토리지 (Vector storage)
• 저장소 메모리 (Repository memory)

이를 통해 Claude는 저장소 전반에서 관련 정보를 검색할 수 있게 되었습니다.

하지만 저는 곧 또 다른 문제를 발견했습니다.

RAG만으로는 부족했던 이유

전통적인 RAG (검색 증강 생성)는 문서에는 잘 작동합니다.

하지만 저장소는 문서가 아닙니다.

저장소는 네트워크입니다.

파일은 다른 파일에 의존합니다.

함수 (Function)는 다른 함수를 호출합니다.

모듈 (Module)은 다른 모듈과 상호작용합니다.

벡터 데이터베이스 (Vector database)는 관련 코드를 검색할 수는 있습니다.

하지만 저장소가 어떻게 연결되어 있는지는 설명할 수 없습니다.

그것을 위해서는 또 다른 레이어가 필요했습니다.

저장소 인텔리전스 (Repository Intelligence) 추가하기

저장소 간의 관계를 이해하기 위해, 저는 특화된 도구들을 만들기 시작했습니다.

결국 RepoMind는 30개 이상의 저장소 인식 도구 (Repository-aware tools)를 갖춘 시스템으로 성장했습니다.

몇 가지 예시는 다음과 같습니다:

• 저장소 분석 (Repository analysis)
• 의존성 그래프 생성 (Dependency graph generation)
• 함수 추출 (Function extraction)
• 클래스 추출 (Class extraction)
• 영향도 분석 (Impact analysis)
• 의존성 체인 (Dependency chains)
• 핵심 파일 탐지 (Critical file detection)
• 시맨틱 검색 (Semantic search)

RepoMind는 저장소(Repository)를 단순한 텍스트로 보는 대신, 하나의 시스템으로 취급합니다.

이를 통해 다음과 같은 질문이 가능해졌습니다:

이 파일을 수정하면 무엇이 망가질까요?

이는 기존의 검색 시스템(Retrieval systems)이 답변하기 어려워하는 질문입니다.

에이전트 계층 (The Agent Layer)

도구들을 구축한 후, 또 다른 문제가 나타났습니다.

모든 저장소 관련 질문을 동일한 방식으로 해결해서는 안 된다는 점이었습니다.

온보딩(Onboarding) 질문은 영향 분석(Impact-analysis) 질문과는 다른 추론(Reasoning)을 필요로 합니다.

그래서 저는 특화된 에이전트(Specialized agents)들을 도입했습니다.

RepoMind는 결과적으로 7개의 에이전트를 가진 시스템으로 진화했습니다:

온보딩 에이전트 (Onboarding Agent)

기여자(Contributor)가 다음 사항을 이해하도록 돕습니다:

• 진입점 (Entry points)
• 핵심 파일 (Key files)
• 학습 경로 (Learning path)

설명 에이전트 (Explanation Agent)

아키텍처(Architecture)와 코드 흐름(Code flow)을 설명합니다.

영향 분석 에이전트 (Impact Analysis Agent)

코드 변경의 결과를 예측합니다.

버그 조사 에이전트 (Bug Investigation Agent)

저장소 컨텍스트(Repository context)를 사용하여 디버깅(Debugging)을 지원합니다.

오케스트레이터 (Orchestrator)

질문을 가장 적합한 에이전트로 라우팅(Routing)합니다.

이를 통해 RepoMind는 단순한 도구 모음에서 실제 저장소 인텔리전스(Repository intelligence) 플랫폼으로 변모했습니다.

내가 가장 좋아하는 데모

제가 가장 좋아하는 질문 중 하나는 다음과 같습니다:

이 파일을 수정하면 무엇이 망가질까요?

대부분의 AI 어시스턴트는 광범위한 수동 컨텍스트(Manual context) 없이는 이 질문에 답할 수 없습니다.

하지만 RepoMind는 가능합니다:

1. 저장소 구조 분석 (Analyze repository structure)
2. 의존성 관계 구축 (Build dependency relationships)
3. 영향을 받는 파일 식별 (Identify affected files)
4. 리스크 추정 (Estimate risk)
5. 해당 컴포넌트들이 왜 영향을 받는지 설명 (Explain why those components are affected)

그 순간, 이것은 단순한 챗봇(Chatbot)이 아니라 엔지니어링 어시스턴트(Engineering assistant)처럼 느껴지기 시작합니다.

가장 큰 교훈

RepoMind를 구축하며 몇 가지 교훈을 얻었습니다.

MCP는 아키텍처를 변화시킨다

처음에는 MCP가 단순히 도구 호출(Tool calling) 기능일 뿐이라고 생각했습니다.

하지만 그렇지 않았습니다.

도구가 일급 객체(First-class components)가 되는 순간, 전체 아키텍처가 변화합니다.

RAG만으로는 저장소 인텔리전스가 될 수 없다

검색(Retrieval)도 중요합니다.

하지만 관계를 이해하는 것(Understanding relationships) 또한 똑같이 중요합니다.

화려한 프롬프트보다 좋은 도구가 더 중요하다

대부분의 개선은 더 긴 프롬프트를 작성하는 것이 아니라, 더 나은 도구를 구축함으로써 이루어졌습니다.

AI 시스템은 아키텍처의 문제다

대부분의 엔지니어링 노력은 프롬프트 엔지니어링 (Prompt engineering)이 아니라 다음 요소들에 투입되었습니다:

• 검색 (Retrieval)
• 오케스트레이션 (Orchestration)
• 의존성 분석 (Dependency analysis)
• 에이전트 라우팅 (Agent routing)
• 저장소 메모리 (Repository memory)

다음 단계는?

여전히 탐구하고 싶은 개선 사항들이 많이 남아 있습니다:

• 풀 리퀘스트 (Pull request) 분석
• 아키텍처 시각화 (Architecture visualization)
• 멀티 리포지토리 추론 (Multi-repository reasoning)
• 기여 추천 시스템 (Contribution recommendation systems)
• 고급 영향력 예측 (Advanced impact prediction)

RepoMind는 여전히 진화하고 있습니다.

마치며

저는 MCP를 배우고 싶어서 이 프로젝트를 시작했습니다.

결과적으로 저는 저장소 인텔리전스 (Repository intelligence) 시스템을 구축하게 되었습니다.

가장 큰 깨달음은 AI에 관한 것이 아니었습니다.

그것은 소프트웨어 엔지니어링 (Software engineering)에 관한 것이었습니다.

소프트웨어를 이해하는 것은 소프트웨어를 작성하는 것보다 종종 더 어렵습니다.

그리고 만약 AI가 개발자들에게 의미 있는 도움을 주고자 한다면, 단순히 코드를 생성하는 것이 아니라 시스템을 이해해야 합니다.

그것이 RepoMind로 이어진 아이디어입니다.

읽어주셔서 감사합니다!
끝까지 함께해주셔서 기쁩니다.
— Kanika Rathore
AI Enthusiast