💡 원문은 devtocash.com에 게시되었습니다 — 이 가이드가 최신 상태로 유지되는 곳입니다. 저는 그곳에서 매주 실무 중심의 DevOps/SRE 심층 분석 글을 작성합니다.

제안, 그리고 던져볼 만한 질문

Graphify는 코드베이스(코드, 문서, 논문, 다이어그램 등)로부터 쿼리가 가능한 지식 그래프 (Knowledge Graph)를 구축하는 오픈 소스 기술입니다. 이를 통해 AI 코딩 어시스턴트가 전체 내용을 컨텍스트 (Context)에 다 집어넣지 않고도 리포지토리(Repository)에 관한 질문에 답할 수 있게 합니다. 이는 실제적인 문제입니다. 코드베이스를 다루는 모든 에이전트 (Agent)는 읽어들이는 컨텍스트에 대한 비용을 지불하며, DevOps AI 에이전트 실행 비용이 얼마나 드는지는 정확히 이 문제, 즉 매 턴마다 다시 보내는 토큰 (Tokens) 양에 달려 있습니다.

따라서 질문은 "지식 그래프가 좋은 아이디어인가"가 아닙니다. 질문은 "이 도구가 신뢰할 수 있을 만큼 정확하고, 계속 실행할 수 있을 만큼 저렴한 결과물을 만들어내는가"입니다. 저는 이를 설치하고 실제 운영 중인 리포지토리를 대상으로 지정하여 측정했습니다. 아래의 모든 내용은 해당 실행 결과입니다.

설치: 예상보다 가볍습니다

패키지 이름에 y가 두 번 들어갑니다. 임포트 (Import) 이름과 PyPI 이름이 도구 이름과 다르기 때문에, 저는 설치에 한 번 실패했습니다:

python3 -m venv .venv && . .venv/bin/activate
pip install graphifyy          # "graphify"가 아닙니다 — 해당 이름은 PyPI에 존재하지 않습니다

이를 통해 graphifyy 0.9.29와 약 25개의 언어 문법을 포함한 tree-sitter, networkx, numpy, 그리고 rapidfuzz가 설치되었습니다. 모델 가중치 (Model weights), 임베딩 서비스 (Embedding service), 벡터 데이터베이스 (Vector database)는 포함되어 있지 않습니다. AI 툴링 (AI tooling) 카테고리의 도구임에도 불구하고 의존성 트리 (Dependency tree)가 진정으로 절제되어 있다는 점은 매우 중요합니다. 이는 핵심 추출 작업이 오프라인에서 실행됨을 의미합니다.

CLI는 graphify install --platform claude 명령어를 제공하며, 이를 통해 해당 기술을 어시스턴트의 설정 디렉토리(Claude, Cursor, Codex, Aider, Gemini 및 기타 수십 가지 도구)로 복사할 수 있습니다. 또한, MCP 서버로 연결하는 것을 선호한다면 별도의 graphify-mcp 바이너리를 사용할 수도 있습니다. 이는 읽기 전용 Kubernetes MCP 서버와 동일한 통합 형태입니다.

테스트: 실제 Next.js 리포지토리 측정

저는 LLM을 사용하지 않는 추출 경로(no-LLM extraction path)를 실제 운영 중인 블로그 리포지토리에 실행해 보았습니다. 해당 리포지토리는 99개의 MDX 문서, 56개의 TypeScript 파일, 그리고 설정 및 스크립트 파일들로 구성되어 있습니다.

graphify update /path/to/repo

/usr/bin/time -v에서 직접 추출한 수치는 다음과 같습니다:

