공통 함수를 고칠 때 어려운 일은 수정할 줄을 찾는 것보다 그 함수를 쓰는 곳을 빠뜨리지 않는 것이다. 파일 검색은 이름이 나온 위치를 보여 주지만, 그 사이의 호출·참조 관계는 다시 읽어야 한다. Graphify는 코드와 문서를 지식 그래프로 바꿔, 수정 전에 살펴볼 연결과 소스 위치를 찾는 도구다.
Graphify 설치 방법: 패키지 이름은 graphifyy
Python 3.10 이상과 uv가 필요하다. uv는 도구마다 분리된 Python 환경을 만들어 설치하는 프로그램이다. 이미 Claude Code 같은 코딩 도우미를 쓰고 있다면, 평소 명령을 입력하는 터미널에서 다음을 실행한다. 설치할 패키지는 끝에 y가 두 개인 graphifyy이고, 실행 명령은 graphify다.
uv tool install graphifyy
graphify install
graphify --help도움말에 extract, explain, affected 같은 명령이 나오면 실행 경로가 잡힌 것이다. 설치 뒤 명령을 찾지 못하면 uv tool update-shell을 실행하고 터미널을 다시 연다. uv 대신 pipx를 쓰는 환경에서는 pipx install graphifyy로 설치할 수 있다.
코딩 도우미에서 분석할 프로젝트를 연 뒤 /graphify .를 입력한다. 점은 현재 폴더다. 공식 README의 기본 경로는 Claude Code이며, Codex는 graphify install --platform codex로 등록하고 도우미 안에서 $graphify로 호출한다. 도우미를 바꾸면 등록 방식과 호출 표기도 함께 맞춰야 한다.
특정 저장소에만 적용하려면 그 폴더에서 graphify install --project --platform claude를 실행한다. 이번 Linux 격리 환경의 0.9.96 등록에서는 스킬 파일, 탐색 지침, 검색 전 훅 설정이 만들어졌다. 훅은 도우미가 파일을 검색하거나 읽기 전에 그래프를 먼저 확인하도록 안내하는 장치다. 프로젝트 등록은 코딩 도우미의 동작 지침도 바꾸므로, 생긴 파일을 확인하고 팀에 공유할지를 정하면 된다.
전체 그래프에서는 구조를 보고, 질문으로 범위를 좁힌다
분석이 끝나면 graphify-out/에 결과가 남는다. graph.html은 브라우저에서 노드를 누르고 검색하거나 묶음을 골라 보는 화면이다. 노드는 파일·클래스·함수 같은 대상을, 선은 둘 사이의 관계를 나타낸다. 색은 자동으로 감지한 연결 묶음이다. 회사의 팀 경계나 사람이 설계한 모듈 구분과 반드시 일치하지는 않는다.
공식 FastAPI 사례에서는 라우터와 보안 관련 대상 등이 색상별 묶음으로 표시된다. FastAPI는 Python으로 웹 API를 만드는 프레임워크다. 오른쪽 체크박스로 볼 묶음을 줄이고 노드를 선택하면, 복잡한 전체 그림에서 특정 대상의 주변으로 탐색 범위를 좁힐 수 있다.
GRAPH_REPORT.md는 연결이 많은 대상과 묶음, 살펴볼 경로를 읽는 보고서다. graph.json은 이후 질의에 다시 사용하는 데이터다. 그림을 계속 확대하는 대신, 무엇을 바꿀지 정해졌을 때 이 데이터에 질문하면 된다. 저장된 그래프가 있으므로 매번 모든 원본 파일을 처음부터 읽을 필요도 줄어든다.
APIRouter를 바꾸기 전에 확인할 위치를 찾았다
활용을 확인하기 위해 FastAPI 저장소의 fastapi/ 패키지에 포함된 코드 파일 52개를 분석했다. Graphify 0.9.96에서 문서를 제외하는 --code-only 옵션으로 노드 999개와 연결 2,725개가 만들어졌다. 이 수치는 해당 코드 스냅샷과 분석 범위의 결과이며, 저장소가 바뀌면 함께 달라진다.
직접 실행하는 경로는 다음과 같다. 아래 ./fastapi/fastapi는 FastAPI 저장소를 현재 폴더의 fastapi에 내려받았을 때의 코드 폴더다. 다른 프로젝트라면 분석 대상 경로로 바꾼다. cluster-only --no-label은 이미 만든 그래프에서 보고서와 화면을 생성하되, 언어 모델로 묶음 이름을 붙이는 작업은 생략한다.
graphify extract ./fastapi/fastapi --code-only
graphify cluster-only ./fastapi/fastapi --no-label
graphify explain APIRouter --graph ./fastapi/fastapi/graphify-out/graph.json
graphify affected APIRouter --depth 1 --graph ./fastapi/fastapi/graphify-out/graph.jsonexplain은 대상의 소스 위치와 주변 연결을 보여 준다. API 경로를 묶는 클래스인 APIRouter는 이번 결과에서 routing.py 2,327행에 있었고, 연결은 39개였다. affected는 그 대상을 참조하거나 사용하는 쪽으로 거슬러 가며 영향 후보를 찾는다. 깊이를 1로 제한한 결과에도 applications.py의 초기화와 include_router(), __init__.py의 가져오기 위치가 나타났다.
인수인계 중 라우터 등록 동작을 바꾼다고 가정하면, 이 목록을 출발점으로 호출부와 타입 참조를 열어 볼 수 있다. 검색어를 몇 개 떠올려 전부 훑는 방식보다 확인 순서를 잡기 쉽다. 두 대상이 어떤 경로로 이어지는지가 궁금할 때는 graphify path, 질문에 맞는 일부 그래프가 필요할 때는 graphify query를 쓴다.
찾아낸 연결과 해석한 연결은 다르게 읽어야 한다
같은 선이라도 근거는 다르다. EXTRACTED는 소스에 명시된 관계, INFERRED는 분석기가 해석하거나 연결 대상을 해소한 관계를 뜻한다. 이번 실행에서는 __init__.py가 APIRouter를 가져오는 관계는 전자였고, APIRouter가 DefaultPlaceholder를 사용하는 관계는 후자였다. 코드만 분석했는데도 추론 표기가 생겼다. 이 표기를 곧바로 언어 모델이 추측했다는 뜻으로 읽으면 안 된다.
코드 분석은 tree-sitter라는 구문 분석기로 구조를 읽는다. 문서·PDF·이미지를 의미로 해석하는 단계는 코딩 도우미의 모델이나 설정한 API를 사용할 수 있어, 코드만 로컬에서 처리하는 경로와 데이터가 전달되는 범위를 구분해야 한다. 처음부터 회사 자료 전체를 넣기보다 코드 전용 분석으로 연결 품질부터 살펴보는 편이 낫다.
영향 후보가 나온 뒤에는 표시된 파일과 행을 열어 현재 코드를 확인하고 관련 테스트를 실행한다. 그래프의 선은 실제 실행 기록이 아니며, 동적으로 결정되는 호출이나 분석 범위 밖의 소비자는 빠질 수 있다. 코드를 수정한 뒤에는 graphify update <분석 폴더>로 그래프도 갱신한다. Graphify가 남기는 것은 수정의 안전 판정이 아니라, 다음에 읽을 위치와 확인할 관계다.