200,000줄 코드베이스를 클릭 가능한 지식 그래프로 바꾸는 Claude Code 플러그인

새 팀, 200,000줄 코드. 어디서 시작하겠습니까?

새 프로젝트에 합류했을 때 가장 많이 드는 생각은 '파일 구조를 먼저 볼까, README를 먼저 읽을까'입니다. 어느 쪽이든 코드를 선형으로 읽는다는 점은 같습니다. 파일 하나, 함수 하나, 의존성 하나씩 머릿속에 쌓아가는 방식이죠. 그 과정이 얼마나 걸리는지는 코드베이스 규모가 말해줍니다. Understand-Anything은 그 과정을 뒤집습니다. 코드를 읽는 대신, 먼저 전체 지형을 봅니다.

---

이 도구가 푸는 문제

대부분의 코드 탐색은 두 가지 문제를 안고 있습니다.

첫째, 출발점이 없습니다. 어떤 파일이 핵심이고 어떤 파일이 유틸인지, 어느 함수가 어디서 불리는지, 레이어가 어떻게 나뉘는지를 직접 읽기 전까지 알 수 없습니다.

둘째, 변경 영향 범위가 보이지 않습니다. 결제 모듈 한 줄을 바꿀 때 알림 서비스나 로그 레이어가 함께 영향받는지를 확인하려면 의존성을 따라 여러 파일을 열어야 합니다.

Understand-Anything은 멀티에이전트 파이프라인으로 프로젝트를 스캔하고, 모든 파일·함수·클래스·의존성을 노드와 엣지로 연결한 지식 그래프를 빌드합니다. 그 결과를 인터랙티브 대시보드로 열어 클릭, 검색, 탐색할 수 있게 합니다.

---

핵심 동작 원리

내부 구조는 Tree-sitter와 LLM의 역할 분리로 설계돼 있습니다.

Tree-sitter(결정론적) 는 소스를 파싱해 임포트, 익스포트, 함수·클래스 정의, 콜 사이트, 상속 관계를 추출합니다. 같은 코드 입력이면 항상 같은 엣지가 나옵니다. 증분 업데이트를 위한 핑거프린트 기반 변경 감지도 여기서 담당합니다.

LLM(의미론적) 은 파서가 할 수 없는 부분을 맡습니다. 파일이 '무엇을 위한 것인지', 아키텍처 레이어 분류, 비즈니스 도메인 매핑, 가이드 투어 생성 등이 여기에 해당합니다.

파이프라인은 6개의 전문화된 에이전트로 구성됩니다.

에이전트	역할
project-scanner	파일 탐색, 언어·프레임워크 감지
file-analyzer	함수·클래스·임포트 추출, 그래프 노드·엣지 생성
architecture-analyzer	아키텍처 레이어 식별
tour-builder	가이드 학습 투어 생성
graph-reviewer	그래프 완전성·참조 무결성 검증
domain-analyzer	비즈니스 도메인·플로우·프로세스 스텝 추출

file-analyzer는 최대 5개 동시, 배치당 20-30개 파일을 병렬 처리합니다.

---

설치 및 시작

Claude Code에서는 플러그인 마켓플레이스로 바로 설치합니다.

/plugin marketplace add Lum1104/Understand-Anything
/plugin install understand-anything

설치 후 프로젝트 루트에서 분석을 실행합니다.

/understand

멀티에이전트 파이프라인이 프로젝트를 스캔하고 .understand-anything/knowledge-graph.json에 그래프를 저장합니다. 이후 대시보드를 엽니다.

/understand-dashboard

아키텍처 레이어별로 색이 분류된 인터랙티브 그래프가 열립니다. 노드를 클릭하면 해당 코드와 관계, 평문 설명을 볼 수 있습니다.

---

실전 사용 시나리오

온보딩 시나리오: 결제 플로우가 어떻게 동작하는지 빠르게 파악해야 할 때.

/understand-chat How does the payment flow work?

그래프 전체를 검색하는 시맨틱 검색으로 관련 노드와 관계를 바로 찾아줍니다. 'auth 처리하는 부분이 어딘가?'처럼 자연어로 물을 수 있습니다.