74MB의 용량과 5초의 시간이 소요되었습니다. 이것이 핵심이며, 이 도구의 가장 강력한 장점입니다. 이 도구는 다른 모든 프로세스와 함께 2GB VPS에서도 여유롭게 실행되는데, 이는 대부분의 "AI 기반 코드 이해 (AI-powered code understanding)" 제품들에 대해서는 말할 수 없는 부분입니다. 추출 과정은 tree-sitter AST 파싱을 사용하므로 결정론적(deterministic)이며 비용이 들지 않습니다. LLM (선택적 API 키를 통한 Gemini)은 문서 및 이미지에 대한 의미론적 추출 (semantic extraction)을 선택한 경우에만 관여합니다.

리포트는 모든 엣지(edge)에 그 출처(provenance)를 표시하며, 이번 실행 결과는 100% 추출됨 (EXTRACTED) · 0% 추론됨 (INFERRED) · 0% 모호함 (AMBIGUOUS)였습니다. 저는 이 도구가 이들을 구분한다는 점이 마음에 듭니다. 추론된 엣지와 파싱된 엣지는 동일한 주장이 아니며, 이 둘을 모호하게 섞어버리는 그래프는 이를 신뢰하는 에이전트(agent)를 조용히 오도할 수 있기 때문입니다.

진정으로 뛰어난 점: 코드 구조

리포지토리의 중심 모듈을 설명해 달라고 요청했을 때, 제가 에이전트가 확인하기를 원했던 바로 그 결과가 반환되었습니다:

graphify explain "posts.ts"

Node: posts.ts
  Source:    src/lib/posts.ts L1
  Community: posts.ts
...

모든 엣지(edge)는 실제 file:line 정보를 포함하고 있습니다. 소스 코드와 대조하여 몇 군데를 무작위로 확인해 본 결과, 모두 정확했습니다. 에이전트(agent)에게 있어 이것은 "이 함수가 어딘가에서 사용되는 것 같습니다"라는 추측과, 직접 열어볼 수 있는 검증 가능한 인용(citation) 사이의 차이를 만듭니다. 이는 온콜 에이전트를 위한 컨텍스트 엔지니어링 (context engineering for on-call agents)이 작동하는 방식과 동일한 원리입니다. 모델에게 텍스트 더미를 주는 대신, 경계가 명확하고 구조화되며 확인 가능한 표면(surface)을 제공하는 것입니다.

또한, 제가 요청하지 않았던 부분도 발견되었습니다. 커뮤니티 허브(community-hub) 목록에 제가 알지 못하는 MDX 파일 이름들이 포함되어 있었는데, 확인 결과 이는 오래된 articles/ 디렉토리였습니다. 실제 게시물과 중복되는 20개의 오래된 초안들이 리포지토리에 남아 있었지만, 포스트 로더(post loader)가 content/posts만 읽기 때문에 사이트에는 서비스되지 않고 있었습니다. 해롭지는 않지만, 이를 지적해 준 것은 진정으로 유용했습니다. 구조적 관점은 파일 목록(file listing)에서는 잡히지 않는 불필요한 데이터(clutter)를 포착해 냅니다.

부족했던 점 — 그리고 왜 시스템이 저 대신 결정을 내렸는가

그다음, 저는 서로 링크되어 있는 두 기사 사이의 경로를 물어보았습니다. 먼저 grep을 사용하여 링크가 실제로 존재하는지 확인했습니다:

grep -o "/blog/kubernetes-rbac-deep-dive-2026" content/posts/...-imagepullbackoff-...mdx
# -> /blog/kubernetes-rbac-deep-dive-2026

graphify path "...imagepullbackoff...mdx" "kubernetes-rbac-deep-dive-2026.mdx"
# -> No path found between ... and ...

본문(prose)에는 링크가 명확하게 존재합니다. 하지만 그래프는 이를 모델링하지 못했습니다. 관계(relation)별로 2,666개의 엣지를 분류해 보면 그 이유를 알 수 있습니다:

