코드 복잡성을 넘어서는 지도, 지식 그래프
광활한 대지에 나침반 없이 서 있다면 어떤 기분일까? 복잡한 코드베이스나 방대한 연구 자료 앞에서 우리는 자주 그런 막막함을 느낀다. 과연 이 모든 정보의 본질을 꿰뚫는 지도를 그릴 수 있을까.
복잡한 지식 속 숨겨진 지도 만들기
우리는 학교에서 새로운 지식을 배울 때, 그저 사실만을 나열하는 것보다 개념들 사이의 관계를 이해할 때 비로소 진짜 학습이 일어난다. 소프트웨어 개발의 세계도 마찬가지다. graphify라는 도구는 이러한 학습의 원리를 그대로 차용하여, 코드나 문서 더미 속에 숨겨진 지식의 관계를 지식 그래프로 시각화한다. 단순히 “무엇”이 있는지 알려주는 것을 넘어, “왜” 그렇게 설계되었는지 그 배경과 의도를 밝혀주는 셈이다. 마치 학급의 여러 학생을 처음 만났을 때, 각 학생의 정보 카드만 보는 것이 아니라, 그들 사이의 관계망과 각자의 숨겨진 이야기를 들으며 학급 전체의 역동성을 파악하는 과정과 같다. graphify는 이 복잡한 코드와 문서의 미로에서 “왜”라는 핵심 질문에 답을 찾아주는 나만의 길잡이가 된다.
다양한 정보 형태, 하나의 그래프로
우리의 지식은 한 가지 형태로만 존재하지 않는다. 교사는 교과서뿐 아니라 학생들의 활동지, 대화, 영상 자료, 심지어는 쉬는 시간의 관찰까지 모든 것을 학습에 활용한다. graphify 또한 이러한 다중 모달리티 학습의 중요성을 잘 안다. 파이썬, 자바스크립트 같은 다양한 프로그래밍 언어의 AST(추상 구문 트리)를 분석하여 코드의 구조와 함수 호출 관계를 추출한다. 놀라운 점은 여기에 그치지 않는다는 사실이다. PDF 논문, 마크다운 문서, 심지어 스크린샷, 다이어그램 이미지, 영상이나 음성 파일까지도 모두 분석하여 개념과 그 관계를 추출한다. 특히 코드와 영상/음성 파일은 사용자 기기에서 로컬로 처리하여 개인 정보 보호에 신경 쓴다. 즉, 언뜻 보기에 서로 다른 종류의 정보들이 graphify의 손을 거치면 하나의 거대한 지식 그래프 안에서 유기적으로 연결된다. 이는 마치 여러 교과목의 지식이 한 학생의 머릿속에서 통합적인 사고로 발현되는 모습과 닮았다.
그래프가 알려주는 통찰
graphify는 단순한 데이터 덩어리를 넘어서, 실질적인 통찰을 제공하는 결과물을 내놓는다. 가장 대표적인 것이 웹 브라우저에서 열어볼 수 있는 인터랙티브 HTML 그래프다. 노드를 클릭하며 관계를 탐색하고, 커뮤니티별로 필터링하여 특정 영역에 집중할 수 있다. 더 중요한 것은 GRAPH_REPORT.md 파일이다. 이 보고서에는 전체 지식 구조에서 가장 중심적인 역할을 하는 개념들, 즉 갓 노드(god nodes)가 명시된다. 또한, 예상치 못한 연결고리인 놀라운 연결(surprising connections)을 발견하고 그 배경 설명을 덧붙인다. 마치 학교에서 한 학생의 성장을 관찰하며, 그 학생의 학습에서 가장 핵심적인 개념(갓 노드)이 무엇이고, 이전에는 생각지 못했던 과목 간의 연결점(놀라운 연결)을 발견하는 것과 같다. 이런 보고서는 복잡한 시스템의 본질을 빠르게 이해하고, 다음에 어떤 질문을 던져야 할지 아이디어를 얻는 데 큰 도움을 준다. 더 나아가, graphify는 원본 파일을 직접 읽는 것에 비해 71.5배 적은 토큰으로 질의를 처리하는 효율성을 자랑한다. 처음 그래프를 구축할 때 토큰이 사용되지만, 이후 질의는 압축된 그래프를 활용하여 비용을 크게 절감한다.
“왜 그랬을까?”를 찾아내는 세 단계
graphify가 이처럼 깊이 있는 지도를 그리는 방식은 세 단계로 나뉜다. 첫째, 코드 파일은 AST 분석을 거쳐 클래스, 함수, 임포트, 호출 그래프 같은 구조적 정보를 추출한다. 이 과정은 LLM(대규모 언어 모델)의 개입 없이 순수하게 결정론적으로 이루어져 정확성이 높다. 둘째, 영상이나 음성 파일은 faster-whisper를 사용해 사용자 기기에서 직접 텍스트로 변환한다. 전사된 내용은 캐시되어 재실행 시 시간을 절약한다. 셋째, 문서, 이미지, 전사된 텍스트는 Claude 같은 LLM 에이전트들이 병렬적으로 분석하여 개념, 관계, 그리고 설계 의도까지 추출한다. 이 모든 결과는 NetworkX 그래프로 통합되고, Leiden 커뮤니티 탐지 알고리즘으로 군집화된다. 모든 관계에는 EXTRACTED(원본에서 직접 발견), INFERRED(합리적인 추론, 신뢰도 점수 포함), AMBIGUOUS(검토 필요) 태그가 붙어, 어떤 정보가 직접적 증거에 기반하며 어떤 정보가 추론인지 명확히 알 수 있다. 투명하게 지식의 근거를 제시하는 점이 인상 깊다.
AI 조교와 함께하는 지식 탐색
graphify는 단순히 그래프를 생성하는 도구가 아니다. Claude Code, GitHub Copilot CLI, VS Code Copilot Chat 등 다양한 AI 코딩 조교와 긴밀하게 연동된다. 우리는 AI 조교가 복잡한 질문에 답하기 위해 모든 원본 파일을 뒤지는 비효율적인 상황을 경험한다. graphify는 이 문제에 두 가지 방식으로 접근한다. 첫째, ‘항상 켜져 있는 지도’를 제공한다. 프로젝트에 graphify를 설치하면, AI 조교는 파일을 검색하기 전에 GRAPH_REPORT.md를 먼저 읽는다. 이는 마치 수업 중 질문이 나왔을 때, 교사가 모든 교과서를 펼쳐보기 전에 핵심 개념 요약본을 먼저 훑어보는 것과 같다. 조교는 구조를 통해 정보를 탐색하는 방법을 배운다. 둘째, ‘정확한 길 찾기’를 위한 명령어를 제공한다. /graphify query나 /graphify path 같은 명령어로 그래프를 직접 탐색하여 특정 개념 간의 연결이나 특정 노드에 대한 설명을 요청할 수 있다. 이는 지도의 큰 그림을 아는 것과, 지도 위에서 특정 지점을 정확히 찾아내는 것의 차이이다.
협력 학습을 위한 지식 자산
오늘날 학교 현장의 프로젝트 학습이나 연구 활동은 팀 단위로 진행되는 경우가 많다. graphify는 이러한 협력 환경에 최적화된 설계 방식을 지닌다. graphify-out/ 폴더의 결과물은 Git 저장소에 커밋하여 팀원들과 공유할 수 있다. 한 명이 초기 그래프를 만들면, 나머지 팀원은 별도의 복잡한 과정 없이 즉시 이 지식 지도를 활용한다. 코드가 변경될 때마다 그래프가 자동으로 재구성되도록 Git 훅을 설치하는 기능도 제공한다. 이는 마치 팀 프로젝트의 진행 상황을 매번 처음부터 이해하는 것이 아니라, 공유된 대시보드를 통해 변경사항과 핵심 요약을 바로 확인하며 협력하는 방식과 같다. 또한, .graphifyignore 파일을 활용하여 그래프에 포함하고 싶지 않은 파일이나 폴더를 쉽게 제외할 수 있다. 팀의 지식 자산을 효율적으로 관리하고 공유하는 데 필수적인 기능이다.
스포츠과학·운동학습의 시선으로 보면
운동 학습 분야에서는 ‘스키마 이론’이 복잡한 동작 습득을 설명한다. 선수는 반복 훈련을 통해 다양한 상황에서 동작을 일반화하는 스키마를 형성한다. graphify가 코드와 문서를 통합하여 지식 그래프를 생성하는 과정은, 선수들이 여러 훈련 경험을 연결하여 유연한 운동 스키마를 구축하는 것과 본질적으로 같다. 이는 단순한 정보의 나열이 아니라, 깊이 있는 연결성을 통해 예측하고 문제 해결에 적용하는 능력을 기른다. 겉으로 보이는 코드의 기능뿐만 아니라, 그 뒤에 숨겨진 설계 의도를 파악하는 것이 마치 운동 상황에서 단순히 기술을 반복하는 것을 넘어, 상황의 맥락을 읽고 창의적으로 움직이는 능력과 유사하다.
출처
- https://github.com/safishamsi/graphify