harshkedia177/axon: 코드베이스를 위한 지식 그래프 — 시각적 탐색 및 AI 에이전트 쿼리 지원

코드베이스를 위한 지식 그래프 — 시각적으로 탐색하거나 AI 에이전트가 쿼리하도록 하세요.

모든 의존성(dependency), 호출 체인(call chain), 클러스터(cluster), 실행 흐름(execution flow)을 포함하여 모든 코드베이스를 구조적 지식 그래프(knowledge graph)로 인덱싱합니다. 힘 지향 그래프 시각화(force-directed graph visualization)가 적용된 **대화형 웹 대시보드(interactive web dashboard)**를 통해 탐색하거나, **MCP 도구(MCP tools)**를 통해 노출하여 AI 에이전트가 모든 도구 호출 시 완전한 구조적 이해를 갖도록 할 수 있습니다.

$ axon analyze .
Walking files... 142 files found
Parsing code... 142/142
...

그 다음 코드베이스를 시각적으로 탐색하세요:

axon ui # localhost:8420에서 대화형 대시보드를 엽니다

세 가지 뷰, 하나의 명령:

Explorer(탐색기)— 대화형 힘 지향 그래프 (Sigma.js + WebGL). 노드를 클릭하면 해당 코드, 호출자(callers), 피호출자(callees), 영향 반경(impact radius) 및 커뮤니티를 볼 수 있습니다. 커뮤니티 헐(Community hull) 오버레이를 통해 아키텍처 클러스터를 한눈에 확인할 수 있습니다.
Analysis(분석)— 건강 점수(Health score), 결합도 히트맵(coupling heatmap), 데드 코드 보고서(dead code report), 상속 트리(inheritance tree), 브랜치 차이(branch diff) — 코드베이스의 상태를 하나의 대시보드에서 확인하세요.
Cypher Console(Cypher 콘솔)— 구문 강조(syntax highlighting), 프리셋(presets), 히스토리(history) 기능과 함께 그래프에 대한 Cypher 쿼리를 작성하고 실행하세요.

추가 기능: 커맨드 팔레트(Cmd+K), 키보드 단축키, 흐름 추적 애니메이션(flow trace animations), 그래프 미니맵(graph minimap), 그리고 watch 모드가 활성화되었을 때 SSE 기반의 라이브 리로드(live reload)를 지원합니다.

당신의 AI 에이전트가 UserService.validate()를 수정합니다.
하지만 에이전트는 47개의 함수가 해당 반환 타입에 의존하고 있으며, 3개의 실행 흐름이 이를 통과하고, payment_handler.py가 80%의 확률로 함께 변경된다는 사실을 알지 못합니다.

파괴적 변경(Breaking changes)이 배포됩니다.

이런 일이 발생하는 이유는 AI 에이전트가 평면 텍스트(flat text)로 작업하기 때문입니다. 에이전트는 호출자를 grep으로 찾지만, 간접적인 호출자는 놓치며, 코드가 어떻게 연결되어 있는지 이해하지 못합니다. 컨텍스트 윈도우(Context windows)는 유한합니다. LSP는 호출 그래프(call graphs)를 노출하지 않습니다. Grep은 문자열을 제공할 뿐, 구조를 제공하지 않습니다.

에이전트에게 필요한 것은 더 많은 텍스트가 아니라 **지식 그래프(knowledge graph)**입니다.

대부분의 코드 인텔리전스(code intelligence) 도구는 에이전트에게 원본 파일을 제공하고 에이전트가 충분히 읽기를 기대합니다. Axon은 다른 접근 방식을 취합니다. **인덱싱 시점에 구조를 미리 계산(precompute structure)**하여, 모든 도구 호출이 완전하고 실행 가능한 컨텍스트(context)를 반환하도록 합니다.

12단계 파이프라인이 저장소(repo)에 대해 한 번 실행됩니다. 그 이후에는 다음과 같이 작동합니다:

axon_impact("validate")

단 한 번의 호출로 영향받는 47개의 모든 심볼(symbols)을 깊이(will break / may break / review)별로 그룹화하고 신뢰도 점수(confidence scores)와 함께 반환합니다.

