[심층분석] AI 코딩 에이전트가 코드베이스를 92% 더 적은 도구 호출로 탐색한다? CodeGraph가 그리는 새로운 풍경

들어가며: AI 코딩 에이전트의 '탐색 비용' 문제

요즘 Claude Code, Cursor, Codex CLI, OpenCode 같은 AI 코딩 에이전트를 쓰는 분들이 정말 많아졌어요. 그런데 한 번이라도 큰 프로젝트에 이 도구들을 붙여본 분이라면 비슷한 답답함을 느껴보셨을 거예요. "이 함수가 어디서 호출되는지 찾아줘" 같은 간단한 질문을 던졌는데, 에이전트가 한참을 끙끙대면서 파일을 수십 개씩 읽고, grep을 수십 번 돌리고, glob으로 또 뒤지는 거죠. 토큰은 어마어마하게 쓰이고, 응답은 느리고, 결국 답은 어딘가 살짝 틀려 있고요.

이게 왜 그런 거냐면요, 현재의 AI 코딩 에이전트들은 코드베이스를 "탐험가"처럼 다뤄요. 이게 무슨 말이냐면, 매번 새로운 질문이 들어올 때마다 마치 처음 가본 도시에서 길을 찾듯이 파일 시스템을 헤매는 거예요. grep(텍스트 검색 명령어)로 "이 단어가 들어간 파일 찾아!" 하고, glob(파일 패턴 매칭)으로 "이런 이름의 파일들 다 모아와!" 하고, 그렇게 모은 파일들을 일일이 Read 도구로 열어서 읽어보는 거죠. 사람이 IDE 없이 vi만 가지고 100만 줄짜리 프로젝트를 파악하려는 거랑 비슷해요. 가능은 한데, 엄청나게 비효율적이거든요.

바로 이 지점에서 colbymchenry/codegraph라는 오픈소스 프로젝트가 등장했어요. 이름 그대로 "코드 그래프"를 미리 만들어두고, AI 에이전트가 파일을 뒤지는 대신 이 그래프에 질문하도록 만든 도구예요. 결과는요? 6개의 실제 코드베이스(VS Code, Excalidraw, Claude Code 자체, Alamofire, Swift 컴파일러 등)를 대상으로 한 벤치마크에서 평균 92% 적은 도구 호출, 71% 빠른 탐색 속도를 기록했다고 해요. 게다가 100% 로컬에서 돌아가요. 외부로 코드가 새지 않는다는 뜻이죠.

이게 단순히 "빠른 도구 하나 나왔네" 수준의 이야기가 아니에요. AI 코딩 에이전트가 코드를 다루는 근본적인 방식이 바뀔 수도 있는 신호거든요. 오늘은 이 CodeGraph가 정확히 뭘 하는 건지, 왜 이런 접근이 나왔는지, 그리고 우리 한국 개발자들에게는 어떤 의미인지 차근차근 풀어볼게요.

CodeGraph가 정확히 뭘 하는 건가요?

핵심 아이디어를 한 줄로 요약하면 이래요: "AI가 매번 코드를 탐색하지 말고, 미리 만들어둔 지도에서 답을 찾게 하자."

조금 더 구체적으로 설명해볼게요. CodeGraph는 프로젝트를 처음 한 번 "인덱싱"해요. 이 인덱싱이라는 게 뭐냐면, 쉽게 말해서 코드베이스 전체를 분석해서 "어떤 함수가 어디에 정의되어 있고, 어떤 클래스를 상속하고, 어디서 호출되는지"를 전부 그래프 자료구조로 만들어두는 거예요. 도서관에 비유하자면, 책장을 한 권 한 권 뒤지는 대신 미리 "이 주제에 관한 책은 3층 A-12 서가에 있어요" 하고 알려주는 카탈로그를 만들어두는 셈이죠.

그래서 에이전트가 "VS Code에서 extension host가 메인 프로세스랑 어떻게 통신하지?"라고 물어보면, 원래는 IPC 관련 키워드로 50번쯤 grep을 돌렸어야 하는데, CodeGraph가 있으면 그래프에서 통신 관련 심볼들의 관계를 즉시 끌어와요. 벤치마크 결과를 다시 보면 인상적이에요.

| 코드베이스 | CodeGraph 있을 때 | 없을 때 | 개선 |
|---|---|---|---|
| VS Code (TS) | 3 호출, 17초 | 52 호출, 1분 37초 | 94% 적음, 82% 빠름 |
| Excalidraw (TS) | 3 호출, 29초 | 47 호출, 1분 45초 | 94% 적음, 72% 빠름 |
| Claude Code (Python+Rust) | 3 호출, 39초 | 40 호출, 1분 8초 | 93% 적음, 43% 빠름 |
| Claude Code (Java) | 1 호출, 19초 | 26 호출, 1분 22초 | 96% 적음, 77% 빠름 |
| Alamofire (Swift) | 3 호출, 22초 | 32 호출, 1분 39초 | 91% 적음, 78% 빠름 |
| Swift 컴파일러 (Swift/C++) | 6 호출, 35초 | 37 호출, 2분 8초 | 84% 적음, 73% 빠름 |

