코드 위키

한 줄 정의

코딩 에이전트가 매번 원시 파일들을 전체 검색(grep)하고 새로 분석하는 대신, 코드베이스의 정적 구조(호출 관계, 의존성, 상속 등)를 사전에 구조화된 데이터베이스 형태로 컴파일하여 저장하고 이를 필요할 때마다 쿼리하여 활용할 수 있도록 돕는 코드 도메인 전용의 지식 관리 아키텍처이다.

핵심 요지

안드레이 카파시의 지식 컴파일 철학의 코드 도메인 이식: 질문할 때마다 문서를 새로 읽는 비효율적 검색 방식(RAG)에서 벗어나, 코드 분석 구조를 SQLite 등의 로컬 데이터베이스에 저장하여 에이전트가 직접 조회하게 만든다.
다단계 간접 의존성 추적: 단순 텍스트 키워드 매칭(grep)으로는 탐지하기 불가능한 다단계 간접 의존성(예: A 함수가 직접 호출하지 않지만 중간 함수를 거쳐 영향받는 경로)을 그래프 경로 탐색을 통해 완벽하게 포착한다.
인지적 비용 및 API 비용 절감: 에이전트가 수많은 소스 코드 원시 텍스트를 통째로 컨텍스트 윈도우에 적재해 추론할 필요 없이, 컴파일된 소량의 핵심 관계 정보만 조회하므로 입력 토큰 소모량을 획기적으로 줄인다.
tree-sitter 기반 구문 분석 및 MCP 연동: 단순 들여쓰기나 정규식이 아닌 구문 분석기를 통해 함수의 경계를 정밀 파악하고, 모델 컨텍스트 프로토콜(MCP)을 사용해 LLM 에이전트와 매끄럽게 연결된다.

상세

1. 코드 위키의 동작 아키텍처

기존의 RAG나 단순 텍스트 검색 방식은 코드를 평면적인 문자열로 취급하기 때문에 구문 간의 계층 구조나 의존성을 논리적으로 이해하지 못한다. 반면, 코드 위키는 코드베이스를 하나의 정밀한 ‘코드 그래프(Code Graph)‘로 구조화하여 관리한다.

파싱 (Parsing): 구문 분석 도구인 tree-sitter를 이용해 다양한 언어의 구문을 정확히 분석하고 클래스, 함수, 변수 등의 심볼과 그 경계를 명확하게 획득한다.
정적 구조 컴파일 (Static Structure Compile): 분석된 심볼을 노드(Node)로, 심볼 간의 호출(Call), 모듈 임포트(Import), 클래스 상속(Inheritance) 관계를 에지(Edge)로 정의하여 SQLite 형태의 로컬 데이터베이스에 저장한다.
MCP 서버 구동 (Model Context Protocol): SQLite에 빌드된 관계 데이터를 MCP 서버 형태로 래핑하여, 에이전트가 텍스트 검색 API 대신 SQL이나 전용 MCP 도구를 통해 직접 그래프 쿼리를 호출하도록 지원한다.
로컬 우선(Local-first) 설계: 모든 파싱과 쿼리 작업이 로컬 개발 장비에서 이루어지므로 외부 클라우드로의 코드 유출이 발생하지 않으며 추가적인 API 요금이 발생하지 않는다.

2. 주요 구현 도구 비교

현재 시장에서 대표적으로 사용되는 오픈소스 코드 위키 도구는 다음과 같이 특징이 구분된다 (raw/Andrej Karpathy’s Fix for LLM Memory Works on Code Too.md).

비교 항목	Codegraph (`colbymchenry/codegraph`)	Code Review Graph (`tirth8205/code-review-graph`)
주요 용도	코딩 중 일상적인 코드베이스 분석 및 관계 추적	풀 리퀘스트(PR) 병합 전 변경 영향 범위 및 테스트 보장 점검
GitHub 스타	60,000개 이상	25,000개 이상
인덱싱 속도	빠름 (OmniRoute 기준 34초)	보통 (OmniRoute 기준 2분 25초)
데이터 크기	조밀함 (OmniRoute 기준 325MB)	큼 (OmniRoute 기준 1.4GB)
상세도 (Granularity)	파일 단위 요약 및 핵심 의존성 식별	라인 번호 및 구체적인 테스트 케이스 이름까지 정밀 맵핑
특화 기능	`impact`, `callers`를 통한 충격 범위 탐색	가중치 기반 위험 점수(Risk Score) 산정 및 PR Gate 기능

예시

1. Codegraph를 이용한 간접 의존성 영향 범위 확인

