Understand Anything 딥다이브
— 코드베이스를 클릭 가능한 "지식 그래프"로 바꾸는 멀티에이전트 플러그인

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

Understand Anything은 코드 이해(code comprehension) 계열의 개발자 도구다. Claude Code 플러그인으로 시작했지만 지금은 Cursor · VS Code Copilot · Codex · Gemini CLI · OpenCode 등 17개 플랫폼에서 동작한다. /understand로 그래프를 만들고, /understand-dashboard로 시각화하며, /understand-chat·/understand-diff·/understand-explain·/understand-onboard·/understand-domain·/understand-knowledge 같은 명령으로 질의·영향분석·온보딩 문서까지 뽑는다.

2왜 주목받는가

트렌딩 이유 · 단순 "AI에게 물어보기"와의 차이.

요즘은 코드를 모르면 그냥 AI에게 물어보면 된다고들 한다. 그런데 LLM에게 "이 코드베이스 설명해줘"라고 하면 매번 답이 다르고, 큰 레포는 컨텍스트에 다 안 들어가며, 환각으로 없는 함수를 지어낸다. Understand Anything이 주목받는 이유는 이 세 약점을 정면으로 푼다는 데 있다 — ① tree-sitter로 구조를 결정적으로 추출(같은 코드 → 같은 그래프), ② 한 번 만든 그래프를 JSON으로 커밋·공유(매번 재분석 불필요), ③ 증분 분석(바뀐 파일만 다시 본다).

3기술 스택 전체 지도

분석 엔진(코어)·대시보드(프론트)·플러그인/인프라 각각.

① 분석 엔진 (코어) — @understand-anything/core

전부 TypeScript(strict 모드) + ESM으로 짜였고, Node.js 22+에서 돈다. 코어는 브라우저(대시보드)에서도 일부 모듈을 재사용하기 위해 ./search·./types·./schema 같은 서브패스 export로 잘게 나뉘어, Node 전용 모듈이 브라우저 번들에 딸려 들어가지 않게 막는다.

② 대시보드 (프론트엔드) — @understand-anything/dashboard

③ 플러그인 · 멀티플랫폼 · 인프라

4아키텍처 심화 분석

코드 → 7단계 멀티에이전트 파이프라인 → 지식 그래프 JSON → 대시보드.

전체 흐름 한눈에

입력은 코드베이스(디렉토리). /understand가 7단계 파이프라인을 오케스트레이션한다. 먼저 스캐너가 파일·언어·프레임워크를 찾고, 파일 분석가가 배치 단위(20~30개)로 병렬 실행되며 각 파일에서 tree-sitter로 구조를 뽑고 LLM으로 요약·태그를 붙인다. 이어 아키텍처 분석가가 계층을 식별하고, 투어 작성가가 의존성 순서대로 학습 투어를 만들며, 검수가가 그래프 무결성을 검증한 뒤, 모든 조각을 합쳐 knowledge-graph.json으로 영속화한다. 마지막에 자동으로 /understand-dashboard가 떠 그래프를 시각화한다.

21종 노드 · 35종 엣지 — 풍부한 그래프 스키마

이 도구의 표현력은 노드 타입 21종, 엣지 타입 35종이라는 풍부한 스키마에서 나온다(core/src/types.ts). 코드뿐 아니라 설정·문서·서비스·테이블·엔드포인트, 나아가 비즈니스 도메인과 위키 지식까지 같은 그래프 안에 표현한다.

export interface GraphNode {
  id: string;
  type: NodeType;          // 21종 중 하나
  name: string;
  filePath?: string;
  lineRange?: [number, number];
  summary: string;         // ← LLM이 채우는 "평이한 설명"
  tags: string[];          // ← LLM 태그
  complexity: "simple" | "moderate" | "complex";
  languageNotes?: string;  // ← 이 노드에 쓰인 언어 개념(제네릭·클로저 등)
  domainMeta?: DomainMeta;
  knowledgeMeta?: KnowledgeMeta;
}

핵심 설계 패턴

5디렉토리 구조 해부

pnpm 모노레포 — 플러그인 안에 core·dashboard·skills·agents가 모두 있다.

6학습 포인트 (기술별)

개발자 도구·LLM 오케스트레이션·그래프 시각화에서 무엇을 배우나.

A. tree-sitter + LLM 하이브리드 — "결정적 + 의미적"의 분업

가장 큰 배울 점은 "무엇을 코드(결정적)로 두고, 무엇을 LLM(확률적)에 맡길지"의 경계 설계다. 구조적 사실은 매번 같아야 하므로 tree-sitter로, "이게 무슨 의도냐"는 본질적으로 해석이라 LLM으로 나눴다. 이 분업 덕에 그래프가 재현 가능하면서도 풍부하다. 이는 RAG·코드 인덱싱·문서 처리 등 "정확성과 유연성을 동시에 원하는 모든 LLM 시스템"에 옮겨 쓸 수 있는 원칙이다.

B. 멀티에이전트 오케스트레이션 — 역할 분담과 중간 결과 격리

9종 에이전트가 릴레이로 일하되, 중간 결과를 컨텍스트로 되돌리지 않고 intermediate/ 디스크에 쓴다는 점이 핵심이다. 큰 코드베이스를 한 컨텍스트에 다 넣을 수 없으니, 파일을 배치(20~30개)로 쪼개 동시 5개 병렬 처리하고 결과만 모은다. "에이전트 = 컨텍스트 윈도우의 분할 정복"이라는 패턴을 실물로 보여 준다.

C. 모노레포 + 브라우저/Node 경계 관리

같은 core 코드를 Node(CLI 분석기)와 브라우저(대시보드)가 함께 쓰는데, Node 전용 모듈(fs 등)이 브라우저 번들에 새면 빌드가 깨진다. 해법은 ./search·./types·./schema 같은 서브패스 export로 브라우저-안전 표면만 노출하는 것. pnpm 워크스페이스에서 패키지 경계를 어떻게 설계하는지 배울 수 있다.

D. 그래프 시각화 — React Flow + 레이아웃·클러스터링

수천 노드를 그냥 뿌리면 "털뭉치(hairball)"가 된다. 이 레포는 elkjs·dagre·d3-force 3종 레이아웃과 graphology의 Louvain 커뮤니티 검출로 연관 노드를 군집화하고, 계층별 색상·엣지 집계(aggregation)로 시각 복잡도를 낮춘다. "대규모 그래프를 사람이 읽게 만드는" 정보 시각화의 정석이다.

7시스템 / 환경 요구사항

설치는 가볍지만, "LLM 코딩 에이전트"가 전제다.

8직접 해볼 수 있는 실습 과제

난이도별 5단계 — 사용부터 내부 엔진 모방까지.

9관련 기술 심화 학습 로드맵

6주 코스 — 구문 분석부터 멀티에이전트·그래프 시각화까지.

10핵심 키워드 사전

본문·소스에 나온 용어 빠른 참조.

11참고 링크

• GitHub: Egonex-AI/Understand-Anything
• 홈페이지 · 라이브 데모: understand-anything.com · /demo
• 원작(전신): Lum1104/Understand-Anything (Yuxiang Lin)
• Claude Code 플러그인 문서: plugins-reference
• tree-sitter: 공식 문서 · web-tree-sitter
• React Flow: @xyflow/react · 레이아웃: elkjs
• 참고 그래프 예제: microservices-demo (커밋된 그래프 포함)