코드베이스를 통째로 다시 읽히지 않기로 했습니다 🔗

요즘 저는 코드를 직접 짜는 시간보다, AI 에이전트에게 코드를 맡기는 시간이 더 깁니다.

그런데 프로젝트가 커질수록 이상한 걸 목격하게 됐어요. 대화를 새로 시작할 때마다 AI가 “이 프로젝트가 어떻게 생겼더라”부터 다시 파악합니다. 파일을 하나씩 열어보고, 또 열어보고요.

같은 구조를 몇 번이고 다시 읽히는 셈입니다. 읽는 분량만큼 시간도 돈도 거기서 새고 있었어요.

어떻게 접근했나

핵심은 코드의 지도를 미리 그려두는 겁니다.

프로젝트 안에는 “이 함수가 저기서 불린다”, “이 파일이 저 파일을 가져다 쓴다” 같은 연결이 잔뜩 있어요. 그 연결만 미리 뽑아 한 장으로 정리해두는 거죠. 점과 선으로 이어진 그림이라 흔히 그래프라고 부릅니다.

그래피파이(graphify)라는 오픈소스 도구를 씁니다.

프로젝트 폴더에서 명령 하나(graphify update .)를 돌리면 됩니다. 코드를 실행해보는 게 아니라 글자 그대로 읽어서 연결 관계만 뽑아내요. 그래서 인터넷도, AI 사용료도 들지 않습니다. 내 컴퓨터 안에서 끝나요.

이렇게 만든 지도에는 graphify query "..."로 물어봅니다. AI가 파일을 무작정 열어보는 대신, 먼저 지도에 물어보고 정말 필요한 파일 한두 개만 여는 순서가 됩니다.

지금은 돈독과 자동화 스크립트까지, 제 개발 폴더 안 여러 프로젝트에 이 방식이 붙어 있습니다.

걸렸던 것들

깔끔해 보이지만, 붙이면서 걸린 지점이 몇 군데 있었습니다.

하나, 지도를 만들면 결과물 폴더가 하나 생기는데 이걸 버전 관리에서 빼는 걸 자꾸 깜빡했습니다. 안 빼두면 코드와 같이 저장돼서 지저분해지거든요. 점검할 때마다 “이거 그대로 올라갈 뻔했다”는 지적이 몇 번이나 반복됐어요. 프로젝트마다 한 줄씩 추가하고서야 끝났습니다.

둘, 욕심을 내서 제 메모 앱에도 같은 방식을 붙여보려 했습니다. 노트 수백 장이 서로 어떻게 참조하는지도 그래프로 만들면, 자료 찾는 시간이 줄지 않을까 싶었거든요. 그런데 이 도구는 코드처럼 연결이 또렷하게 적혀 있는 것만 잡아냅니다. 노트는 줄글이라 “이 문장이 저 문장을 부른다” 같은 게 없죠. 지도를 만들어도 이어지는 선이 거의 안 나왔습니다. 결국 노트 쪽엔 이 도구를 연결하지 않기로 했고, 대신 노트는 개념과 개념의 선후관계를 제가 직접 정의하는 다른 방식으로 따로 풀었습니다.

셋, 지도가 알려주는 건 구조지 의미가 아니었습니다. “이 함수가 어디서 불리는지”는 바로 나오지만 “왜 이렇게 짜여 있는지”는 안 나옵니다. 그러니까 이 도구가 파일 읽기 자체를 없애주는 게 아니라, 뭘 읽을지 후보를 좁혀주는 1차 필터라는 걸 받아들여야 했어요.

---

그래프는 구조를 알려줄 뿐, 의미까지 대신 읽어주진 않습니다.

그래서 뭐가 달라졌나

이전에는 대화를 새로 시작할 때마다 AI가 구조를 파악하려고 파일을 여러 개 순서대로 열었습니다. 그만큼 시간도, 비용도 나갔어요.

지금은 구조에 대한 질문은 그래프에 먼저 묻고, 정말 필요한 파일 한두 개만 엽니다. 같은 프로젝트를 여러 날에 걸쳐 계속 붙잡고 있는 저 같은 경우엔 이 차이가 매번 쌓입니다.

따라 해보고 싶다면

그래피파이는 오픈소스라 구독도 키도 없이 프로젝트 폴더에서 바로 씁니다. 프로젝트가 클수록, 그리고 작업이 자주 끊겼다 이어질수록 체감이 큽니다.

시각화가 필요하면 그래프를 별도 폴더로 내보내는 옵션도 있는데, 지식 노트 폴더와는 분리해서 관리하시길 권합니다. 위에서 얘기했듯 이 도구는 코드 전용이라, 노트 폴더에 섞어두면 오히려 헷갈립니다.

남은 것

그래피파이 자체는 화려한 도구가 아닙니다. “다시 읽지 않아도 되게, 구조를 미리 적어둔다”는 단순한 발상이 전부예요.

그런데 그 단순한 장치 하나가, 매번 파일을 뒤지던 시간을 조금씩 줄여줍니다. 그렇게 되찾은 시간은 결국 초록이한테 씁니다.

오늘도 한 걸음. 🐴