가정과 데이터

일반적인 가정: docstring(문서화 문자열)은 자연어와 더 유사해 보이므로, 이를 임베딩하면 벡터 모델이 코드를 더 잘 이해하는 데 도움이 될 것이다. 대부분의 엔지니어는 주석이 강화된 인덱싱(comment-enhanced indexing)으로 시작한다.

하지만 데이터는 이에 동의하지 않는다.

실험 설계

데이터셋: 5개의 비즈니스 모듈(auth, database, cache, payment, notification)에 걸친 27개의 Python 함수

세 가지 전략, 동일한 임베딩 모델 (BAAI/bge-large-zh-v1.5):

Strategy A: Raw code (원본 코드)
  함수 본문 전체를 임베딩 — 변수 이름, 라이브러리 호출,
  제어 흐름(control flow) 모두 보존
...

세 가지 전략 모두 동일한 모델을 사용한다. 차이점은 모델의 품질이 아니라 입력 형식에서만 발생한다.

지표: Recall@3 및 Recall@5 (12개의 자연어 쿼리 × 정답 관련 함수)

결과

Strategy                       Recall@3    Recall@5    vs A
──────────────────────────── ──────────  ──────────  ──────
A_raw_code                        0.889       0.958    base
...

전략 A(Strategy A)의 승리. B와 C는 동률이며, 둘 다 A보다 0.041 낮다.

쿼리별 세부 분석 (Recall@5)

Query                                                   A       B       C
────────────────────────────────────────────────── ──────  ──────  ──────
verify user identity and check JWT token validity    1.00    0.50    0.50 ←
...

두 가지 쿼리에서 차이가 발생한다:

Q1 (JWT 검증): A=1.0, B/C=0.5

전략 B는 다음만을 임베딩한다:

def validate_jwt_token(token: str)
"""Decode and validate a JWT token. Returns payload if valid."""

전략 A는 다음도 함께 임베딩한다:

payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
except jwt.ExpiredSignatureError:
except jwt.InvalidTokenError:

jwt.decode, ExpiredSignatureError, InvalidTokenError는 임베딩 모델에게 이 함수가 JWT 도메인의 어디에 위치하는지를 정확하게 알려준다. docstring은 "decode and validate"라고 말하는데, 이는 정확하지만 부정확하다. 즉, 변별력을 발휘하는 구체적인 기술 어휘(technical vocabulary)를 놓치고 있다.

Q8 (Stripe 결제): 세 가지 전략 모두 0.50점

세 가지 전략 모두 create_payment_intent는 검색해냈지만, calculate_order_total은 놓쳤다. 쿼리는 "결제를 처리하고 Stripe charge를 생성하라(process payment and create Stripe charge)"이지만, calculate_order_total의 docstring(문서화 문자열)에는 "아이템 가격을 합산하고, 할인을 적용하며, 세금을 계산한다(Sum item prices, apply discount, compute tax)"라고 적혀 있다. 벡터 공간(vector space)에서 이들은 의미론적으로 멀리 떨어져 있다. 어떤 임베딩 (embedding) 전략도 그 간극을 메우지 못한다.

원본 코드 (Raw Code)가 더 나은 성능을 보이는 이유

코드는 고품질의 의미론적 신호 (semantic signal) 역할을 하는 풍부한 기술 어휘 (technical vocabulary)를 포함하고 있다:

함수 및 변수 이름:
  validate_jwt_token → "JWT" "token" "validate"
  hash_password → "hash" "password"
...

이러한 기술 용어들은 사전 학습 (pre-training) 데이터 내에서 풍부한 문맥을 가지고 있다. 임베딩 (embedding) 모델은 이들을 정밀한 의미론적 이웃 (semantic neighborhoods)으로 매핑한다. Docstring은 "자연어에 더 가깝다"는 장점에도 불구하고, 코드 자체의 기술 어휘보다 변별력이 낮은 모호한 동사("처리하다(process)", "다루다(handle)", "관리하다(manage)")를 사용하는 경향이 있다.

비유하자면: 의학 문헌에서 "열, 기침, 인후통"은 "몸 상태가 좋지 않음"보다 의사에게 더 많은 진단 신호를 제공한다. 전자가 "더 자연스러운 언어"가 아님에도 불구하고 말이다.

