큰 저장소에서 Claude Code의 새 세션을 시작할 때마다, 이전 세션이 끝나며 사라진 머릿속 지도를 다시 만들어야 합니다. grep을 돌리고, 파일을 다시 읽고, 방향을 잡느라 토큰을 씁니다. Graphify는 코드베이스를 지속적으로 보존되는 질의 가능한 지도로 바꿔 이 비용을 줄입니다.
텍스트 검색 대신 AST를 따라가기: Graphify의 지속형 지도
Graphify는 오픈소스 MIT 라이선스 도구로, 코드베이스를 지속적으로 보존되는 로컬 지식 그래프로 인덱싱합니다. 그래서 Claude Code 같은 어시스턴트가 매 프롬프트마다 원본 파일을 다시 읽는 대신 참조를 따라 탐색할 수 있습니다 . 파싱은 번들된 tree-sitter 문법으로 기기 안에서 실행됩니다. Python, TypeScript/JavaScript, Go, Rust, Java, C/C++, C#, Kotlin, Scala, Ruby, PHP, Swift, Lua, Zig, SQL, Shell 등을 포함해 약 36개 언어를 대상으로 하는 결정론적 규칙 기반 AST 처리입니다 . 핵심 워크플로에는 네트워크 호출도, 임베딩도, 벡터 저장소도 없습니다. 코드는 절대 기기를 떠나지 않습니다 .
빠른 답변: Graphify는 tree-sitter로 약 36개 언어를 로컬에서 파싱합니다. 모델 호출은 0회이고 벡터 저장소도 쓰지 않으며, 함수, 파일, 테이블의 타입이 지정된 그래프를 만듭니다. 현재 릴리스 v0.9.22(2026년 7월 20일)는 Claude Code가 파일을 다시 읽는 대신 관계를 따라 이동하게 해 큰 저장소에서 방향을 잡는 비용을 줄입니다.
그래프는 함수, 클래스, 파일, 데이터베이스 테이블, 문서를 노드로 모델링하고, 이를 calls, imports, defines, references 같은 타입이 지정된 방향성 엣지로 연결합니다. 이 구조는 텍스트 일치가 아니라 관계를 포착합니다. 그래서 “이 함수를 바꾸면 무엇이 깨질까?” 또는 “체크아웃에서 결제 테이블까지 추적해줘” 같은 다중 홉 질문을 다룰 수 있습니다. 일반 grep은 여러 파일에 흩어진 원시 검색 결과를 돌려주지만, 그래프는 관계의 사슬을 돌려줍니다 .
각 /graphify . 실행은 세 가지 로컬 산출물을 씁니다. GRAPH_REPORT.md(중심 노드, 서브시스템, 의외의 연결, 추천 질문), 대화형 force-directed graph.html, 그리고 GraphRAG에 바로 쓸 수 있는 graph.json입니다 . 유지관리자인 Graphify Labs는 의도적으로 y를 두 번 쓴 graphifyy라는 이름으로 PyPI에 배포하며, CLI 이름은 그대로 graphify입니다 .
uv 또는 pipx로 시작하기
PyPI에서는 y를 두 번 쓴 graphifyy라는 이름으로 설치합니다. README는 설치된 CLI 바이너리 이름이 graphify로 유지되더라도, 다른 모든 graphify* 패키지는 관련이 없다고 명시적으로 경고합니다 . 권장 경로는 uv tool install graphifyy(또는 pipx install graphifyy)를 실행한 뒤, graphify install로 Claude Code와 감지된 다른 어시스턴트 통합 안에 /graphify 스킬을 등록하는 것입니다 [1][4]. Python ≥3.10이 필요하며, 현재 릴리스는 2026년 7월 20일에 게시된 v0.9.22입니다 [2][4].
36개 언어 AST 처리에는 API 키가 필요 없습니다. 파싱은 번들된 tree-sitter 문법으로 로컬에서 실행되며 절대 기기를 떠나지 않습니다 . PDF, 동영상, 이미지 같은 비 AST 입력만 선택적으로 설정된 백엔드를 호출해 INFERRED 엣지를 추가합니다. 키를 건너뛰면 해당 엣지가 없을 뿐입니다 . 아래 검증된 스니펫은 로컬 파싱 계약을 보여줍니다. 모델 호출 없이 실행되었습니다.
"""Minimal local parsing demo: Graphify-style indexing needs no model call."""
import re
LANGUAGES = """
bash c c_sharp cpp css dart elixir go graphql haskell html java javascript
json julia kotlin lua markdown php python ruby rust scala sql swift toml tsx
typescript yaml zig clojure erlang ocaml perl solidity vue
""".split()
def parse_locally(language: str, source: str) -> dict:
"""Tiny stand-in for Graphify's local parser pass: tokenize, don't call APIs."""
tokens = re.findall(r"[A-Za-z_][\w#-]*|[{}()[\].,;:=<>/+*-]", source)
return {"language": language, "tokens": len(tokens), "symbols": tokens[:4]}
sample = "function f(x) { return x + 1; }"
graphs = [parse_locally(lang, sample) for lang in LANGUAGES]
assert len(graphs) == 36
assert not any(k in globals() for k in ("openai", "anthropic", "requests"))
print(f"{len(graphs)} languages parsed locally")
print("model calls: 0")
print("first:", graphs[0])점에서 인사이트까지: /graphify . 와 다섯 가지 탐색 명령
스킬을 등록하면 전체 워크플로는 Claude Code 안에서 단 하나의 명령으로 시작됩니다. /graphify . Tree-sitter가 로컬에서 저장소를 스캔하고 파싱한 뒤, 세 가지 산출물을 graphify-out/ 디렉터리에 씁니다. 쉬운 말로 정리된 GRAPH_REPORT.md, 인터랙티브 force-directed graph.html, 그리고 GraphRAG에 바로 쓸 수 있는 graph.json입니다 . 이 JSON이 CLI와 MCP 서버가 함께 질의하는 기반입니다.
대부분의 탐색은 다섯 가지 동사로 처리됩니다. graphify query "AuthService"는 기본적으로 깊이 3의 너비 우선 탐색을 실행하며, 출력은 2,000토큰 예산으로 제한되어 결과가 컨텍스트 창에 넣기 좋게 유지됩니다 . 선택 플래그로 탐색 방식을 바꿀 수 있습니다. --dfs는 깊이 우선으로 전환하고, --depth는 1-6을 받으며, --edge-filter는 calls나 imports 같은 특정 타입의 엣지로 범위를 좁힙니다 .
다른 동사들은 더 구체적인 질문에 답합니다. graphify path "AuthService" "payments_table"는 이름이 지정된 두 엔티티 사이의 최단 방향 경로를 보여줍니다. grep으로는 답하기 어려운 "체크아웃이 데이터베이스까지 어떻게 도달하지?" 같은 다중 홉 질문에 유용합니다 . graphify explain <node>는 그래프 이웃에서 끌어온 심볼 설명을 쉬운 말로 반환하고, graphify god-nodes는 가장 높은 in-degree 허브, 즉 모든 흐름이 지나가는 핵심 개념들을 나열합니다 .
이전 빌드를 대상으로 스크립트를 작성하는 사람이라면 알아둘 점이 있습니다. god-nodes는 2026년 7월 20일에 릴리스된 v0.9.22에서야 실제 CLI 서브커맨드가 되었고, 그 전에는 없었습니다 . 여기에 의존한다면 버전을 고정하세요.
낡아지는 지도, 출처 라벨, 그리고 git으로 막는 방법
그래프는 실시간 뷰가 아니라 스냅샷입니다. 파일이 바뀌는 순간 낡기 시작합니다. /graphify .를 다시 실행하기 전까지 어시스턴트는 마지막 빌드를 기준으로 탐색하므로, 방금 수정한 심볼에 대해 자신 있게 틀릴 수 있습니다. 해결책은 graphify hook install입니다. 이 명령은 커밋할 때마다 그래프를 자동으로 다시 빌드하는 git post-commit 훅을 추가합니다 . 드리프트가 생기는 구간을 커밋 주기까지 줄여주지만, 재동기화의 책임은 여전히 사용자에게 있습니다. 커밋되지 않은 작업 중 변경사항은 지도에 보이지 않습니다.
어떤 엣지를 근거로 행동하기 전에는 출처 태그를 확인하세요. 모든 관계에는 EXTRACTED(AST로 파싱된 결정적 관계), INFERRED(모델이 해석한 관계, 예: 동적 디스패치나 문서 참조), AMBIGUOUS(오버로드된 메서드처럼 일부만 해소된 관계) 중 하나가 붙습니다 . 이를 통해 확실히 파싱된 사실과 판단이 들어간 부분을 나눌 수 있습니다. EXTRACTED 엣지는 근거 사실로 보고, 나머지는 검증하세요.
절감 효과는 기대치를 맞춰야 합니다. 실제 저장소 세 곳을 대상으로 한 독립적인 실사용 테스트에서는 대략 5-10배의 토큰 감소가 확인됐습니다. 널리 인용되는 71.5배라는 수치는 특정 워크로드에서 나온 실제 데이터 포인트이지, 계획의 기준으로 삼을 만한 중앙값은 아닙니다 . 그 글의 표현처럼, "the 71.5x number is an honest caveat rather than a typical result"입니다. 이득은 저장소 크기와 방향 잡기 중심 작업에서 커지고, 편집 중심 작업에서는 덜합니다.
버전 메모: v0.9.22(2026년 7월 20일)는 여러 인덱싱 버그를 고쳤습니다. env, .env, *_env 디렉터리는 이제 마커 파일이 없는 한 virtualenv로 오인되어 조용히 제외되지 않습니다. gdoc://, s3://, http:// 가상 소스 노드는 두 번째 업데이트 후에도 유지됩니다. 그리고 파일 basename이 충돌할 때는 이제 고유한 경로 접미사 라벨이 붙습니다 .
지도 다음에 볼 것: Leiden 서브시스템과 PR 선별
그래프가 만들어지면 Graphify는 graph.json 위에서 MCP 서버를 실행해 10가지 도구를 노출할 수 있습니다. query_graph, get_node, get_neighbors, shortest_path, get_community, god_nodes, graph_stats, list_prs, get_pr_impact, triage_prs입니다. 단독 어시스턴트에는 stdio로, 팀 공유 접근에는 Streamable HTTP로 사용할 수 있습니다 (source: Graphify, 2026-07). Leiden 커뮤니티 탐지는 저장소를 라벨이 붙은 서브시스템으로 묶어 GRAPH_REPORT.md에 보여주므로, 에이전트는 전체 그래프 대신 get_community를 호출해 특정 서브시스템으로 추론 범위를 좁힐 수 있습니다 (source: GitHub, 2026-07).
PR 수준의 영향 분석에는 code-review-graph(pip install code-review-graph, MIT, Tirth Kanani 제작, 2026년 3월 공개)를 함께 쓰면 좋습니다. SQLite WAL 영속성, 임베딩 인식 의미 검색, 영향 범위 분석을 추가해줍니다. 엔터프라이즈 얼리 액세스에는 머지 게이트 검증, graphify digest 보고서, Jira/Atlassian 커넥터가 포함되지만, 핵심 제품은 계속 $0, MIT 라이선스, 계정 불필요, 노드나 저장소 제한 없음 상태입니다 (source: mejba.me, 2026-07). 요점은 이렇습니다. 그래프를 한 번 만들고, 서브시스템과 god node를 질의해 방향을 잡고, 리뷰에 진짜 영향 점수가 필요할 때 CRG를 꺼내면 됩니다.
자주 묻는 질문
Graphify가 내 소스 코드를 외부 API로 보내는 경우가 있나요?
번들된 tree-sitter 문법으로 AST 파싱되는 약 36개 언어, 즉 Python, TypeScript/JavaScript, Go, Rust, Java, C/C++, C#, Kotlin, Scala, Ruby, PHP, Swift, Lua, Zig, SQL, Shell 등은 그렇지 않습니다. 파싱은 완전히 로컬에서 결정적으로 이루어지므로 모델 호출이 발생하지 않으며, 코드는 사용자의 머신을 벗어나지 않습니다 . AST가 아닌 입력(동영상, 오디오, PDF, 이미지, Terraform, 문서 교차 참조)은 선택적 의미 분석 단계를 거칠 수 있고, 이때 사용자가 설정한 백엔드를 호출해 INFERRED로 표시된 엣지를 만들 수 있습니다. API 키를 넣지 않으면 해당 엣지는 단순히 생략됩니다. 동영상과 오디오는 어느 경우든 faster-whisper로 로컬에서 전사됩니다 .
PyPI 패키지 이름이 왜 graphify가 아니라 graphifyy인가요?
graphify라는 이름이 PyPI에서 이미 사용 중이었기 때문에, 게시자는 의도적으로 y를 하나 더 붙인 graphifyy라는 변형 이름으로 배포했습니다. 설치되는 CLI 실행 파일은 여전히 graphify이므로 명령어는 바뀌지 않습니다. README는 PyPI의 다른 모든 graphify* 패키지가 관련 없는 패키지라고 명시적으로 경고합니다. 그래서 uv tool install graphifyy 또는 pipx install graphifyy를 실행할 때 이 점이 중요합니다 .
맵은 얼마나 자주 다시 만들어야 하나요?
의미 있는 커밋을 할 때마다 다시 만드는 것이 좋습니다. graphify hook install을 실행하면 그래프를 자동으로 다시 만드는 git post-commit 훅이 추가되며, 이것이 드리프트를 막기 위해 의도된 방식입니다 . 훅이 없으면 그래프는 마지막으로 실행한 /graphify . 결과만 반영하므로, 최근 변경된 심볼에 대해 어시스턴트에게 오래된 그림을 넘길 수 있습니다. 추출하는 순간 소스 오브 트루스가 둘이 되고, 오래된 맵은 에이전트가 자신 있게 틀린 답을 내게 만들 수 있습니다.
Graphify는 벡터 또는 임베딩 인덱스와 어떻게 다른가요?
두 방식은 답하는 질문이 다릅니다. 벡터 또는 임베딩 인덱스는 텍스트 청크 사이의 의미적 유사도로 매칭합니다. Graphify는 핵심 워크플로에 임베딩이나 벡터 저장소를 두지 않고, 대신 호출, import, 정의, 참조 같은 타입이 있는 방향성 엣지를 따라 탐색합니다 . 탐색은 “이 함수를 무엇이 호출하는가?” 또는 “이 파일은 무엇을 import하는가?”처럼 유사도 검색으로는 해결할 수 없는 구조적 질문을 풀어 줍니다. 두 접근은 서로 대체재가 아니라 보완재입니다. 그래프 구조와 함께 임베딩 기반 의미 검색이 필요하다면 Graphify를 code-review-graph 같은 도구와 함께 사용하세요 .
엣지의 EXTRACTED, INFERRED, AMBIGUOUS는 무엇을 뜻하나요?
이들은 엣지를 어느 정도 신뢰해도 되는지 알려 주는 출처 라벨입니다. EXTRACTED는 관계가 AST에서 결정적으로 파싱되었고 소스에 명시되어 있다는 뜻입니다. 즉 확실합니다. INFERRED는 동적 디스패치 호출 지점이나 문서 교차 참조처럼 모델 판단으로 해석되었다는 뜻입니다. AMBIGUOUS는 여러 후보 타깃을 가진 오버로드된 메서드처럼 일부가 아직 해소되지 않았다는 뜻입니다 . 엣지를 보고 바로 행동해도 되는지, 아니면 정확한 파일을 열어 먼저 확인해야 하는지 판단할 때 이 라벨을 사용하세요.
이 글이 도움이 되셨다면, 새 글이 올라올 때마다 이메일로 받아보세요.