그래프의 약 93%가 contains 관계입니다. 즉, 파일이 그 내부의 심볼(symbols)을 가리키는 형태입니다. 진정한 관계형 엣지(imports, calls, extends)는 총 176개로 약 6.6%에 불과하며, 이들은 모두 코드입니다. 이 LLM 미사용(no-LLM) 모드에서는 MDX 파일이 노드(node)가 되지만, 파일 간의 마크다운(markdown) 링크는 결코 엣지(edge)가 되지 않습니다. 이는 방어 가능한 설계 결정입니다. 이 도구는 AST 추출기(AST extractor)이며, 본문의 링크는 AST가 아니기 때문입니다. 하지만 이것이 바로 제가 필요로 했던 정확한 엣지 유형이었습니다.

결론: 저에게는 맞지 않지만, 그렇다고 비판하는 것은 아닙니다

가치 있는 관계가 import(임포트)가 아닌 산문(prose) 속에 존재하는 콘텐츠 저장소의 경우, 이 도구는 제가 이미 가지고 있는 것을 대체하지 못합니다. 이미 생성된 작은 knowledge.json 파일이 모든 포스트와 카테고리, 태그, 그리고 전체 내부 링크 그래프(internal-link graph)를 모델링하고 있습니다. 이는 Graphify의 코드 모드(code mode)가 포착하지 못하는 관계들입니다. 제가 약하지 않은 부분에서 강점을 가진 두 번째 그래프를 추가하는 것은 보상 없는 복잡성만 더하는 일입니다.

어느 쪽이든 실질적인 주의 사항 하나를 말씀드리자면: graphify update는 지정한 리포지토리 내부로 graphify-out/ 디렉토리를 작성합니다. graph.json, 대화형 graph.html, 그리고 캐시를 포함하여 총 6.6MB에 달합니다. 다음 커밋을 하기 전에 반드시 .gitignore에 추가하세요:

echo "graphify-out/" >> .gitignore

이런 경우라면 사용하세요: 당신의 리포지토리가 여러 언어로 구성된 수천 개의 파일을 가진 실제 코드베이스(codebase)이며, 에이전트가 무작정 grep(그렙)을 하는 대신 인용(citation)과 함께 import(임포트) 및 호출 체인(call chains)을 탐색하기를 원한다면 유용합니다. 속도가 빠르고 74MB의 점유율(footprint) 덕분에 훅(hook)에서 graphify update를 실행하여 최신 상태를 유지하는 비용이 저렴하며, 토큰 비용이 전혀 들지 않으므로 그래프 자체가 모델 비용(model bill)에 영향을 주지 않습니다.

이런 경우라면 건너뛰세요: 리포지토리가 직접 읽기에 충분히 작거나, 당신이 중요하게 생각하는 관계가 구문론적(syntactic)인 것이 아니라 의미론적(semantic)인 경우입니다. 전자의 경우 그래프는 오버헤드(overhead)일 뿐이며, 후자의 경우 코드 모드 추출 방식으로는 당신이 원하는 것을 포착할 수 없습니다. 이 경우 선택 사항인 LLM 경로에 의존해야 하는데, 이는 당신이 피하려고 했던 비용을 다시 발생시킵니다.

그것이 솔직한 결론입니다. 이 도구는 빠르고, 무료이며, 자체적인 신뢰 수준(confidence levels)에 대해 정확합니다. 이는 제가 더 많은 AI 툴링이 갖추기를 바라는 세 가지 요소입니다. 다만, 제가 겪고 있지 않은 문제를 해결할 뿐입니다. 코드 구조 측면이 아닌 이 질문의 메모리 계층(memory-layer) 측면에서는, SelfMem이 더 적합한 선택이며, 이 모든 것을 마법이 아닌 인프라(infrastructure)로 취급해야 한다는 더 넓은 논거는 the agent harness as infrastructure에서 확인할 수 있습니다.

📌 이 가이드의 최신 버전 — 그리고 DevOps, SRE, Kubernetes, 관측성(observability) 및 클라우드 비용(cloud-cost) 가이드 전체 라이브러리 — 를 devtocash.com에서 읽어보세요.