AI 코딩 어시스턴트에게 코드베이스를 이해시키는 방법이라고 하면, 임베딩(embedding) + 벡터 DB를 이용한 RAG가 정석처럼 되어 왔습니다. 그런 가운데, 2026년 4월에 등장한 Graphify는 '벡터 스토어는 사용하지 않는다'라며 정면으로 반기를 드는 OSS입니다. 공개 후 약 4개월 만에 약 103.6k 스타(2026년 8월 7일 기준)와 YC S26 선정이라는 이례적인 성장세를 보이고 있습니다. 필자 역시 리포지토리를 clone하여 README, ARCHITECTURE.md, 소스 코드 등의 일차 정보를 전반적으로 읽어보았습니다. 본 기사는 그 조사 결과를 정리한 것입니다.

• RAG(Retrieval-Augmented Generation)의 기본적인 작동 원리
• 그래프 구조(노드・엣지)의 기초
• 환경: Python 실행 환경과 uv가 도입되어 있어야 함 (설치 시 uv tool install 사용)

에이전트에게 코드베이스를 탐색하게 하면, 실제로는 grep과 Read의 반복이 되기 쉽습니다. 토큰을 대량으로 소비할 뿐만 아니라, '어떤 함수가 어디서 호출되고 있는지'와 같은 구조적인 질문에는 취약하다는 단점이 있습니다. 반면 벡터 RAG는 의미적 유사 검색에 능하지만, 임베딩 생성 비용이 들고, 청크 분할(chunking) 과정에서 구조 정보가 손실되며, '왜 이 청크가 반환되었는지' 설명 가능성도 부족하다는 과제가 있습니다.

Graphify는 이에 대해 '코드는 결정적으로 분석할 수 있으니, LLM이나 임베딩을 사용하지 않고 그래프를 만들면 된다'라는 접근 방식을 취합니다. README에는 '그래프 구조 자체가 유사도 시그널이다'라는 사상이 명확하게 밝혀져 있습니다(docs/how-it-works.md).

한마디로 말하면, 프로젝트 전체(코드・문서・PDF・이미지・영상)를 질의 가능한 지식 그래프(knowledge graph)로 변환하는 Python CLI + AI 어시스턴트용 스킬입니다. Claude Code나 Cursor에서 /graphify . 라고 입력하면 그래프가 구축되며, 이후로는 grep 대신 그래프...

「벡터 DB 없음」이라고 해서 「LLM 완전 미사용」은 아니라는 점은 짚고 넘어갈 필요가 있습니다. 문서류를 포함할 경우 LLM 백엔드(Claude / Gemini / OpenAI / DeepSeek / Kimi / Ollama / AWS Bedrock / Azure OpenAI의 8종 중 선택)가 작동합니다.

Pass 1의 주역인 AST (추상 구문 트리 (Abstract Syntax Tree)) 해석을 조금 더 깊이 파헤쳐 보겠습니다. AST란 소스 코드를 「함수 정의」, 「클래스」, 「호출식」과 같은 구문 요소의 트리 구조로 표현한 것이며, tree-sitter는 각 언어의 문법 정의 (Grammar)에 따라 이를 고속으로 구축하는 파서 라이브러리 (Parser Library)입니다. LLM에게 코드를 읽히는 경우와 달리, 동일한 입력으로부터 반드시 동일한 트리가 얻어지는 결정론적인 처리이므로, 할루시네이션 (Hallucination)의 여지가 없습니다. 재해석에 소요되는 것은 CPU 시간뿐이며, LLM의 API 비용은 전혀 발생하지 않습니다.

Graphify는 36개의 tree-sitter 문법을 가지고 있습니다. 커버하는 언어 수에 대해서는 README에는 「50개 이상」, docs/how-it-works.md에는 Pass 1에 대해 「25개 언어」라고 적혀 있어, 공식 자료 간에도 수치에 차이가 있다는 점은 주의해야 합니다. graphify/extractors/ 하위에는 언어별 extractor (rust.py, sql.py, terraform.py, Salesforce용 apex.py 등. 필자가 2026년 7월 26일 시점에 clone한 트리에서는 약 30개 파일)가 나열되어 있습니다 (graphify/extractors/). 각 extractor는 AST를 순회하며 노드 (Node)와 엣지 (Edge)로 변환합니다. 이미지는 다음과 같습니다.

# payment.py
from billing import charge_card
def process_order(order):
...

