큰 Python 프로젝트에서 정말 어려운 일은 파일을 찾는 것이 아닙니다. 어떤 모듈이 중심인지, 클래스와 함수가 어디서 연결되는지, 한 변경이 어디까지 영향을 미치는지 파악하는 일입니다.
Graphify와 NetworkX를 함께 쓰면 이 문제를 “코드 검색”이 아니라 “그래프 분석”으로 다룰 수 있습니다. Graphify가 코드베이스를 지식 그래프로 만들고, NetworkX가 그 그래프에서 중심성·커뮤니티·경로 같은 구조적 신호를 뽑아내는 방식입니다.
Graphify: 코드베이스를 지식 그래프로 바꾸는 출발점
Graphify는 코드, 문서, PDF, 이미지, 영상 등 폴더 안의 자료를 질의 가능한 지식 그래프로 매핑하는 도구입니다.1 애플리케이션 코드뿐 아니라 데이터베이스 스키마와 인프라 정보도 하나의 그래프에 함께 담을 수 있습니다.1
Python 애플리케이션을 분석할 때 중요한 점은 그래프 추출이 로컬에서 이뤄진다는 것입니다. Graphify는 tree-sitter 기반 정적 분석을 사용해 클래스, 함수, import, 호출 관계 등을 추출합니다.2 이 튜토리얼의 핵심 흐름도 API 키나 LLM 백엔드 없이, 로컬에서 생성된 그래프를 분석하는 데 있습니다.
Graphify 실행 결과는 기본적으로 세 가지 파일로 정리됩니다.1
graph.html: 브라우저에서 열어 노드를 클릭하고, 검색하고, 필터링할 수 있는 시각화 파일GRAPH_REPORT.md: 주요 개념, 예상 밖의 연결, 추천 질문을 요약한 보고서graph.json: 전체 그래프를 담고 있어 나중에 다시 읽거나 분석할 수 있는 데이터 파일
여기서 graph.html과 GRAPH_REPORT.md는 빠르게 구조를 훑는 데 유용합니다. 하지만 더 깊은 분석은 graph.json에서 시작됩니다.
NetworkX: 시각화를 분석 가능한 데이터로 바꾸기
NetworkX는 복잡한 네트워크를 만들고, 조작하고, 분석하는 Python 패키지입니다.3 Graphify가 만든 graph.json은 NetworkX로 불러와 파일 유형, 관계 유형, 중심성 점수, 커뮤니티, 최단 경로를 분석하는 데 사용할 수 있습니다.
이때 그래프는 단순한 그림이 아니라 코드베이스의 구조를 묻는 도구가 됩니다. 특히 다음 질문에 답하기 좋습니다.
1. 무엇이 시스템의 중심인가?
중심성 점수는 연결이 많은 노드, 즉 구조적으로 중요한 파일·모듈·클래스·함수를 찾는 데 도움이 됩니다.
예를 들어 인증 모듈, DB 세션 객체, 설정 객체처럼 많은 코드가 의존하는 노드가 높게 나타날 수 있습니다. 이런 노드는 시스템의 핵심 축일 가능성이 높고, 변경 시 영향 범위를 더 신중하게 검토해야 합니다.
2. 실제 아키텍처 경계는 어디인가?
커뮤니티 감지는 서로 강하게 연결된 노드 묶음을 보여줍니다. Graphify는 연결 밀도를 기준으로 노드를 묶는 Leiden 커뮤니티 탐지를 사용합니다.2
이 결과는 패키지 구조와 실제 의존 구조를 비교하는 데 유용합니다. 디렉터리상으로는 분리된 모듈인데 그래프에서는 강하게 묶여 있다면, 숨은 결합이 있다는 신호일 수 있습니다. 반대로 한 패키지 안에 있지만 서로 거의 연결되지 않는다면 분리 가능성을 검토할 수 있습니다.
3. 왜 이 코드가 저 코드에 영향을 주는가?
최단 경로 분석은 두 노드 사이의 연결 과정을 보여줍니다. 예를 들어 특정 API 핸들러와 데이터베이스 객체 사이의 경로를 보면, 어떤 함수와 클래스를 거쳐 의존이 이어지는지 확인할 수 있습니다.
이 관점은 코드 리뷰, 장애 분석, 리팩터링 계획에 특히 실용적입니다. “느낌상 연결되어 있다”가 아니라 “이 경로로 연결되어 있다”고 설명할 수 있기 때문입니다.
언제 유용한가
이 접근은 작은 프로젝트에는 과할 수 있습니다. 파일 몇 개짜리 코드라면 직접 읽는 편이 더 빠릅니다.
하지만 모듈이 많고 클래스, 함수, 데이터베이스 객체가 얽힌 Python 애플리케이션이라면 가치가 커집니다. 먼저 graph.html로 전체 구조를 살피고, GRAPH_REPORT.md로 주요 개념과 예상 밖 연결을 확인합니다. 그다음 graph.json을 NetworkX에 불러와 중심성, 커뮤니티, 최단 경로를 분석하면 됩니다.
핵심은 코드를 예쁘게 시각화하는 것이 아닙니다. Graphify와 NetworkX를 함께 쓰면 코드베이스를 변경 영향, 구조적 결합도, 아키텍처 경계라는 질문으로 읽을 수 있습니다. 복잡한 Python 프로젝트를 이해해야 한다면, 그래프는 코드의 또 다른 지도 역할을 합니다.
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.