클로드 코드가 파일부터 뒤지지 않게 만드는 Graphify 가이드
큰 코드베이스에서 클로드가 파일을 하나씩 열어 헤매는 게 느린 분께 맞는 글입니다. Graphify로 지식 그래프를 만들고 질문하고 갱신하는 3단계를 정리했습니다.
Graphify는 폴더 하나를 노드와 엣지로 이루어진 지식 그래프로 바꿔, 클로드가 파일을 하나씩 열지 않고 그래프에 질문해 답을 찾게 하는 도구입니다. 그래프는 코드가 바뀌면 낡으므로 --update로 갱신하는 습관이 함께 필요합니다.
이 저장소에 Graphify를 적용하려고 해. 1. /graphify로 그래프를 만드는 순서를 알려 줘 2. 그래프가 만들어진 뒤 /graphify query로 "이 설정값을 어디서 바꾸는지" 같은 질문을 하는 방법을 알려 줘 3. 큰 작업을 시작하기 전에 --update로 갱신하는 절차를 체크 항목으로 정리해 줘
Graphify(그래피파이)는 폴더 하나를 통째로 넣으면 그 안의 코드·문서 관계를 노드(개념 하나)와 엣지(관계 하나)로 이루어진 지식 그래프로 바꿔 주는 도구입니다.
한 번 만들어 두면 다음부터는 클로드가 파일을 하나씩 열어보는 대신 이 그래프에 질문을 던져 답을 찾습니다.
파일을 뒤지는 게 왜 느린가요
클로드는 기본적으로 관련 있어 보이는 파일을 검색하고, 열어서 읽고, 다시 다른 파일을 찾는 방식으로 코드베이스를 파악합니다. 코드베이스가 커질수록 이 과정에서 읽는 파일 수도, 그만큼 쓰는 컨텍스트(대화가 기억하는 범위)도 늘어납니다.
Graphify는 이 과정을 미리 한 번 해 둡니다. 코드 파일은 AST(코드를 구조적으로 분석하는 방식)로, 문서·이미지는 LLM(언어모델)으로 읽어 "이 함수는 저 클래스를 호출한다" 같은 관계를 추출해 그래프로 저장합니다.
그래프 만들기
/graphify 또는 /graphify <경로>를 실행하면 파일을 감지하고, 구조·의미 관계를 추출해 graphify-out/graph.json과 GRAPH_REPORT.md를 만듭니다. 코드만 있는 저장소는 API 키 없이 구조 분석만으로 동작합니다.
/graphify
/graphify <경로>질문하기
그래프가 이미 있으면 /graphify query "질문"으로 바로 답을 찾습니다. 이때는 다시 빌드하지 않고 저장된 그래프를 씁니다.
/graphify query "이 설정값은 어디서 바꾸나"갱신하기
코드가 바뀌면 /graphify <경로> --update로 바뀐 파일만 다시 추출합니다. 전체를 다시 만들지 않아도 됩니다.
/graphify <경로> --update적용 전후, 내가 느낀 변화
큰 저장소에서 "이 설정값을 어디서 바꾸는지" 같은 질문을 할 때, 예전에는 클로드가 grep(문자열 검색)으로 여러 파일을 돌아다녔습니다. 그래프를 만든 뒤로는 /graphify query로 관련 노드를 바로 짚어 주는 느낌을 받았습니다.
다만 저는 정식으로 시간을 재서 비교하지는 않았습니다. 체감상 빨라졌다는 것이지, "몇 배 빠르다"는 수치는 제가 직접 측정한 값이 아닙니다.
자주 하는 실수
처음에는 그래프를 한 번 만들고 그대로 계속 썼습니다. 코드가 바뀌었는데 그래프는 예전 상태를 가리키고 있어서, 클로드가 이미 지운 함수를 찾으려 한 적이 있습니다.
--update로 갱신하는 습관이 없으면 그래프가 오히려 낡은 지도가 됩니다. 지금은 큰 작업을 시작하기 전에 --update부터 돌립니다. 그래프가 코드와 어긋나 있으면 안 만든 것만 못하다는 걸 겪고 나서 바꾼 습관입니다.
자주 묻는 질문
API 키가 꼭 있어야 하나요?
코드만 있는 저장소는 필요 없습니다. 구조 분석(AST)은 API 키 없이 동작하고, 문서·이미지처럼 의미 파악이 필요한 파일에만 선택적으로 LLM을 씁니다.
아무 프로젝트에나 다 도움이 되나요?
파일이 몇 개 안 되는 작은 프로젝트는 굳이 필요 없습니다. 관계가 복잡하게 얽힌 큰 코드베이스에서 효과를 체감하기 쉽습니다.
한 번 만든 그래프는 계속 정확한가요?
아닙니다. 코드가 바뀌면 그래프도 낡습니다. --update로 바뀐 파일만 다시 추출하는 방식이라 매번 처음부터 다시 만들 필요는 없지만, 갱신 자체는 직접 챙겨야 합니다.
정리
큰 코드베이스에서는 매번 파일을 뒤지는 대신, 관계를 미리 그려 두고 그 지도에 질문하는 편이 낫습니다. 다만 지도는 관리하지 않으면 낡습니다.
공식 자료
- Graphify 스킬 문서(로컬 설치본):
~/.claude/skills/graphify/SKILL.md - lazyowen.com 가이드: 클로드 코드가 파일부터 뒤지지 않게 만드는 Graphify 가이드