이 표에서 눈여겨볼 점은 언어를 가리지 않는다는 거예요. TypeScript, Python, Rust, Java, Swift, C++ 다 됩니다. 그리고 단순한 작은 프로젝트가 아니라 VS Code나 Swift 컴파일러 같은 거대 프로젝트에서도 효과가 나온다는 점이에요.

동작 원리: AST와 지식 그래프

그럼 이 마법 같은 일이 어떻게 가능한 걸까요? 핵심은 두 가지 개념이에요: AST(Abstract Syntax Tree) 와 지식 그래프(Knowledge Graph).

AST가 뭐냐면요, 우리가 짜는 코드를 컴퓨터가 이해하기 쉬운 트리 구조로 바꿔놓은 거예요. 예를 들어 function hello() { return 'hi' } 같은 코드를 보면 사람은 그냥 텍스트로 읽지만, 컴파일러나 분석 도구는 "이건 함수 선언이고, 이름은 hello고, 본문에 return 문이 있고, 그 값은 문자열 'hi'다" 하는 식으로 트리로 쪼개요. CodeGraph는 각 언어별로 이 AST를 추출하는 파서(parser, 코드를 분석해서 구조를 뽑아내는 프로그램)를 갖고 있어요. 저장소 안에 debug_python_ast.js 같은 디버그 파일이 보이는 걸로 봐서 언어별로 따로 처리하는 구조인 것 같아요.

지식 그래프는 또 뭐냐면요, 노드(점)와 엣지(선)로 이루어진 자료구조예요. 노드는 "함수", "클래스", "파일" 같은 코드의 구성 요소고, 엣지는 "호출한다", "상속한다", "임포트한다" 같은 관계예요. 그래서 "이 함수를 호출하는 곳 다 보여줘"라고 하면 그래프에서 해당 노드에 연결된 "호출한다" 엣지들만 따라가면 끝나는 거죠. grep으로 텍스트를 일일이 매칭할 필요가 없어요.

예를 들어볼게요. 여러분이 어떤 React 프로젝트에서 <Button> 컴포넌트가 어디서 쓰이는지 찾고 싶다고 해봐요.

기존 방식: 에이전트가 grep -r "Button" src/를 돌려요. 그런데 IconButton, ButtonGroup, buttonStyle 같은 무관한 결과가 잔뜩 나와요. 그걸 다시 필터링하려고 파일을 일일이 읽어요. 토큰 폭발.
CodeGraph 방식: 그래프에서 Button 노드를 찾고, 거기에 연결된 "사용된다" 엣지를 따라가면 바로 정확한 위치 리스트가 나와요. 텍스트 매칭이 아니라 의미론적(semantic) 검색이에요.

이 차이가 대규모 프로젝트에서는 정말 어마어마해요. 100만 줄짜리 코드베이스에서 한 번에 정답을 찾느냐, 50번 시행착오를 거치냐의 차이거든요.

100% 로컬이라는 점의 의미

CodeGraph가 강조하는 또 하나의 포인트가 "100% local"이에요. 이게 왜 중요한지 설명할게요.

요즘 비슷한 콘셉트의 상용 도구들이 있긴 해요. Sourcegraph Cody, GitHub Copilot Workspace, Cursor의 자체 인덱싱 같은 것들이요. 그런데 이런 서비스들은 대부분 코드를 클라우드로 보내서 인덱싱해요. 회사 보안 정책상 외부로 코드를 못 내보내는 곳이 많잖아요? 금융권, 공공기관, 대기업 내부 프로젝트 같은 곳요. 이런 환경에서는 아무리 좋은 AI 도구가 있어도 못 쓰는 경우가 허다해요.

CodeGraph는 npm 패키지로 설치해서 내 노트북에서 인덱싱하고, 내 노트북에서 쿼리해요. 코드가 단 1바이트도 외부로 나가지 않아요. 에이전트가 쓰는 LLM(거대 언어 모델)이 클라우드 기반이긴 하지만, 그 LLM에 넘기는 컨텍스트도 "전체 파일"이 아니라 "그래프에서 추출한 관련 심볼 정보"로 축소되니까 노출되는 양도 훨씬 적어요.

경쟁 기술과의 비교

이 분야에 비슷한 시도들이 꽤 있었어요. 한번 정리해볼게요.

1. Sourcegraph (전통적인 코드 검색 엔진) 원조 격이에요. 코드를 인덱싱해서 빠르게 검색하게 해줘요. 그런데 주로 "사람이 검색"하는 용도로 설계됐어요. AI 에이전트가 쓰기엔 API가 조금 무겁고, 셀프 호스팅도 가능하지만 설정이 복잡해요.

2. Cursor의 내장 인덱싱 Cursor 에디터는 자체적으로 코드베이스를 임베딩(embedding, 텍스트를 벡터로 바꿔서 의미 검색이 가능하게 하는 기술)해요. 그런데 이건 Cursor 안에서만 동작하고, 다른 에이전트(Claude Code, Codex 등)랑은 공유가 안 돼요.

