Claude Code에 지식 그래프(Knowledge Graph)를 설치한 후 14일간의 감사 결과와 깨달음

graphify에 대해 들었을 때, 저는 이것이 제 코드를 개선하고 토큰(tokens) 사용량을 줄여줄 것이라고 생각했습니다. 그래서 15일 전, 두 개의 프로덕션(production) 프로젝트에 이를 설치했습니다. 저는 제 에이전트(agent)를 업그레이드했다고 확신했습니다. 2주 후, 저는 JSONL 트랜스크립트(transcripts)를 감사(audit)했습니다. 저는 숫자를 두 번이나 다시 읽어야 했습니다. 60개의 세션 동안, 에이전트는 약 1,500번의 훅(hook) 리마인더를 실행했지만, 그래프를 호출한 횟수는 정확히 0번이었습니다. grep이 매번 차익 거래(arbitrage)에서 승리했는데, 이는 그래프가 나빠서가 아니라 그래프가 한 단계를 더 거쳤기 때문입니다. 요약하자면(TLDR): 여러분은 CLAUDE.md에 가장 아름다운 규칙을 작성하고, MCP 서버를 선언하며, 모든 커밋 시 핑(ping)을 보내는 훅을 배치할 수 있습니다. 에이전트는 고개를 끄덕이지만, 결국 다른 일을 합니다. 에이전트의 행동을 변화시키는 것은 여러분이 제공하는 컨텍스트(context)가 아닙니다. 그것은 에이전트의 경로에서 무엇을 제거하느냐입니다.

저는 이것이 제대로 작동하기를 간절히 바랐습니다. 저는 graphify에 모든 것을 걸었습니다. 세 가지 약속: 코드베이스에 대한 지속적인 메모리(persistent memory), 지도처럼 읽을 수 있는 감사 가능한 그래프(auditable graph), LLM 캐시(cache)가 볼 수 없는 문서 간의 놀라움. 그래프를 깔끔하게 타격하는 쿼리(queries)에 대해 토큰 절감 효과가 49~71배 범위라는 수치가 발표되었습니다. 모든 조건이 충족되었습니다. 저는 두 프로젝트 모두에 전체 프로세스를 실행했습니다: Convex 백엔드(backend) 위에 구축된 Next.js 스토어프론트(storefront, 약 290개 파일)와 제가 계속해서 작업하는 콘텐츠 파이프라인(content pipeline, 387개 TypeScript 파일)입니다. 하나의 AST 패스(pass)와 시맨틱 추출(semantic extraction) 레이어를 더해, Sonnet 기준으로 프로젝트당 약 $0.30에서 $1 정도가 들었습니다. 포스트 커밋(post-commit) git 훅이 들어갔고, MCP 서버가 선언되었으며, CLAUDE.md 규칙은 graphify claude install에 의해 그대로 주입되었습니다. 패널에는 7개의 도구(tools)가 보였습니다. 깔끔했습니다. 그 후 저는 더 밀어붙였습니다. 성과를 추적하기 위한 사용 로그 파일, graphify 피드백만을 위한 전용 Claude 메모리. 검토 날짜는 7일 후로 잡았으나, 데이터가 부족하다고 느껴 14일로 연장했습니다. 저는 단 하나의 데이터 포인트도 얻기 전에 평가 일정을 작성했는데, 돌이켜보면 이는 이미 답을 원하는 사람의 행동이었습니다. (당신도 예전에 그런 일정을 작성한 적이 있죠, 저만 그런 게 아닙니다.) 저는 방금 제 에이전트를 업그레이드했다고 확신했습니다. MCP 서버는 살아 숨 쉬고 있었습니다. 그래프는 활성화되어 있었고, 훅은 실행되고 있었습니다.

저는 그저 성과가 나타나기만을 기다릴 수밖에 없었습니다.

