CodeGraph로 DaejinLab 블로그 구조를 읽어본 기록

AI에게 코드베이스를 맡기고 싶을 때가 있습니다. 파일을 하나씩 열어보는 시간이 아깝고, “이 구조를 한 번에 읽고 설명해주면 좋겠다”는 생각도 듭니다. 그런데 막상 프로젝트 전체를 읽는 도구를 붙이려고 하면 손이 살짝 멈춥니다.

내 repo를 어디까지 읽는지. 인덱스 파일은 어디에 생기는지. 그 결과물이 git에 섞이지는 않는지. 도구가 편해 보이는 것과, 내 작업 폴더에 안전하게 들어와도 되는지는 다른 문제였습니다.

그래서 이번에는 CodeGraph를 DaejinLab 블로그 repo에 바로 전역 도구처럼 붙인 게 아니라, 작은 pilot로만 봤습니다. 이 글은 설치 홍보가 아닙니다. “코드 인덱스 도구를 쓰면 개발이 빨라진다”는 결론을 내리려는 글도 아닙니다. 제 블로그 repo를 대상으로 실제로 한 번 읽혀보고, 어디서 멈춰야 하는지 적은 기록입니다.

CodeGraph pilot result

먼저 본 것은 기능보다 범위였습니다

CodeGraph 자체는 로컬 code knowledge graph와 MCP 도구를 제공하는 쪽에 가깝습니다. wiki 기록 기준으로 Hermes Agent 지원을 명시하고 있고, 검색·context·callers·callees·impact 같은 도구가 있습니다. 이름만 보면 꽤 매력적입니다. 파일을 일일이 뒤지는 대신 코드 구조를 질의할 수 있으니까요.

하지만 저는 먼저 “얼마나 똑똑한가”보다 “어디에 붙는가”를 봤습니다.

이전 검토에서 CodeGraph는 기본 profile이 아니라 dev profile 한정 pilot 후보로 분류했습니다. 이유는 단순합니다. installer나 MCP 도구가 profile config를 건드릴 수 있고, 프로젝트별 index/cache를 만들 수 있기 때문입니다. 편리한 도구일수록 처음부터 기본 작업 환경에 넣으면 나중에 되돌릴 때 더 귀찮아집니다.

이번 DaejinLab pilot도 같은 방식으로 작게 시작했습니다.

실제로 DaejinLab repo에서 확인한 값

wiki 기록에 남긴 실행은 이렇습니다.

codegraph init -i .

대상은 DaejinLab 블로그 repo 하나였습니다. 결과는 다음처럼 나왔습니다.

Indexed 14 files
241 nodes
356 edges after verification
DB size about 0.51 MB
.codegraph directory about 524K

숫자만 보면 작은 편입니다. DaejinLab은 거대한 서비스 코드베이스가 아니라 Astro 기반 블로그입니다. 그래도 이 정도만 봐도 감은 옵니다. 글 목록, layout, script, content schema처럼 반복해서 확인하는 부분을 코드 인덱스가 잡아줄 수 있겠다는 느낌은 있었습니다.

CLI smoke check도 했습니다.

codegraph files --path .
codegraph query --path . --limit 8 blog
codegraph query --path . --limit 8 page

여기까지는 좋았습니다. 그런데 바로 다음에 현실적인 문제가 보였습니다.

.codegraph/가 생깁니다.

이건 이상한 일이 아닙니다. 인덱스 도구니까 DB와 cache가 필요합니다. 다만 DaejinLab처럼 public GitHub repo로 배포되는 프로젝트에서는 이런 생성물이 source tree에 섞이는 순간 바로 정리 대상이 됩니다. 실제로 pilot 직후에는 root 기준으로 untracked directory가 보였고, 이후 사용자 승인 후 root .gitignore에 .codegraph/를 추가하는 방향으로 처리했습니다.

왜 이것을 글로 남기나

개발 도구 글을 보면 보통 “설치 → 실행 → 결과”로 끝나는 경우가 많습니다. 저도 예전에는 그런 글이 편했습니다. 빠르게 따라 하면 되니까요.

그런데 개인 프로젝트를 계속 운영하다 보니, 설치 성공보다 더 자주 문제가 되는 건 뒤처리였습니다.

생성 파일이 git에 섞이는 문제
config가 어느 profile에 들어갔는지 모르는 문제
rollback 명령을 남겨두지 않는 문제
한 번 편해서 전역에 붙였다가, 나중에 원인을 모르는 문제가 생기는 상황

CodeGraph pilot에서 얻은 가장 큰 수확은 “이 도구가 쓸 만하다”보다 “이런 도구는 profile과 repo를 좁혀서 봐야 한다”였습니다.

CodeGraph approval boundary

내가 정한 적용 기준

이번 기록을 기준으로, 저는 코드 인덱스 도구를 볼 때 다음 순서로 보려고 합니다.

