jerry-ai-dev/MODULAR-RAG-MCP-SERVER

플러그인 방식의 관찰 가능한 모듈형 RAG (Retrieval-Augmented Generation, 검색 증강 생성) 서비스 프레임워크로, MCP (Model Context Protocol) 프로토콜을 통해 외부로 도구 인터페이스를 노출하며 Copilot / Claude 등 AI 어시스턴트의 직접 호출을 지원합니다. 동시에 대규모 언어 모델 (LLM) 관련 직무의 학습 및 면접/취업을 위해 설계된 실전 프로젝트이자 부속 교육 리소스이기도 합니다.

본 프로젝트는 RAG 면접에서 가장 흔히 등장하는 핵심 단계인 검색 (Hybrid Search + Rerank), 멀티모달 시각 처리 (Image Captioning), RAG 평가 (Ragas + Custom), 생성 (LLM Response) 및 현재 가장 인기 있는 애플리케이션 프로토콜인 **MCP (Model Context Protocol)**를 하나의 완전하고 실행 가능한 엔지니어링 프로젝트로 연결합니다.

이 프로젝트의 큰 장점은 여러분의 비즈니스에 매우 쉽게 적응할 수 있다는 점입니다. 전 과정(Full-stack) 플러그인 아키텍처 덕분에, 여러분의 배경이나 요구사항이 무엇이든 기존 프로젝트에 빠르게 결합할 수 있으며 자신에게 맞는 사용 방식을 찾을 수 있습니다. 구체적인 사용 전략은 후술할 '누가 이 프로젝트를 사용하기 적합한가 & 어떻게 사용하는가'에서 자세히 다룹니다.

이 프로젝트 자체보다 더 가치 있는 것은 그 이면에 담긴 일련의 엔지니어링 사고방식입니다:

• 개발을 주도하기 위한 DEV_SPEC (개발 규격 문서) 작성 방법
• Spec을 기반으로 코드를 자동 완성하는 Skill 사용법
• 자동화 테스트, 패키징, 환경 설정을 위한 Skill 사용법
• 플러그인 아키텍처를 기반으로 확장하는 방법 (예: Agent로 확장)

사고방식을 배우면 스스로 새로운 프로젝트를 만들고 확장할 수 있습니다. 위의 각 단계에 대한 구체적인 방법과 설계 아이디어는 노트의 대응하는 영상 설명에 포함되어 있으므로 함께 시청하는 것을 권장합니다.

모듈	능력	설명
Ingestion Pipeline	PDF → Markdown → Chunk → Transform → Embedding → Upsert	전 과정 데이터 수집, 멀티모달 이미지 캡셔닝 (Image Captioning) 지원
Hybrid Search	Dense (벡터) + Sparse (BM25) + RRF Fusion + Rerank	초안 검색(Recall) + 재정렬(Rerank)의 2단계 검색 아키텍처
MCP Server	표준 MCP 프로토콜로 도구 노출	query_knowledge_hub , list_collections , get_document_summary
Dashboard	Streamlit 기반 6개 페이지 관리 플랫폼	시스템 개요 / 데이터 브라우징 / Ingestion 관리 / 수집 추적 / 쿼리 추적 / 평가 패널
Evaluation	Ragas + Custom 평가 체계	Golden test set 회귀 테스트 지원, '감'에 의존한 튜닝 방지
Observability	전 과정 화이트박스 추적	Ingestion 및 Query 두 경로의 모든 중간 상태를 투명하게 확인 가능
Skill 기반 프로세스	작성부터 테스트, 패키징, 설정까지 원클릭 완료	auto-coder / qa-tester / package / setup 등의 Skill이 전체 개발 생명주기를 커버 (노트의 각 Skill 사용법 및 설계 아이디어는 부속 영상을 참고하세요)

🔌 전 과정 플러그인 아키텍처: LLM / Embedding / Reranker / Splitter / VectorStore / Evaluator의 모든 핵심 단계에 추상 인터페이스가 정의되어 있어,

🤖 Skill 기반의 전체 프로세스 구동: auto-coder (자동 코딩), qa-tester (자동 테스트), package (정리 및 패키징), setup (원클릭 설정) 등 다양한 Agent Skill이 내장되어 있어, 코드 작성부터 테스트, 패키징, 배포에 이르는 전체 개발 생명 주기 (Lifecycle)를 커버합니다. 각 Skill의 사용 방법과 설계 아이디어는 노트의 프로젝트 섹션에 설명 영상이 있으니 참고하여 학습할 수 있습니다.

📖 상세 아키텍처 설계, 모듈 설명 및 작업 일정은 DEV_SPEC.md를 참조하십시오.

본 프로젝트는 서로 다른 사용 시나리오를 위해 세 가지 브랜치를 제공하므로, 자신의 필요에 따라 선택하십시오:

• 항상 1개의 commit만 존재하며, 프로젝트의 최신 전체 코드를 포함함
  적합한 대상:

  • 프로젝트의 전체 기능을 빠르게 체험하고 싶은 분
  • 시간이 촉박하여 면접용 프로젝트를 빠르게 확보하고, 중간 개발 과정을 건너뛰고 싶은 분
  • 해당 프로젝트를 기반으로 직접 2차 확장을 하고 싶은 분
    사용 방식: 클론(Clone) 후 즉시 Setup Skill을 실행하여 체험 가능

