파일 검색 대신 코드베이스를 그래프로 질의하는 방법

Graphify는 프로젝트의 코드와 문서를 파싱해 브라우저 뷰(graph.html), 요약 보고서(GRAPH_REPORT.md), 질의용 그래프(graph.json)를 만들고, 심볼의 위치와 연결 관계, 두 이름 사이의 최단 경로, 질문 범위에 맞춘 부분 그래프를 돌려줍니다.

코딩 에이전트가 심볼의 사용처를 찾으려고 소스 파일을 하나씩 차례로 열어보는데도 import 목록만으로는 두 이름이 어떻게 이어지는지 드러나지 않을 때, 매번 파일 검색을 처음부터 다시 돌리지 않고 이어서 답을 얻고 싶을 때 이 도구를 실행합니다.

모든 간선에는 EXTRACTED 또는 INFERRED 태그가 붙어, 소스에 직접 적힌 내용과 graphify가 추론해 연결한 내용을 구분할 수 있습니다.

없을 때와 있을 때

이 스킬이 없으면 에이전트는 구조 관련 질문을 파일 검색으로 처리합니다. 문서에 예시로 나온 FastAPI 프로젝트에서 FastAPI가 ModelField와 어떻게 연결되는지 물으면, 소스 파일에서 두 이름을 찾아 일치하는 부분을 읽는 식입니다. 돌아오는 답은 파일 위치 목록뿐이며, 그 연결이 소스에 직접 적혀 있었는지 추론해 넣었는지는 알려주지 않습니다. 그래프로 저장된 것이 없으므로 다음 질문을 하면 검색을 처음부터 다시 시작합니다.

이 스킬이 있으면 같은 질문이 이미 만들어진 그래프를 대상으로 하는 경로 질의로 바뀝니다. 문서에 나온 FastAPI 실행 결과는 세 개의 간선으로 이루어진 최단 경로입니다. FastAPI는 DefaultPlaceholder를 사용하고, get_request_handler()는 DefaultPlaceholder를 참조하며, get_request_handler()는 ModelField를 참조합니다. 각 간선에는 EXTRACTED 또는 INFERRED 태그가 붙고, 경로 끝에는 가장 약한 간선의 신뢰도가 함께 표시됩니다. 이어서 APIRouter를 물으면 저장된 노드를 읽어 routing.py의 2210번째 줄, 커뮤니티 2, 연결 47개, 그리고 각 연결의 관계까지 바로 보여줍니다.

입력에 따른 처리 분기

Graphify는 모든 파일을 똑같은 순서로 처리하지 않습니다. 입력 종류에 따라 경로를 나누며, 코드 분기는 모델을 호출하기 전에 작업을 끝냅니다.

소스 코드는 로컬 머신에서 tree-sitter 추상 구문 트리로 파싱합니다. 이 파싱은 결정론적으로 동작합니다. 언어 모델을 호출하지 않고, 이 단계에서 나온 어떤 데이터도 머신 밖으로 나가지 않습니다. 여러 파일에 걸친 연결도 해석해 내며, 약 40개 언어에서 calls, imports, inherits, mixes_in 관계를 기록합니다. 소스에 관계가 명시되어 있으면 간선에 EXTRACTED 태그를 붙이고, 직접 적힌 구문을 읽은 것이 아니라 graphify가 연결을 해석해 낸 경우에는 INFERRED 태그를 붙입니다. 이 간선들을 기록하고 나면 코드 처리 단계는 멈춥니다. 파일을 임베딩하지도 않고 벡터 인덱스를 만들지도 않습니다.

문서, PDF, 이미지, 영상이나 오디오는 다른 경로를 탑니다. 시맨틱 패스를 통해 이런 입력도 같은 그래프에 추가할 수 있습니다. 이 단계는 어시스턴트의 모델이나 설정된 API 키를 사용하며, 백엔드가 설정되어 있을 때만 백엔드를 호출합니다. 설정된 백엔드가 없으면 이 단계는 실행되지 않습니다. NOTE:나 WHY:로 시작하는 주석과 ADR 또는 RFC 인용은 해당 주석이 담긴 코드와 이어지는 노드가 됩니다.

남은 그래프에서는 Leiden 알고리즘으로 커뮤니티를 탐지하고, 언어 모델 없이 각 커뮤니티에 라벨을 붙입니다. 연결이 가장 많은 개념인 갓 노드(god node)도 표시합니다. 그런 다음 파일 세 개를 저장하고 마칩니다. graph.html은 브라우저용 뷰로, 노드는 개념을, 색상은 커뮤니티를 나타내며 클릭과 필터링, 검색을 지원합니다. GRAPH_REPORT.md에는 주요 개념, 의외의 연결, 추천 질문 목록이 담깁니다. graph.json은 전체 그래프와 함께 graph.schema_version 및 graph.graphify_version을 담아, 이후 도구가 포맷 변경을 감지하고 파일을 생성한 릴리스 버전을 식별할 수 있게 합니다.