나의 열정을 꺾어버린 감사 (The Audit That Killed My Enthusiasm)
Claude Code는 모든 세션의 기록을 ~/.claude/projects/<repo>/ 디렉토리 아래에 .jsonl 파일로 저장합니다. 모든 도구 호출 (tool call)은 그 이름과 입력값과 함께 로그로 남습니다. 실제 호출은 `

GoPenAI의 Mustafa Genc와 CLSkills 통합 가이드(2026년 4월)에 기록된 49~71배의 토큰 절약 수치와 비교하면 미미한 수준입니다. 해당 수치들은 에이전트가 반드시 그래프를 사용해야만 하는 통제된 벤치마크(benchmarks)에서 측정된 것입니다. 저의 감사는 그 반대를 측정합니다. 에이전트에게 선택권이 있을 때 무엇을 하는지를 측정합니다.

Grep이 승리한 이유: Grep이 더 짧기 때문
AI 에이전트는 매 단계에서 실시간 차익 거래 (arbitrage)를 수행합니다. '완료까지 가는 가장 저렴한 경로는 무엇인가?' 텍스트 규칙은 이러한 차익 거래 과정에서 법(laws)이 아닌 신호(signals)로 진입합니다. Yajin Zhou는 2026년 3월 포스트에서 이를 명확하게 표현했습니다: AI에게 규칙은 법이 아니라 제안일 뿐입니다. Christoph Schweres는 한 달 전 아키텍처 측면을 기록했습니다: 컨텍스트 압축 (context compression) 이후, CLAUDE.md의 상태는 변합니다. 그것은 더 이상 규칙이 아니라 에이전트가 가중치를 부여할 수도 있고 그렇지 않을 수도 있는 정보가 됩니다. 이것이 바로 제가 목격한 1,500개의 무시된 훅 (hook) 알림에서 나타난 현상입니다.

graphify가 차익 거래에서 패배한 두 가지 구체적인 이유:

이유 1: 짧은 경로가 항상 승리합니다.
"X가 어디에 정의되어 있는가?", "누가 Y를 호출하는가?", "Z에 영향을 주는 것은 무엇인가?"라는 질문에 답하기 위해 grep -r을 사용하면 1~2초 안에 정확한 라인을 찾아줍니다. 반면 GRAPH_REPORT.md를 읽으면 500 토큰 분량의 주제별 요약을 얻게 되지만, 그 후에도 에이전트는 여전히 파일을 열어야 합니다. 한 단계와 두 단계의 차이입니다. 실시간 차익 거래는 당신이 CLAUDE.md 안에 대문자로 무엇을 적었든 상관없이 짧은 경로를 선택합니다. 이것은 버그가 아닙니다. 그것은 훈련된 대로의 가중치 부여 (weighting) 결과입니다.

이유 2: 텍스트 규칙에는 지속적인 규율이 없습니다.
저의 PreToolUse:Bash 훅은 에이전트에게 "범위 내 파일 3개가 변경되었습니다. /graphify update를 다시 실행하세요"라는 알림을 1,500번 이상 보냈습니다. 하지만 단 한 번도 그래프 조회를 트리거하지 않았습니다. 알림은 파싱(parse)하고 건너뛰어야 할 소음 (noise)이 되었습니다. 이 패턴은 현재 많이 문서화되어 있습니다: GitHub 이슈 #18660, #22022, #19635, 그리고 가장 최근인 5월 8일에 접수된 #57200 (보고자는 이미 메모리에 있는 결정을 재발견하기 위해 85K 토큰을 낭비했는데, 이는 laws.md의 규칙이 컨텍스트 압축 과정에서 살아남지 못했기 때문입니다).

Mustafa Morbel은 지난 4월 기고문에서 그 차이를 잘 정의했습니다: CLAUDE.md는 본질적으로 권고 사항(advisory)인 반면, 훅(hooks)은 결정론적(deterministic)입니다. 텍스트는 논쟁의 대상이 될 수 있지만, 메커니즘은 그렇지 않습니다. 저는 이전에 CLAUDE.md의 위생(hygiene)에 대해, 즉 제 CLAUDE.md의 47개 라인과 왜 Claude가 제 규칙을 불러오기도 전에 50개의 지침을 소모해 버리는지에 대해 글을 쓴 적이 있습니다. 그 글에서는 더 나은 규칙을 작성하라고 말했습니다. 이 글은 가장 잘 작성된 규칙이라 할지라도 여전히 권고 사항에 머물며 차익 거래(arbitrage)에 밀린다고 말합니다. 두 가지 모두 사실입니다. 하지만 어느 쪽도 충분하지는 않습니다.

내가 사용했어야 했던 곳 (그리고 당신도 아마 그래야 할 곳)
저는 설정 실수를 저질렀습니다. 사실 두 가지 실수를 했습니다.

실수 1: 익숙한 영역에 탐색 도구(discovery tool)를 설치했습니다. graphify 문서는 대상 사용 사례를 명확히 명시하고 있습니다: 처음 접하는 코드베이스(codebase), 읽기 목록(논문, 트윗, 노트), 연구 코퍼스(research corpus), 모든 것을 쏟아붓는 개인용 /raw 폴더 등입니다. 제가 진행 중인 두 프로젝트 중 어느 것도 이에 해당하지 않았습니다. 저는 코드의 절반을 직접 작성했고, 나머지는 여러 번 다시 읽었습니다. Claude 역시 마찬가지로, 이 저장소(repos)들에 대한 모델의 작업 기억(working memory)은 이미 예열(warm)된 상태였습니다. 커뮤니티 탐지(community-detection) 단계가 드러내야 할 문서 간의 놀라운 연결 고리들은, 이미 그 연결을 알고 있는 사람에게는 전혀 놀랍지 않습니다. 저는 5년 동안 살아온 아파트 안에 나침반을 설치한 셈입니다.

실수 2: 도구를 예열된 상태(hot)가 아닌 차가운 상태(cold)로 배포했습니다. 컨텍스트 도구는 에이전트(agent)에게 더 저렴한 대안이 없을 때 실시간 차익 거래(real-time arbitrage)에서 승리합니다. 새로운 저장소에서는 grep이 여전히 비용이 많이 들기 때문에(에이전트가 눈먼 상태로 훑어야 함), 그래프를 먼저 읽는 것이 지름길이 됩니다. 하지만 3~6개월 정도 노출되면 grep은 예열된 캐시(warmth cache)를 갖게 되고, 그래프는 다시 우회로가 되어버립니다. 저는 이미 두 프로젝트 모두에서 몇 달 전에 그 선을 넘었습니다. graphify가 도착했을 때, 에이전트는 무상태 시스템(stateless system)에서 근육 기억(muscle memory)이라 부를 수 있는 무엇인가를 이미 구축한 상태였고, 그 근육 기억은 "먼저 grep을 하고, 질문은 하지 마라"라고 말하고 있었습니다.

다음은 제가 첫날부터 준수했어야 했던 사용 지도(usage map)입니다. 자신이 잘 모르는 상태에서 인계받은 저장소에 온보딩(onboarding)할 때입니다.

아마도 그래프(graph)가 승리할 것입니다. 왜냐하면 grep은 처음에 눈먼 상태이지만, 주제별 지도(topical map)는 실제 읽는 시간을 절약해주기 때문입니다. 이는 Jo Van Eyck가 그의 "AI 코딩 에이전트는 대규모 코드베이스에서 무용지물이다"라는 영상에서 주장했던 사례이며, 그 특정 프레임에 있어서 그는 옳습니다. 알 수 없는 영역(unknown surface)이 커질수록, 전역 지도(global map)의 가치는 더욱 높아집니다. 숨겨진 의존성(dependencies)을 추적해야 하는 레거시 저장소(legacy repo)에서의 모듈 간 보안 감사(Cross-module security audit)가 그 예입니다. 이는 graphify 문서에 명시된 구체적인 사례이며, 에이전트가 단일 grep으로는 얻을 수 없는 전역적 관점(global view)을 필요로 한다는 점에서 타당합니다. 당신은 문자열(string)을 찾는 것이 아니라 위상(topology)을 찾는 것이기 때문입니다. 논문, 노트, 트윗, 참조 코드 등이 섞인 혼합 읽기 목록(Mixed reading list)에서 커뮤니티 탐지(community detection)는 grep이 생성할 수 없는 관점을 진정으로 드러내 줍니다. 아마도 이것이 가장 강력한 유스케이스(use case)이며, 이 모든 대화를 시작하게 만든 원래의 /raw 철학에 가장 가까운 사례일 것입니다. 이질적인 코퍼스(Heterogeneous corpora)는 다양한 형식에 걸친 grep이 형편없는 수준이기 때문에, 구조적 추출(structural extraction)로부터 가장 큰 이득을 얻습니다.

이미 잘 알고 있는 프로젝트를 유지보수하기 위한 용도는 아닙니다. 그것이 제가 했던 방식이었고, 잘못된 적용이었습니다. 이러한 미묘한 차이가 제 경험을 정당화해주지는 않습니다. 다만 제가 무엇을 먼저 테스트했어야 했는지를 명확히 해줄 뿐입니다. Rajistics는 RAG 측면에서 유사한 입장을 취하는 "GraphRAG (아마도 당신은 그것이 필요하지 않을 것입니다)"라는 제목의 YouTube 영상을 가지고 있습니다. 지식 그래프(knowledge graphs)에 대한 결론은 동일합니다. 케이스 바이 케이스(case-by-case)이며, 항상 필요한 것은 아닙니다. (별로 진전은 없는 사족이지만: 저는 가장 열정적으로 설치하는 도구들이 사전에 가장 적게 읽어본 도구들이라는 점을 계속 발견하곤 합니다. 한 번 훑어보고 잊어버리는 지루한 도구들이 대개 6개월 후에도 계속 사용하고 있는 것들입니다. 아마도 열정이 평가를 어떻게 왜곡하는지에 대한 교훈이 담겨 있을지도 모릅니다. 아니면 그냥 제가 도구에 대한 취향이 나쁜 것일 수도 있습니다. 솔직히 말하기 어렵네요.)

진정한 교훈: 텍스트는 에이전트의 행동을 바꾸지 않는다. 메커니즘(Mechanics)이 바꾼다. 이 패턴은 graphify보다 더 거대합니다. 당신은 에이전트에게 새로운 도구, 새로운 문서, 새로운 규칙을 건넵니다. 당신은 그것을 잘 작성합니다. CLAUDE.md에서 그것을 상기시킵니다. 핑(ping)을 보내는 훅(hook)을 던집니다. 에이전트는 고개를 끄덕입니다.

그러고 나서 그것은 다른 행동을 합니다. 이러한 패턴은 GitHub 이슈, r/ClaudeAI 스레드, 그리고 최소 12개 이상의 최근 Medium 게시물 전반에서 나타납니다. 이것은 2026년 컨텍스트 도구(contextual tooling)의 지배적인 실패 모드(failure mode)입니다. 실제로 작동하는 것은 세 가지 기계적 레버(mechanical levers)입니다. 레버 1, 상기시키는 대신 차단하십시오(block instead of remind). 대안적인 행동을 거부하는 PreToolUse 훅(hook)이 경로를 강제합니다. Mustafa Morbel은 이미 그 차이를 기록했습니다. CLAUDE.md는 권고적(advisory)이지만, 훅(hook)은 결정론적(deterministic)입니다. 실시간 차익 거래(real-time arbitrage)가 더 짧은 경로를 찾는 순간, 무시될 수 있는 모든 규칙은 무시될 것입니다. 해결책은 더 나은 문구(wording)를 사용하는 것이 아닙니다. 해결책은 메뉴에서 대안을 제거하는 것입니다. 만약 당신의 훅(hook)이 단지 상기시키기만 한다면, 당신은 에이전트가 무시하는 법을 배우게 될 공손한 목소리를 만든 것입니다. 만약 당신의 훅(hook)이 호출을 차단한다면, 당신은 벽을 만든 것입니다. 레버 2, 도구를 우회로가 아닌 지름길로 만드십시오. 질문에 답을 주는 지식 그래프(knowledge graph)가 승리합니다. 에이전트가 여전히 열어봐야 하는 파일들을 가리키기만 하는 지식 그래프는 패배합니다. 단계를 제거하는 대신 단계를 추가했기 때문입니다. MCP 서버의 경우도 동일한 원리가 적용됩니다. N개의 도구 호출(tool calls)을 제거하는 서버가 승리하고, N+1개의 호출을 추가하는 서버는 패배합니다. 저는 '왜 CLI가 AI 에이전트에게 MCP보다 우월한가(why CLIs beat MCP for AI agents)'에서 CLI와 MCP에 대해 동일한 주장을 했습니다. CLI가 승리하는 이유는 에이전트에게 JSON-RPC 핸드셰이크(handshake)로 우회하라고 요청하는 대신, 에이전트의 네이티브 경로(native path)에 딱 들어맞기 때문입니다. 이 메커니즘은 모든 컨텍스트 도구에 일반화됩니다. 단계를 추가하면 패배하고, 단계를 제거하면 승리합니다. 그것이 게임의 전부입니다. 레버 3, 적절한 시점에 도구를 도입하십시오. 컨텍스트 도구는 콜드 스타트(cold start) 시점에 승리하며, 워밍 유지보수(warm maintenance) 시점에는 승리하지 못합니다. 이것이 제가 graphify에서 저지른 실수였지만, 개발자들이 프로젝트 시작 6개월 후에 CLAUDE.md에 200줄을 추가할 때 저지르는 실수이기도 합니다. 너무 늦었습니다. 그때쯤이면 해당 레포지토리(repo)에서 에이전트의 행동 패턴은 기존 도구들(grep, ls, cat, 이미 탐색하는 법을 익힌 파일 트리)에 의해 고정되어 버립니다.

그 위에 추가된 새로운 도구는 관성(inertia)을 극복해야 합니다. 실시간 차익 거래(real-time arbitrage) 상황에서의 관성이란 "지난번에는 이 경로가 저렴했으니, 다시 이 경로를 택하라"는 의미를 뜻합니다. 세 가지 레버(levers)에는 비용이 따릅니다. 그것들은 도구를 더 침습적(invasive)으로 만듭니다. 차단형 훅(blocking hook)은 예외를 만들고 싶을 때 당신을 짜증 나게 합니다. 단축 경로 도구(short-path tool)는 grep의 유연성을 고정된 스키마(fixed schema)의 경직성으로 대체합니다. 콜드 스타트(cold-start) 도구는 프로젝트를 시작하기도 전에 도구를 계획해야 함을 의미하는데, 우리 대부분은 프로젝트를 시작하기 전이 아니라 고통을 느낄 때 도구를 설치하기 때문에 결코 그렇게 하지 않습니다. 그래서 모두가 대신 권고 계층(advisory layer)에 의존하게 됩니다. CLAUDE.md에 더 많은 줄을 작성하고, 또 다른 리마인더 훅(reminder hook)을 추가하며, 이번에는 규칙이 충분히 명확하다고 스스로를 다독입니다. 저도 그렇게 해왔습니다. 당신도 아마 그럴 것입니다. 권고 계층이 편안한 이유는 바로 우리가 에이전트의 행동을 변화시켰다고 착각하게 해주기 때문입니다.