• 코드가 main과 완전히 일치하지만, 전체 commit 히스토리를 유지함

  • 제로 베이스에서 단계별로 구축해 나간 모든 과정을 기록하고 있으며, 수많은 중간 노드(Intermediate nodes)를 포함함
    적합한 대상: 프로젝트가 어떻게 단계별로 구축되었는지 알고 싶은 분. commit 히스토리를 통해 개발 사고 과정을 추적할 수 있음

• 엔지니어링 골격(Agent Skills + DEV_SPEC)만 포함하며, 모든 작업 진행도는 초기화됨

  • 전체 Skill 설정은 유지되어 Agent의 보조를 받아 개발할 수 있음
    적합한 대상:
  • 시간이 충분하여 처음부터 직접 개발하고 싶은 분 (강력 권장)
  • 전체 워크플로우를 체험하고 싶은 분: Spec 작성 → 작업 분할 → 코드 작성 → 테스트 작성 → 반복 최적화
  • 심지어 자신의 이해를 바탕으로 아키텍처를 재설계하거나, 자신의 논리로 구현하며 각 모듈을 깊이 있게 이해할 수 있음
  • 우리가 설명한 모든 대응 사고 방식(Spec 기반 개발, 테스트 우선, 플러그형 아키텍처 등)을 사용하여 프로젝트 전체를 완성할 수 있음

핵심 이념: 프로젝트 전체의 코드 작성은 AI가 DEV_SPEC을 기반으로 자동으로 완료하도록 하는 것입니다. 사용자가 직접 코드를 작성할 필요가 없습니다. AI는 Skill을 통해 Spec에 정의된 작업 정의, 아키텍처 설계, 인터페이스 규격을 읽고 규격에 맞는 코드를 자동으로 생성합니다. 이 사고 방식은 노트의 해당 영상 설명을 참고하십시오: 5.1 프로젝트 Skills 사용: 어떻게 AI가 Skill을 사용하여 DEV_SPEC을 준수하며 코드를 완성하게 하는가.

git clone <repo-url>
cd Modular-RAG-MCP-Server

본 프로젝트는 Provider 선택 → API Key 설정 → 의존성 설치 → 설정 파일 생성 → Dashboard 실행을 포함한 모든 환경 설정을 한 번에 완료하는 Setup Skill을 제공합니다.

VS Code에서 프로젝트를 열고, Copilot / Claude 대화창에 다음을 입력하십시오:

setup

Agent가 자동으로 모든 설정 프로세스를 안내할 것입니다.

💡 Skill 사용 방식이 익숙하지 않다면, 함께 제공되는 노트의 Setup Skill 사용 설명 영상을 시청하십시오.

사람마다 배경이 다릅니다. 어떤 분은 신입 채용(校招)을 준비하고, 어떤 분은 경력직(社招)을 준비합니다. 기초 실력도 다릅니다. AI 프로젝트 경험이 있는 분도 있고, 직무를 전환하는 분도 있습니다. 따라서 이 프로젝트를 사용하는 전략도 달라야 합니다. 반드시 유연하게 사용해야 하며, 무조건적으로 따라 하는 것은 피하십시오.

하지만 한 가지 공통적인 점이 있습니다. 바로 프로젝트 전체를 관통하는 사고 방식입니다. 어떻게 Spec을 작성하여 프로젝트를 빠르게 가동시키는지, 어떻게 Skill을 사용하여 AI의 자동 코딩과 테스트를 유도하는지 등의 엔지니어링 방법론은 어떤 프로젝트에도 적용 가능하며, 모든 이가 참고하고 학습할 가치가 있습니다.

프로젝트 자체를 다양한 시나리오에서 사용하는 전략에 대해, 저는 구체적인 예시를 제공하고 저의 실제 경험을 바탕으로 풀어낼 것입니다. 즉, **'만약 나였다면, 상황에 따라 이 프로젝트를 어떻게 사용했을 것인가'**를 여러분의 참고 자료로 제공하겠습니다.

이 프로젝트 자체는 완전한 RAG 시스템이며, RAG 학습을 위한 실전 프로젝트로 활용할 수 있습니다.

제가 처음 RAG를 공부할 때 본 책은 《대규모 언어 모델 RAG 실전: RAG 원리, 응용 및 시스템 구축》(汪鹏, 谷清水, 卞龙鹏 등 인공지능 분야 전문가 저술)이었습니다. 여러분은 이 책과 결합하여 RAG를 학습할 수 있습니다. 책에서 다루는 전형적인 단계들인 검색(Retrieval), 생성(Generation), 벡터 데이터베이스(Vector Database), 분할 전략(Chunking Strategy), 재정렬(Reranking) 등은 사실 어떤 RAG 관련 서적을 보더라도 핵심 내용은 동일합니다.

