GitNexus: AI 에이전트를 위한 코드베이스 지식 그래프 구축

Cursor, Claude Code, Windsurf 같은 AI 코딩 도구들은 강력하지만, 코드베이스 구조를 진정으로 이해하지는 못합니다. AI가 UserService.validate()를 수정해도, 47개 함수가 그 반환 타입에 의존한다는 걸 모릅니다. 결과? Breaking changes가 배포됩니다.

GitNexus는 이 문제를 **지식 그래프(Knowledge Graph)**로 해결합니다. 모든 의존성, 호출 체인, 클러스터, 실행 흐름을 인덱싱하고, MCP를 통해 AI 에이전트에 노출합니다.

1) 전통적 Graph RAG vs GitNexus

전통적 접근은 LLM에게 원시 그래프 엣지를 주고 충분히 탐색하기를 바랍니다. GitNexus는 인덱스 시점에 구조를 사전 계산합니다.

전통적 방식:
  사용자: "UserService에 의존하는 게 뭐야?"
  → 쿼리 1: 호출자 찾기
  → 쿼리 2: 어떤 파일?
  → 쿼리 3: 테스트 필터?
  → 쿼리 4: 고위험?
  → 4+ 쿼리 후 답변

GitNexus:
  사용자: "UserService에 의존하는 게 뭐야?"
  → impact({target: "UserService", direction: "upstream"})
  → 즉시: 8개 호출자, 3개 클러스터, 모두 90%+ 신뢰도

핵심 혁신: 사전 계산된 관계형 인텔리전스

2) 아키텍처 분석

2.1 인덱싱 파이프라인

GitNexus는 다단계 파이프라인으로 지식 그래프를 구축합니다.

1. Structure   → 파일 트리 탐색, 폴더/파일 관계 매핑
2. Parsing     → Tree-sitter AST로 함수/클래스/메서드 추출
3. Resolution  → import, 호출, 상속, 생성자 추론 해결
4. Clustering  → 관련 심볼을 기능 커뮤니티로 그룹화
5. Processes   → 진입점에서 호출 체인까지 실행 흐름 추적
6. Search      → 하이브리드 검색 인덱스 구축 (BM25 + semantic)

2.2 기술 스택

2.3 멀티 리포지토리 MCP 아키텍처

flowchart TD
    subgraph CLI
        Setup["gitnexus setup"]
        Analyze["gitnexus analyze"]
    end

    subgraph Registry
        RegFile["~/.gitnexus/registry.json"]
    end

    subgraph Repos
        RepoA[".gitnexus/ in repo A"]
        RepoB[".gitnexus/ in repo B"]
    end

    subgraph MCP
        Server["MCP Server"]
        Pool["Connection Pool"]
    end

    Analyze -->|"registers repo"| RegFile
    Analyze -->|"stores index"| RepoA
    Server -->|"reads registry"| RegFile
    Pool -->|"lazy open"| RepoA
    Pool -->|"lazy open"| RepoB

작동 방식:

• 각 gitnexus analyze는 인덱스를 .gitnexus/에 저장 (gitignore)
• ~/.gitnexus/registry.json에 포인터 등록
• MCP 서버가 레지스트리를 읽어 모든 인덱싱된 리포 서빙
• LadybugDB 연결은 첫 쿼리 시 지연 생성, 5분 비활성 후 제거

3) MCP 도구 분석

3.1 7개 도구

3.2 Impact Analysis 예시

impact({target: "UserService", direction: "upstream", minConfidence: 0.8})

TARGET: Class UserService (src/services/user.ts)

UPSTREAM (what depends on this):
  Depth 1 (WILL BREAK):
    handleLogin [CALLS 90%] -> src/api/auth.ts:45
    handleRegister [CALLS 90%] -> src/api/auth.ts:78
    UserController [CALLS 85%] -> src/controllers/user.ts:12
  Depth 2 (LIKELY AFFECTED):
    authRouter [IMPORTS] -> src/routes/auth.ts

3.3 Context (360도 심볼 뷰)

context({name: "validateUser"})

symbol:
  kind: Function
  filePath: src/auth/validate.ts
  startLine: 15

