graphify, 코드베이스를 질문으로 탐색하는 지식 그래프로 바꿔요

낯선 코드베이스를 맡으면 파일명 검색만으로는 구조를 파악하기 어려워요. graphify는 코드와 문서를 연결된 지식 그래프로 만들고, 자연어 질문이나 경로 질의로 필요한 부분을 좁혀 주는 오픈소스 개발자 도구예요. 코드 분석은 로컬에서 처리하고, 어떤 연결이 원문에서 왔는지 추론으로 만들어졌는지도 구분해요. 1

핵심 요약

구분	핵심	왜 볼 만한가요
탐색 방식	코드의 호출·상속·임포트 관계를 그래프로 만들어요	파일을 차례로 읽기 전에 관련 서브그래프부터 볼 수 있어요
로컬 분석	코드는 tree-sitter AST로 머신 안에서 분석해요	API 키 없이 시작할 수 있고 소스 코드 외부 전송을 줄여요
근거 표시	연결마다 `EXTRACTED`와 `INFERRED` 태그를 붙여요	소스에 명시된 관계와 도구가 해석한 관계를 나눠 확인할 수 있어요
활용 범위	질문·최단 경로·개념 설명 질의와 MCP 서버를 제공해요	코드 리뷰와 구조 파악, 개발 도구 연동에 같은 그래프를 쓸 수 있어요

1. 파일 검색보다 관계를 먼저 보여줘요

graphify를 설치한 뒤 지원되는 AI 코딩 도구에서 `/graphify .`을 실행하면 `graph.html`, `GRAPH_REPORT.md`, `graph.json`을 만들어요. `graph.html`에서는 노드와 커뮤니티를 브라우저로 살펴볼 수 있어요. `graph.json`은 다시 원본 파일 전체를 읽지 않고 질의할 때 쓰는 데이터예요. Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot 등 여러 개발 환경을 지원해요. 2

일반 검색은 이름이 같은 파일이나 문자열을 찾는 데는 빨라요. 하지만 인증 코드가 데이터베이스 모델까지 어떤 호출을 거치는지, 특정 클래스가 어느 모듈과 연결되는지는 여러 파일을 오가며 확인해야 해요. graphify는 이런 관계를 `calls`, `imports`, `inherits` 같은 엣지로 묶어요. 자연어 질문에는 관련 범위만 담은 서브그래프를 돌려주고, `path` 명령은 두 대상 사이의 최단 경로를 홉 단위로 보여줘요. `explain` 명령에서는 소스 위치와 연결 목록, 소속 커뮤니티를 확인할 수 있어요.

728x90

코드 그래프는 LLM 없이 만들어요

코드는 tree-sitter AST로 파싱해요. 공식 설명에 따르면 약 40개 언어에서 파일을 가로지르는 호출·임포트·상속 관계를 분석해요. 이 과정은 결정론적으로 로컬에서 실행되며 LLM을 호출하지 않아요. 소스 코드가 외부 모델로 전송되지 않기 때문에 보안 정책이나 데이터 레지던시 조건이 까다로운 조직도 검토해 볼 수 있어요. 그래프를 다시 만들 때 모델 토큰 비용이 들지 않는 점도 반복 인덱싱에 유리해요. 2

여기에는 범위를 정확히 구분할 필요가 있어요. 코드 분석은 LLM 없이 로컬에서 끝나지만, 문서와 PDF, 이미지, 영상의 의미를 읽는 단계는 코딩 도구의 모델이나 별도로 설정한 API를 사용할 수 있어요. 저장소 설명도 코드와 미디어의 처리 경로를 나눠 적고 있어요. 완전 오프라인이 꼭 필요하다면 코드만 대상으로 쓰는지, 문서·미디어 분석 백엔드를 켰는지부터 확인해야 해요.

추출한 관계와 추론한 관계를 나눠요

그래프의 모든 연결에는 `EXTRACTED` 또는 `INFERRED`가 붙어요. `EXTRACTED`는 소스에 직접 적힌 관계예요. `INFERRED`는 이름과 구조를 바탕으로 graphify가 해석한 관계예요. 두 태그를 나누면 결과가 어디까지 코드에 명시돼 있고 어디부터 도구의 해석인지 추적하기 쉬워요.

`# NOTE:`와 `# WHY:` 주석, ADR·RFC 인용도 별도 노드로 다뤄요. 함수 호출만 연결하는 데서 그치지 않고, 구현 당시 남긴 설계 이유를 코드와 함께 찾을 수 있어요. 오래된 서비스에서 "왜 이 우회 로직을 남겼는가"를 찾거나 리팩터링 전에 변경 범위를 조사할 때 쓸 만한 부분이에요.

벡터 검색과 쓰임이 달라요

graphify는 임베딩이나 벡터 저장소를 쓰지 않아요. 의미가 비슷한 조각을 순위대로 찾는 대신, 실제 그래프를 따라 두 대상이 어떻게 연결되는지 보여줘요. 이름이 비슷하지 않아도 호출이나 참조 관계로 이어진 경로를 확인할 수 있어요. 반대로 자연어 의미가 닮은 문서를 폭넓게 찾는 일에는 벡터 검색이 더 잘 맞을 수 있어요. 검색 방식을 서로 대체재로 보기보다 질문의 종류에 맞춰 고르는 편이 좋아요.

생성한 `graphify-out/`을 저장소에 함께 두면 팀원이 같은 코드 지도를 사용할 수 있어요. 커밋 때 그래프를 다시 만드는 흐름도 구성할 수 있어요. `python -m graphify.serve`로 MCP 서버를 띄우고 HTTP 전송을 사용하면 여러 개발 도구가 같은 그래프에 접근할 수도 있어요. 다만 공유 서버를 운영할 때는 그래프 안에 소스 경로와 설계 정보가 들어갈 수 있으니 접근 권한을 별도로 설계해야 해요.

현재 공식 패키지 이름은 `graphifyy`이고, CLI 명령은 `graphify`예요. Python 3.10 이상이 필요해요. 라이선스는 저장소 기본 브랜치 기준 Apache 2.0이며, 이전 MIT 라이선스 고지도 함께 남아 있어요. 도입 전에는 지원 언어와 생성 파일 크기, 변경된 코드의 재인덱싱 시간, 추론 관계의 정확도를 실제 저장소에서 확인해 보는 편이 안전해요. 2

왜 중요한가요

AI 코딩 도구에 큰 저장소를 통째로 읽히면 컨텍스트가 빠르게 늘어요. 관련 없는 파일까지 반복해서 읽으면 응답 시간과 모델 사용량도 커져요. graphify가 먼저 관계 범위를 좁혀 주면 코딩 도구는 질문과 가까운 코드부터 확인할 수 있어요. 특히 처음 보는 레거시 코드, 서비스가 여러 개인 저장소, 문서와 구현이 흩어진 프로젝트에서 탐색 순서를 잡는 데 도움이 될 수 있어요. 1

그래프가 있다고 코드 이해가 자동으로 끝나는 것은 아니에요. 동적 호출과 런타임 설정, 외부 서비스의 실제 동작은 정적 구조만으로 놓칠 수 있어요. `INFERRED` 연결도 검토가 필요해요. 그래프를 정답으로 쓰기보다 조사 범위를 줄이는 지도처럼 쓰고, 중요한 변경 전에는 원본 코드와 테스트로 다시 확인하는 방식이 현실적이에요. 2

참고 자료

graphify - 코드베이스를 질의 가능한 지식 그래프로 바꾸는 도구 — GeekNews
Graphify-Labs/graphify — GitHub

728x90