클로드 코드 성능 200% 끌어올리기 초보자를 위한 지식 그래프(Knowledge Graph) 세팅 가이드

 

Claude Code Practical Guide

클로드 코드 성능 200% 끌어올리기
초보자를 위한 지식 그래프(Knowledge Graph) 세팅 가이드

프로젝트가 커져도 똑똑함을 유지하는 AI 에이전트 환경 구축법

클로드 코드(Claude Code)나 루프 엔지니어링을 활용해 개발하다 보면, 코드베이스가 조금만 커져도 AI가 기존 코드를 잊어버리거나 멀쩡한 다른 파일에 버그를 만드는 **'컨텍스트 유실(Context Drift)'** 현상을 겪게 됩니다.

이를 해결하는 가장 강력한 방법이 바로 안드레이 카파시(Andrej Karpathy)가 강조한 지식 그래프(Knowledge Graph) 구축입니다. 코드의 전체 구조(AST)와 의존성을 지도처럼 만들어 클로드 코드에 주입해주는 과정을 초보자 눈높이에 맞춰 단계별로 정리했습니다.

💡 지식 그래프가 왜 필요한가요?

AI에게 파일 하나만 넘겨주는 것은 '지도 없이 건물 안을 탐색'하게 만드는 것과 같습니다. 반면 AST 기반의 지식 그래프는 '건물 전체의 정밀 설계도'를 넘겨주어, 코드 수정 시 어떤 파일과 함수가 영향을 받는지 1초 만에 파악하도록 돕습니다.

STEP 1. 필수 사전 준비물 설치하기

컴퓨터의 터미널(Terminal) 또는 CMD를 열고 아래 명령어를 입력하여 필요한 라이브러리를 설치합니다.

# 코드 파싱 및 그래프 생성 라이브러리 설치
pip install tree-sitter tree-sitter-python networkx mcp
  • tree-sitter: 소스코드를 분석하여 구조(AST)를 뽑아내는 도구
  • networkx: 노드(파일/함수)와 엣지(연결관계)로 그래프를 만드는 라이브러리
  • mcp: 클로드 코드와 외부 도구를 연결해 주는 표준 프로토콜

STEP 2. 지식 그래프 자동 추출 스크립트 작성

내 프로젝트 폴더 안에 build_graph.py 파일을 만들고 아래 코드를 복사해서 붙여넣습니다.

import os
import networkx as nx
import json

class SimpleCodeGraph:
    def __init__(self):
        self.graph = nx.DiGraph()

    def add_dependency(self, source, target, rel_type="CALLS"):
        self.graph.add_edge(source, target, relation=rel_type)

    def save_graph(self, output_file="code_graph.json"):
        data = nx.node_link_data(self.graph)
        with open(output_file, "w", encoding="utf-8") as f:
            json.dump(data, f, ensure_ascii=False, indent=2)
        print(f"✅ 지식 그래프가 성공적으로 저장되었습니다: {output_file}")

# 간단한 그래프 생성 예시
cg = SimpleCodeGraph()
cg.add_dependency("auth_service.py", "database.py", "IMPORTS")
cg.add_dependency("login_user()", "verify_password()", "CALLS")
cg.save_graph()

STEP 3. Claude Code와 MCP로 연결하기

클로드 코드가 지식 그래프 파일(code_graph.json)을 읽을 수 있도록 프로젝트 루트 디렉토리에 .mcp.json 파일을 설정해 줍니다.

{
  "mcpServers": {
    "codebase-graph": {
      "command": "python",
      "args": ["-m", "mcp_graph_server"],
      "env": {
        "GRAPH_PATH": "./code_graph.json"
      }
    }
  }
}

STEP 4. 실전 활용 명령어 예시

이제 클로드 코드를 실행하고 터미널에 아래처럼 프롬프트를 입력해보세요.

프롬프트 예시 1

"auth_service.py의 verify_password 함수를 수정하려고 해. 지식 그래프를 조회해서 이 수정으로 영향받는 다른 파일들과 함수 목록을 먼저 알려줘."

프롬프트 예시 2

"프로젝트 전체 지식 그래프를 바탕으로, 호출 구조가 가장 복잡해서 리팩토링이 시급한 함수 Top 3를 뽑아줘."

🎯 요약 및 결론

루프 엔지니어링이 에이전트에게 '스스로 시도하고 수정하는 손발'을 달아준 것이라면, 지식 그래프는 '전체 구조를 조망하는 눈'을 달아준 것입니다. 지식 그래프를 활용해 클로드 코드가 프로젝트의 거대한 맥락을 놓치지 않도록 세팅해보세요!

댓글

댓글 쓰기