이 프로젝트는 바로 이러한 단계들을 하나로 연결해 놓은 것입니다. 따라서 전체 과정을 학습하기 위한 범용적인 RAG 전체 프로세스 프로젝트로 사용할 수 있습니다. 이 책과 병행할 수도 있고, 다른 RAG 서적과 병행할 수도 있습니다. 프로세스는 통하기 때문입니다. RAG 면접 또한 결국 이러한 과정들의 조합, 원리, 그리고 실제 상황에서 마주치는 어려움과 최적화에 관한 것입니다.

만약 현재 AI 관련 프로젝트가 없고, 면접을 위해 프로젝트가 급히 필요하다면 다음과 같이 할 수 있습니다:

본 프로젝트를 직접 사용하십시오. main 브랜치를 클론하여...

브랜치를 사용하여 실행해 보세요. Resume Writer Skill을 결합하여 자신만의 이력서를 작성하세요 (Skill이 사용자의 배경에 맞춰 프로젝트 설명을 맞춤형으로 생성합니다). 프로젝트를 이해하려고 시도하세요. 핵심 프로세스를 실행해 보고, 제가 추후 정리할 이 프로젝트의 면접 질문들과 결합하여 먼저 면접을 보러 가세요. 면접을 통해 프로젝트를 깊이 이해하고 확장하세요 —— 면접 그 자체가 최고의 학습 동력입니다.

예를 들어 지금이 3월이고, 여름 인턴십을 찾아야 하는 학생이라면 시간이 촉박할 것입니다. —— 일단 이력서에 적어 넣고, 면접을 보면서 동시에 학습하세요. 시간이 나면 확장하면 됩니다. 면접은 봐야 하는데 프로젝트가 없는 절박한 상황을 해결해 줍니다. 핵심 사고방식은 다음과 같습니다: 먼저 적어 넣는다 → 면접을 본다 → 면접 피드백에 따라 프로젝트를 개선한다.

보통 여름 인턴십은 3월부터 7월까지 기회가 있습니다. 인턴십을 찾고 대규모 언어 모델 (LLM) 프로젝트 경험을 쌓은 후, 이를 발판 삼아 계속 학습하세요. 7~10월 하반기 채용, 심지어 내년 3월 상반기 채용까지 지속적으로 축적할 수 있는 충분한 시간이 있습니다. 지금 시작하는 것이 다소 늦어 보일 수 있지만, 사실 늦지 않았습니다. 학습 리듬을 유지할 수 있다면, 지금부터 내년 3월까지 꼬박 1년 동안 학습하게 되며, 신입 채용에서 LLM 분야로 합격하는 것은 절대 문제가 되지 않을 것입니다. 관건은 본인이 이토록 긴 시간 동안 학습력을 유지할 수 있느냐에 달려 있습니다.

이 프로젝트를 시작점으로 삼아 자신의 발전 방향에 따라 타겟팅된 확장을 진행할 수 있습니다. DEV_SPEC에도 확장 방향이 적혀 있지만, 여기 몇 가지 흔한 사례를 나열하겠습니다:

Agent 지식을 보충하고 싶은 경우: 직접 Agent 측을 구현하여 컨텍스트 처리, 도구 호출 (Tool Calling), ReAct 로직 등을 수행하고, 본 프로젝트를 Agent의 하나의 모듈이자 능력으로 만들어 Agent + RAG 프로젝트로 변모시킵니다.
백엔드 엔지니어링 능력을 보여주고 싶은 경우: 백엔드 배포 능력을 추가하여 Dockerfile을 작성하고, CI/CD 파이프라인을 구축하며, 모니터링과 로그 수집 기능을 추가합니다.
RAG를 심도 있게 다루고 싶은 경우: Agentic RAG, Graph RAG 등 고급 형태로 확장하거나, 검색 전략 (Retrieval Strategy) 측면에서 더 많은 최적화 실험을 수행합니다.

사람마다 발전 방향은 다릅니다. 프로젝트에 포함된 Resume Writer Skill이 이력서를 쓸 때 사용자의 배경과 상황을 먼저 묻는 것과 같습니다. 사용자가 LLM 애플리케이션 개발 엔지니어, RAG 엔지니어, 풀스택 엔지니어를 목표로 하는지에 따라, 그리고 신입 채용인지 경력 채용인지에 따라 요구사항이 모두 다릅니다 (구체적인 LLM 직무 소개와 기술 스택은 노트의 LLM 직무 소개 부분을 참고하세요). 따라서 자신에게 맞는 타겟팅된 확장이 필요합니다.

강력히 권장하는 사항은 다음과 같습니다: 어떤 배경을 가졌든, 어떻게 확장하든, 여러분은 높은 확률로 자신의 비즈니스 도메인을 결합하여 이력서를 써야 합니다. 그러니 최소한 한 번은 시도해 보세요. 자신의 분야 문서(금융, 법률, 의료 또는 실제 업무 문서)를 집어넣고 검색 효과를 확인해 보는 것입니다. 효과가 좋지 않다면 그때 조정하고 개선하면 됩니다. 이 과정 자체가 최고의 학습이며, 면접 시 가장 설득력 있는 실전 경험이 됩니다.

시간적 여유가 있다면, clean-start 브랜치부터 시작하는 것을 추천합니다. 심지어 clean-start를 기반으로 DEV_SPEC을 삭제하고, 문서 설계부터 시작하여 하나씩 경험해 보세요:

