Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 21. 20:47

Graphify가 어떻게 우리 팀의 쿼리당 수천 개의 토큰 소모를 막아주었는가

요약

Graphify를 사용하여 Cursor의 컨텍스트 검색 방식을 지식 그래프 기반으로 최적화하는 방법을 소개합니다. 코드베이스를 지식 그래프로 전처리하여 불필요한 토큰 소모를 줄이고, 효율적인 코드 탐색과 아키텍처 파악이 가능해집니다.

핵심 포인트

  • Graphify는 코드베이스를 지식 그래프로 변환하여 컨텍스트 검색 효율을 높임
  • tree-sitter AST 파싱을 통해 로컬에서 안전하게 코드를 추출함
  • Cursor와 통합하여 불필요한 파일 읽기와 토큰 낭비를 방지함
  • 프로젝트 구조를 요약한 아키텍처 보고서(GRAPH_REPORT.md)를 제공함

우리의 인증 흐름(auth flow)에 대해 Cursor에게 물어볼 때마다, Cursor는 8~12개의 파일을 열고 각각을 읽어 내려가며 답변을 시작하기도 전에 토큰을 소모해 버리곤 했습니다. 6명의 개발자가 유지 관리하는 React Native 코드베이스의 경우, 이는 빠르게 누적됩니다.

저는 React Native 앱을 구축하는 프론트엔드 팀을 이끌고 있습니다. Cursor는 우리의 주요 IDE입니다. Cursor는 코드를 이해하는 능력이 뛰어나지만, grepping 및 원시 파일(raw files)을 순차적으로 읽는 방식의 컨텍스트(context) 검색 방식은 규모가 큰 프로젝트에서는 확장성이 떨어집니다.

그러다 Graphify를 발견했고, 이는 우리의 AI 어시스턴트가 코드베이스와 상호작용하는 방식을 근본적으로 바꾸어 놓았습니다.

Graphify가 실제로 하는 일

설정에 들어가기에 앞서, 그 메커니즘을 이해할 가치가 있습니다. 왜냐하면 이것은 단순한 또 다른 Cursor 플러그인이 아니기 때문입니다.

Graphify는 프로젝트 전체를 **지식 그래프 (knowledge graph)**로 전처리합니다. 모든 함수, 클래스, 모듈, 개념이 노드(node)가 되고, 그들 사이의 모든 관계가 엣지(edge)가 되는 코드베이스의 지도라고 생각하면 됩니다. Cursor가 질문에 답해야 할 때, 흐름을 이해하기 위해 47개의 파일을 읽는 대신 graphify query "auth flow"를 실행합니다. 이는 관련 노드와 연결만 반환하는 범위가 지정된 서브그래프(subgraph) 조회입니다.

중요한 부분은 코드 추출이 tree-sitter AST 파싱을 통해 완전히 로컬에서 이루어진다는 점입니다. API 호출도 없고, 코드가 기기를 벗어나지도 않습니다. 문서, PDF 또는 이미지를 처리할 때만 LLM을 사용합니다. 순수 코드 프로젝트(대부분의 React Native 앱이 그러하듯)의 경우, 추출 비용은 기본적으로 제로에 가깝습니다.

출력물은 세 개의 파일로 구성됩니다:

  • graph.json — 전체 그래프 (어시스턴트가 쿼리하는 핵심 결과물)
  • graph.html — 브라우저에서 탐색할 수 있는 대화형 시각화 도구
  • GRAPH_REPORT.md — 주요 노드(god nodes), 놀라운 연결 관계, 제안된 질문들이 포함된 아키텍처 요약 보고서

그 보고서 하나만으로도 설정할 가치가 충분합니다. 보고서는 당신이 존재를 몰랐던 모듈 간의 연결을 찾아내고, 프로젝트에서 가장 많이 연결된 개념들, 즉 모든 것이 흘러가는 핵심 요소들을 드러내 줍니다.

Cursor를 위한 Graphify 설정

저는 M1 MacBook Pro를 사용하고 있습니다. 제가 성공했던 정확한 설정 방법은 다음과 같습니다.

설치

brew install uv  # 아직 설치되어 있지 않다면 실행
uv tool install graphifyy

