로컬 환경에서 코드베이스를 지식 그래프로 변환하는 Graphify

개요

코드가 커지면 파일 이름 검색만으로 호출 관계와 설정 흐름을 잡기 어렵습니다. Graphify는 소스·문서·SQL 스키마를 그래프로 묶어 graph.json과 브라우저용 graph.html을 만드는 CLI입니다. 이 글은 Python 프로젝트에서 함수 관계를 찾는 경로만 다룹니다.

Graphify는 코드 분석에 LLM을 필수로 쓰지 않습니다. README 기준 코드 파일은 tree-sitter AST로 로컬에서 파싱하고, 문서·PDF·이미지 같은 비코드 자료만 설정한 백엔드를 사용합니다. 소스 외부 전송이 부담스러운 저장소라면 이 구분부터 확인해야 합니다.

1. 맞는 작업

새 저장소를 인수받았거나, API 핸들러가 어느 모델과 설정을 참조하는지 추적할 때 맞습니다. imports, calls, inherits 같은 연결을 그래프로 남기므로 함수 이름만 찾고 파일을 왕복하는 시간을 줄입니다.

반대로 작은 스크립트 하나나 파일 구조가 단순한 서비스에는 rg와 IDE 참조 찾기가 더 낫습니다. 그래프 생성물도 관리 대상이 됩니다. 저는 변경 빈도가 높고 사람이 여러 명인 저장소에서 먼저 검토하겠습니다.

Graphify는 벡터 DB가 아닙니다. 임베딩·벡터 저장소 없이 그래프를 탐색하며, 각 연결에는 소스에서 읽은 EXTRACTED 또는 해석된 INFERRED 표시가 붙습니다. 추론 결과를 원문 사실처럼 받아들이지 않는 이유입니다.

2. 사전 준비 사항

공식 패키지 이름은 graphifyy이고 실행 명령은 graphify입니다. npm의 graphify는 다른 Random Graph Generator 패키지입니다. 패키지명을 혼동하면 전혀 다른 도구를 설치합니다. Python 3.10 이상과 uv 또는 pipx가 필요합니다.

uv를 쓰면 격리된 도구 환경으로 설치됩니다.

uv tool install graphifyy
graphify install --project --platform codex

pipx도 같은 용도입니다.

pipx install graphifyy
graphify install --project --platform cursor

프로젝트 범위 설치는 .agents/skills/ 또는 플랫폼별 설정 파일을 만듭니다. 팀 저장소에 넣기 전에는 생성 파일을 git diff로 확인해주시면 됩니다.

3. 그래프 생성과 질문

먼저 대상 저장소 루트에서 코드를 추출합니다. 코드만 볼 때는 --code-only가 문서·이미지 처리를 건너뜁니다.

graphify extract . --code-only
graphify query "show the auth flow"

명령이 끝나면 graphify-out/graph.json과 시각화 파일이 생성됩니다. 특정 관계는 path나 explain으로 좁힙니다.

graphify explain "APIRouter"
graphify path "APIRouter" "ModelField"

graphify query 결과는 그래프 범위에 맞춰 확인해야 합니다. 문서까지 포함하려면 모델 백엔드가 필요할 수 있으니, 코드 전용 작업과 문서 의미 추출을 같은 보안 수준으로 보면 안 됩니다.

4. 자동화 연결

Codex, Claude Code, Cursor 같은 도구에 설치하면 원본 파일을 넓게 읽기 전 그래프 질의를 우선하도록 유도할 수 있습니다. 기존 자동화 환경을 유지하려면 n8n 셀프 호스팅 설치 글처럼 설정 파일과 실행 경로를 분리해 두는 방식도 유용합니다.

선택 의존성도 확인할 부분입니다. 기본 패키지는 여러 tree-sitter 언어를 포함하지만, DreamMaker와 Pascal 추출기는 선택 항목입니다. README의 graphifyy[dm], graphifyy[pascal] 설치 범위를 확인하시면 됩니다. Linux에서 dm 추출기는 C 컴파일러와 python3-dev가 필요할 수 있습니다.

5. 확인

설치 경로와 버전은 아래 명령으로 확인합니다.

graphify --version
graphify query "what connects auth to database?"

버전이 출력되고 질문에 연결된 노드가 나오면 CLI와 그래프 조회가 정상입니다.