문서 설계 → AI 코드 작성 → 개선 및 반복 (Iteration) → 테스트 → 배포

이 전체 과정의 방법론을 말합니다. 그중 DEV_SPEC을 어떻게 작성하는지, Skill을 어떻게 설계하는지는 노트 프로젝트 부분의 해당 영상에서 설명하고 있습니다. 문서를 재설계하거나 개선할 수도 있고, 심지어 직접 Agent 방향의 결과물을 만들어 전체 프로세스를 완주할 수도 있습니다.

이렇게 하면 프로젝트를 개발하는 전체적인 사고방식을 배우게 됩니다. 이 방법론의 가장 큰 장점은 하한선(Lower bound)이 매우 낮다는 것입니다. 즉, 거의 누구나 설계하고 전체 프로젝트를 완성할 수 있습니다. 이를 통해 사고방식과 과정을 모두 배우면서도 프로젝트를 고도로 커스텀할 수 있습니다. 이미 단톡방의 많은 분이 이렇게 하고 있습니다.

이것은 사실 매우 좋은 전략이며, 저 또한 이런 방식을 사용할 수도 있습니다. 제 경험을 예로 들어 말씀드리겠습니다:

이전에 구직 활동을 할 때

대규모 언어 모델 (LLM) 제품 관리자 (PM) 면접에서는 점점 더 RAG 관련 지식을 묻는 경우가 많아지고 있으며, 어떤 기업은 제품 관리자에게 직접 POC (Proof of Concept, 개념 증명)를 작성하여 개발자에게 전달할 것을 요구하기도 합니다. 이 프로젝트와 그 이면에 담긴 방법론은 바로 이러한 요구를 충족시키는 데 완벽한 도움을 줄 수 있습니다.

PM이 사용할 수 있는 이유:

면접 대비: LLM 제품 직무에서는 RAG의 기본 원리와 프로세스를 테스트합니다. 이 프로젝트를 통해 문서 수집 (Ingestion), 청킹 (Chunking), 벡터화 (Vectorization), 검색 (Retrieval), 재정렬 (Reranking)부터 최종 생성에 이르는 RAG의 전체 과정을 직관적으로 경험하며 제품 관점의 이해를 구축할 수 있습니다.
POC 능력: 이 방법론을 사용하여 전체 프로젝트를 구축할 수 있습니다. 문서를 작성 (DEV_SPEC)하거나 기존 문서를 사용한 뒤, Skill을 통해 AI가 코드를 생성하도록 할 수 있습니다. 면접 시에는 본인의 사고방식과 제품 설계를 설명하고, 코드는 AI의 도움을 받아 작성했다고 말하는 것은 현재 매우 합리적인 방식입니다.
기술적 세부 사항에 대한 부담 완화: 제품 관리자가 모든 코드 라인을 어떻게 작성하는지 알 필요는 없지만, 이 프로세스를 직접 실행해 봄으로써 제품 관점에서 페인 포인트 (Pain Point)를 고민할 수 있습니다. 예를 들어, 검색 정확도가 낮을 때 지표를 어떻게 정의할지, 사용자 경험 (UX) 측면에서 피드백 메커니즘을 어떻게 설계할지, 데이터 품질이 RAG 효과에 어떤 영향을 미치는지 등을 생각할 수 있습니다.

구체적인 실행 방법:

• main 브랜치를 클론(Clone)하고, Setup Skill을 사용하여 전체 프로세스를 경험해 보세요. 본인의 비즈니스 도메인 문서를 넣어보고 검색 효과를 확인하며, 제품 관점의 최적화 방향을 고민해 보세요.
• 면접 시에는 본인의 제품 기획 의도와 설계 사고를 설명하고, 기술적 구현 부분은 AI의 보조를 받아 완성했다고 설명하세요.

💡 노트에는 비기술적 배경을 가진 분들이 AI를 활용해 빠르게 프로토타입을 구축할 수 있도록 돕는 Vibe Coding 관련 튜토리얼 (예: Tina Huang 강사의 설명)도 제공되어 참고하기 매우 좋습니다.

마지막으로, 위 모든 상황에 적용되는 한 가지 사항을 독립적으로 강조하고 싶습니다.

모든 프로젝트의 심도 있는 최적화는 한 번에 이루어지지 않습니다.

만약 커리어 전환을 준비 중이고 프로젝트를 직접 만들었다면, 면접관으로부터 프로젝트가 얕다는 평가를 어느 정도 받을 수 있습니다. 제가 이전에도 언급했던 부분이지만, 두려워할 필요는 없습니다.