중요: pip install이 아닌 uv tool install을 사용하세요. M1 Mac의 경우, Graphify가 런타임에 캐시된 경로로부터 Python 바이너리를 찾아내기 때문에 pip를 사용하면 Python 경로 해석 (path resolution)이 깨질 수 있습니다. uv는 환경을 격리하여 이 문제를 완전히 방지합니다. 저는 이 과정을 통해 뼈아픈 교훈을 얻었습니다.

그래프 구축 (Build the graph)

cd your-project
graphify extract .

첫 실행은 코드베이스 크기에 따라 몇 분 정도 소요됩니다. 저희 프로젝트는 모두 코드(PDF/문서 없음)로 구성되어 있어, 전체 추출 과정이 tree-sitter 상에서 로컬로 실행됩니다. 이 단계에서는 API 키가 필요하지 않습니다.

Cursor 통합 설치

graphify cursor install

이 명령은 alwaysApply: true가 설정된 .cursor/rules/graphify.mdc 파일을 생성합니다. Cursor의 규칙 시스템 (rule system)을 사용해 보셨다면 이것이 무엇을 의미하는지 아실 겁니다. 이 규칙은 모든 대화에 자동으로 주입되어, Cursor가 원본 소스 파일을 읽는 대신 graphify query를 우선적으로 사용하도록 지시합니다.

.mdc 파일을 다루는 분들을 위한 짧은 참고 사항: alwaysApply: false이면서 globs와 description이 없는 규칙은 절대 자동으로 적용되지 않으며, 수동으로 @ 멘션(mention)을 해야만 사용할 수 있습니다. Graphify는 전역 프로젝트 컨텍스트 규칙에 적합한 방식인 alwaysApply: true로 설정합니다.

git hook 설정

graphify hook install

이 명령은 post-commit 훅을 설치합니다. 누군가 커밋을 할 때마다 tree-sitter를 사용하여 그래프를 자동으로 재구축합니다. 이 과정은 완전히 로컬에서 이루어지며 몇 초밖에 걸리지 않습니다. 또한 git 머지 드라이버 (merge driver)를 설정하여, 두 명의 개발자가 병렬로 그래프 업데이트를 커밋하더라도 충돌 표시 (conflict markers)가 남는 대신 graph.json이 자동으로 합집합 머지 (union-merged)되도록 합니다.

이 설정을 마치고 나면, 여러분은 기본적으로 Graphify가 실행되고 있다는 사실조차 잊게 됩니다. 그래프는 모든 커밋과 함께 최신 상태를 유지합니다.

팀에 도입하기

이 도구를 도입하기 전에 제가 가장 많이 질문했던 부분입니다. 실무적인 내용들을 다루어 보겠습니다.

커밋해야 할 항목

다음 항목들을 저장소(repo)에 추가하세요:

graphify-out/
├── graph.json          # 핵심 아티팩트 (core artifact)
├── graph.html          # 인터랙티브 시각화 (interactive visualization)
...

.gitignore에 다음을 추가하세요:

graphify-out/cost.json

cost.json은 추출 과정 중 Graphify 자체의 LLM API 비용을 추적합니다. Cursor에서 절약된 토큰이 아닙니다. 이는 로컬 회계(local accounting) 용도이며, 공유 아티팩트(shared artifact)가 아닙니다.

Graphify를 사용하지 않는 팀원들에게 미치는 영향

없음 (Zero). 이 점이 중요합니다. Graphify는 순수하게 부가적인(additive) 도구입니다.

graphify-out/ 폴더는 단순히 불활성 데이터 파일(inert data files)일 뿐입니다. 빌드 프로세스가 이 파일에 의존하지 않으며, 이 파일이 없다고 해서 CI가 깨지지도 않습니다. .mdc 파일은 해당 규칙을 활성화한 Cursor 사용자에게만 영향을 미칩니다. 만약 Graphify가 설치되지 않은 개발자가 post-commit 훅(hook)을 트리거하면, 오류가 조용히 발생하고(실행 파일을 찾을 수 없음) 커밋은 정상적으로 진행됩니다.