이 코드로부터는 대략 다음과 같은 그래프 요소가 추출됩니다.

노드: payment.py, process_order, billing, charge_card
엣지: payment.py --imports--> billing [EXTRACTED]
process_order --calls--> charge_card [EXTRACTED]

import 문이나 호출식은 AST 상에 명시되어 있으므로 EXTRACTED가 됩니다. 반면, 동적 디스패치 (Dynamic Dispatch) 대상의 해결과 같이 추론을 거치는 것은 INFERRED로서 점수와 함께 구분됩니다. SQL이라면 테이블, 뷰, 외래 키 (Foreign Key), JOIN이 동일한 방식으로 결정론적으로 추출됩니다 (docs/how-it-works.md).

필자가 가장 참고가 되었던 부분은 여기입니다. EXTRACTED 엣지의 confidence_score는 항상 1.0이며, INFERRED 엣지에는 0.95 (명시적인 크로스 파일 참조가 있고 후보가 1개인 경우) / 0.85 (명명과 문맥이 일치하는 경우) / 0.75 (문맥적이지만 암시적인 경우) / 0.65 (명명의 유사성만 있는 경우) / 0.55 (추측)라는 이산적 루브릭 (Rubric)으로 점수가 부여됩니다 (docs/how-it-works.md). 또한 graphify explain "개념"을 실행하면 해당 노드의 상세 정보와 연결원을 확인할 수 있습니다 (공식 문서, PyPI: graphifyy). LLM을 결합한 시스템에서 「사실과 추측을 분리하여 보여주는」 설계의 실례로서, RAG 이외의 문맥에서도 응용이 가능해 보입니다.

uv tool install graphifyy # 패키지 이름은 graphifyy (y가 두 개임)에 주의
graphify install # 20개 이상의 AI 어시스턴트에 스킬 등록

그 후, 어시스턴트 (Claude Code 등) 내부에서는 슬래시 명령어를 사용합니다. 이는 셸 (Shell)이 아니라 어시스턴트 내부에서 입력하는 것입니다.

/graphify . # 그래프 구축 (--update로 차분 업데이트)

구축 후의 질의는 셸에서도 CLI로 실행할 수 있습니다.

graphify query "인증은 어디서 처리하고 있어?"
graphify path UserService PaymentService # 2개 개념 간의 최단 경로
graphify explain "PaymentService" # 노드의 상세 정보와 연결원
...

구축된 그래프는 MCP 서버로서도 공개할 수 있습니다. stdio 외에도 Streamable HTTP 트랜스포트 (Transport)를 지원하며, --api-key를 통해 Bearer 인증을 추가하면 팀 공유 서버로도 사용할 수 있습니다 (README.md).

python -m graphify.serve graphify-out/graph.json --transport http

공개되는 도구는 query_graph / get_node / get_neighbors / shortest_path 외에도, PR 트리아지 (Triage) 계열(list_prs / get_pr_impact / triage_prs)까지 갖추고 있습니다.

Claude Code 연동에서는 PreToolUse 후크 (Hook)를 사용하여, 에이전트가 grep이나 원본 파일 읽기를 수행하기 전에 그래프로 유도하는 장치가 들어 있습니다. 기본값은 "grep 전에 그래프를 조회하라"고 완만하게 권장하는 소프트 너지 (soft nudge) 방식이며, --strict를 붙이면 세션당 단 1회에 한해 첫 번째 원본 소스 읽기를 차단하고 그래프로 리다이렉트(Redirect)하는 후크로 격상됩니다. graphify install --project --strict로 활성화할 수 있으며, 환경 변수 GRAPHIFY_HOOK_STRICT=1 / 0으로 실행 시 전환할 수 있습니다 (공식 문서). Claude Code의 후크 활용 사례로서도 구체적이고 흥미로운 설계라고 느꼈습니다.

필자는 평소 mattpocock/skills (TDD, 코드 리뷰, 버그 진단 등의 워크플로우 계열 스킬 모음)를 Claude Code / Cowork에 넣어 사용하고 있습니다. Graphify 역시 동일하게 스킬로서 상주하지만, 담당하는 레이어 (Layer)가 다르기 때문에 충돌하지 않고 오히려 보완 관계가 됩니다. mattpocock-skills가 "작업 방식 (Workflow)"을 규정하는 반면, Graphify는 "코드베이스의 구조적 메모리"를 제공하기 때문입니다.

