가르치는 그래프: Understand-Anything이 코드베이스를 인터랙티브 지도로 만드는 방법

저는 새로운 직장에서의 첫날을 여전히 기억합니다. 코드베이스는 제가 한 번도 본 적 없는 마이크로서비스 아키텍처 (microservices architecture)에 걸쳐 20만 줄에 달했습니다. 매니저는 "일주일 동안 익숙해지는 시간을 가지세요"라고 말했습니다. 저는 그 시간의 대부분을 grep 결과와 IDE 탭 속에 빠져 허우적거리며 보냈습니다.

대부분의 코드 시각화 도구들은 당신에게 깊은 인상을 주려고 노력합니다. 그들은 데모에서는 멋져 보이지만, 실제로 무언가를 이해해야 할 때는 당신을 압도해 버리는 수백 개의 노드 (nodes)를 가진 복잡한 그래프를 생성합니다.

그것이 바로 LLM 멀티 에이전트 협업 (LLM multi-agent collaboration)을 연구하는 Georgia Tech의 연구원 Lum1104가 해결하고자 했던 문제입니다. 그의 프로젝트 슬로건은 노골적입니다: "인상을 주는 그래프보다 가르치는 그래프가 낫다 (Graphs that teach > graphs that impress)."

문제점: 인간이 아닌 AI를 위한 코드 지도

최근 많은 지식 그래프 (knowledge graph) 도구들을 보았습니다. 많은 도구들이 AI 에이전트가 코드를 탐색할 수 있도록 구축되었습니다. 즉, 에이전트가 더 나은 응답을 생성하거나 패치 (patches)를 작성할 수 있도록 구조화된 컨텍스트 (context)를 제공하는 것입니다.

하지만 인간은 다릅니다. 새로운 팀에 합류했을 때, 당신에게 필요한 것은 완벽한 그래프가 아닙니다. 당신에게 필요한 것은 이야기 (story) 입니다. 이 API 라우트 (API route)가 저 데이터베이스 호출 (database call)과 어떻게 연결되는가? 결제 흐름 (payment flow)의 진입점 (entry point)은 무엇인가? 하는 것들 말이죠.

기존 도구들은 당신이 탐정 놀이를 하게 만듭니다. 파일을 열고, 임포트 (import)를 따라가고, 정의 (definition)로 점프하고, 이를 반복하는 식입니다. 모든 질문은 시간과 정신적 에너지를 소모합니다.

철학: 한 번 스캔하고, 여러 번 재사용하라

Understand-Anything (GitHub: Lum1104/Understand-Anything, 45.9k stars)은 이 모델을 뒤집습니다. 모든 질문마다 LLM이 소스 파일을 다시 읽게 하여 토큰 (tokens)과 컨텍스트 (context)를 낭비하는 대신, 프로젝트 전체를 단일 JSON 지식 그래프 (knowledge graph)로 압축합니다.

단 한 번만. 처음에 말이죠.

이후의 모든 상호작용은 원본 소스 코드 (raw source code) 대신 이 미리 구축된 그래프를 쿼리합니다. 유사한 프로젝트인 code-review-graph는 리뷰 작업에서 6.8배의 토큰을 절약하고, 일상적인 코딩에서는 49배를 절약했다고 보고했습니다. 이는 단순한 효율성의 문제가 아닙니다. 코드 이해 (code comprehension)에 대해 근본적으로 다르게 생각하는 방식입니다.

작동 원리: 두 세계의 장점 결합

이 아키텍처 (architecture)는 진정으로 우아합니다. 하이브리드 접근 방식 (hybrid approach)을 사용합니다:

Tree-sitter (결정론적, deterministic): 소스 코드를 구체 구문 트리 (concrete syntax trees)로 파싱 (parse)합니다. 매번 동일한 입력에 대해 동일한 출력을 보장합니다. 이를 통해 임포트 (imports), 엑스포트 (exports), 함수/클래스 정의 (function/class definitions), 호출 지점 (call sites), 상속 (inheritance)과 같은 구조적 사실을 추출합니다. 또한 증분 업데이트 (incremental updates)를 위한 지문 기반 변경 감지 (fingerprint-based change detection)를 가능하게 합니다.

LLM (의미론적, semantic): 파싱된 구조를 원본 소스 코드와 함께 읽어 평이한 영어 요약, 태그, 아키텍처 계층 할당, 비즈니스 도메인 매핑 (business-domain mapping), 그리고 가이드 투어 (guided tours)를 생성합니다.