• 프로젝트의 깊이가 입문의 필수 조건은 아닙니다. 저는 작년에 대기업을 포함해 6개의 오퍼 (Offer)를 받았지만, 그럼에도 불구하고 제 프로젝트가 얕다고 평가하는 면접관들이 있었습니다. 면접은 이론적 기초, 알고리즘 능력, 배경 적합성, 지식의 폭 등 다른 많은 측면을 고려합니다. 커리어 전환자라는 이유로 프로젝트가 얕다는 생각에 사로잡혀 포기하지 마세요.
• 프로젝트는 끊임없이 최적화되고 심화되는 과정입니다. 면접관이 프로젝트가 얕다고 한다면, 그 피드백을 경청하여 왜 그렇게 느꼈는지 파악해야 합니다. 예를 들어 데이터가 충분히 복잡하지 않다고 한다면 복잡한 데이터를 생성하면 되고, 이미지 처리가 너무 단순하다고 한다면 멀티모달 (Multimodal) 전략을 확장하면 됩니다. 저 또한 면접 과정에서 프로젝트에 계속해서 요소를 추가했습니다. 이전에 진행했던 Agent 프로젝트의 경우, 면접이 진행됨에 따라 배포, 학습, 반성 데이터 (Reflection Data), 평가 모듈 등을 계속 추가했습니다. 이 모든 과정은 면접과 동시에 진행되었습니다.

면접 시간을 충분히 확보하고, 면접을 보면서 동시에 프로젝트를 개선하고 심화시키세요. 이것이 바로 이 프로젝트 세트의 핵심 사고방식입니다. 이러한 사고방식을 익혀야 지속적으로 확장할 수 있으며, 아이디어만 있다면 AI에게 작성을 맡기면 되므로 확장의 문턱은 매우 낮습니다. 그러니 두려워하지 마세요.

실제 데이터를 하나 말씀드리자면, 이 프로젝트는 제가 퇴근 후 약 2개월 동안 만든 것입니다. 그 기간 동안 저는 직장 생활과 콘텐츠 제작을 병행해야 했습니다. 따라서 특히 경력직 분들이라면 이 프로젝트 하나만으로 별도의 확장 없이 완벽하게 깊이 있는 프로젝트가 되기를 기대해서는 안 됩니다. 하지만 반대로 생각해보세요. 퇴근 후 2개월 만에 이 정도를 만들어냈다면, 만약 여러분이 이 방법론을 익힌다면 스스로 확장하는 속도가 얼마나 빠를까요?

방법론은 모두 갖춰져 있으며, 모든 방안, 과정, 기록은 문서와 영상 설명으로 남아 있습니다. 결국에는 반드시 스스로 확장하고 반복(Iteration)하여 자신에게 가장 적합한 프로젝트로 만들어내야 합니다.

⚠️ 강력 권장: 아래의 예시를 그대로 복사하지 말고, 프로젝트에 내장된 Resume Writer Skill을 사용하여 본인의 이력서 프로젝트 경험을 생성하세요. [이력서 프로젝트 경험]

반드시 타겟팅되어야 합니다. 본인의 비즈니스 배경, 목표 직무, 기술적 중점에 맞춰 맞춤형으로 생성해야 합니다. 아래의 예시는 Skill의 출력 결과와 다양한 시나리오의 작성 방식을 참고하기 위한 용도일 뿐이며, 그대로 베끼는 것은 아무런 의미가 없습니다.

Resume Writer Skill 사용 방법: VS Code에서 Copilot 또는 Claude 대화창에 写简历 또는 resume를 입력하면

지능형 지식 검색 및 질의응답 시스템 | 2024.09 - 2025.02 | 독립 설계 및 개발

배경: 기업급 지식 베이스(Knowledge Base) 시나리오에서 발생하는 문서 분산, 검색 정밀도 부족, AI 애플리케이션의 프라이빗 지식 접근 어려움이라는 공통적인 페인 포인트(Pain Point)를 해결하기 위해 모듈형 RAG (Retrieval-Augmented Generation) 검색 프레임워크를 설계하고 구현했습니다.

목표: 하이브리드 검색 (Hybrid Search) + MCP (Model Context Protocol) 프로토콜 기반의 지능형 지식 질의응답 시스템을 구축하여, 정밀한 의미론적 검색(Semantic Search)과 AI 에이전트 (AI Agent)가 프라이빗 지식 베이스를 직접 호출할 수 있는 능력을 구현하고, 문서 질의응답 정확도를 90% 이상으로 높이는 것을 목표로 했습니다.

과정:

