Context7 분석 (2) 코드 스니펫 vs 정보 스니펫

Context7 분석 시리즈
(1) 문서 특화 청킹 전략
(2) 코드 스니펫 vs 정보 스니펫 ← 현재 글
(3) 서버 사이드 리랭킹
(4) 5단계 품질 파이프라인
(5) 다층 품질 스코어링

청크를 왜 두 종류로 나누나?

1편에서 Context7이 마크다운 문서를 H2 제목 기준으로 청킹(chunking)한다는 것을 살펴봤습니다. 그런데 Context7은 여기서 한 발 더 나갑니다. 만들어진 청크를 하나의 타입으로 통째로 저장하지 않고, 코드 스니펫(codeSnippets)과 정보 스니펫(infoSnippets)이라는 두 가지 타입으로 분류해서 인덱싱합니다.

"스니펫이 결국 청크인 건가?"라고 궁금할 수 있습니다. 맞습니다. 두 스니펫 모두 Context7이 문서를 쪼갠 청크입니다. 다만 모든 청크를 동일하게 취급하는 대신, "코드가 핵심인 청크"와 "설명이 핵심인 청크"로 나눠서 각각에 최적화된 방식으로 인덱싱한다는 점이 핵심입니다.

두 스니펫의 차이

구체적으로 무엇이 다른지 비교해 봅시다:

	코드 스니펫 (codeSnippets)	정보 스니펫 (infoSnippets)
내용	실행 가능한 코드 블록 + 짧은 제목/설명	산문 형태의 설명, 개념 소개, 주의사항
저장 메타데이터	제목, 설명, 프로그래밍 언어, 토큰 수, 소스 URL, 코드 블록(복수 가능)	브레드크럼 경로(예: "Routing > Middleware"), 본문 텍스트
임베딩 대상	LLM이 생성한 짧은 설명 (코드 원문이 아님!)	본문 텍스트 자체
검색 매칭 방식	자연어 설명으로 매칭 → 원본 코드를 반환	본문 텍스트로 직접 매칭

코드 스니펫은 코드 자체를 임베딩하지 않는다

여기서 가장 주목할 점은 코드 스니펫의 임베딩 대상입니다. 직관적으로 생각하면 코드 원문을 그대로 벡터화할 것 같지만, 그렇게 하면 검색 정확도가 크게 떨어집니다.

왜일까요? 임베딩 모델은 자연어를 이해하도록 학습되었습니다. 사용자가 "Next.js에서 인증 미들웨어를 어떻게 구현하나요?"라고 질문하면, 이 질문은 자연어입니다. 그런데 코드는 export function middleware(request: NextRequest) { ... } 같은 프로그래밍 언어이죠. 자연어 질문과 프로그래밍 코드 사이의 의미적 거리(semantic gap)가 크기 때문에, 코드 원문을 임베딩해봤자 관련 질문과 잘 매칭되지 않습니다.

Context7의 해법: 4편에서 다룰 Enrich 단계에서 LLM이 각 코드 블록을 읽고 "이 코드는 Next.js 미들웨어에서 쿠키 기반 인증 토큰을 확인하고, 없으면 로그인 페이지로 리다이렉트하는 예제" 같은 자연어 설명을 생성합니다. 이 설명을 임베딩하고, 원본 코드는 메타데이터로 별도 보관합니다. 검색할 때는 자연어끼리 매칭하고(질문 ↔ 설명), 결과로 돌려줄 때는 원본 코드를 반환하는 "설명으로 검색, 코드로 응답" 방식입니다.

항상 함께 불린다

"코드를 짤 때는 코드 스니펫만 가져오고, 개념을 물으면 정보 스니펫만 가져오나?" 그렇지 않습니다. query-docs API를 한 번 호출하면 응답 안에 codeSnippets와 infoSnippets 배열이 동시에 들어옵니다. AI 에이전트는 두 배열을 모두 컨텍스트에 넣어 참조합니다.