단계적으로 도입할 수 있습니다. 본인에게 먼저 설치하고 graphify-out/을 커밋하면, 다른 개발자들은 나중에 Graphify를 설치할 때마다 그래프의 혜택을 누릴 수 있습니다. 별도의 조율이 필요하지 않습니다.

권장되는 팀 워크플로우 (workflow)

  1. main 브랜치에서의 초기 설정 — main 브랜치에서 첫 번째 graphify extract .를 실행하고 graphify-out/을 커밋하세요. 이것이 모든 사람이 가져오는(pull) 공유 기준점(shared baseline)이 됩니다.
  2. 기능 브랜치(Feature branches)의 자동 업데이트 — git 훅(hook)이 모든 브랜치의 커밋 이후에 점진적으로(incrementally) 재빌드합니다.
  3. main으로 머지(merge) 시 — 기능 브랜치의 그래프가 함께 따라옵니다. 머지 드라이버(merge driver)가 동시 업데이트를 처리합니다.

한 가지 예외 상황: 만약 누군가 훅(hook)이 설치되지 않은 상태로 장기간 유지되는 기능 브랜치를 운영한다면, 그들의 graph.json은 드리프트(drift, 차이 발생)될 것입니다. MR(Merge Request)을 올리기 전에 수동으로 graphify extract . --update를 실행하면 동기화됩니다. 이를 우리 MR 체크리스트에 추가하는 것도 고려해 보았지만, 솔직히 훅(hook)이 99%의 케이스를 처리합니다.

발생할 수 있는 문제

제가 직접 겪었거나 예상했던 몇 가지 사항입니다:

M1 pip 문제. 위에서 이미 언급했듯이, pip 대신 uv tool install을 사용하세요. 이 문제를 파악하기 전까지 경로 해석(path resolution)을 디버깅하는 데 약 20분을 허비했습니다.

실제로 토큰 절약량을 측정할 수 있나요? 솔직히 말해서, 직접적으로는 불가능합니다. Cursor는 대화당 토큰 사용량을 공개하지 않습니다. 대신 다음과 같은 현상을 관찰할 수 있습니다: 응답 지연 시간(latency) 감소(그래프 쿼리가 여러 파일을 읽는 것보다 빠름), 컨텍스트 윈도우(context window) 압박 감소(

  • 코드베이스에 50개 이상의 파일과 상호작용하는 여러 모듈이 있는 경우
  • Cursor (또는 Claude Code, Codex, Gemini CLI — 10개 이상의 어시스턴트를 지원함)를 사용하는 경우
  • 팀 단위로 작업하며, AI 어시스턴트가 세션 사이의 코드베이스를 "알지" 못하는 것에 지친 경우
  • 코드 리뷰를 수행하며 변경 사항이 시스템의 나머지 부분과 어떻게 연결되는지 빠르게 이해해야 하는 경우

5~6개의 파일로 구성된 작은 프로젝트의 경우, 그래프가 구조적 명확성을 더해주기는 하지만 토큰 절약 효과는 미미합니다. 파일들이 이미 컨텍스트 윈도우(context window)에 들어갈 수 있기 때문입니다.

사용해 보기

brew install uv
uv tool install graphifyy
cd your-project
...

설정하는 데 단 5개의 명령어가 필요합니다. 그래프가 구축되면 어시스턴트가 이를 사용하기 시작하며, 훅(hook)이 최신 상태를 유지합니다. 작성해야 할 설정 파일도, 실행해야 할 서비스도 없습니다.

전체 문서는 Graphify repo에서 확인하세요. 특히 Cursor를 사용 중이라면, .mdc 통합이 가장 매끄러운 방법입니다. 그냥 바로 작동합니다.

만약 Cursor가 대화할 때마다 코드베이스를 "잊어버리는" 것처럼 느껴지거나, 굳이 읽을 필요가 없는 파일들을 읽느라 컨텍스트를 낭비하고 있다면, Graphify를 설정하는 데 10분을 투자할 가치가 있습니다. 저에게는 그랬습니다.

저는 AI 지원 개발 워크플로우를 탐구하고 있는 React Native 테크 리드입니다. Twitter와 GitHub에서 저를 찾아보세요.

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0