이후 질문을 하면 저장소를 다시 훑지 않고 graph.json만 읽습니다. graphify query는 일상어로 작성한 질문 범위에 맞춰 크기를 줄인 그래프를 반환합니다.

사용법

쓸 때

구조 질문을 시작하기 전에 현재 프로젝트의 그래프와 보고서, 브라우저 뷰를 한 번에 생성해 두고 싶을 때입니다.

/graphify .

graphify-out 디렉터리 아래에 graph.html, GRAPH_REPORT.md, graph.json 파일이 생성됩니다.

쓸 때

이미 graph.json이 만들어진 상태에서, 특정 심볼이 어느 파일 몇 번째 줄에 있고 어떤 노드들과 연결돼 있는지 한 번에 짚어보고 싶을 때입니다.

graphify explain "APIRouter"

해당 개념의 소스 파일과 줄 번호, 커뮤니티 번호, 연결 개수, 그리고 각 연결의 관계와 EXTRACTED 또는 INFERRED 태그가 돌아옵니다.

쓸 때

소스 트리를 다시 뒤지거나 import 목록을 일일이 따라가지 않고 두 이름 사이의 최단 연결 경로를 확인하고 싶을 때입니다.

graphify path "FastAPI" "ModelField"

두 이름 사이에 이어진 간선 목록과 그 경로에서 가장 약한 간선의 신뢰도가 함께 돌아옵니다.

설치

Python 3.10 이상이 필요합니다.

uv tool install graphifyy
graphify install

첫 번째 명령 대신 pipx install graphifyy를 쓸 수 있고, macOS에서는 brew install python@3.12 uv로 사전 요구 사항을 설치합니다. 어시스턴트에서 가장 먼저 입력할 명령은 /graphify .입니다.

이 도구가 맞지 않을 때

문서, PDF, 이미지, 영상을 매핑해야 하는데 모델을 전혀 호출할 수 없는 환경이라면 Graphify는 맞지 않습니다. 코드 처리 단계는 로컬 머신에 머물며 언어 모델을 쓰지 않지만, 문서·PDF·이미지·영상·오디오는 시맨틱 패스를 위해 어시스턴트 모델이나 설정된 API 키를 사용합니다.

저장소	graphify를 고를 상황	해당 저장소를 고를 상황	스타
morluto/rea	바이너리 동작이 아니라 코드 연결 구조를 알고 싶을 때	네이티브 바이너리 수준까지 앱 동작을 리버스 엔지니어링해야 할 때	457,628
mattpocock/skills	스킬 디렉터리가 아니라 질의 가능한 프로젝트 그래프가 필요할 때	에이전트 디렉터리에서 가져온 스킬을 쓰고 싶을 때	323,811
obra/superpowers	작업 방법론이 아니라 프로젝트 그래프가 필요할 때	에이전트 스킬 프레임워크와 개발 방법론을 원할 때	317,228

스타 수는 어떤 도구를 고를지 결정하는 기준이 아닙니다. 프로젝트의 두 부분이 어떻게 이어지는지 다음번에 확인해야 한다면 설치하고, 임베딩이나 바이너리 리버스 엔지니어링, 범용 스킬 묶음이 필요하다면 설치하지 마세요.

Graphify-Labs/graphify는 스타 147,281개, 포크 14,115개, 미해결 이슈 1,653개를 기록하고 있으며 2026-04-03에 생겨 2026-11-12에 마지막으로 푸시됐고, Apache-2.0 라이선스를 따릅니다.

많이 묻는 질문

어떤 어시스턴트에 스킬을 등록할 수 있나요?

graphify install은 사용 중인 어시스턴트를 감지해 스킬을 등록합니다. 문서에는 Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot이 나와 있으며, 한 번의 설치로 macOS, Linux, Windows 환경의 20개 이상 어시스턴트를 추가로 지원한다고 안내합니다.

로컬 그래프는 세션마다 자동으로 갱신되나요?

어시스턴트에서 /graphify .을 입력해 그래프를 만들면 이후 명령들은 저장된 graph.json을 읽습니다. 소프트웨어 개발 수명 주기 전반에 걸쳐 그래프를 최신 상태로 유지하는 기능은 로컬 명령이 아니라 Graphify Cloud가 제공합니다.

코드 처리 단계에서 소스 코드가 외부로 전송되나요?

코드는 로컬에서 tree-sitter로 파싱하고 언어 모델을 호출하지 않으므로, 이 단계의 어떤 내용도 머신 밖으로 나가지 않습니다. 문서, PDF, 이미지, 영상, 오디오만 시맨틱 패스를 위해 어시스턴트 모델이나 설정된 API 키를 사용합니다.

출처: GitHub 저장소 Graphify-Labs/graphify, https://github.com/Graphify-Labs/graphify