• BM25 + Dense Embedding 하이브리드 호출(Recall) 아키텍처를 설계하고, RRF (Reciprocal Rank Fusion) 융합 랭킹을 통해 재현율(Recall)과 정밀도(Precision)의 균형을 맞추었으며, Cross-Encoder 재정렬(Reranking)을 결합하여 Top-10 히트율(Hit Rate)을 약 25% 향상시켰습니다.
• 전체 파이프라인 인제스션 파이프라인 (Ingestion Pipeline: PDF 파싱 → Markdown → 의미론적 청킹 (Semantic Chunking) → 메타데이터 (Metadata) 강화 → 임베딩 (Embedding) → 업서트 (Upsert))을 구축했습니다. Vision LLM을 통합하여 이미지 자동 설명을 생성하고 이를 청크 (Chunk)에 결합함으로써, 텍스트 파이프라인만 재사용하여 "텍스트 검색으로 이미지 찾기"가 가능하도록 구현했습니다.
• LLM / Embedding / Reranker / VectorStore 전체 링크의 플러그형 (Pluggable) 아키텍처를 구현했습니다. 통일된 추상 인터페이스를 정의하여 설정 파일을 통해 백엔드 프로바이더 (Provider)를 원클릭으로 전환할 수 있게 했으며, 4개 이상의 LLM 프로바이더를 코드 수정 없이 전환할 수 있도록 지원합니다.
• Ragas + 커스텀 (Custom) 이중 평가 체계를 통합하고, 골든 테스트 세트 (Golden Test Set) 회귀 테스트 메커니즘을 구축하여 Faithfulness (충실도) / Relevancy (관련성) / Recall (재현율) 등의 차원을 커버함으로써 "감에 의존하는" 튜닝을 지양했습니다.
• 스킬 (Skill) 기반의 전 과정 개발을 진행했습니다. auto-coder / qa-tester / setup / package 등 5대 에이전트 스킬 (Agent Skill)을 통해 코딩, 테스트, 설정, 패키징의 전체 생명 주기를 커버하였으며, 2개월의 여가 시간을 활용해 68개의 서브 태스크 (Sub-task)를 전량 완수했습니다.

결과: 시스템은 5,000개 이상의 문서에 대한 실시간 의미론적 검색을 지원하며, 검색 정확도 (Hit Rate@10)는 92%에 달합니다. 엔드 투 엔드 (End-to-End) 쿼리 지연 시간은 800ms 이내로 제어하였으며, 3단계 테스트 체계 (Unit / Integration / E2E)를 통해 1,200개 이상의 테스트 케이스를 커버했습니다.

기술 스택: Python / LangChain / ChromaDB / BM25 / Cross-Encoder / MCP Protocol / Streamlit / Ragas / Azure OpenAI

다음은 "경력직 채용, 에이전트 방향, Windows 플랫폼 개발 업무 배경"을 기반으로 Skill이 생성한 예시 출력입니다 (RAG 능력을 기존 에이전트 프로젝트에 통합):

Windows 플랫폼 지능형 지식 어시스턴트 | 2024.06 - 2025.02 | 핵심 개발

배경: Windows 플랫폼 개발 팀 내에서 버전 출시 관련 정보 (Release Notes, 변경 로그, 패치 공지, 호환성 설명 등)가 여러 Wiki, 문서 저장소 및 내부 시스템에 분산되어 있습니다. 엔지니어가 버전 차이를 조사하거나 고객 질문에 답변할 때 여러 시스템을 넘나들며 찾아야 하며, 기존 키워드 검색은 의미론적 이해가 불가능하여 검색 효율이 낮고 정보 누락이 빈번하게 발생합니다.

목표: 팀을 위해 에이전트 (Agent) + RAG 아키텍처 기반의 지능형 지식 어시스턴트를 구축하여, 시스템 간 문서의 의미론적 검색 및 자동 질의응답을 구현합니다. MCP 프로토콜을 통해 엔지니어의 일상적인 툴체인 (VS Code / Claude Desktop)에 통합함으로써 문서 탐색 시간을 60% 이상 단축하는 것을 목표로 합니다.

과정:

• Agent + RAG 계층형 아키텍처 설계: Agent 단은 의도 인식(Intent Recognition) 및 도구 호출(Tool Calling)을 담당하고, RAG 단은 BM25 + 밀집 임베딩(Dense Embedding) 혼합 검색(Hybrid Retrieval)과 Cross-Encoder 재정렬(Reranking)을 결합한 2단계 검색 능력을 제공하며, MCP 프로토콜을 통해 표준화된 도구 인터페이스를 노출하여 Agent가 호출할 수 있도록 함
• 전 과정 인제스션 파이프라인 (Ingestion Pipeline) 구현: PDF / Markdown 등 다양한 형식의 문서 파싱을 지원하며, Vision LLM을 통합하여 이미지 설명(아키텍처 다이어그램, 스크린샷 등)을 자동으로 생성함으로써 "텍스트 검색 시 이미지 결과 제공"이라는 멀티모달 검색 요구사항을 해결
• 플러그형 백엔드 아키텍처 구축: LLM / Embedding / Reranker / VectorStore를 모두 추상 인터페이스로 정의하여 Azure OpenAI ↔ DeepSeek ↔ Ollama 간의 원클릭 전환을 지원하며, 팀의 다양한 네트워크 환경에 적응 가능하도록 설계
• Streamlit 대시보드 관리 플랫폼 구축: 데이터 브라우징, 인제스션(Ingestion) 추적, 쿼리 추적, 평가 패널 등 6가지 주요 기능 페이지를 제공하여 전 과정의 화이트박스 가시성(White-box Observability)을 실현
• Ragas 평가 프레임워크 + Golden Test Set 회귀 테스트 통합: 버전 반복 과정에서 검색 품질을 지속적으로 모니터링하며, Faithfulness 점수를 0.85 이상으로 안정적으로 유지
• Skill 기반 전 과정 개발 모드 채택: DEV_SPEC 사양 문서를 작성하여 auto-coder의 자동 코딩, qa-tester의 자동 테스트 및 수정, setup의 원클릭 환경 설정을 유도함. 5가지 Agent Skill이 전체 개발 생명주기를 커버하며, 2개월의 여가 시간을 활용해 68개의 서브 태스크를 완료하여 인도함