incoming:
  calls: [handleLogin, handleRegister, UserController]
  imports: [authRouter]

outgoing:
  calls: [checkPassword, createSession]

processes:
  - LoginFlow (step 2/7)
  - RegistrationFlow (step 3/5)

3.4 Next-Step Hints

GitNexus는 각 툴 응답에 다음 단계 힌트를 추가합니다. 에이전트가 한 번의 툴 호출 후 멈추는 것을 방지합니다.

// server.ts
function getNextStepHint(toolName: string, args: Record<string, any>): string {
  switch (toolName) {
    case 'query':
      return `\n\n---\n**Next:** Use context({name: "<symbol_name>"}) to see categorized refs.`;
    case 'context':
      return `\n\n---\n**Next:** Use impact({target: "..."}) to check blast radius.`;
    // ...
  }
}

4) 에이전트 스킬

GitNexus는 6개의 사전 정의된 스킬을 .claude/skills/에 설치합니다.

PR Review 스킬 워크플로우

1. gh pr diff <number>                                    → Get raw diff
2. detect_changes({scope: "compare", base_ref: "main"})  → Map to affected flows
3. For each changed symbol:
   impact({target: "<symbol>", direction: "upstream"})   → Blast radius
4. context({name: "<key symbol>"})                        → Understand callers
5. READ gitnexus://repo/{name}/processes                  → Check flows
6. Summarize with risk assessment

5) 지원 언어

6) 사용 방법

Quick Start

# 리포 인덱싱 (리포 루트에서 실행)
npx gitnexus analyze

이 한 줄로:

• 코드베이스 인덱싱
• 에이전트 스킬 설치
• Claude Code 훅 등록
• AGENTS.md / CLAUDE.md 컨텍스트 파일 생성

MCP 설정

Claude Code:

claude mcp add gitnexus -- npx -y gitnexus@latest mcp

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

CLI 명령어

gitnexus setup                    # MCP 설정 (일회성)
gitnexus analyze [path]           # 리포 인덱싱
gitnexus analyze --force          # 전체 재인덱싱
gitnexus analyze --skills         # 리포별 스킬 생성
gitnexus mcp                      # MCP 서버 시작
gitnexus serve                    # 로컬 HTTP 서버 (Web UI용)
gitnexus list                     # 인덱싱된 리포 목록
gitnexus wiki [path]              # 지식 그래프로 위키 생성

7) Web UI

완전한 클라이언트 사이드 그래프 탐색기 + AI 채팅.

바로 사용: gitnexus.vercel.app

• ZIP 드래그 & 드롭으로 탐색 시작
• 모든 것이 브라우저에서 실행 — 코드가 서버로 전송되지 않음
• Tree-sitter WASM + LadybugDB WASM

로컬 백엔드 모드: gitnexus serve 실행 후 로컬에서 Web UI 열면 — 인덱싱된 모든 리포를 재업로드 없이 탐색 가능.

8) 대안들과의 비교

마치며: AI 에이전트를 위한 “신경계”

GitNexus는 단순한 코드 검색 도구가 아닙니다. AI 에이전트를 위한 코드베이스 신경계입니다.

“코드를 설명하는 게 아니라, 코드의 관계를 분석한다.”

특히 인상적인 점:

1. 사전 계산된 구조: LLM이 탐색할 필요 없이 이미 구조화된 응답
2. Next-Step Hints: 에이전트가 스스로 다음 단계를 찾는 자가 유도 워크플로우
3. 멀티 리포 아키텍처: 한 번 설정으로 모든 리포 서빙

이 패턴은 다른 정적 분석 도구에도 적용할 수 있습니다. 지식 그래프 + MCP 조합은 AI 에이전트가 “진정으로 이해하는” 코딩 파트너가 되는 길입니다.

🔗 관련 정보

• GitHub: https://github.com/abhigyanpatwari/GitNexus
• npm: https://www.npmjs.com/package/gitnexus
• Web UI: https://gitnexus.vercel.app
• Discord: https://discord.gg/AAsRVT6fGb
• LadybugDB: https://ladybugdb.com/
• MCP 사양: https://modelcontextprotocol.io/