그 결과는 재현 가능하면서도 똑똑합니다. 구조적인 측면은 예상치 않게 변하지 않지만, 의미론적인 측면은 사용자의 특정 코드베이스 (codebase)에 맞춰 적응합니다.

멀티 에이전트 파이프라인 (The Multi-Agent Pipeline)

배후에서는 6~7개의 특화된 에이전트 (agents)가 협업합니다:

에이전트	역할
project-scanner	파일 발견, 언어 및 프레임워크 감지
...

파일 분석기 (File analyzers)는 병렬로 실행되며, 최대 5개가 동시에 작동하여 배치 (batch)당 20~30개의 파일을 처리합니다. 또한 증분 방식 (incremental)이기 때문에 변경된 파일만 다시 분석됩니다.

차별점

핵심 지식 그래프 (knowledge graph) 외에도 세 가지 기능이 특히 눈에 띄었습니다:

1. 가이드형 온보딩 투어 (Guided Onboarding Tours)

/understand-onboard 명령은 의존성 (dependency) 순서에 따라 아키텍처를 훑어볼 수 있는 워크스루 (walkthrough)를 생성합니다. 새로운 팀원들은 단순히 그래프를 받는 것이 아니라, 그 안을 관통하는 '경로'를 얻게 됩니다.

2. Diff 영향 분석 (Diff Impact Analysis)

변경 사항을 적용한 후 무엇을 망가뜨렸을지 궁금했던 적이 있나요? /understand-diff는 사용자의 git diff를 지식 그래프에 매핑하여 시스템의 정확히 어느 부분이 영향을 받는지 보여줍니다. 이는 마치 아키텍처 측면의 사후 통찰력을 갖는 것과 같습니다.

3. 비즈니스 도메인 뷰 (Business Domain View)

모든 것이 기술적인 것만은 아닙니다. /understand-domain은 비즈니스 도메인 (Business Domains), 흐름 (Flows), 그리고 단계 (Steps)를 추출하여 코드가 실제 비즈니스 프로세스에 어떻게 매핑되는지를 보여줍니다. 마케팅 팀은 마침내 엔지니어링 팀을 이해할 수 있는 가교를 갖게 됩니다.

플랫폼 지원 (Platform Support)

Understand-Anything은 17개의 플랫폼을 지원합니다: Claude Code (네이티브 플러그인), Cursor, VS Code + GitHub Copilot, Copilot CLI, Codex, OpenCode, OpenClaw, Antigravity, Gemini CLI, Pi Agent, Vibe CLI, Hermes, Cline, KIMI CLI, Trae.

설치는 놀라울 정도로 간단합니다:

# For Claude Code
/plugin marketplace add Lum1104/Understand-Anything
/plugin install understand-anything
...

이것이 아닌 것 (What It's Not)

이 점이 중요합니다. Understand-Anything은 당신을 대신해 코드를 작성해주지 않습니다. 이것은 코드 생성기 (Code Generator)가 아닙니다. 이것은 이해 (Comprehension) 도구입니다.

만약 당신이 모놀리스 (Monolith)를 자동으로 리팩터링 (Refactor)하거나 새로운 기능을 생성해 줄 무언가를 찾고 있다면, 다른 곳을 찾아보십시오. 하지만 당신이 첫 출근 날이든 혹은 천 번째 출근 날이든 상관없이 코드베이스 (Codebase)를 이해해야 한다면, 이 도구는 게임의 판도를 바꿀 것입니다.

더 큰 그림 (The Bigger Picture)

"한 번 스캔하고, 여러 번 재사용한다"는 철학은 앞으로 우리가 더 많이 보게 될 패턴처럼 느껴집니다. 코드베이스가 성장하고 AI 코딩 어시스턴트 (AI Coding Assistants)가 표준이 됨에 따라, 병목 현상은 코드를 _작성하는 것_에서 코드를 _이해하는 것_으로 이동합니다.

Understand-Anything과 같은 도구는 인간의 판단을 대체하는 것이 아니라, 이를 증강 (Augment)합니다. 이 도구는 당신이 더 나은 결정을 더 빠르게 내릴 수 있도록 컨텍스트 (Context)를 제공합니다.

그리고 우리 모두가 점점 더 자신이 작성하지 않은 코드와 함께 일하게 되는 세상에서, 이것은 단순히 유용한 수준이 아닙니다. 필수적입니다.

시도해보기: github.com/Lum1104/Understand-Anything

라이선스 (License): MIT

최신 버전: v2.7.3 (2026년 5월)