변경 영향 분석: 현재 수정 중인 코드가 시스템 어느 부분에 영향을 주는지 커밋 전에 확인합니다.

/understand-diff

변경된 파일과 연결된 노드들을 오버레이로 보여줘서 리플 이펙트를 사전에 파악할 수 있습니다.

팀 공유: 그래프는 JSON 파일입니다. .understand-anything/ 폴더를 커밋하면 팀원은 파이프라인 재실행 없이 동일한 그래프를 바로 사용할 수 있습니다.

# .gitignore에 추가
.understand-anything/intermediate/
.understand-anything/diff-overlay.json

---

언제 쓰면 안 되는가 / 트레이드오프

• 소규모 프로젝트(1,000줄 미만): 파이프라인 초기 스캔 시간 대비 얻는 이득이 작을 수 있습니다. 직접 파일을 여는 게 빠를 수 있습니다.
• 그래프 크기: 큰 모노레포의 경우 .understand-anything/*.json이 10MB를 넘을 수 있습니다. 이 경우 git-lfs가 필요합니다.
• LLM 의존: 레이어 분류와 도메인 매핑은 LLM이 담당하므로 동일 코드라도 모델 변경 시 의미론적 결과가 달라질 수 있습니다. 구조적 엣지(Tree-sitter 파트)는 재현 가능하지만 시맨틱 파트는 그렇지 않습니다.
• 온라인 연결 필요: LLM 에이전트가 파일을 분석하므로 오프라인 환경에서는 동작하지 않습니다.

---

같은 카테고리 대안 비교

Codeium / GitHub Copilot Chat: 코드 질문에 답하는 데는 강하지만 전체 그래프를 시각화하거나 레이어 구조를 대시보드로 보여주지는 않습니다. 탐색보다 질의응답에 가깝습니다.

CodeSee (서비스 종료): 비슷한 코드맵 개념이었지만 SaaS 의존 모델이었습니다. Understand-Anything은 로컬 JSON으로 그래프를 생성하고 팀이 자체 관리할 수 있습니다.

Understand-Anything의 차별점은 팀 공유 가능한 커밋 가능 JSON 그래프와 비즈니스 도메인 뷰입니다. 개인 탐색 도구가 아니라 팀 온보딩과 PR 리뷰 워크플로에 통합할 수 있는 구조입니다.

---

자주 묻는 질문

코드베이스를 지식 그래프로 바꾸는 플러그인은 언제 쓰는 게 좋을까?

먼저 되돌릴 수 있는 작은 입력으로 시험하고, 출력이 기대와 맞는지 확인한 뒤 실제 워크플로에 붙이는 편이 안전하다.

코드베이스를 지식 그래프로 바꾸는 플러그인을 적용하기 전에 무엇을 확인해야 할까?

먼저 되돌릴 수 있는 작은 입력으로 시험하고, 출력이 기대와 맞는지 확인한 뒤 실제 워크플로에 붙이는 편이 안전하다.

결과가 제대로 나왔는지 어떻게 검증할까?

먼저 되돌릴 수 있는 작은 입력으로 시험하고, 출력이 기대와 맞는지 확인한 뒤 실제 워크플로에 붙이는 편이 안전하다.

마무리

Understand-Anything이 흥미로운 이유는 '그래프가 예쁘다'가 아닙니다. 코드베이스의 복잡함을 과시하는 그래프가 아니라, 모든 조각이 어떻게 맞는지 조용히 가르쳐주는 그래프를 목표로 한다는 점입니다.

낯선 레포를 빠르게 파악해야 하거나, 온보딩 문서를 별도로 만들기 어려운 팀이라면 /understand --auto-update로 커밋마다 그래프를 자동 갱신하는 워크플로가 실용적입니다./understand-onboard로 신규 팀원용 온보딩 가이드를 자동 생성하는 조합도 체크해볼 만합니다.

---

🐦 X에서 더 빠르게: @baegseungh7061
📚 이 시리즈 더 보기: AI 인사이트
💌 새 글 알림: X 팔로우 또는 블로그 RSS 구독