axon_query("auth handler")

단순한 이름 매칭 목록이 아닌, 실행 흐름(execution flow)별로 그룹화된 하이브리드 랭킹(hybrid-ranked) 결과를 반환합니다.

axon_context("UserService")

호출자(callers), 피호출자(callees), 타입 참조(type references), 커뮤니티 멤버십(community membership), 그리고 데드 코드(dead code) 상태를 반환하여 전체적인 그림을 보여줍니다.

세 가지 이점:

신뢰성 (Reliability)— 컨텍스트가 이미 도구 응답에 포함되어 있습니다. 코드를 놓칠 수 있는 다단계 탐색 과정이 필요 없습니다.
토큰 효율성 (Token efficiency)— 10번의 쿼리 검색 체인 대신 단 한 번의 도구 호출로 해결합니다. 에이전트(Agents)는 탐색이 아닌 추론(reasoning)에 토큰을 사용합니다.
모델 민주화 (Model democratization)— 도구가 복잡한 작업을 대신 수행하므로, 더 작은 모델들도 전체적인 아키텍처(architectural) 명확성을 확보할 수 있습니다.

클라우드 의존성 제로 (Zero cloud dependencies). 파싱(parsing), 그래프 저장(graph storage), 임베딩(embeddings), 검색(search) 등 모든 과정이 로컬에서 실행됩니다. API 키가 필요 없으며, 데이터가 기기를 벗어나지 않습니다.

pip install axoniq # 1. 설치
cd your-project && axon analyze . # 2. 인덱싱 (단일 명령, 대부분의 저장소에서 약 5초 소요)
axon ui # 3. localhost:8420에서 시각적으로 탐색

AI 에이전트용 — 프로젝트 루트의 .mcp.json에 다음을 추가하세요:

