한국에서 SW 개발자로 산다는것: 사용기 - CodeGraph 사용하여 Codex 가 코드를 구조화된 코드 그래프로 이해하게 만들기

2026년 6월 12일

사용기 - CodeGraph 사용하여 Codex 가 코드를 구조화된 코드 그래프로 이해하게 만들기

AI 코딩 도구를 사용하면 자주 경험하는 문제는 "프로젝트 구조를 파악하는 데 시간이 많이 걸린다" 였다. 특히 멀티 모듈이나 대규모 코드로 구성된 프로젝트의 경우 기존 소스를 검색하여 파악하는데 많은 시간이 걸린다.

CodeGraph 는 소스 코드를 분석해서 코드베이스를 그래프 형태로 인덱싱하는 오픈소스 프로젝트이다.

CodeGraph는 AI 코딩 에이전트가 프로젝트 소스코드를 매번 grep, find, Read로 처음부터 탐색하지 않도록, 코드베이스를 미리 인덱싱해 코드 지식 그래프로 제공하는 도구다. 로컬 코드베이스를 분석해 .codegraph/ 디렉터리에 인덱스를 저장하고, Codex CLI, Claude Code, Cursor, Gemini CLI, Antigravity IDE 같은 AI 에이전트가 MCP를 통해 이 그래프를 조회할 수 있도록 해준다. 공식 설명에서도 CodeGraph는 tree-sitter 기반으로 코드베이스를 파싱하고, 심볼·엣지·파일 정보를 SQLite/FTS5에 저장하며, MCP를 통해 AI 에이전트에 제공하는 로컬 우선 코드 인텔리전스 도구라고 설명한다.

CodeGraph 는 AST(Abstract Syntax Tree) 결과를 이용하여 코드 그래프를 만들어 사용하고 있는데 관련하여 2026년 arXiv 논문 "Codebase-Memory:Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP" 에 따르면Tree-sitter 기반 코드 지식 그래프 + MCP 방식이 **토큰은 10배 적게, tool call은 2.1배 적게 사용했지만, 답변 품질은 파일 탐색형 agent 92% 대비 83%**였다고 보고한다. 즉, 그래프 기반 탐색은 효율성은 높지만, 원본 파일을 충분히 읽는 방식보다 품질이 낮아질 수 있다는 문제를 보여주고 있다.

CodeGraph는 이런 품질 이슈를 “자동 정답화”로 해결하지 않고, AST 기반 그래프 + context/trace/impact + 원본 body 제공으로 사실 확인 비용을 줄이는 방식으로 완화하고 있다.

1. 설치하기

환경

Model : MacBook Pro (14-inch, 2021)
CPU : Apple M1 Pro
MENORY : 16GB
DISK : 512 GB SSD
OS : macOS 15.3.1 (24D70)
AI Coding Agent : Codex

설치는 npm 을 사용하여 전역으로 설치하는 방식을 사용했다. (여러 프로젝트에서 사용할 수 있도록)

npm install -g @colbymchenry/codegraph

설치 이후에는 다음 명령으로 확인 할 수 있다.

codegraph --version
which codegraph

2. AI 코딩 에이전트에 MCP 연결

CodeGraph는 MCP 서버로 동작한다. 따라서 Codex, Claude Code, Cursor 같은 AI 코딩 도구에서 사용하려면 먼저 MCP 설정을 연결해야 한다. Codex 를 주력으로 사용하고 있어 Codex 에 MCP 로 등록했다.

codegraph install

이 명령은 현재 개발환경에 설치된 AI 에이전트를 감지하고, CodeGraph MCP 서버 설정을 자동으로 추가한다. 공식 README 기준으로 자동 설정 대상에는 Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro 등이 포함된다.