[AI] CodeGraph

개요

CodeGraph는 코드베이스를 그래프로 인덱싱해 AI 코딩 에이전트가 코드 구조를 빠르게 찾도록 돕는 오픈소스 도구이다.

함수, 클래스, 파일, 호출 관계, import 관계를 로컬 SQLite 데이터베이스에 저장한다.
이후 MCP(Model Context Protocol), CLI, TypeScript API로 조회할 수 있다.

기존 방식에서는 AI 에이전트가 grep, 파일 목록 조회, 파일 읽기를 반복하며 코드를 이해한다. 작은 프로젝트에서는 크게 문제 되지 않는다.

하지만 모듈이 많고 호출 관계가 복잡한 저장소에서는 탐색 비용이 커진다.
CodeGraph는 이 탐색 과정을 미리 만든 인덱스로 줄이는 도구에 가깝다.

팀 관점에서는 신규 코드 파악, 영향 범위 분석, 리팩터링 전 확인 작업에 의미가 있다.
Codex, Claude Code, Cursor 같은 AI 도구를 운영 흐름에 붙여 쓰는 팀이라면 코드 검색을 매번 처음부터 시키지 않아도 된다.

주요 특징

CodeGraph의 핵심은 로컬 인덱스이다.

tree-sitter로 코드를 파싱하고, 심볼과 관계를 .codegraph/ 아래에 저장한다.
공식 문서 기준으로 20개 이상 언어를 지원한다고 설명되어 있다.

다만 실제 지원 범위와 품질은 사용하는 언어와 프레임워크에 따라 확인이 필요하다.

MCP 서버를 제공하는 점도 중요하다.

CodeGraph를 MCP로 연결하면 에이전트가 다음과 같은 도구를 호출해 코드 구조를 조회할 수 있다.

codegraph_context
codegraph_callers
codegraph_impact

CLI도 제공하며 설치, 인덱싱, 상태 확인, 심볼 검색, 영향 범위 확인을 터미널에서 실행할 수 있다.
AI 에이전트 없이도 코드 구조를 확인하는 용도로 쓸 수 있다.

다른 단순 코드 검색 도구와의 차이는 "문자열 검색"보다 "구조 검색"에 있다.

예를 들어 UserService라는 문자열이 어디 있는지 찾는 것이 아니라,
해당 심볼을 누가 호출하는지, 바꾸면 어떤 테스트가 영향을 받을 수 있는지 확인하는 방식이다.

사용이 필요한 상황

CodeGraph는 아래와 같은 상황에서 유용하다.

여러 저장소에서 비슷한 코드 탐색 작업을 반복하는 경우
대형 코드베이스에서 함수 호출 관계를 빠르게 확인해야 하는 경우
AI 코딩 에이전트가 파일 탐색에 너무 많은 시간을 쓰는 경우
리팩터링 전에 영향 범위를 보고 싶은 경우
신규 팀원이 프로젝트 구조를 빠르게 파악해야 하는 경우
PoC 단계에서 AI 도구와 코드 인덱싱 흐름을 검증하고 싶은 경우

작은 규모의 저장소에는 과할 수 있다. 반대로 서비스 코드, 모노레포, 여러 모듈이 얽힌 백엔드에서는 체감이 더 크다.

설치 또는 시작 방법

Node.js와 npm이 필요하다.
공식 문서에서는 npx 실행과 전역 설치 방식을 안내한다.

npx @colbymchenry/codegraph

이 명령은 대화형 설치를 실행한다. 사용하는 AI 도구에 맞춰 설정을 추가하는 흐름이다.

프로젝트에서 CodeGraph를 초기화하려면 저장소 루트에서 실행한다.

cd your-project
codegraph init -i
codegraph status

codegraph init -i는 프로젝트에 .codegraph/를 만들고 인덱싱까지 수행한다.
codegraph status는 인덱스 상태, 파일 수, 백엔드 정보를 확인한다.

MCP 서버를 직접 확인하려면 아래처럼 실행할 수 있다.

codegraph serve --mcp