결과: 시스템은 팀의 8,000개 이상의 기술 문서를 커버하며, 엔지니어의 일평균 문서 조회 시간을 15분에서 3분으로 단축하였고, 검색 정확도인 Hit Rate@10은 90%에 달함. 이미 MCP 프로토콜을 통해 3개의 내부 AI 도구에 연결되었으며, 누적 2만 건 이상의 쿼리를 처리함.

기술 스택: Python / Agent / Tool Calling / RAG / BM25 / Dense Retrieval / Cross-Encoder / MCP Protocol / ChromaDB / Streamlit / Ragas / Skill-Driven Development / Azure OpenAI

다음은 "경력직 AI 전환, 백엔드/아키텍처 방향, 금융 컴플라이언스 업무 배경"을 바탕으로 Skill이 생성한 예시 출력입니다:

컴플라이언스 지능형 문서 검색 시스템 | 2024.10 - 2025.02 | 설계 및 개발 주도

배경: 특정 금융 기관의 컴플라이언스 부서에서 법규 문서와 내부 정책 문서가 만 단위 규모로 지속적으로 증가함에 따라, 컴플라이언스 팀은 검토 및 컨설팅 시나리오에서 특정 조항을 빠르게 찾아내야 했음. 그러나 기존 전체 텍스트 검색 시스템은 키워드 정밀 매칭만 가능하여 "자금세탁방지"와 "AML" 같은 의미적 유의어 표현을 이해하지 못해 조항 탐색 효율이 낮았음.

목표: 모듈형 RAG 검색 시스템을 설계 및 구현하여 컴플라이언스 문서 관리 프로세스에 의미론적 검색(Semantic Search) 능력을 도입하고, 유의어 및 교차 언어 조항 매칭을 지원하여 컴플라이언스 조항 탐색 정확도를 90% 이상으로 높이는 것을 목표로 함.

과정:

• 시스템 아키텍처 설계 주도: 전 과정 플러그형 아키텍처를 채택하여 LLM / Embedding / Reranker / Splitter / VectorStore를 모두 추상 인터페이스와 팩토리 패턴(Factory Pattern)으로 정의함. YAML 설정을 통해 백엔드를 원클릭으로 전환할 수 있어 코드 수정 없이 다양한 배포 환경에 적응 가능함
• BM25 희소 검색(Sparse Retrieval) + Dense Embedding 의미 검색의 혼합 검색 전략 구현: RRF(Reciprocal Rank Fusion) 결합 정렬을 통해 전문 용어의 정밀 매칭과 의미적 유의어 매칭을 모두 충족하며, 검색 정확도를 순수 벡터 방식 대비 22% 향상시킴
• 완전한 데이터 인제스션 파이프라인 구축: PDF 파싱 → 의미론적 청킹(Semantic Chunking) → 청크 정제(Chunk Refinement) → 메타데이터 강화(Metadata Enrichment) → 벡터 저장으로 이어지는 과정을 지원하며, DocumentManager의 멱등성(Idempotency) 관리를 통해 문서 업데이트 시 데이터 일관성을 보장함
• 3계층 테스트 체계(Unit / Integration / E2E) 구축: 1,200개 이상의 테스트 케이스를 커버하며, Ragas 평가 프레임워크를 통합하여 자동 회귀 메커니즘을 구축함으로써 반복 과정에서 검색 품질이 저하되지 않도록 보장함
• MCP 프로토콜을 기반으로 표준화된 도구 인터페이스 노출: GitHub Copilot / Claude Desktop 등 AI 어시스턴트가 직접 호출할 수 있도록 지원하여 "한 번의 개발로 다중 엔드포인트 호출"이 가능한 서비스형 배포를 실현함
• Skill 기반 전 과정 엔지니어링 방법론 실천: DEV_SPEC 사양 문서를 기반으로 AI Agent가 코딩(auto-coder), 테스트(qa-tester), 환경 설정(setup), 정리 및 패키징(package)을 자동으로 완료하도록 유도함. 68개의 서브 태스크 전체를 Agent가 인도하였으며, 개발 주기를 2개월의 여가 시간으로 압축함

결과: 시스템 출시 후 12,000개 이상의 컴플라이언스 문서에 대한 실시간 의미 검색을 지원하며, 조항 탐색 정확도를 68%에서 91%로 높였고, 단일 쿼리 지연 시간(Latency)을 700ms 이내로 제어하여 컴플라이언스 팀의 문서 검토 효율을 약 50% 향상시킴.

기술 스택 (Tech Stack): Python / 플러그형 아키텍처 (Pluggable Architecture) / 팩토리 패턴 (Factory Pattern) / BM25 / 밀집 검색 (Dense Retrieval) / RRF / 교차 인코더 (Cross-Encoder) / ChromaDB / MCP 프로토콜 (MCP Protocol) / Streamlit / Ragas / 스킬 주도 개발 (Skill-Driven Development) / Azure OpenAI

💡

사용 시 주의사항 및 중요 안내:

