Claude Code + CodeGraph: AI 코딩 비용을 절반으로 줄이는 방법

Claude Code를 쓰다 보면 항상 마주치는 장면이 있다.

 

 

⏺ Explore("인증 미들웨어가 JWT를 어떻게 검증하지?")
⎿ Done (52 tool uses · 89.4k tokens · 1m 37s)

질문 하나 던졌을 뿐인데 Claude는 수십 번 파일을 뒤지고, 토큰을 잔뜩 태우고, 거의 2분이 지나서야 겨우 실제 작업을 시작한다. 이게 매 세션마다 반복된다.

이 문제를 깔끔하게 해결해 주는 오픈소스 도구를 발견했다. 바로 CodeGraph다.

---

문제의 본질: "탐색 세금"

Claude Code는 코드베이스에 대한 기억이 없다. 그래서 매번 Explore 에이전트를 띄워서 grep, glob, Read 호출로 파일을 샅샅이 뒤진다. 이 툴 호출 하나하나가 토큰을 소모하고, 파일을 스캔할수록 컨텍스트 윈도우가 줄어든다. Medium

실제로 측정해 봤더니 하나의 아키텍처 질문에 60번 툴 호출, 157,800 토큰, 거의 2분이 필요했다. 근데 이 중 대부분은 "어디에 뭐가 있는지" 찾는 탐색 작업이지, 실제 코드 분석이 아니다.

AI 코딩 에이전트가 코드베이스 아키텍처에 대한 질문을 받으면, 탐색 하위 에이전트들을 생성해서 심볼 정의를 찾기 위해 grep, 패턴으로 파일을 찾기 위해 glob, 파일 내용을 처리하기 위해 Read를 호출한다. 이 호출들은 각각 별도의 툴 인보케이션으로 토큰 비용이 발생하고 레이턴시를 추가한다. Tosea

이게 바로 **탐색 세금(discovery tax)**이다.

 

 

---

CodeGraph란 무엇인가?

CodeGraph는 코드베이스의 사전 인덱싱된 지식 그래프(심볼, 콜 그래프, 임포트, 상속, 코드 구조)를 빌드하는 오픈소스 도구다. 에이전트가 파일을 하나씩 스캔하는 대신 그 그래프를 한 번에 쿼리한다. Claude Code용 MCP 서버로 실행되며, MIT 라이센스, 19개 이상의 언어를 지원하고, 100% 로컬에서 동작한다. DEV Community

핵심 아이디어는 단순하다. 에이전트가 탐색하기 전에 지도를 먼저 건네주는 것이다.

CodeGraph는 로컬 코드 인텔리전스 라이브러리 + CLI + MCP 서버로, tree-sitter로 코드를 파싱하고 심볼/엣지/파일을 SQLite(FTS5)에 저장한 뒤, MCP를 통해 AI 에이전트에게 지식 그래프를 노출한다. 프로젝트별 데이터는 .codegraph/ 폴더에 저장되며, 추출은 LLM 요약이 아닌 AST 기반으로 결정적(deterministic)이다. GitHub

 

 

 

 

 

---

실제 성능 차이

7개의 실제 오픈소스 코드베이스, 7가지 언어를 대상으로 CodeGraph 유무를 비교한 공식 벤치마크 결과(Claude Opus 4.8, 2026년 6월 재검증): 평균 16% 비용 절감, 47% 토큰 감소, 22% 속도 향상, 58% 툴 호출 감소. GitHub

 

 

 

특히 VS Code 환경에서는 툴 호출이 최대 81%까지 줄어들었는데, 대형 레포일수록 파일 탐색 오버헤드가 크기 때문이다. 반대로 100개 미만의 소규모 프로젝트에서는 효과가 미미하다. DEV Community

---

설치 방법 (3줄이면 끝)

 

 

bash

# 1. 설치
npm install -g @colbymchenry/codegraph

# 2. 프로젝트 인덱싱
cd my-project
codegraph init

# 3. 상태 확인
codegraph status

CodeGraph v0.9.9는 프로그래매틱 라이브러리 사용을 위해 Node.js 22+가 필요하다. CLI와 MCP 서버는 자체 런타임을 번들링하므로, 글로벌 설치 시 Node 버전을 별도로 관리할 필요가 없다. DEV Community

Claude Code에서 MCP 서버를 활성화하려면 .claude/settings.json에 다음을 추가하면 된다.

 

 

json

{
  "mcpServers": {
    "codegraph": {
      "command": "codegraph",
      "args": ["mcp"]
    }
  }
}

---

실제로 어떻게 동작하나?

CodeGraph를 적용하면 Claude Code의 흐름이 완전히 달라진다.

Before (CodeGraph 없이):

 

 

⏺ Explore("JWT 검증 로직 찾기")
  → grep → glob → Read → Read → Read → ...
⎿ Done (52 tool uses · 89.4k tokens · 1m 37s)

After (CodeGraph 적용):

 

 

⏺ codegraph_explore("JWT validation middleware")
⎿ AuthMiddleware.kt:23 - validateToken()
  JwtService.kt:45  - verify(), decode()
  TokenRepository.kt:12 - findByToken()
Done (1 tool use · 3.2k tokens · 4s)

codegraph_explore는 관련 없는 구현들을 시그니처로 축약하면서도, 수천 줄짜리 파일 안에 묻혀 있어도 답을 완전히 보여준다. 응답 크기가 파일 수가 아닌 답변의 내용에 맞게 최적화된다. GitHub

---

언제 쓰면 좋을까?

CodeGraph는 토큰 소모와 툴 호출 빈도라는 AI 지원 개발의 핵심 문제를 해결한다. 100% 로컬에서 동작하기 때문에 민감한 코드가 외부로 나갈 걱정이 없다. AIToolly

쉽게 판단하자면, 아래 상황이면 바로 써볼 만하다.

• 파일이 100개 이상인 프로젝트를 Claude Code로 작업할 때
• "Explore 에이전트가 같은 파일을 계속 반복 스캔한다"는 느낌이 들 때
• Claude Code 비용이 부담될 때
• 코드베이스 아키텍처 질문을 자주 던질 때

반대로 작은 프로젝트나 파일 수가 적은 경우엔 효과가 제한적이다.

---

마무리

CodeGraph의 핵심 아이디어는 생각해 보면 당연하다. AI에게 코드를 탐색하게 두는 게 아니라, 미리 인덱싱된 지식 그래프를 주는 것. Spring Boot 쓸 때 Entity를 매번 파일로 뒤지는 게 아니라 DB 스키마를 보는 것과 비슷한 개념이다.

AI 코딩 도구의 중요한 방향을 보여주는 프로젝트다. 더 강력한 모델만이 답이 아니라, 모델에게 더 좋은 로컬 코드 컨텍스트를 제공하는 것도 하나의 답이다. KnightLi Blog

GitHub 레포는 colbymchenry/codegraph에서 확인할 수 있다. MIT 라이센스 오픈소스다.