기준	확인할 것	이유
적용 범위	default가 아니라 dev profile 한정인지	일상 작업 환경 오염을 줄이기 위해
생성물	DB/cache/log가 어디 생기는지	public repo에 섞이면 안 됨
config 변경	어떤 config 파일을 수정하는지	rollback을 남겨야 함
외부 호출	로컬 인덱스인지, 원격 전송이 있는지	private code/내용 보호
성능 평가	search/read 대비 실제로 줄어드는지	도구 추가 자체가 목적이 아니기 때문

여기서 마지막 줄이 의외로 큽니다. 도구가 하나 더 늘면 당장은 좋아 보입니다. 하지만 실제 작업 시간이 줄지 않으면 관리 대상만 늘어납니다. 저는 DaejinLab처럼 작은 repo에서는 “정말 필요한 순간에만 쓰는 보조 도구” 정도가 맞다고 봅니다.

좋았던 점

좋았던 점도 분명히 있습니다.

우선 CodeGraph는 “코드베이스를 읽는 도구”라는 목적이 비교적 선명했습니다. 적어도 제가 본 검토 범위에서는 Hermes dev profile에 붙여볼 명분이 있었습니다. 파일·노드·호출 관계를 다루는 도구가 있으니, 큰 repo에서 특정 변경 영향도를 볼 때는 도움이 될 수 있습니다.

또 DaejinLab pilot처럼 작은 프로젝트에 먼저 붙여본 것도 괜찮았습니다. 큰 repo에서 바로 실험했다면 index 생성물, config, 성능, rollback을 한꺼번에 봐야 했을 겁니다. 작은 블로그 repo에서는 문제가 작게 드러납니다. 이게 pilot의 장점입니다.

아쉬웠던 점과 조심할 점

아쉬운 점은, 이런 도구는 “붙이는 순간 끝”이 아니라는 점입니다. index를 최신으로 유지해야 하고, 생성물을 무시해야 하고, profile config도 기억해야 합니다. 특히 .codegraph/ 같은 로컬 생성물은 초보자 입장에서는 “이거 commit 해야 하나?” 하고 헷갈릴 수 있습니다.

그리고 MCP로 붙는 도구는 사용감이 좋아질수록 오히려 경계가 흐려질 수 있습니다. 처음에는 코드 검색만 하다가, 나중에는 여러 도구와 섞여 자동 수정 흐름으로 이어질 수 있습니다. 그래서 DaejinLab 기준으로는 code intelligence tool도 approval boundary 안에 넣어두는 편이 마음이 편합니다.

확인한 것과 아직 확인하지 않은 것

확인한 것:

DaejinLab blog repo에서 CodeGraph index 생성 가능
14 files, 241 nodes, 356 edges 생성 기록
.codegraph/ generated directory 발생
root .gitignore에 .codegraph/ 추가 필요성 확인
dev profile 한정 MCP 연결 방향이 더 안전하다는 판단

아직 확인하지 않은 것:

큰 repo에서 실제로 search/read 대비 시간이 줄어드는지
코드 수정 전 영향도 분석에 얼마나 도움이 되는지
장기 운영 시 index stale 문제가 얼마나 자주 생기는지
팀 프로젝트에서 이 도구를 어떻게 공유해야 하는지

이 글을 공개한다면, 저는 “CodeGraph 추천기”보다는 “코드 인덱스 도구를 내 repo에 들일 때의 작은 점검 기록”으로 두고 싶습니다.

FAQ

CodeGraph를 모든 프로젝트에 바로 붙여도 될까요?

저는 그렇게 하지 않으려고 합니다. 먼저 repo 하나, profile 하나로 좁혀서 봅니다. 생성 파일과 config 변경을 확인한 뒤에 넓히는 편이 안전합니다.

`.codegraph/`는 commit해야 하나요?

DaejinLab 기준으로는 아닙니다. 로컬 인덱스 DB/cache 성격이므로 public repo에는 넣지 않는 쪽이 맞다고 봤습니다.

작은 블로그 repo에도 이런 도구가 필요한가요?

항상 필요한 건 아닙니다. 다만 도구 pilot에는 작은 repo가 오히려 좋았습니다. 문제가 작게 보이고, rollback도 쉽기 때문입니다.

다음 기준

다음에 CodeGraph를 다시 쓰면, 저는 “정말 작업 시간이 줄었는지”를 보려고 합니다. index가 잘 만들어졌다는 것만으로는 부족합니다. 기존 search_files, read_file, 수동 구조 파악보다 적은 호출과 적은 실수로 같은 결론에 도달할 때, 그때 계속 쓸 이유가 생긴다고 봅니다.

출처와 기준일

기준일: 2026-05-25
내부 wiki: CodeGraph Daejin Lab Blog Index Pilot 2026-05-24
내부 wiki: Codegraph Dev Pilot Apply Log 2026-05-24
원문 repo: colbymchenry/codegraph
출처 품질: wiki 운영 로그와 GitHub 원문 기반 A, confidence high/medium 혼합

참고한 공식 문서 추가

Codegraph로 구조를 보는 일도 결국 공개 사이트의 연결을 이해하기 위한 보조 작업입니다. 도구 결과를 그대로 결론으로 쓰기보다, Astro 콘텐츠 구조와 실제 내부 링크 기준을 함께 확인해야 했습니다.