AI 도구에서 연결이 안 될 때는 이 명령이 정상 실행되는지 먼저 확인하는 것이 좋다.

실습

간단한 시나리오는 "리팩터링 전 영향 범위 확인"이다.

1. 사전 조건

Node.js와 npm이 설치되어 있어야 한다.
프로젝트는 Git 저장소 루트에서 실행하는 편이 좋다.

2. 설치

npx @colbymchenry/codegraph를 실행한다.
필요하면 전역 설치도 가능하다.

3. 설정

프로젝트 루트에서 codegraph init -i를 실행한다.
이때 .codegraph/config.json이 생성된다.

node_modules, dist, build 같은 디렉터리는 기본적으로 제외하는 편이 낫다.

4. 실행

심볼을 검색하거나 컨텍스트를 만든다.

codegraph query UserService
codegraph context "fix login bug"
codegraph affected src/auth/UserService.ts

query는 심볼을 찾는다.
context는 특정 작업에 필요한 코드 맥락을 구성한다.
affected는 변경 파일과 관련된 테스트나 의존 파일을 찾는 데 사용한다.

5. 결과 확인

CLI 결과에서 관련 파일과 심볼을 확인한다.
MCP로 연결했다면 AI 에이전트가 이 정보를 직접 조회한다.

알아야 할 사항

CodeGraph는 로컬 우선 도구이다.
코드가 외부 서비스로 전송되지 않는 구조라고 공식 문서에서 설명한다.

그래도 회사 저장소에 적용할 때는 다음 항목을 확인해야 한다.

MCP 설정 파일
인덱스 저장 위치
접근 권한
저장소 보안 정책

운영 환경에서 직접 서비스 트래픽을 처리하는 도구는 아니다. 개발자 워크스테이션이나 CI 보조 도구에 가깝다.

CI에서 사용할 경우 인덱싱 시간, 캐시 전략, 저장소 크기를 함께 봐야 한다. SQLite 백엔드도 확인해야 한다.
공식 README에는 native 백엔드와 WASM fallback 관련 주의사항이 있다.

WASM fallback에서는 인덱싱이나 MCP 조회가 느릴 수 있다고 설명한다.
codegraph status에서 백엔드 상태를 확인하는 것이 좋다.

대체 도구와 비교하면, 일반 검색 도구는 문자열 검색에 가깝고 CodeGraph는 AST 기반 관계 조회에 가깝다.

Semgrep, Sourcegraph, IDE 인덱스와 겹치는 부분도 있지만 목표가 조금 다르다.
CodeGraph는 AI 에이전트가 구조적 질문을 적은 호출로 해결하게 하는 데 초점이 있다.

장점과 아쉬운 점

구분	내용
장점	로컬에서 동작한다. 코드 구조를 심볼과 관계 기준으로 조회할 수 있다. MCP를 통해 AI 코딩 도구와 연결할 수 있다.
아쉬운 점	언어와 프레임워크별 인식 품질은 직접 확인해야 한다. 큰 저장소에서는 초기 인덱싱 시간이 걸린다. 팀 표준으로 쓰려면 MCP 설정 관리가 필요하다.

정리

CodeGraph는 AI 코딩 에이전트가 코드베이스를 더 구조적으로 읽도록 돕는 도구이다.

문자열 검색만으로는 부족한 호출 관계, 영향 범위, 파일 구조를 로컬 인덱스로 조회한다.

DevOps 엔지니어와 플랫폼 엔지니어에게는
AI 개발 도구를 팀 환경에 붙일 때 검토할 만한 선택지다.

개발자에게는 리팩터링 전 탐색 시간을 줄이는 보조 도구로 쓸 수 있다.

바로 전체 저장소에 적용하기보다 작은 프로젝트나 PoC 저장소에서 먼저 확인하는 편이 낫다.
언어 지원, 인덱싱 시간, MCP 연결 방식, 팀 보안 정책을 검증한 뒤 확대하는 흐름이 현실적이다.

최신 설치 방법과 지원 범위는 공식 문서, GitHub README, 릴리즈 노트를 기준으로 확인해야 한다.