그래피파이 사용법, 코드를 지식 그래프로 만들어 토큰 줄이기

그래피파이(Graphify)는 프로젝트의 코드와 문서를 "지식 그래프"라는 지도 하나로 엮어 두고, AI 코딩 도구가 파일을 처음부터 다시 읽는 대신 그 지도에 먼저 묻게 하는 무료 오픈소스입니다. 이 글은 그래피파이 사용법으로 클로드 코드에 설치하고, 지도를 만들고, 질문하고, 지우는 순서까지 적었습니다.

그래피파이가 토큰을 아끼는 방식

클로드 코드는 새 대화를 열면 이전 대화의 기억 없이 시작합니다. 코드 구조를 파악하려고 파일을 다시 열어 보고 검색하는 과정에서 토큰(AI가 처리하는 글자 단위, 사용량 한도의 기준)이 듭니다. 프로젝트가 클수록 이 비용이 커집니다.

그래피파이는 이 과정을 한 번만 하도록 바꿉니다.

1. 프로젝트 폴더를 한 번 분석해 파일, 함수, 문서 사이의 관계를 그래프로 저장합니다. "어떤 함수가 어디서 불리는가" 같은 연결이 여기에 들어갑니다.
2. 다음부터 AI는 파일을 하나씩 열기 전에 이 그래프에 먼저 묻습니다.
3. 필요한 부분만 찾아 읽으니 읽는 양이 줄어듭니다.

줄어드는 정도는 프로젝트 크기와 질문 종류에 따라 크게 다릅니다. "49배", "499배" 같은 배수는 써 본 사람들의 보고로 퍼진 숫자이고, 저장소가 공개한 벤치마크는 토큰 절감 배수가 아니라 기억 검색의 정확도 중심입니다(자체 시험 기준). 파일이 수백 개인 프로젝트에서 효과를 기대하고, 파일 몇 개짜리 프로젝트에서는 차이가 작다고 보는 편이 맞습니다.

코드는 밖으로 나가는가

그래피파이의 설명으로는 처리 방식이 파일 종류마다 다릅니다.

코드만 있는 프로젝트라면 AI 모델 없이 지도를 만들 수 있습니다. 비밀 문서가 섞인 폴더에서 /graphify를 돌릴 때는 이 표의 마지막 줄을 기억합니다. AI 모델을 아예 쓰지 않게 하려면 환경 변수 GRAPHIFY_BACKEND=none을 설정합니다.

설치 전 확인

• 쓰는 곳: 클로드 코드(터미널). 그래피파이는 /graphify라는 스킬로 등록됩니다. 클로드 코드 외의 AI 코딩 도구용 설치도 저장소에 안내돼 있습니다.
• 필요한 것: Python 3.10 이상, 파이썬 도구 설치기 uv(또는 pipx).
• 출처: 저장소는 Graphify-Labs/graphify이고(예전 주소 safishamsi/graphify는 이 주소로 연결됩니다) 라이선스는 Apache-2.0입니다. 파이썬 패키지 이름은 graphifyy로 y가 두 개입니다. 이름이 비슷한 다른 패키지는 이 프로젝트와 관련이 없다고 저장소가 안내하므로, 철자를 정확히 입력합니다.
• 별 수와 기능은 바뀌므로 설치 전에 저장소 첫 화면을 한 번 읽습니다. 저장소에는 별도 유료 서비스인 Graphify Cloud 홍보도 함께 있습니다. 아래 설치와 사용은 무료 오픈소스 쪽입니다(2026년 10월 기준).

클로드 코드에 설치하기

1. 터미널을 엽니다. 맥은 터미널 앱, 윈도우는 PowerShell을 씁니다.
2. 그래피파이를 설치합니다.

uv tool install graphifyy

3. 클로드 코드 같은 AI 코딩 도구를 찾아 스킬을 등록합니다.

graphify install

4. graphify 명령을 찾을 수 없다고 나오면 아래 명령을 실행하고 터미널을 새로 엽니다.

uv tool update-shell

지도 만들고 질문하기

1. 분석할 프로젝트 폴더에서 클로드 코드를 실행합니다.
2. 아래 명령으로 지도를 만듭니다.

/graphify .

3. 끝나면 graphify-out/ 폴더에 graph.html(눈으로 보는 지도), GRAPH_REPORT.md(요약 보고서), graph.json(AI가 읽는 지도)이 생깁니다. graph.html을 브라우저로 열면 연결 모양을 볼 수 있습니다.
4. 지도에 직접 물어볼 수 있습니다.

/graphify query "로그인 기능은 데이터베이스와 어떻게 연결되나?"
/graphify path "UserService" "DatabasePool"
/graphify explain "RateLimiter"

query는 질문, path는 두 항목 사이의 연결 경로, explain은 한 항목의 설명입니다. 따옴표 안의 이름은 내 프로젝트의 실제 이름으로 바꿉니다.

5. 평소 대화에서도 AI가 지도를 먼저 보게 하려면 프로젝트 안에서 아래 명령을 한 번 실행합니다. 검색이나 파일 읽기 도구를 쓰기 전에 지도를 참고하도록 설정을 써 넣는 명령입니다. 정확히 어떤 파일이 바뀌는지는 저장소 문서에서 확인합니다.

graphify claude install

6. 코드가 바뀌면 지도도 낡습니다. 커밋과 브랜치 전환 때마다 자동으로 다시 만들려면 아래 명령을 씁니다.

graphify hook install

git pull로 코드를 받은 뒤에는 graphify update .로 갱신합니다.

설치 확인

• 클로드 코드에서 /graphify를 입력했을 때 명령이 보이면 스킬이 등록된 것입니다.
• /graphify .가 끝난 뒤 graphify-out/ 폴더가 생기면 지도 만들기가 성공한 것입니다.
• GRAPH_REPORT.md를 열어 프로젝트의 핵심 파일과 묶음이 실제 구조와 맞는지 눈으로 확인합니다.

지우기

클로드 코드에서만 빼려면 아래 명령을 씁니다.

graphify claude uninstall

모든 도구에서 빼려면 아래 명령을 씁니다. 끝에 --purge를 붙이면 graphify-out/ 폴더까지 지웁니다.

graphify uninstall

막힐 때

• 지도는 만들어졌는데 빈 곳이 많다면: .h, .inc 같은 확장자는 다른 언어로 잘못 읽힐 수 있고, 이때는 오류 없이 지도만 허전해집니다. 저장소 안내대로 .graphifyrc에 언어를 지정합니다.
• 질문 기록이 남는 것이 싫다면: 질문은 기본으로 ~/.cache/graphify-queries.log에 기록됩니다. 끄려면 환경 변수 GRAPHIFY_QUERY_LOG_DISABLE=1을 설정합니다.
• 문서와 PDF를 읽는 단계의 사용량이 걱정된다면: 이 단계는 연결된 모델을 쓰므로 토큰이 듭니다. 코드만 분석하면 이 비용이 없습니다. 로컬 모델 Ollama를 쓰는 방법도 있습니다.