조합 예시를 두 가지 들겠습니다.

• diagnosing-bugs × Graphify: 버그 진단에서는 호출 경로를 특정하는 것이 조사 단계의 핵심입니다. 이때 grep 대신 graphify path A B (shortest_path)나 get_neighbors를 사용하면, "이 핸들러에서 이 리포지토리 레이어까지 어떤 경로로 연결되어 있는가"를 적은 토큰 (Token)으로 가져올 수 있어 가설 구축이 빨라집니다.
• codebase-design × Graphify: 모듈 설계 검토에서는 "어디가 신 클래스 (God Class)화 되어 있는가"를 파악하는 것이 출발점입니다. Graphify의 analyze 단계에서 출력하는 god node 분석 (연결 과다 노드 검출)은 그 재료로 바로 사용할 수 있습니다.

참고로 이는 필자의 운용 아이디어이며, Graphify가 공식적으로 mattpocock-skills 연동을 내세우고 있는 것은 아닙니다. 두 가지 모두 "스킬 + MCP"라는 표준적인 메커니즘 위에 올라와 있기 때문에, 이러한 종류의 조합이 자유롭게 작동한다는 것이 본질입니다.

필자가 1차 정보를 읽으며 "도입 전에 알아두어야 할 점"이라고 느낀 점들을 나열합니다.

• 패키지 이름의 함정: PyPI 패키지는 graphifyy (y가 2개)이며, CLI 커맨드는 graphify입니다. PyPI 상의 다른 graphify* 패키지들은 무관하다고 README 자체에서 반복해서 주의를 주고 있습니다.
• 라이선스가 최근 변경됨: 현재는 Apache-2.0입니다. NOTICE에는 "본 제품은 Apache License 2.0으로 라이선스된다. 재라이선스 이전의 MIT로 기여된 부분은 계속해서 MIT로 이용 가능하다"라고 명시되어 있으며, 리포지토리에는 LICENSE (Apache-2.0)와 LICENSE-MIT가 모두 남아 있습니다. 따라서 GitHub 상의 표시도 "Apache-2.0 and MIT"가 됩니다 (NOTICE). 필자가 2026년 7월 26일 기준으로 확인한 범위 내에서, 전환은 v0.9.25 (2026-07-22)에서 이루어졌으며, 이유는 특허 허가 조항 (Patent Grant)의 명시였습니다. 사내 이용 시 라이선스 심사가 필요한 경우 최신 LICENSE / NOTICE를 확인하시기 바랍니다.
• 개인 주도 프로젝트: 필자가 2026년 7월 26일 기준으로 clone 하여 git shortlog

확인한 결과, 약 1,250개의 커밋 중 70% 이상을 메인 개발자 1명이 차지하고 있었습니다. 개발 속도는 매우 빠르지만(0.9.24 → 0.9.26이 4일 소요), 버스 계수 (Bus Coefficient) 관점에서는 평가에 고려해 둘 필요가 있습니다.

• v1.0 미만: 버전은 0.9.x이며 (2026년 8월 7일 기준 최신은 0.9.35), API 및 출력 형식이 변경될 가능성을 염두에 두어야 합니다.

Graphify는 "코드의 구조는 결정적으로 파악할 수 있으므로 LLM에게 읽힐 필요가 없다"라는 과감한 판단과, EXTRACTED / INFERRED / AMBIGUOUS 신뢰도 태그를 통한 설명 가능성 (Explainability) 설계가 돋보이는 OSS였습니다. 벡터 RAG (Vector RAG)를 전면적으로 대체하는 것이라기보다, 코드베이스 탐색에는 그래프를, 의미 검색 (Semantic Search)이 정말 필요한 부분에만 임베딩 (Embedding)을 사용하는 식의 역할 분담을 고민하게 만드는 계기가 될 것 같습니다. 우선 코드만 있는 프로젝트에서 테스트해 보면 API 키도 필요 없으므로, uv tool install graphifyy를 통해 가볍게 사용해 보세요.

같은 주제를 추적하고 계신 분들의 지견도 알고 싶습니다. 실제로 도입해 본 소감이나, 벡터 RAG와의 구분 사용 사례가 있다면 댓글로 알려주시면 감사하겠습니다. 도움이 되었다면 LGTM 또는 스크랩(Stock) 부탁드립니다. 큰 힘이 됩니다.