3. tree-sitter 기반 도구들 tree-sitter라는 빠른 파서 라이브러리를 활용해서 AST를 뽑는 도구들이 많아요. CodeGraph도 내부적으로 비슷한 접근일 가능성이 높아요. 차이점은 CodeGraph는 "여러 AI 에이전트가 공통으로 쓰는 인터페이스"를 제공한다는 점이죠.

4. LSP(Language Server Protocol) 사실 VS Code 같은 IDE가 "이 함수 정의로 가기", "참조 찾기"를 빠르게 하는 비결이 LSP예요. 그런데 LSP는 IDE-언어서버 1대1 통신용이라 AI 에이전트 워크플로우에 직접 끼워 쓰기엔 어색해요. CodeGraph는 이걸 에이전트 친화적인 형태로 재포장한 느낌이에요.

비유하자면, 기존 도구들이 "각 IDE에 내장된 사전"이었다면, CodeGraph는 "모든 AI 에이전트가 공유하는 도서관 카탈로그"인 거죠.

한국 개발자에게 주는 시사점

자, 그럼 우리 입장에서 이걸 어떻게 활용하면 좋을까요? 몇 가지 시나리오를 그려볼게요.

시나리오 1: 레거시 프로젝트에 신규 입사한 주니어 개발자 5년 된 Spring Boot 프로젝트에 막 들어왔다고 해봐요. 코드가 수십만 줄이고, 사수는 바쁘고, 문서는 옛날 거. 이럴 때 Claude Code에 CodeGraph를 붙이고 "결제 처리 흐름 설명해줘" 하면, 에이전트가 정확히 관련 클래스/메서드만 짚어서 설명해줘요. 기존이라면 30분 걸릴 파악이 3분으로 줄어요.

시나리오 2: 대기업 보안 환경 외부 API로 코드를 못 보내는 환경에서도 로컬로 인덱싱하니까 도입 장벽이 낮아요. "우리 회사는 Cursor 못 써요" 하시던 분들에게 대안이 될 수 있어요.

시나리오 3: 멀티 언어 모노레포 프론트는 TypeScript, 백엔드는 Python, 데이터 파이프라인은 Rust인 모노레포(monorepo, 여러 프로젝트를 한 저장소에 두는 구조). 보통 언어마다 다른 도구를 써야 하는데, CodeGraph는 다 묶어서 처리해줘요.

도입 시 고려할 점:

초기 인덱싱 시간이 코드베이스 크기에 비례해요. VS Code급이면 첫 인덱싱에 수십 분 걸릴 수 있어요.
코드가 자주 바뀌면 인덱스 갱신 전략을 잘 짜야 해요. 보통 git hook으로 변경된 파일만 재인덱싱하는 방식이 효율적이에요.
아직 신생 프로젝트라 엣지 케이스(예: 동적 타이핑이 심한 Python 코드, 매크로가 많은 Rust)에서 정확도가 떨어질 수 있어요.

학습 로드맵 제안:
1. 일단 npx @colbymchenry/codegraph로 작은 사이드 프로젝트에 붙여보세요. 5분이면 돼요.
2. AST와 LSP의 기본 개념을 익히세요. 이건 CodeGraph뿐 아니라 앞으로 나올 비슷한 도구들 다 이해하는 데 도움돼요.
3. tree-sitter 문서를 한번 훑어보세요. 직접 커스텀 분석 도구를 만들고 싶을 때 든든한 기초가 돼요.

마무리: 코딩 에이전트의 다음 챕터

CodeGraph가 던지는 더 큰 메시지는 이거예요. "AI 에이전트의 성능은 모델 크기만으로 결정되지 않는다." 같은 Claude Opus를 쓰더라도, 컨텍스트를 어떻게 떠먹여주느냐에 따라 결과가 천지차이라는 거죠. 앞으로는 "더 큰 모델"보다 "더 똑똑한 컨텍스트 엔지니어링"이 차별화 포인트가 될 가능성이 커요.

또 하나, AI 에이전트의 도구(tool)가 점점 정교해지고 있다는 점도 주목할 만해요. 처음엔 그냥 bash 하나 던져주고 "알아서 해" 였다면, 이제는 코드베이스 전용 그래프 쿼리, 데이터베이스 스키마 인덱스, API 명세 인덱스 같은 도메인 특화 인덱스들이 줄줄이 나올 거예요.

여러분께 묻고 싶어요. 지금 쓰시는 AI 코딩 에이전트에서 가장 답답한 순간이 언제인가요? "왜 이걸 이렇게 오래 찾고 있지?" 싶었던 경험, 댓글로 공유해주세요. 그리고 CodeGraph 같은 인덱싱 도구를 회사 프로젝트에 도입한다면 어떤 장벽이 있을 것 같은지도 궁금해요. 같이 이야기 나눠봐요.

🔗 출처: GitHub

이 글도 읽어보세요