왜 항상 함께일까요? LLM이 정확한 코드를 생성하려면 두 가지 정보가 모두 필요하기 때문입니다:

• 코드 스니펫: "이 함수의 시그니처가 정확히 이렇다" → LLM이 올바른 API를 호출할 수 있음
• 정보 스니펫: "이 함수는 이런 조건에서 이런 효과를 낸다" → LLM이 적절한 맥락에서 코드를 배치할 수 있음

코드만 있으면 "이 코드를 왜, 어디에 써야 하는지" 맥락이 빠지고, 설명만 있으면 "실제로 어떻게 구현하는지" 감이 안 잡힙니다. 마치 요리 레시피에서 재료 목록(코드)과 조리 설명(정보)이 모두 있어야 요리를 완성할 수 있는 것과 같습니다.

개발자 사이트 콘텐츠는 어디에 들어가나?

실제로 개발자 사이트를 운영하거나 자체 RAG를 만들 때 가장 궁금한 부분입니다. API Reference, API Guide, Sample Code는 각각 어떤 스니펫 타입으로 분류될까요?

문서 유형	들어가는 스니펫 타입	이유
API Reference (함수 시그니처, 파라미터)	코드 스니펫 + 정보 스니펫	코드 예제 부분은 코드 스니펫으로, 파라미터 설명 텍스트는 정보 스니펫으로
API Guide (개념 설명, 튜토리얼)	코드 스니펫 + 정보 스니펫	가이드 본문은 정보 스니펫으로, 포함된 코드 예제는 코드 스니펫으로
Sample Code (예제 프로젝트)	코드 스니펫	거의 전부 실행 가능한 코드이므로 코드 스니펫 중심

핵심은 "원본 문서의 종류"가 분류 기준이 아니라는 것입니다. 하나의 API Reference 페이지라도, 코드 블록이 포함된 청크는 코드 스니펫으로, 텍스트 위주의 청크는 정보 스니펫으로 분류됩니다. 분류 기준은 "해당 청크 안에 실행 가능한 코드가 있느냐"입니다.

따라서 자체 MCP/RAG를 만들 때 API Reference용 파이프라인, API Guide용 파이프라인을 따로 만들 필요가 없습니다. 하나의 파싱 파이프라인을 거친 뒤, 각 청크의 내용 특성에 따라 자동 분류하면 됩니다.

분리 인덱싱, 통합 검색

정리하면 Context7의 스니펫 전략은 "인덱싱은 분리, 검색은 통합"입니다:

1. 인덱싱(저장): 코드 스니펫은 LLM 설명으로 임베딩, 정보 스니펫은 본문으로 임베딩 → 별도 인덱스에 저장
2. 검색(조회): query-docs API가 두 인덱스를 모두 검색 → 하나의 응답으로 합쳐서 반환

분리 인덱싱의 장점은 각 타입에 맞는 품질 평가와 랭킹을 적용할 수 있다는 것입니다. 코드 스니펫은 "이 코드가 문법적으로 올바른가? 실행 가능한가?"를, 정보 스니펫은 "이 설명이 질문에 충분히 답하는가?"를 각각 다른 기준으로 평가할 수 있습니다.

자체 RAG에 적용할 때의 교훈

• 코드를 직접 임베딩하지 마라: 코드 원문 대신 자연어 설명을 임베딩하고, 코드는 메타데이터로 보관하라
• 문서 종류별 파이프라인을 나누지 마라: 하나의 파이프라인으로 파싱한 뒤 청크 내 코드 유무에 따라 자동 분류하라
• 검색 결과는 항상 양쪽을 함께 반환하라: 코드만 주면 맥락이 빠지고, 설명만 주면 구현이 빠진다

Context7 분석 시리즈
(1) 문서 특화 청킹 전략
(2) 코드 스니펫 vs 정보 스니펫 ← 현재 글
(3) 서버 사이드 리랭킹
(4) 5단계 품질 파이프라인
(5) 다층 품질 스코어링

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.