개발자가 OmniRoute 프로젝트(raw/Andrej Karpathy’s Fix for LLM Memory Works on Code Too.md에 언급된 8,000개 이상의 파일을 가진 오픈소스)의 라우팅 인증 핵심 함수인 classifyRoute를 수정하려고 한다.

단순 키워드 검색(grep)을 적용하는 경우, “classifyRoute”를 포함한 3개 파일의 17개 매칭 결과만 검출될 뿐, 해당 함수를 직접 호출하지 않는 proxy.ts는 탐지 대상에서 누락된다. proxy.ts는 중간 매개 함수인 runAuthzPipeline을 통해 간접적으로 연결되어 있기 때문이다.

이때 코드 위키의 일종인 codegraph에 impact 명령어를 입력하면 그래프 경로 탐색을 수행하여 단 344바이트 크기의 정제된 간접 의존 관계 리포트를 반환한다.

# codegraph 설치 및 초기화
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
codegraph install
codegraph init
 
# classifyRoute 수정 시 영향 범위 쿼리
codegraph impact classifyRoute

이 방식은 영향 범위에 속한 전체 원시 파일들을 LLM 에이전트에게 그대로 다 읽히는 기존 RAG 방식 대비 입력 데이터 전송량을 98.7% 가량 절감하여 경제적이고 신속한 응답을 유도한다 (raw/Andrej Karpathy’s Fix for LLM Memory Works on Code Too.md).

2. Code Review Graph를 이용한 테스트 확인 및 위험도 제어

코드 변경이 완료된 후 풀 리퀘스트(PR)를 작성하기 직전 단계에서는 code-review-graph를 활용한다.

# code-review-graph 설치 및 빌드
pip install code-review-graph
code-review-graph install
code-review-graph build

수정된 함수 classifyRoute의 영향 범위를 조회하면, code-review-graph는 단순 파일명뿐만 아니라 이 함수를 검증하고 있는 구체적인 테스트 케이스 4개의 정확한 명칭과 코드 라인 번호까지 상세 리스트로 반환한다 (raw/Andrej Karpathy’s Fix for LLM Memory Works on Code Too.md).

동시에 다음 6가지 가중치 요인을 합산하여 변경 사항의 위험도 점수(Risk Score)를 매기고, 기준 점수 초과 시 PR 병합을 차단(Gate)하는 보호 장치를 구성한다 (raw/Andrej Karpathy’s Fix for LLM Memory Works on Code Too.md).

호출 빈도 (호출 노드가 많을수록 고가중치)
변경 지점의 테스트 커버리지 유무
보안 관련 키워드(예: Auth, Credentials, SSL 등) 일치 여부
(기타 수정한 영역의 가중치 요인 등 총 6가지 요소의 합산 및 상한선 적용)

충돌

자동 실시간 동기화 오작동: 코드를 수정하고 파일이 저장되는 즉시 자동으로 인덱스가 갱신되는 기능이 간혹 오작동하는 것으로 보고되었다 (raw/Andrej Karpathy’s Fix for LLM Memory Works on Code Too.md). 이 경우 해시값 불일치로 인해 삭제된 이전 노드가 그래프 상에 잔존하거나 신규 노드가 쿼리에서 누락되는 문제가 발생한다. 안정성이 필요한 중요 작업 전에는 인덱스를 완전히 재구축(Rebuild)해야 한다.
특정 프로그래밍 언어의 파싱 제한: tree-sitter 구문 파서는 매크로 사용이 극도로 잦은 C 언어 등에서 전처리 단계의 매크로를 올바르게 처리하지 못해 파싱 정확도가 하락하고 그래프에 결손이 생기는 구조적 문제가 벤치마크 결과 확인되었다 (raw/Andrej Karpathy’s Fix for LLM Memory Works on Code Too.md).
영향 범위 검출의 정밀도 한계 (노이즈): code-review-graph 공식 데이터에 따르면 도구가 ‘변경에 영향받음’으로 지목한 노드 10개 중 4개는 실제 변경과 전혀 관련이 없는 무관한 파일이었다 (raw/Andrej Karpathy’s Fix for LLM Memory Works on Code Too.md). 이는 과도하게 넓은 범위로 탐색을 시도했을 때 596KB에 달하는 대용량 데이터가 출력되며 노드가 일부 유실(5,264개 노드 중 500개만 출력되고 나머지는 생략)되는 부작용과도 이어진다. 따라서 도구의 분석 결과를 맹신하기보다는 좁은 쿼리 범위를 유지하며 시니어 엔지니어의 크로스체크를 병행해야 한다.

LLM Wiki

탐색기