{
"mcpServers": {
"axon": {
...

개발자용 — 직접 그래프를 탐색하세요:

axon ui # 대화형 대시보드 (독립 실행 또는 실행 중인 호스트에 연결)
axon ui --watch # 파일 변경 시 실시간 리로드 (Live reload)
axon host --watch # 공유 호스트: UI + 멀티 세션 MCP

웹 UI (Web UI)

터미널이나 확장 프로그램이 필요 없는 완전한 대화형 대시보드입니다. 단 하나의 명령으로 실행 가능합니다:

axon ui # localhost:8420에서 실행
axon ui --watch # 파일 변경 시 실시간 리로드
axon ui --port 9000 # 사용자 지정 포트
...

보기 (View)	표시 내용
Explorer (탐색기)	대화형 힘 지향 그래프 (Interactive force-directed graph, Sigma.js + WebGL), 파일 트리 사이드바, 코드 미리보기가 포함된 심볼 상세 패널, 호출자/피호출자 (callers/callees), 영향 분석 (impact analysis), 프로세스 멤버십. 커뮤니티 헐 (Community hull) 오버레이를 통해 아키텍처 클러스터를 확인할 수 있습니다.
Analysis (분석)	상태 점수 (Health score), 결합도 히트맵 (coupling heatmap), 데드 코드 보고서 (dead code report), 상속 트리 시각화, 브랜치 차이 (branch diff), 그리고 종합 통계 — 코드베이스의 상태를 한눈에 파악할 수 있습니다.
Cypher Console (Cypher 콘솔)	구문 강조 (syntax highlighting)가 지원되는 쿼리 에디터, 프리셋 쿼리 라이브러리, 결과 테이블, 그리고 쿼리 히스토리.

기타 기능 (Extras): 커맨드 팔레트 (Cmd+K), 키보드 단축키, 그래프 미니맵, 흐름 추적 (flow trace) 및 영향 파동 (impact ripple) 애니메이션, watch 모드 활성화 시 SSE 기반의 라이브 리로드 (live reload).

UI는 전체 REST API를 갖춘 FastAPI 서버에 의해 구동됩니다 — 아래의 API 엔드포인트 (API Endpoints)를 참조하세요.

하이브리드 검색 (Hybrid Search: BM25 + Vector + Fuzzy)

상호 순위 융합 (Reciprocal Rank Fusion) 기술로 결합된 세 가지 검색 전략:

BM25 전체 텍스트 검색 (full-text search) — KuzuDB FTS를 통한 빠른 정확한 이름 및 키워드 매칭
시맨틱 벡터 검색 (Semantic vector search) — 384차원 임베딩 (BAAI/bge-small-en-v1.5)을 통한 개념적 쿼리
퍼지 이름 검색 (Fuzzy name search) — 오타 및 부분 일치를 위한 레벤슈타인 (Levenshtein) 폴백

결과는 테스트 파일의 순위를 낮추고 (0.5x), 소스 함수/클래스의 순위를 높이는 (1.2x) 방식으로 정렬된 후, 실행 흐름 (execution flow)별로 그룹화되어 에이전트가 단 한 번의 호출로 아키텍처 맥락을 파악할 수 있게 합니다.

깊이 그룹화 기반 영향 분석 (Impact Analysis with Depth Grouping)

심볼을 변경하려는 순간, Axon은 호출 그래프 (call graph), 타입 참조 (type references), 그리고 git 결합 이력 (git coupling history)을 통해 상위 호출 경로를 추적합니다. 결과는 실행 가능성을 높이기 위해 깊이별로 그룹화됩니다:

Depth 1 — 직접적인 호출자 (반드시 깨짐)
Depth 2 — 간접적인 호출자 (깨질 수 있음)
Depth 3+ — 전이적 호출자 (검토 필요)

모든 엣지 (edge)에는 신뢰도 점수 (1.0 = 정확한 일치, 0.8 = 수신 메서드, 0.5 = 퍼지 매칭)가 부여되어 검토 우선순위를 정할 수 있습니다.

데드 코드 탐지 (Dead Code Detection)

단순히 "호출자가 0명"인 것을 찾는 것이 아니라, 사용 중인 프레임워크를 이해하는 다회차 분석 (multi-pass analysis)을 수행합니다:

초기 스캔 (Initial scan)— 호출이 없는 심볼 (symbols)을 플래그 처리합니다.
예외 사항 (Exemptions)— 엔트리 포인트 (entry points), 내보내기 (exports), 생성자 (constructors), 테스트 코드, 던더 메서드 (dunder methods), __init__.py 심볼, 데코레이터가 적용된 함수 (decorated functions), @property 메서드
오버라이드 패스 (Override pass)— 데드 코드(dead code)가 아닌 베이스 클래스의 메서드를 오버라이드하는 메서드의 플래그를 해제합니다.
프로토콜 준수 (Protocol conformance)— 프로토콜을 준수하는 클래스의 메서드 플래그를 해제합니다.
프로토콜 스텁 (Protocol stubs)— 프로토콜 클래스의 모든 메서드(인터페이스 계약) 플래그를 해제합니다.

실행 흐름 추적 (Execution Flow Tracing)

프레임워크를 인식하는 패턴을 사용하여 엔트리 포인트를 감지합니다:

Python: @app.route, @router.get, @click.command, test_* 함수, __main__ 블록
JavaScript/TypeScript: Express 핸들러, 내보내진 함수 (exported functions), handler / middleware 패턴

그 다음, 각 엔트리 포인트로부터 호출 그래프 (call graph)를 통해 BFS 실행 흐름을 추적하며, 흐름을 커뮤니티 내부 (intra-community) 또는 커뮤니티 간 (cross-community)으로 분류합니다.

커뮤니티 탐지 (Community Detection)

Leiden 알고리즘 (igraph + leidenalg)을 사용하여 기능적 클러스터 (functional clusters)를 자동으로 발견합니다. 각 커뮤니티에는 응집도 점수 (cohesion score)와 자동 생성된 레이블이 부여됩니다. 에이전트는 단 하나의 설계 문서도 읽지 않고도 "이 심볼은 어떤 클러스터에 속해 있나요?"라고 질문하고 답을 얻을 수 있습니다.

Git이 알고 있는 숨겨진 의존성 찾기

변경 결합도 (Change Coupling (Git History))

정적 분석 (static analysis)이 놓치는 의존성을 찾기 위해 6개월간의 git 히스토리를 분석합니다:

coupling(A, B) = co_changes(A, B) / max(changes(A), changes(B))

결합 강도 (coupling strength)가 0.3 이상이고 3회 이상의 공동 변경 (co-changes)이 발생한 파일들은 서로 연결됩니다. 이는 영향 분석 (impact analysis) 시 나타납니다. 즉, user.py를 변경할 때 에이전트는 user_test.py와 auth_middleware.py도 확인해야 함을 알게 됩니다.

워치 모드 (Watch Mode)

Rust 기반 파일 와처 (watchfiles)를 통해 실시간 재인덱싱 (re-indexing)을 지원합니다:

$ axon watch
Watching /Users/you/project for changes...
[10:32:15] src/auth/validate.py modified -> re-indexed (0.3s)
...

파일 로컬 단계 (parse, imports, calls, types)는 변경 즉시 실행됩니다. 글로벌 단계 (communities, processes, dead code)는 30초마다 배치 (batch)로 실행됩니다.

브랜치 비교 (Branch Comparison)

git worktree를 사용하여 심볼(symbol) 수준에서 브랜치를 비교합니다 (stashing이 필요하지 않습니다):

$ axon diff main..feature
Symbols added (4):
+ process_payment (Function) -- src/payments/stripe.py
...

노이즈 필터링 (Noise Filtering)

내장된 블랙리스트(138개 항목)가 호출 그래프(call graph)에서 언어 내장 함수(print, len, isinstance), JS/TS 전역 변수(console, setTimeout, fetch), React 훅(useState, useEffect), 그리고 일반적인 표준 라이브러리(stdlib) 메서드들을 자동으로 필터링합니다. 여러분의 그래프는 list.append()와 같은 노이즈가 아닌, 여러분의 코드 간의 관계를 보여줍니다.

Axon은 12단계의 순차적 분석 단계를 통해 깊은 구조적 이해를 구축합니다:

단계	수행 내용
파일 탐색 (File Walking)	.gitignore를 준수하며 리포지토리를 탐색하고, 지원되는 언어로 필터링함
구조 (Structure)	CONTAINS 관계를 가진 파일/폴더 계층 구조를 생성함
파싱 (Parsing)	tree-sitter AST 추출 — 함수, 클래스, 메서드, 인터페이스, 열거형(enum), 타입 별칭(type alias)
임포트 해결 (Import Resolution)	임포트 문을 실제 파일로 해결 (상대 경로, 절대 경로, bare specifier)
호출 추적 (Call Tracing)	신뢰도 점수와 함께 함수 호출을 매핑. 노이즈 필터링을 통해 138개의 언어 내장 함수를 건너뜀
상속 (Heritage)	클래스 상속 (EXTENDS) 및 인터페이스 구현 (IMPLEMENTS)을 추적함
타입 분석 (Type Analysis)	매개변수, 반환 타입, 변수 어노테이션에서 타입 참조를 추출함
커뮤니티 탐지 (Community Detection)	Leiden 알고리즘을 사용하여 관련 심볼들을 기능적 커뮤니티로 클러스터링함
프로세스 탐지 (Process Detection)	프레임워크를 인식하는 엔트리 포인트 탐지 + BFS 흐름 추적
데드 코드 탐지 (Dead Code Detection)	오버라이드(override), 프로토콜(protocol), 데코레이터(decorator)를 인식하는 다중 패스 분석
변경 결합도 (Change Coupling)	Git 히스토리 분석 — 항상 함께 변경되는 파일들을 찾아냄
임베딩 (Embeddings)	모든 심볼에 대해 384차원 벡터를 생성하여 의미론적 검색(semantic search)을 가능하게 함. --no-embeddings로 건너뛸 수 있음

Axon은 자신의 모든 지능을 MCP 서버로 노출합니다. 한 번 설정해 두면, 여러분의 AI 에이전트는 영구적으로 코드베이스에 대한 구조적 이해를 갖게 됩니다.

Claude Code — .mcp.json에 추가하세요

프로젝트 루트에 (또는 claude mcp add axon -- axon serve --watch를 실행하세요):

{
"mcpServers": {
"axon": {
...

Cursor — MCP 설정에 추가하세요:

{
"axon": {
"command": "axon",
...

선택 사항인 새로운 기능:

axon host --watch

이 명령은 UI와 여러 MCP 클라이언트를 위한 공유 호스트를 시작합니다. axon setup --claude / axon setup --cursor는 여전히 표준 설정을 출력합니다.

--watch 플래그는 실시간 재인덱싱 (live re-indexing)을 활성화하여, 코드를 수정함에 따라 그래프가 업데이트됩니다.

도구	에이전트가 얻는 정보
axon_query	실행 흐름별로 그룹화된 결과가 포함된 하이브리드 검색 (BM25 + 벡터 + 퍼지 검색)
axon_context	360도 뷰 — 호출자 (callers), 피호출자 (callees), 타입 참조 (type refs), 신뢰도 태그 (confidence tags), 데드 코드 상태
axon_impact	깊이별로 그룹화된 영향 범위 (Blast radius) — 직접적 (파손됨), 간접적 (파손될 수 있음), 전이적 (transitive)
axon_dead_code	파일별로 그룹화된 모든 도달 불가능한 심볼 (unreachable symbols)
axon_detect_changes	git diff를 영향을 받는 심볼 및 실행 흐름으로 매핑
axon_list_repos	통계가 포함된 모든 인덱싱된 저장소
axon_cypher	지식 그래프에 대한 읽기 전용 Cypher 쿼리

모든 도구 응답에는 에이전트가 자연스러운 조사 워크플로우를 따를 수 있도록 안내하는 **다음 단계 힌트 (next-step hint)**가 포함됩니다:

query -> "다음 단계: 전체 그림을 보려면 특정 심볼에 대해 context()를 사용하세요."
context -> "다음 단계: 이 심볼에 대한 변경을 계획 중이라면 impact()를 사용하세요."
impact -> "팁: 변경을 수행하기 전에 영향을 받는 각 심볼을 검토하세요."

URI	설명
axon://overview	유형별 노드 및 관계 수
axon://dead-code	전체 데드 코드 보고서
axon://schema	Cypher 쿼리를 위한 그래프 스키마 (schema) 참조

웹 UI는 FastAPI 서버를 기반으로 합니다. 모든 엔드포인트는 /api 하위에 있습니다:

엔드포인트 (Endpoint)	설명 (Description)
GET /api/graph	전체 지식 그래프 (페이지네이션 적용)
GET /api/node/{id}	호출자 (callers), 피호출자 (callees), 타입 참조 (type refs)를 포함한 노드 상세 정보
GET /api/overview	노드/엣지 (node/edge) 수의 집계 데이터
GET /api/search	하이브리드 검색 (BM25 + 벡터 (vector) + 퍼지 (fuzzy))
GET /api/impact/{id}	깊이 (depth)별 영향 범위 (blast radius) 분석
GET /api/dead-code	데드 코드 (dead code) 보고서
GET /api/communities	멤버를 포함한 커뮤니티 목록
GET /api/coupling	변경 결합도 (change coupling) 히트맵 데이터
GET /api/files/{path}	구문 컨텍스트 (syntax context)를 포함한 소스 파일 내용
POST /api/cypher	읽기 전용 Cypher 쿼리 실행
GET /api/diff	구조적 브랜치 비교
GET /api/processes	실행 흐름 (execution flow) 목록
GET /api/events	라이브 리로드 (live reload) 이벤트를 위한 SSE 스트림
POST /api/reindex	전체 재인덱싱 (re-index) 트리거 (watch 모드 전용)

Cypher 쿼리는 서버 측에서 검증됩니다. 주석을 제거한 후 쓰기 키워드 (CREATE, DELETE, DROP 등)가 발견되면 거부됩니다.