1. 증폭 전략 (Amplification Strategy)에 대하여: Resume Writer Skill에는 제가 설계한 증폭 전략이 내장되어 있습니다. 즉, AI가 합리적인 범위 내에서 귀하의 프로젝트 경험을 포장하고 증폭합니다(예: 정량적 지표, 비즈니스 규모 등). 이는 제가 허용하는 범위이며, 이력서 작성의 일반적인 방식이기도 합니다. 하지만 이는 다음을 의미합니다: 이력서 생성 후, 면접관이 각 항목에 대해 어떤 추가 질문을 던질 수 있는지, 그리고 어떻게 답변해야 할지를 반드시 깊이 고민해야 합니다. Skill은 이력서를 생성함과 동시에 3~5개의 면접 예상 질문을 자동으로 제공하므로, 이 질문들을 진지하게 준비하시기 바랍니다.

2. 이력서를 실습 목록으로 활용하세요: 이력서에 기재된 모든 기술 포인트는 실제로 직접 시도해 보아야 합니다. 예를 들어 이력서에 "검색 정확도 XX% 향상"이라고 적었다면, 본인의 데이터로 직접 실행해 보고 실제 효과가 어떠한지, 과정에서 어떤 문제에 부딪혔으며 어떻게 튜닝하여 해결했는지 확인해야 합니다. 이러한 실습 경험이야말로 면접에서 진정한 설득력을 갖는 내용이며, 실제로 무언가를 배우는 과정입니다. 이력서에 포함되지 않은 부분(예: 멀티모달을 시도해보지 않았거나 평가를 실행해보지 않은 경우 등)도 이를 계기로 코드 실험을 진행해 볼 수 있습니다.

3. 생성된 결과물은 초안입니다. 반드시 본인의 상황에 맞춰 수정하세요: Skill이 생성한 이력서는 초안이지 최종본이 아닙니다. 본인의 실제 상황에 맞춰 조정해야 합니다. 어떤 기술을 정말 깊이 있게 사용했는지, 어떤 것은 단순히 알고 있는 정도인지, 어떤 데이터는 본인의 것으로 교체해야 하는지 등을 결정해야 합니다. 이력서 작성에는 철칙이 있습니다: 이력서에 쓴 내용은 반드시 설명할 수 있어야 합니다. 설령 어떤 항목이 증폭된 것이라 할지라도, 면접관이 어떻게 질문할지, 그리고 어떻게 논리적으로 답변할지를 명확히 생각해야 합니다. 설명하기 어려운 내용은 차라리 쓰지 않는 것이 나으며, 일단 썼다면 추궁하는 질문을 견뎌낼 수 있어야 합니다.

4. 템플릿보다 방법론이 더 중요합니다: 이력서 작성의 전체적인 사고방식은 저의 것입니다. 증폭 전략, 4단계 구조(배경 → 목표 → 과정 → 결과 → 기술 스택), 하이라이트 매칭 로직 등을 포함하여 이 모든 것이 Resume Writer Skill에 축적되어 있습니다. 만약 본인이 더 신뢰하는 이력서 템플릿이 있거나 프로젝트를 확장 및 수정했다면, Skill 자체를 수정하여 적응시킬 수 있습니다. "Skill을 통해 방법론을 정립하고, AI가 규칙에 따라 실행하게 만드는" 이 로직을 배우는 것이 이력서 자체보다 더 가치 있습니다. 이 사고방식은 향후 귀하의 어떤 프로젝트 이력서 작성에도 재사용될 수 있습니다.

5. Skill 주도 전체 프로세스(Skill-Driven Full Process)를 작성할 것을 강력히 권장합니다: 개인적인 의견으로는, Skill 주도 전체 프로세스 개발이라는 폐쇄 루프(Closed Loop)는 누구의 이력서에도 적합한 내용입니다. Skill은 현재 매우 뜨거운 분야이며 이미 면접의 필수 질문 항목이 되었고, 많은 기업 내부에서도 어떻게 Skill을 사용하여 프로젝트 구축을 가속화할지 연구하고 있습니다. 귀하가 어떻게 Skill을 사용하여 코딩 → 테스트 → 수정 → 구성 → 패키징에 이르는 전체 프로젝트 폐쇄 루프를 완성했는지 명확히 설명하는 것 자체가 비교적 혁신적이고 앞선 하이라이트가 될 것이며, 면접관에게 깊은 인상을 남길 것입니다. Skill 관련 내용을 면접에서 어떻게 말하고 추궁에 어떻게 답변할지에 대해서는 추후 참고용 예시를 제공해 드리겠습니다.

매우 간단합니다 — AI에게 직접 요청하여 완료하면 됩니다.

프로젝트는 아키텍처 설계 단계에서 **팩토리 패턴 (Factory Pattern)**을 사용하였으므로, Provider의 확장과 전환이 매우 편리합니다. 내부 원리를 이해하고 나면 다음과 같은 사실을 알게 될 것입니다: 서로 다른 API는 본질적으로 유사한 HTTP 요청이며, 심지어 대부분이 OpenAI의 요청 형식을 따르기 때문에 전환이 매우 쉽습니다.

구체적인 조작 방식에는 두 가지가 있습니다: