2개월 만에 별 46,000개 달성: 모든 코드베이스를 시각적 지식 그래프로 변환하는 오픈 소스 도구

요약: Understand-Anything는 모든 코드베이스, 지식 베이스(Knowledge Base) 또는 문서를 탐색, 검색 및 질문이 가능한 대화형 지식 그래프(Knowledge Graph)로 변환하는 오픈 소스 CLI 도구(46K★, MIT 라이선스)입니다. 이 도구는 멀티 에이전트 파이프라인(Multi-agent pipeline)을 사용하여 모든 파일, 함수, 클래스 및 의존성(Dependency)을 매핑한 다음, 가이드 투어, 의미론적 검색(Semantic search) 및 차이 영향 분석(Diff impact analysis) 기능이 포함된 시각적 대시보드를 제공합니다. 단 하나의 명령과 5분이면, 더 이상 코드의 내용을 모른 채 무작정 읽는 일을 멈출 수 있습니다.

이해합니다. 당신은 방금 새로운 팀에 합류했습니다. 코드베이스는 1,500개의 파일에 걸쳐 200,000줄에 달하며, 당신이 거의 알지 못하는 스택—Rust 백엔드, React 프론트엔드, 커스텀 ORM, 그리고 세 가지의 서로 다른 빌드 시스템—으로 구성되어 있습니다.

도대체 어디서부터 시작해야 할까요?

저도 그런 경험이 있습니다. 실제로 작년에 두 번이나 그랬죠. 첫 번째 때는 아무런 순서 없이 파일을 읽으며 2주를 보냈고, 머릿속에 그린 지도는 계속해서 무너져 내렸습니다. 두 번째 때는 디렉토리 트리 전체를 출력하여 탐정의 코르크 게시판처럼 벽에 붙여 놓았습니다.

그러다 Understand-Anything를 발견했고, 그 이후로는

1. Scout Agent — 프로젝트를 빠르게 훑으며 진입점(entry points), 설정 파일(config files), 그리고 최상위 구조를 식별합니다.
2. Parser Agent — 임포트(imports), 엑스포트(exports), 함수 시그니처(function signatures), 그리고 클래스 계층 구조(class hierarchies)를 분석합니다.
3. Entity Agent — 함수, 클래스, 인터페이스, 타입 등 모든 명명된 엔티티(named entity)를 추출합니다.
4. Relationship Agent — 점들을 연결합니다: 누가 누구를 호출하는지, 어떤 모듈이 무엇에 의존하는지를 파악합니다.
5. Summarizer Agent — 모든 노드(node)에 대해 쉬운 영어(plain-English) 설명을 작성합니다.
6. Guide Agent — 의존성 순서(dependency order)에 따라 노드를 정렬하여 가이드 투어를 생성합니다.

전체 프로세스는 중간 규모의 프로젝트 기준으로 약 3~7분이 소요됩니다.

차별점

저는 거의 모든 코드 시각화 도구를 사용해 보았습니다. 이 도구가 실제로 계속 손이 가는 이유는 다음과 같습니다:

매우 간단한 설정

claude /plugin marketplace add Lum1104/Understand-Anything

또는 단 한 줄의 npx 명령어로 가능합니다. 데이터베이스도, Docker도, 클라우드 서비스도 필요 없습니다.

오프라인 작동
모든 분석은 로컬(locally)에서 이루어집니다. 여러분의 코드는 절대 기기를 벗어나지 않습니다.

사용할수록 향상됨
지식 그래프(knowledge graph)는 사용자의 탐색 패턴을 기억하며, 시간이 지날수록 관련 노드를 더 빠르게 노출합니다.

코드에만 국한되지 않음
문서(documentation), 위키 리포지토리(wiki repos), 또는 설계 사양서(design specs)를 대상으로 지정할 수도 있습니다. 지식 베이스(knowledge bases)도 처리할 수 있습니다.

FAQ

Q: 모노레포(mono repos)에서도 작동하나요?
A: 네. 워크스페이스 기반의 프로젝트 구조와 워크스페이스 간 의존성 매핑(cross-workspace dependency mapping)을 처리합니다.

Q: 그래프를 이미지나 JSON으로 내보낼 수 있나요?
A: 대시보드에서 내보내기를 지원합니다. 기반이 되는 그래프 데이터는 프로그래밍 방식(programmatic use)으로 접근할 수 있습니다.

Q: 얼마나 큰 코드베이스까지 처리할 수 있나요?
A: 팀에서는 정기적으로 최대 50만 줄(500K lines) 규모의 리포지토리에서 테스트를 진행합니다. 더 큰 코드베이스도 작동하지만 분석에 더 오랜 시간이 걸립니다.

Q: GPU가 필요한가요?
A: 아니요. 모든 작업은 CPU에서 실행됩니다. LLM 호출은 Claude Code의 기존 인프라를 통해 이루어집니다.

Q: GitHub/GitLab과 통합되나요?
A: 현재는 CLI 기반입니다. 팀에서는 PR(Pull Request) 리뷰 시 자동으로 그래프를 생성할 수 있도록 CI/CD 통합 기능을 구축 중입니다.

Q: 무료인가요?
A: MIT 라이선스 하에 제공되는 오픈 소스 (Open source)입니다. 대시보드는 D3.js로 구축되었으며 완전히 브라우저 내에서 실행됩니다.

솔직한 후기

저는 3주 동안 이 도구를 사용해 왔습니다. 가이드 투어 (guided tours) 기능은 제가 계속해서 이 도구를 찾게 만드는 핵심 요소입니다. 마치 코드베이스를 이미 숙지하고 있는 시니어 개발자가 지도를 그려주며 안내해 주는 것과 같습니다.

차이점 영향 분석 (diff impact analysis) 기능은 우리 팀의 다음 프로덕션 장애 (production incident)를 막아줄 것입니다. 머지 (merge)를 하기 전에 어떤 모듈이 깨질지 미리 아는 것은 초능력 수준으로 유용합니다.

아쉬운 점: 시맨틱 검색 (semantic search)이 문맥 의존적 (context-dependent)인 쿼리를 놓칠 때가 있습니다. 페르소나 적응형 UI (persona-adaptive UI)가 제가 필요로 하는 상세 수준을 항상 정확하게 맞추는 것도 아닙니다. 하지만 두 기능 모두 활발히 개선되고 있습니다. 이 리포지토리 (repo)는 출시된 지 단 2개월밖에 되지 않았음에도 이미 97개의 커밋 (commits)이 쌓였습니다.

빠른 시작 (Quick Start)

# Claude Code 플러그인으로 설치
claude /plugin marketplace add Lum1104/Understand-Anything

...

이게 전부입니다. 세 개의 명령어로 5분이면 충분하며, 이제 다시는