문제점

AI 코딩 도구를 만드는 5개 팀에게 LLM을 위해 코드베이스를 어떻게 표현하는지 물어본다면, 두 가지 답변을 듣게 될 것입니다: 임베딩(embeddings) 또는 의존성 그래프(dependency graph)입니다. 두 진영 모두 각기 다른 질문에 대해서는 옳습니다. 사용 사례에 맞지 않는 도구를 선택하는 것이 일부 "시맨틱 코드 검색 (semantic code search)" 도구들이 기술적으로는 유사하지만 실제로는 쓸모없는 결과를 반환하는 이유입니다.

아키텍처: 각 모델이 실제로 포착하는 것

벡터(Vectors): 시맨틱 유사성 (Semantic Similarity)

embed("parse a JWT token") ≈ embed(function verifyToken(token) {...})

임베딩(Embeddings)은 의미론적으로 유사한 함수들을 벡터 공간(vector space)에서 가깝게 배치합니다. 쿼리는 정확한 키워드 일치가 필요하지 않습니다. "parse a JWT token"은 함수의 이름이 decodeAuthPayload라 할지라도 적절한 유틸리티를 찾아냅니다.

최적의 용도: 의도에 따른 생소한 코드 찾기, 서로 다른 스타일 간의 코드 완성 (code completion), 중복 로직 식별, 문서의 시맨틱 클러스터링 (semantic clustering).

한계: 벡터는 의미를 포착하지만 구조를 포착하지는 않습니다. 의미론적으로 유사한 두 함수는 제작 시기가 몇 년씩 차이 날 수 있으며, 하나는 폐기(deprecated)되었고 다른 하나는 운영 환경(production)에서 실행 중일 수 있습니다. 임베딩은 그 차이를 알지 못합니다.

그래프(Graphs): 구조적 진실 (Structural Truth)

callers(auth/middleware.js) → [23 modules]
communities() → [{name: "billing", files: [...]}, {name: "auth", files: [...]}]

임포트(imports), 호출(calls), 상속(inheritance)을 탐색하는 것은 도달 가능성(reachability), 이행적 의존성(transitive dependencies), 소유권 경계(ownership boundaries)와 같은 정확한 구조적 질문에 답합니다.

최적의 용도: 함수를 변경했을 때 무엇이 깨지는지 찾기, 모듈 의존성 매핑, 핫 패스(hot-path) 슬라이스 식별, 커뮤니티 탐지(community detection)를 통한 팀 경계 감지.

한계: 그래프는 구조적으로 "도달 가능한 (reachable)" 모든 것을 찾아내지만, 관련성에 따라 순위를 매기거나 관련 없는 컴포넌트 간의 의도 기반 유사성을 포착할 수는 없습니다. 그래프 탐색은 당신의 질문에 실제로 중요한 3개가 무엇인지에 대한 감각 없이, 구조적으로 연결된 40개의 파일을 기꺼이 반환할 것입니다.

구현: 결합된 패턴

어느 모델도 압도적으로 승리하지 않습니다. 표준적인 패턴은 이들을 체인(chain)으로 연결하는 것입니다:

# 1단계: 그래프 우선 이웃 탐색 (graph-first neighborhood)
neighborhood = graph.get_neighborhood(
    target_file,
...

이를 통해 여러분은 연결성이 확보된(구조적으로 관련이 있다고 그래프로 검증된) 결과와 의미론적 관련성(해당 제한된 집합 내에서 벡터로 순위가 매겨진)을 모두 얻을 수 있습니다. 이는 노이즈가 많은 전역 벡터 검색(global vector search)이나, 구조적으로 도달 가능한 모든 것을 순위 없이 쌓아놓은 결과 대신 더 나은 대안을 제공합니다.

주의해야 할 실패 모드 (Failure Modes)

학습 내용 (Learnings)

일반화할 수 있는 의사결정 프레임워크는 다음과 같습니다: 엔지니어들이 실제로 무엇을 쿼리(query)하는지 질문하십시오.

• 주로 "X를 수행하는 코드를 찾아줘" → 벡터만으로도 충분할 가능성이 높음
• 주로 "X를 변경하면 무엇이 깨지는가" 또는 "팀의 경계(boundaries)는 어디인가" → 그래프가 필요함
• 대부분의 성숙한 코드베이스는 결국 위와 같이 체인(chain)으로 연결된 두 가지 방식 모두를 필요로 함

리소스 (Resources)

• Spiderbrain은 정확히 이 패턴을 사용합니다: 미리 구축된 구조적 그래프(structural graph)에 쿼리 시점에 의미론적 재순위화(semantic re-ranking)를 적용합니다.
• 관련 자료: Every AI Coding Assistant Sees Your Files, Not Your Architecture (이 논쟁의 그래프 측면을 더 심도 있게 다룸)

🚀 Local 버전 무료 · ☁️ Pro & Cortex 버전 호스팅 제공

링크 : https://spiderbrain.ai/

Linkedin : https://www.linkedin.com/company/spiderbrain

토론 : 만약 여러분이 오늘 코드베이스에 대해 벡터 검색을 실행하고 있다면, 먼저 어떤 구조적 신호(structural signal)로 후보를 제한하고 있습니까, 아니면 매번 전체 임베딩 공간(embedding space)을 검색하고 있습니까?