주석 강화 (Comment-Enhanced)가 실제로 승리하는 경우

전략 B와 C가 쓸모없는 것은 아니다. 특정 상황에서는 전략 A보다 뛰어난 성능을 보인다:

상황 1: 코드가 불투명한 명명 규칙 (opaque naming)을 사용하는 경우

def do_proc_v2(x, y, flag=False):
    """레거시 모드로 폴백(fallback)하여 사용자 인증을 처리합니다."""
    result = _run_auth_pipeline(x, y)
...

do_proc_v2, x, y는 아무런 의미론적 정보를 담고 있지 않다. 여기서 docstring이 유일하게 유용한 신호다. 이 경우 전략 B가 전략 A를 크게 앞설 것이다.

상황 2: 주석에 코드에서 보이지 않는 비즈니스 문맥 (business context)이 포함된 경우

def calculate_fee(amount: float) -> float:
    """
    Partner XYZ와의 2024년 가격 합의에 따른 플랫폼 수수료.
...

"Partner XYZ"와 "2024년 가격 합의"는 구현부(implementation)에서는 보이지 않는 비즈니스 문맥이다. 오직 docstring만이 이 정보를 포함하고 있다.

상황 3: 고품질의 docstring 커버리지가 확보된 경우

코드베이스가 문서화 표준을 강제하고 대부분의 함수가 실질적인 docstring을 보유하고 있는 경우(커버리지 > 60%), 전략 B와 C가 더 경쟁력을 갖게 됩니다.

엔지니어링 권장 사항 (Engineering Recommendations)

대부분의 코드베이스의 경우: 전략 A(원본 코드, raw code)로 시작하십시오. 단순하고 효과적이며 전처리가 필요하지 않습니다.

전략 C를 고려해야 하는 경우:

• 코드베이스에 "의미론적으로 불투명한 (semantically opaque)" 함수가 많은 경우 (부실한 명명 규칙, 의미 없는 파라미터 이름 등)
• 고품질의 docstring 커버리지가 확보된 경우 (함수의 60% 이상이 실질적인 docstring을 보유)
• 질의 패턴이 기술 용어("JWT token validation")보다 비즈니스 언어("user registration flow")에 치우쳐 있는 경우

함수 단위 청크(function-level chunks)에는 항상 구조화된 메타데이터(structured metadata)를 첨부하십시오:

{
    "content": func_body,               # 임베딩할 텍스트
    "metadata": {
...

메타데이터는 임베딩 품질에 영향을 주지 않으면서 검색 후 필터링("auth 모듈만 검색")을 가능하게 하고 탐색("정의로 이동")을 지원합니다.

요약 (Summary)

1. 원본 코드 임베딩이 가장 높은 점수를 기록함 (Recall@5=0.958): 코드 내의 기술적 어휘(라이브러리 이름, 예외 클래스, 함수 이름 등)는 임베딩 모델이 정확하게 활용할 수 있는 정밀한 의미론적 신호(semantic signals)를 제공합니다.
2. Q1은 근본 원인을 지목함: jwt.decode, ExpiredSignatureError는 전략 A가 B보다 우위를 점하게 만드는 구체적인 용어들입니다. 주석만 사용하는 방식은 이러한 정밀한 기술적 신호를 제거하고 이를 모호한 동사로 대체해 버립니다.
3. Q8은 벡터 검색이 메울 수 없는 의미론적 간극을 드러냄: calculate_order_total과 "create Stripe charge" 사이의 거리는 임베딩 전략과 관계없이 의미 공간(semantic space)에 존재합니다. 이러한 사례는 이를 메우기 위해 보완적인 접근 방식(키워드 검색, 호출 그래프)이 필요합니다.

참고 문헌 (References)

• 전체 데모 코드: codebase-kb-03-embedding

PrimeSkills를 확인해 보세요 — 실제 기업급 워크플로우에서 검증된 AI 에이전트와 기술들을 엄선하여 제공하는 마켓플레이스입니다. 불필요한 내용은 빼고, 실제로 작동하는 것들만 모았습니다.

제 홈페이지에서 더 유용한 지식과 흥미로운 제품들을 찾아보세요.